Installation zh

安装

环境要求

组件	最低版本
.NET SDK	8.0
Runtime	.NET NativeAOT (plugin side)
Host OS	Windows / Linux / macOS

插件使用 PublishAot=true 编译，并导出非托管入口点。跨平台插件必须针对每个目标系统分别构建。

---

添加 NativePluginKit 到项目

方式一：NuGet

<PackageReference Include="NativePluginKit" Version="1.2.0" />

方式二：项目引用

<ProjectReference Include="..\NativePluginKit\NativePluginKit.csproj" />

方式三：Git 子模块

git submodule add https://github.com/GoWelkinDev/NativePluginKit.git

---

宿主端配置

在客户端初始化代码中，构建 HostApiTable 并创建 PluginLoader:

using NativePluginKit.Loader;
using NativePluginKit.Loader.Constants;

var api = HostApiBridgeBuilder.Create(
    freeString:             ptr => Marshal.FreeCoTaskMem(ptr),
    transition:             (pathPtr, fadeOut) => { /* ... */ },
    getCurrentScenePath:    () => IntPtr.Zero,
    printLog:               ptr => { /* ... */ },
    printWarning:           ptr => { /* ... */ },
    printError:             ptr => { /* ... */ },
    logDebug:               ptr => { /* ... */ },
    getCharacterImagePath:  ptr => IntPtr.Zero,
    getExecutableDirectory: () => IntPtr.Zero,
    getPluginsDirectory:    () => IntPtr.Zero,
    getTimeSinceStartup:    () => 0,
    registerEvent:          (t, cb, ud) => true,
    unregisterEvent:        (t, cb, ud) => true,
    getCurrentTimelineName: () => IntPtr.Zero,
    isBattle:               () => 0,
    startTimeline:          (ptr, battle) => { },
    endTimeline:            skip => { },
    sendSignal:             ptr => { },
    // Cards, Entity — see HostApiBridgeBuilder.Create full signature
    /* ... */
);

var loader = new PluginLoader(
    logAction:  msg => Console.WriteLine(msg),
    apiTable:   api,
    apiVersion: new Version(1, 0, 0));

loader.LoadPluginsFromDirectory(
    Path.Combine(AppContext.BaseDirectory, "plugins"));

Create 方法有 70+ 个参数。实际项目中应把所有委托实例保存为 static readonly 字段，避免被 GC 回收——HostApiBridgeBuilder 内部已持有强引用，但传递进来的 lambda 本身不能是临时的

---

插件端配置

1. 创建面向 net8.0 的类库项目

2. 编辑 .csproj：

   <PropertyGroup>
     <TargetFramework>net8.0</TargetFramework>
     <Nullable>enable</Nullable>
     <PublishAot>true</PublishAot>
     <NativeLib>Shared</NativeLib>
     <IlcExportUnmanagedEntrypoints>true</IlcExportUnmanagedEntrypoints>
     <RuntimeIdentifier>win-x64</RuntimeIdentifier>   <!-- 或 linux-x64 / osx-x64 -->
     <InvariantGlobalization>true</InvariantGlobalization>
   </PropertyGroup>
   
   <ItemGroup>
     <ProjectReference Include="..\NativePluginKit\NativePluginKit.csproj" />
     <ProjectReference Include="..\NativePluginKit.SourceGenerators\NativePluginKit.SourceGenerators.csproj"
                       OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
     <UnmanagedEntryPointsAssembly Include="NativePluginKit" />
   </ItemGroup>

   UnmanagedEntryPointsAssembly 用于让 NativePluginKit 中声明的 Plugin.GetPluginInfo 从插件 DLL 中导出

3. 构建：

   dotnet publish -c Release -r win-x64

4. 将生成的 YourPlugin.dll 复制到 <游戏根目录>/plugins/