Home

NativePluginKit API Reference

NativeAOT-compatible plugin system for the Unknown: Site-0 game client.

---

Table of Contents

• NativePluginKit.Features.FMOD
  • Transition
• NativePluginKit.Features.Logger
  • Log
• NativePluginKit.Loader
  • PluginLoader
• NativePluginKit.Loader.Constants
  • HostApiBridgeBuilder
  • HostApiTable
  • PluginInfo
  • PluginInitDelegate
• NativePluginKit.Loader.Plugins
  • Plugin
  • PluginContext

---

NativePluginKit.Features.FMOD

Transition

public class Transition

提供场景切换功能，调用宿主 API 的 TransitionToScene 函数。

Constructors

Member	Description
Transition()	默认构造函数

Methods

Member	Returns	Description
TransitionToScene(string scenePath, bool fadeOut)	void	请求宿主程序切换到指定场景

TransitionToScene(string, bool)

public static void TransitionToScene(string scenePath, bool fadeOut)

请求宿主程序切换到指定场景。

Parameter	Type	Description
scenePath	string	场景路径 (UTF-8)
fadeOut	bool	是否使用淡出过渡效果，默认为 true

场景路径以非托管 UTF-8 字符串传递，调用后立即释放内存。

---

NativePluginKit.Features.Logger

Log

public class Log

提供插件端日志输出功能，调用宿主 API 的 PrintLog 函数。

Constructors

Member	Description
Log()	默认构造函数

Methods

Member	Returns	Description
PrintLog(string message)	void	向宿主程序输出一条日志消息

PrintLog(string)

public static void PrintLog(string message)

向宿主程序输出一条日志消息。

Parameter	Type	Description
message	string	要输出的日志内容

消息被转换为非托管 UTF-8 字符串后传递给宿主 API，调用后立即释放内存。

---

NativePluginKit.Loader

PluginLoader

public class PluginLoader

负责加载和管理插件的核心类。使用非托管代码 (LoadLibrary) 动态加载插件并调用其导出函数。

Constructors

PluginLoader(Action, HostApiTable, Version)

public PluginLoader(Action<string> logAction, HostApiTable apiTable, Version apiVersion)

初始化 PluginLoader 类的新实例。

Parameter	Type	Description
logAction	Action<string>	用于接收日志消息的委托
apiTable	HostApiTable	要传递给插件的主程序 API 函数表
apiVersion	Version	主程序的 API 版本

Properties

Member	Type	Description
Api	HostApiTable	主程序暴露给插件的 API 函数表
CurrentApiVersion	Version	主程序的 API 版本，用于与插件所需版本比较
LogWriter	Action<string>	主程序的日志输出委托，用于记录加载过程信息

Methods

Member	Returns	Description
LoadPlugin(string)	bool	加载指定路径的插件，并调用其导出的 OnInit 函数
LoadPluginsFromDirectory(string)	void	加载指定目录下的所有插件 (*.dll)
UnloadAll()	void	卸载所有已加载的插件并释放库句柄

LoadPlugin(string)

public bool LoadPlugin(string dllPath)

加载指定路径的插件，并调用其导出的 OnInit 函数。

Parameter	Type	Description
dllPath	string	插件的完整路径

Returns: 如果加载并初始化成功，返回 true；否则返回 false。

加载成功后模块句柄会保留，以便插件在宿主进程生命周期内保持加载状态。初始化函数指针类型为 delegate* unmanaged<IntPtr, void>。

LoadPluginsFromDirectory(string)

public void LoadPluginsFromDirectory(string directoryPath)

加载指定目录下的所有插件 (*.dll)。

Parameter	Type	Description
directoryPath	string	插件目录路径

若目录不存在则静默返回。每个 DLL 的加载过程会通过 LogWriter 记录。

UnloadAll()

public void UnloadAll()

卸载所有已加载的插件并释放库句柄。

---

NativePluginKit.Loader.Constants

HostApiBridgeBuilder

public static class HostApiBridgeBuilder

用于构建 HostApiTable 的静态工厂类，将托管委托转换为非托管函数指针。

Methods

Member	Returns	Description
Create(TransitionToSceneDelegate, PrintLogDelegate)	HostApiTable	创建填充了函数指针的 HostApiTable 实例

