API Events

NativePluginKit.Events

Event types and payload structures used across the ABI.

---

EventType

public enum EventType
{
    PluginLoaded = 100, PluginUnloaded = 101,

    SceneChanging = 200, SceneChanged = 201,

    TimelineStarted = 300, TimelineEnded = 301, TimelineSignal = 302,

    BattleStarted = 400, BattleEnded = 401,
    TurnStarted = 402, TurnEnded = 403, BattleMessage = 404,

    CardDrawn = 500, CardPlayRequested = 501,
    CardPlayed = 502, CardDiscarded = 503,

    EntityDamaged = 600, EntityHealed = 601,
    EntityDied = 602, EntityUpdated = 603,

    EffectApplied = 700, EffectExpired = 701,
}

Numeric values are frozen once published.

---

Event Payloads

Each payload begins with an EventHeader (int EventType, int DataSize). All payloads are [StructLayout(LayoutKind.Sequential)].

Event	Struct	Fields (beyond header)
PluginLoaded	PluginLoadedEvent	IntPtr PluginNamePtr, IntPtr VersionPtr
SceneChanging, SceneChanged	SceneEvent	IntPtr ScenePathPtr
TimelineStarted, TimelineEnded	TimelineEvent	IntPtr TimelineNamePtr, bool IsBattle
TimelineSignal	TimelineSignalEvent	IntPtr SignalNamePtr
BattleMessage	BattleMessageEvent	IntPtr MessagePtr
TurnStarted, TurnEnded	TurnEvent	int Turn
CardDrawn, CardPlayed, ...	CardEvent	ObjectIdNative OwnerEntityId, IntPtr CardNamePtr, ObjectIdNative TargetEntityId
EntityDamaged	EntityDamagedEvent	ObjectIdNative EntityId, int RawDamage, int HpDamage, int AttackType, int RemainingHP, bool Dodged, int ShieldAbsorbed, int ArmorAbsorbed
EntityDied	EntityDiedEvent	ObjectIdNative EntityId
EntityUpdated	EntityUpdatedEvent	ObjectIdNative EntityId, int CurrentHP, int CurrentCost
EffectApplied, EffectExpired	EffectEvent	ObjectIdNative OwnerEntityId, IntPtr EffectIdPtr, IntPtr EffectNamePtr, int RemainingDuration, int CurrentStacks

---

EventDispatcher (host side)

public static class EventDispatcher
{
    public static bool Register(int eventType, IntPtr callback, IntPtr userData);
    public static bool Unregister(int eventType, IntPtr callback, IntPtr userData);
    public static void ClearAll();
    public static void Raise(EventType type, IntPtr data);
    public static void Raise<T>(EventType type, ref T payload) where T : unmanaged;
}

Host-side event router. Subscriptions are keyed by (callback, userData) — the same dispatcher function can be registered for multiple plugins with different userData values.

Rules

• Raise must be called on the main thread.
• The data pointer is valid only for the duration of the call. Plugins must copy anything they want to keep.