API Loader Constants zh

NativePluginKit.Loader.Constants

宿主与插件共享的 ABI 定义。

---

HostApiAttribute

[AttributeUsage(AttributeTargets.Field)]
public sealed class HostApiAttribute : Attribute
{
    public string TargetNamespace { get; }
    public string ClassName { get; }
    public string MethodName { get; }
    public Type NativeDelegate { get; }
    public Type? PublicDelegate { get; }

    public HostApiAttribute(string targetNamespace, string className,
        string methodName, Type nativeDelegate, Type? publicDelegate = null);
}

标记 HostApiTable 中的字段，使源生成器产出对应的公共 API 类。NativeDelegate 描述原始 ABI 签名（指针参数），PublicDelegate 描述面向开发者的签名（使用 string 等托管类型）。

---

HostApiTable

[StructLayout(LayoutKind.Sequential)]
public struct HostApiTable
{
    // 约 70 个 IntPtr 字段，每个对应一个生成的 API 方法
}

不要手动编辑 HostApiTable —— 每个字段都带有 [HostApi] 特性，用于驱动代码生成。新增 API 的流程是：添加字段 + 添加特性 + 扩展 HostApiBridgeBuilder.Create + 在宿主中实现对应委托。

字段按组划分（按顺序）：

分组	示例字段
基础设施	FreeString
场景	TransitionToScene、Scene_GetCurrentScenePath
日志	PrintLog、PrintWarning、PrintError、LogDebug
配置	Config_GetCharacterImagePath、Config_GetExecutableDirectory、Config_GetPluginsDirectory
计时	Timing_GetTimeSinceStartup
事件	RegisterEventCallback、UnregisterEventCallback
剧情	Story_GetCurrentTimelineName、Story_IsBattle、Story_StartTimeline、Story_EndTimeline、Story_SendSignal
卡牌	Card_GetCardCount、Card_GetCardNameAt … Card_GetAppliedEffectParam2
实体	Entity_GetCount、Entity_GetIdAt … Entity_GetEffectMaxStacks

---

HostApiBridgeBuilder

public static unsafe class HostApiBridgeBuilder
{
    public static HostApiTable Create(
        FreeStringDelegate freeString,
        TransitionToSceneDelegate transition,
        GetStringDelegate getCurrentScenePath,
        PrintLogDelegate printLog,
        // ... 约 70 个参数
        );

    // 委托均为嵌套类型（TransitionToSceneDelegate、PrintLogDelegate 等）
}

静态工厂，将托管委托转换为非托管函数指针并填充 HostApiTable。

生命周期： builder 内部为每个传入的委托保留强引用，因此调用方无需自己维护引用。

当开发侧 API 返回 bool 时，委托使用 bool 返回值（例如 RegisterEventDelegate）；以 C ABI 安全方式返回枚举的方法使用 int。

---

PluginInfo

[StructLayout(LayoutKind.Sequential)]
public struct PluginInfo
{
    public IntPtr NamePtr;
    public IntPtr DescriptionPtr;
    public IntPtr AuthorPtr;
    public int MajorVersion, MinorVersion, BuildVersion, RevisionVersion;
    public int RequiredApiMajor, RequiredApiMinor;

    public string  GetName();
    public string  GetDescription();
    public string  GetAuthor();
    public Version GetVersion();
    public Version GetRequiredApiVersion();
}

由插件的 GetPluginInfo 导出返回的元数据块。字符串为 UTF-8 指针，由 StringToCoTaskMemUTF8 分配，在插件生命周期内有效。

---

PluginInitDelegate

[UnmanagedFunctionPointer(CallingConvention.Cdecl)]
public delegate void PluginInitDelegate(IntPtr hostApiTable);

与插件的 OnInit 导出一致。