4.1 KiB
4.1 KiB
MonoScriptRuntime
命名空间: XCEngine::Scripting
类型: class
头文件: XCEngine/Scripting/Mono/MonoScriptRuntime.h
描述: 基于 Mono 的脚本运行时实现，负责程序集加载、类发现、实例创建、internal call 桥接和生命周期调用。
概览
MonoScriptRuntime 是当前唯一的真实托管脚本后端。它把 ScriptEngine 提供的抽象调用翻译成 Mono 世界里的具体动作：
- 初始化 root domain 和 app domain。
- 加载脚本核心程序集与游戏程序集。
- 发现继承
MonoBehaviour的可用脚本类。 - 构建类元数据缓存。
- 创建和销毁脚本实例。
- 通过 internal call 让托管脚本访问原生
GameObject、Transform、Camera等能力。
生命周期
- 构造时接收一份
Settings，并做路径补全。 - Initialize 会完成完整 Mono 初始化流程。
- Shutdown 会销毁 app domain、清空类缓存与实例缓存。
- 析构会自动调用
Shutdown()。
常用访问器
IsInitialized()GetSettings()GetLastError()
这些访问器主要用于测试、诊断和工具层。当前文档对 GetLastError() 单独补页，因为它直接关系到失败排查。
设计要点
ScriptEngine不直接碰 Mono API；所有后端细节收敛在这个类里。- 类缓存和实例缓存都基于稳定键，便于场景重建和脚本回绑。
- internal call 注册集中在本实现里，说明当前托管 API 面是围绕 Mono 后端组织的，而不是独立脚本 ABI。
当前实现边界
- 当前只发现应用程序集中的非抽象
MonoBehaviour子类。 - 支持的公共字段类型只覆盖
float / double / bool / int32 / uint64 / string / Vector2 / Vector3 / Vector4 / GameObject。 SyncManagedFieldsToStorage()只会回写已经存在于ScriptFieldStorage中的字段；运行时临时字段不会自动持久化。OnRuntimeStop()只清理当前活动场景与实例，不会做完整Shutdown()。
公开方法
| 方法 | 说明 |
|---|---|
| Constructor | 创建 Mono 运行时对象并解析设置。 |
| Destructor | 析构时执行 Shutdown()。 |
| Initialize | 初始化 Mono 域并发现脚本类。 |
| Shutdown | 关闭当前 Mono 运行时。 |
| GetLastError | 读取最近一次错误描述。 |
| IsClassAvailable | 查询脚本类是否已发现。 |
| GetScriptClassNames | 返回已发现脚本类名列表。 |
| TryGetClassFieldMetadata | 读取脚本类字段元数据。 |
| HasManagedInstance | 判断某脚本组件是否已有托管实例。 |
| GetManagedInstanceCount | 返回当前托管实例数。 |
| GetManagedInstanceObject | 读取托管对象裸指针。 |
| CreateManagedComponentWrapper | 为原生组件创建托管包装对象。 |
| TryGetFieldValue | 直接读取托管实例字段。 |
| OnRuntimeStart | 启动脚本运行时上下文。 |
| OnRuntimeStop | 停止当前运行场景的托管上下文。 |
| TrySetManagedFieldValue | 写托管字段。 |
| TryGetManagedFieldValue | 读托管字段。 |
| SyncManagedFieldsToStorage | 回写本地字段缓存。 |
| CreateScriptInstance | 创建脚本实例。 |
| DestroyScriptInstance | 销毁脚本实例。 |
| InvokeMethod | 调用生命周期方法。 |
真实行为依据
engine/src/Scripting/Mono/MonoScriptRuntime.cpptests/scripting/test_mono_script_runtime.cpp