XCEngine/docs/api/XCEngine/Scripting/IScriptRuntime/IScriptRuntime.md

# IScriptRuntime

**命名空间**: `XCEngine::Scripting`

**类型**: `class (abstract)`

**头文件**: `XCEngine/Scripting/IScriptRuntime.h`

**描述**: 定义引擎脚本调度层与具体脚本后端之间的统一契约。

## 概览

`IScriptRuntime` 是 `ScriptEngine` 唯一应该直接依赖的脚本后端接口。当前这份契约覆盖四类能力：

- 运行时启停。
- 可用脚本类发现、字段元数据和默认值读取。
- 托管字段读写与字段同步。
- 脚本实例创建/销毁与生命周期方法调用。

这使得 `ScriptEngine` 只负责“什么时候该调什么”，而把 Mono 域、程序集加载、GCHandle 和 internal call 之类的细节留给具体实现。

## 公开概念

### ScriptLifecycleMethod

当前生命周期枚举值为：

- `Awake`
- `OnEnable`
- `Start`
- `FixedUpdate`
- `Update`
- `LateUpdate`
- `OnDisable`
- `OnDestroy`

### ScriptClassDescriptor

`ScriptClassDescriptor` 用来表示一个可绑定脚本类：

| 字段 | 说明 |
|------|------|
| `assemblyName` | 所属程序集，如默认的 `GameScripts`。 |
| `namespaceName` | 托管命名空间，可为空。 |
| `className` | 托管类名。 |

`GetFullName()` 会把命名空间和类名拼成 `Namespace.Class` 形式；`ScriptEngine::TryGetAvailableScriptClasses()` 会直接返回这一结构的排序结果。

### ScriptRuntimeContext

`ScriptRuntimeContext` 是后端执行脚本实例时的最小上下文：

| 字段 | 说明 |
|------|------|
| `scene` | 当前运行场景。 |
| `gameObject` | 当前脚本所属对象。 |
| `component` | 当前脚本组件。 |
| `gameObjectUUID` | 原生对象 UUID。 |
| `scriptComponentUUID` | 脚本组件 UUID。 |

## 线程语义

- 接口本身不承诺线程安全。
- 当前引擎默认由主线程按固定时序调用这些方法。

## 公开方法

| 方法 | 说明 |
|------|------|
| [OnRuntimeStart](OnRuntimeStart.md) | 运行时开始时的后端入口。 |
| [OnRuntimeStop](OnRuntimeStop.md) | 运行时停止时的后端入口。 |
| [TryGetAvailableScriptClasses](TryGetAvailableScriptClasses.md) | 返回后端当前可绑定的脚本类列表。 |
| [TryGetClassFieldMetadata](TryGetClassFieldMetadata.md) | 查询脚本类字段元数据。 |
| [TryGetClassFieldDefaultValues](TryGetClassFieldDefaultValues.md) | 查询脚本类字段默认值。 |
| [TrySetManagedFieldValue](TrySetManagedFieldValue.md) | 向托管实例写字段。 |
| [TryGetManagedFieldValue](TryGetManagedFieldValue.md) | 从托管实例读字段。 |
| [SyncManagedFieldsToStorage](SyncManagedFieldsToStorage.md) | 把托管字段同步回本地存储。 |
| [CreateScriptInstance](CreateScriptInstance.md) | 创建脚本实例。 |
| [DestroyScriptInstance](DestroyScriptInstance.md) | 销毁脚本实例。 |
| [InvokeMethod](InvokeMethod.md) | 调用生命周期方法。 |

## 当前契约边界

- 接口不承诺线程安全；当前调用点默认都在主线程。
- 返回 `false` 可能代表类不存在、后端未初始化，或实现根本不支持该能力；调用方需要按方法语义区分。
- `TryGetClassFieldDefaultValues()` 的默认值应反映托管类构造后的初始字段状态，而不只是原生类型零值。

## 相关文档

- [ScriptEngine](../ScriptEngine/ScriptEngine.md)
- [NullScriptRuntime](../NullScriptRuntime/NullScriptRuntime.md)
- [MonoScriptRuntime](../Mono/MonoScriptRuntime/MonoScriptRuntime.md)