3.4 KiB
3.4 KiB
IScriptRuntime
命名空间: XCEngine::Scripting
类型: class (abstract)
头文件: XCEngine/Scripting/IScriptRuntime.h
描述: 定义引擎脚本调度层与具体脚本后端之间的统一契约。
概览
IScriptRuntime 是 ScriptEngine 唯一应该直接依赖的脚本后端接口。当前这份契约覆盖四类能力：
- 运行时启停。
- 可用脚本类发现、字段元数据和默认值读取。
- 托管字段读写与字段同步。
- 脚本实例创建/销毁与生命周期方法调用。
这使得 ScriptEngine 只负责“什么时候该调什么”，而把 Mono 域、程序集加载、GCHandle 和 internal call 之类的细节留给具体实现。
公开概念
ScriptLifecycleMethod
当前生命周期枚举值为：
AwakeOnEnableStartFixedUpdateUpdateLateUpdateOnDisableOnDestroy
ScriptClassDescriptor
ScriptClassDescriptor 用来表示一个可绑定脚本类：
| 字段 | 说明 |
|---|---|
assemblyName |
所属程序集，如默认的 GameScripts。 |
namespaceName |
托管命名空间，可为空。 |
className |
托管类名。 |
GetFullName() 会把命名空间和类名拼成 Namespace.Class 形式；ScriptEngine::TryGetAvailableScriptClasses() 会直接返回这一结构的排序结果。
ScriptRuntimeContext
ScriptRuntimeContext 是后端执行脚本实例时的最小上下文：
| 字段 | 说明 |
|---|---|
scene |
当前运行场景。 |
gameObject |
当前脚本所属对象。 |
component |
当前脚本组件。 |
gameObjectUUID |
原生对象 UUID。 |
scriptComponentUUID |
脚本组件 UUID。 |
线程语义
- 接口本身不承诺线程安全。
- 当前引擎默认由主线程按固定时序调用这些方法。
公开方法
| 方法 | 说明 |
|---|---|
| OnRuntimeStart | 运行时开始时的后端入口。 |
| OnRuntimeStop | 运行时停止时的后端入口。 |
| TryGetAvailableScriptClasses | 返回后端当前可绑定的脚本类列表。 |
| TryGetClassFieldMetadata | 查询脚本类字段元数据。 |
| TryGetClassFieldDefaultValues | 查询脚本类字段默认值。 |
| TrySetManagedFieldValue | 向托管实例写字段。 |
| TryGetManagedFieldValue | 从托管实例读字段。 |
| SyncManagedFieldsToStorage | 把托管字段同步回本地存储。 |
| CreateScriptInstance | 创建脚本实例。 |
| DestroyScriptInstance | 销毁脚本实例。 |
| InvokeMethod | 调用生命周期方法。 |
当前契约边界
- 接口不承诺线程安全；当前调用点默认都在主线程。
- 返回
false可能代表类不存在、后端未初始化，或实现根本不支持该能力；调用方需要按方法语义区分。 TryGetClassFieldDefaultValues()的默认值应反映托管类构造后的初始字段状态，而不只是原生类型零值。