Messaging System

One of the most useful ways to hook into the game is by use of the MessagingSystem.

Ardenfall has a host of messages that are sent when stuff happens. "CharacterDeathMessage", "CharacterKillMessage", "EffectAddMessage"... there are over 100 messages that you can subscribe (or send).

You can also define your own messages, for yourself or other mods.

Example of a mod that begins listening to CharacterDeathMessage on initialize, and stops listening on uninitialize.

Important: Be sure to clean up your listeners!

using Ardenfall;
using UnityEngine;
using System;

namespace ExampleMod 
{	
	public class ExampleMod : ModRoot
	{
		public override void Initialize(string id)
		{
			base.Initialize(id);

			//Begin listening to death messages
			MessagingSystem.AddListener(typeof(CharacterDeathMessage), (Action<CharacterBase, DamageContext>)OnDeath);
		}
        
		public override void Uninitialize()
		{
			base.Uninitialize();

			//Stoplistening to death messages
			MessagingSystem.RemoveListener(typeof(CharacterDeathMessage), (Action<CharacterBase, DamageContext>)OnDeath);
		}

		//Triggered when any character dies
		private void OnDeath(CharacterBase character, DamageContext context) 
		{
			if(character is PlayerCharacter)
				Debug.Log($"Player has died!"); 
			else
				Debug.Log($"Character {character.GetVisualName()} has died!"); 
		}
	}
}

Useful Messages

CharacterDeathMessage(CharacterBase target, DamageContext context)

Triggered when a character dies.

CharacterDamageMessage(CharacterBase target, DamageContext context)

Triggered when character is damaged.

CharacterKillMessage(CharacterBase killer, DamageContext context)

Triggered when a character kills another. You can access context.victim to read who died.

EffectAddMessage(StatusEffectInstance effect)

Triggered whenever an Effect is added to an IEffectable. Can access effect.Target to read who the target is.

EffectRemoveMessage(StatusEffectInstance effect)

Triggered whenever an Effect is removed from an IEffectable. Can access effect.Target to read who the target is.

InventoryChangeMessage(Inventory inventory, ItemData item, int count, bool isAdded)

Triggered whenever an item stack in an Inventory is modified (items added or removed). Can access inventory.OwnerChar (can be null) to see what character owns it, if any. Inventories are also used with containers.

EquipChangeMessage(CharacterBase character, BaseItem item, bool isEquipped)

Triggered whenever a character unequips or equips an item

Tooling

Planned: Add tool to easily view all messages available

Under Consideration: Add tool to detect + display messages being triggered