API Events zh

NativePluginKit.Events

跨 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,
}

数值一经发布即不可修改

---

事件载荷

每个载荷前 8 字节固定为 EventHeader (int EventType, int DataSize), 所有载荷均标记为 [StructLayout(LayoutKind.Sequential)]

事件	结构体	字段 (除 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（宿主侧）

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;
}

宿主侧事件路由。订阅以 (callback, userData) 组合为键——同一个分发器函数指针可被多个插件以不同 userData 注册。

规则

• Raise 必须在主线程调用
• data 指针仅在本次调用期间有效。插件需自行复制任何要保留的数据