Create(TransitionToSceneDelegate, PrintLogDelegate)

public static HostApiTable Create(TransitionToSceneDelegate transition, PrintLogDelegate printLog)

创建填充了函数指针的 HostApiTable 实例。

Parameter	Type	Description
transition	TransitionToSceneDelegate	实现场景切换的托管委托
printLog	PrintLogDelegate	实现日志输出的托管委托

Returns: 包含非托管函数指针的 API 表结构体。

Nested Types

Type	Description
PrintLogDelegate	表示日志输出函数的委托，与宿主 API 中的 PrintLog 匹配
TransitionToSceneDelegate	表示场景切换函数的委托，与宿主 API 中的 TransitionToScene 匹配

PrintLogDelegate

public delegate void PrintLogDelegate(IntPtr messagePtr)

表示日志输出函数的委托，与宿主 API 中的 PrintLog 匹配。

TransitionToSceneDelegate

public delegate void TransitionToSceneDelegate(IntPtr scenePathPtr, bool fadeOut)

表示场景切换函数的委托，与宿主 API 中的 TransitionToScene 匹配。

---

HostApiTable

public struct HostApiTable

主程序暴露给插件的函数指针表，包含插件可调用的宿主功能。结构体采用顺序布局，与非托管内存直接对应。

Fields

Member	Type	Description
PrintLog	IntPtr	指向 PrintLog 函数的指针。函数签名：void PrintLog(IntPtr messagePtr)
TransitionToScene	IntPtr	指向 TransitionToScene 函数的指针。函数签名：void TransitionToScene(IntPtr scenePathPtr, bool fadeOut)

---

PluginInfo

public struct PluginInfo

插件元数据信息，以非托管结构体形式存储，供宿主程序读取。

Methods

Member	Returns	Description
GetAuthor()	string	获取插件作者名称
GetDescription()	string	获取插件描述信息
GetName()	string	获取插件名称
GetRequiredApiVersion()	Version	获取插件所需的宿主 API 版本
GetVersion()	Version	获取插件版本

Fields

Member	Type	Description
AuthorPtr	IntPtr	指向 UTF-8 作者名称字符串的指针
BuildVersion	int	构建版本号
DescriptionPtr	IntPtr	指向 UTF-8 描述字符串的指针
MajorVersion	int	主版本号
MinorVersion	int	次版本号
NamePtr	IntPtr	指向 UTF-8 插件名称字符串的指针
RequiredApiMajor	int	所需宿主 API 主版本号
RequiredApiMinor	int	所需宿主 API 次版本号
RevisionVersion	int	修订版本号

---

PluginInitDelegate

public delegate void PluginInitDelegate(IntPtr hostApiTable)

插件导出的初始化函数签名。插件必须导出一个名为 OnInit 的函数，参数为指向 HostApiTable 的指针。

---

NativePluginKit.Loader.Plugins

Plugin

public abstract class Plugin

所有插件的基类，提供与宿主程序交互的基础功能。插件继承此类并实现 OnStart 和 OnStop 方法。

Properties

Member	Type	Description
Api	HostApiTable	获取宿主程序提供的 API 函数表，插件可通过它调用宿主功能
Author	string	插件作者
Description	string	插件描述信息
Name	string	插件名称
RequiredApiVersion	Version	插件所要求的宿主程序 API 版本
Version	Version?	插件版本号，默认为所在程序集的版本号

Methods

Member	Returns	Description
GetPluginInfo()	IntPtr	返回插件信息结构体指针，供宿主程序查询
OnStop()	void	插件停止时调用的抽象方法，子类必须实现具体的清理逻辑

GetPluginInfo()

public static IntPtr GetPluginInfo()

返回插件信息结构体指针，供宿主程序查询。

OnStop()

public void OnStop()

插件停止时调用的抽象方法，子类必须实现具体的清理逻辑。

---

PluginContext

public static class PluginContext

提供插件运行时的全局上下文，用于访问宿主 API 函数表。

Properties

Member	Type	Description
CurrentApi	HostApiTable	获取当前插件使用的宿主 API 函数表。该属性在插件初始化时被设置