API Features zh

NativePluginKit.Features

宿主提供的功能模块。所有方法均为静态方法，必须在主线程调用。

---

Features.Strings.Strings

public static class Strings
{
    public static void Free(IntPtr ptr);
}

释放由宿主分配的非托管 UTF-8 字符串。

---

Features.Logger.Log

public static class Log
{
    public static void PrintLog(string message);
    public static void PrintWarning(string message);
    public static void PrintError(string message);
    public static void Debug(string message);
}

将日志写入宿主日志系统。

---

Features.Scene.Scene

public static class Scene
{
    public static string GetCurrentScenePath();
}

返回当前场景资源路径，若无则为空字符串。

---

Features.Config.Config

public static class Config
{
    public static string GetCharacterImagePath(string imageName);
    public static string GetPluginsDirectory();
}

路径辅助方法。GetPluginsDirectory() 返回宿主指定的插件目录。

---

Features.Timing.Timing

public static class Timing
{
    public static double GetTimeSinceStartup();
}

返回自宿主启动以来经过的秒数。

---

Features.Story.Story

public static class Story
{
    public static string GetCurrentTimelineName();
    public static bool   IsBattle();
}

剧情/时间线状态

---

Features.Cards.Card

public static partial class Card
{
    // 枚举
    public static int    GetCardCount();
    public static string GetCardNameAt(int index);
    public static bool   Contains(string name);

    // 元数据
    public static string GetDisplayName(string name);
    public static string GetDescription(string name);
    public static string GetImageName(string name);
    public static int    GetCost(string name);
    public static int    GetBaseAttack(string name);
    public static int    GetMaxStack(string name);
    public static int    GetWeight(string name);
    public static int    GetAttackType(string name);
    public static int    GetCardType(string name);

    // 附加效果
    public static int     GetAppliedEffectCount(string name);
    public static string  GetAppliedEffectId(string name, int index);
    public static string  GetAppliedEffectName(string name, int index);
    public static int     GetAppliedEffectCategory(string name, int index);
    public static int     GetAppliedEffectDuration(string name, int index);
    public static bool    GetAppliedEffectIsStackable(string name, int index);
    public static int     GetAppliedEffectMaxStacks(string name, int index);
    public static float   GetAppliedEffectParam1(string name, int index);
    public static float   GetAppliedEffectParam2(string name, int index);
}

手写扩展

public static CardAttackType GetAttackTypeEnum(string name);
public static CardCategory   GetCardTypeEnum(string name);
public static EffectCategory GetAppliedEffectCategoryEnum(string name, int index);
public static CardEffectInfo[] GetAppliedEffects(string name);

CardEffectInfo 是一个 readonly record struct，包含 EffectId、Name、Category、Duration、IsStackable、MaxStacks、Param1、Param2。

---

Features.Entities.Entity

public static partial class Entity
{
    // 枚举（原始 API）
    public static int  GetEntityCount();
    public static int  GetEntityIdAt(int index, IntPtr out16Bytes);

    // 查找与元数据
    public static bool   Contains(ulong low, ulong high);
    public static string GetName(ulong low, ulong high);
    public static string GetDisplayName(ulong low, ulong high);
    public static string GetImagePath(ulong low, ulong high);

    // 属性
    public static int GetMaxHP(ulong low, ulong high);
    public static int GetCurrentHP(ulong low, ulong high);
    public static int GetAttackPower(ulong low, ulong high);
    public static int GetDodgeChance(ulong low, ulong high);
    public static int GetShieldValue(ulong low, ulong high);
    public static int GetArmorValue(ulong low, ulong high);
    public static int GetCurrentCost(ulong low, ulong high);
    public static int GetMaxCost(ulong low, ulong high);

    // 状态
    public static bool IsAlive(ulong low, ulong high);
    public static bool IsDead(ulong low, ulong high);
    public static bool CanAct(ulong low, ulong high);
    public static bool IsPlayer(ulong low, ulong high);
    public static bool IsMob(ulong low, ulong high);

    // 效果
    public static int    GetEffectCount(ulong low, ulong high);
    public static string GetEffectId(ulong low, ulong high, int index);
    public static string GetEffectName(ulong low, ulong high, int index);
    public static int    GetEffectCategory(ulong low, ulong high, int index);
    public static int    GetEffectRemainingDuration(ulong low, ulong high, int index);
    public static int    GetEffectCurrentStacks(ulong low, ulong high, int index);
    public static int    GetEffectMaxStacks(ulong low, ulong high, int index);
}

手写扩展（Entity.Manual.cs）

public static EntityId   GetEntityIdAt(int index);
public static EntityId[] GetAllEntityIds();

// 以上所有方法的 EntityId 重载
public static bool   Contains(EntityId id);
public static string GetDisplayName(EntityId id);
public static int    GetCurrentHP(EntityId id);
// ... 其余同理

public static EffectCategory GetEffectCategoryEnum(EntityId id, int index);
public static EntityEffectInfo[] GetAllEffects(EntityId id);

EntityEffectInfo 是一个 readonly record struct，包含 EffectId, Name, Category, RemainingDuration, CurrentStacks, MaxStacks

---

Features.Events.EventBus

public static class EventBus
{
    public static void On<T>(EventType type, Action<T> handler) where T : unmanaged;
    public static void Off<T>(EventType type, Action<T> handler) where T : unmanaged;
}

高级、强类型的事件订阅封装。泛型 T 必须是非托管结构体，即 NativePluginKit.Events.EventData 中定义的载荷之一。

示例

EventBus.On<EntityDamagedEvent>(EventType.EntityDamaged, e => { /* ... */ });
EventBus.Off<EntityDamagedEvent>(EventType.EntityDamaged, handler);

内部通过 GCHandle 将转换器实例编码到原始 EventBridge.Register 的 userData 槽位。