docs(scripting): add baseline api reference and guide

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

@@ -0,0 +1,28 @@
+# IScriptRuntime::CreateScriptInstance
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/IScriptRuntime.h`
+
+## 签名
+
+```cpp
+virtual bool CreateScriptInstance(
+    const ScriptRuntimeContext& context) = 0;
+```
+
+## 作用
+
+为某个 `ScriptComponent` 创建对应的脚本实例。
+
+## 契约要求
+
+- 成功返回 `true`，失败返回 `false`。
+- 实现应使用 `context` 里的 UUID 和组件信息完成绑定。
+
+## 相关文档
+
+- [DestroyScriptInstance](DestroyScriptInstance.md)
+- [ScriptEngine::OnRuntimeStart](../ScriptEngine/OnRuntimeStart.md)

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

@@ -0,0 +1,23 @@
+# IScriptRuntime::DestroyScriptInstance
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/IScriptRuntime.h`
+
+## 签名
+
+```cpp
+virtual void DestroyScriptInstance(
+    const ScriptRuntimeContext& context) = 0;
+```
+
+## 作用
+
+销毁某个脚本实例，并释放运行时后端对它的跟踪状态。
+
+## 相关文档
+
+- [CreateScriptInstance](CreateScriptInstance.md)
+- [ScriptEngine::OnRuntimeStop](../ScriptEngine/OnRuntimeStop.md)

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

@@ -0,0 +1,71 @@
+# IScriptRuntime
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `class (abstract)`
+
+**头文件**: `XCEngine/Scripting/IScriptRuntime.h`
+
+**描述**: 定义引擎脚本调度层与具体脚本后端之间的统一契约。
+
+## 概览
+
+`IScriptRuntime` 是 `ScriptEngine` 唯一应该依赖的脚本后端接口。它把脚本后端抽象成三类能力：
+
+- 运行时启停。
+- 托管类/字段元数据查询与字段读写。
+- 脚本实例创建销毁与生命周期方法调用。
+
+这种设计让 `ScriptEngine` 能专注于“调度”，而把 Mono、GCHandle、程序集加载这些实现细节留给具体后端。
+
+## 公开概念
+
+### ScriptLifecycleMethod
+
+当前生命周期枚举值为：
+
+- `Awake`
+- `OnEnable`
+- `Start`
+- `FixedUpdate`
+- `Update`
+- `LateUpdate`
+- `OnDisable`
+- `OnDestroy`
+
+### ScriptRuntimeContext
+
+`ScriptRuntimeContext` 是后端执行脚本实例时的最小上下文：
+
+| 字段 | 说明 |
+|------|------|
+| `scene` | 当前运行场景。 |
+| `gameObject` | 当前脚本所属对象。 |
+| `component` | 当前脚本组件。 |
+| `gameObjectUUID` | 原生对象 UUID。 |
+| `scriptComponentUUID` | 脚本组件 UUID。 |
+
+## 线程语义
+
+- 接口本身不承诺线程安全。
+- 当前引擎默认由主线程按固定时序调用这些方法。
+
+## 公开方法
+
+| 方法 | 说明 |
+|------|------|
+| [OnRuntimeStart](OnRuntimeStart.md) | 运行时开始时的后端入口。 |
+| [OnRuntimeStop](OnRuntimeStop.md) | 运行时停止时的后端入口。 |
+| [TryGetClassFieldMetadata](TryGetClassFieldMetadata.md) | 查询脚本类字段元数据。 |
+| [TrySetManagedFieldValue](TrySetManagedFieldValue.md) | 向托管实例写字段。 |
+| [TryGetManagedFieldValue](TryGetManagedFieldValue.md) | 从托管实例读字段。 |
+| [SyncManagedFieldsToStorage](SyncManagedFieldsToStorage.md) | 把托管字段同步回本地存储。 |
+| [CreateScriptInstance](CreateScriptInstance.md) | 创建脚本实例。 |
+| [DestroyScriptInstance](DestroyScriptInstance.md) | 销毁脚本实例。 |
+| [InvokeMethod](InvokeMethod.md) | 调用生命周期方法。 |
+
+## 相关文档
+
+- [ScriptEngine](../ScriptEngine/ScriptEngine.md)
+- [NullScriptRuntime](../NullScriptRuntime/NullScriptRuntime.md)
+- [MonoScriptRuntime](../Mono/MonoScriptRuntime/MonoScriptRuntime.md)

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

@@ -0,0 +1,33 @@
+# IScriptRuntime::InvokeMethod
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/IScriptRuntime.h`
+
+## 签名
+
+```cpp
+virtual void InvokeMethod(
+    const ScriptRuntimeContext& context,
+    ScriptLifecycleMethod method,
+    float deltaTime) = 0;
+```
+
+## 作用
+
+调用脚本实例上的某个生命周期方法。
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| `context` | 当前脚本实例上下文。 |
+| `method` | 要调用的生命周期枚举。 |
+| `deltaTime` | 帧相关时间参数；并非每个生命周期都会使用。 |
+
+## 相关文档
+
+- [ScriptLifecycleMethod](IScriptRuntime.md)
+- [ScriptEngine::OnUpdate](../ScriptEngine/OnUpdate.md)

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

@@ -0,0 +1,31 @@
+# IScriptRuntime::OnRuntimeStart
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/IScriptRuntime.h`
+
+## 签名
+
+```cpp
+virtual void OnRuntimeStart(Components::Scene* scene) = 0;
+```
+
+## 作用
+
+通知具体脚本后端：某个场景的脚本运行时已经开始。
+
+## 调用方
+
+当前由 [ScriptEngine::OnRuntimeStart](../ScriptEngine/OnRuntimeStart.md) 调用。
+
+## 契约要求
+
+- 后端可以在这里做场景绑定、运行时初始化或缓存清理。
+- 不应假定脚本实例已经全部创建；实例创建由后续 `CreateScriptInstance()` 驱动。
+
+## 相关文档
+
+- [IScriptRuntime](IScriptRuntime.md)
+- [OnRuntimeStop](OnRuntimeStop.md)

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

@@ -0,0 +1,27 @@
+# IScriptRuntime::OnRuntimeStop
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/IScriptRuntime.h`
+
+## 签名
+
+```cpp
+virtual void OnRuntimeStop(Components::Scene* scene) = 0;
+```
+
+## 作用
+
+通知脚本后端当前场景运行时正在结束。
+
+## 契约要求
+
+- 应释放与当前运行场景关联的运行态资源。
+- 不应再假定脚本实例继续可用。
+
+## 相关文档
+
+- [IScriptRuntime](IScriptRuntime.md)
+- [OnRuntimeStart](OnRuntimeStart.md)

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

@@ -0,0 +1,31 @@
+# IScriptRuntime::SyncManagedFieldsToStorage
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/IScriptRuntime.h`
+
+## 签名
+
+```cpp
+virtual void SyncManagedFieldsToStorage(
+    const ScriptRuntimeContext& context) = 0;
+```
+
+## 作用
+
+把托管实例中的字段变化同步回原生侧字段存储。
+
+## 调用时机
+
+当前 `ScriptEngine` 会在每次生命周期方法调用后执行这一步。
+
+## 设计意义
+
+这让场景序列化层可以观察到运行时字段回写结果，而不要求场景系统直接理解托管对象。
+
+## 相关文档
+
+- [ScriptFieldStorage](../ScriptFieldStorage/ScriptFieldStorage.md)
+- [InvokeMethod](InvokeMethod.md)

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

@@ -0,0 +1,35 @@
+# IScriptRuntime::TryGetClassFieldMetadata
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/IScriptRuntime.h`
+
+## 签名
+
+```cpp
+virtual bool TryGetClassFieldMetadata(
+    const std::string& assemblyName,
+    const std::string& namespaceName,
+    const std::string& className,
+    std::vector<ScriptFieldMetadata>& outFields) const = 0;
+```
+
+## 作用
+
+查询某个脚本类公开字段的元数据。
+
+## 返回值语义
+
+- 返回 `true`：后端确认这个类存在，并成功返回字段元数据。
+- 返回 `false`：类不存在、后端未初始化，或后端根本不支持这类查询。
+
+## 设计意义
+
+`ScriptEngine` 依赖它来做字段编辑校验、字段模型拼装和运行时/本地字段差异对比。
+
+## 相关文档
+
+- [ScriptField](../ScriptField/ScriptField.md)
+- [ScriptEngine::TryGetScriptFieldModel](../ScriptEngine/TryGetScriptFieldModel.md)

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

@@ -0,0 +1,29 @@
+# IScriptRuntime::TryGetManagedFieldValue
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/IScriptRuntime.h`
+
+## 签名
+
+```cpp
+virtual bool TryGetManagedFieldValue(
+    const ScriptRuntimeContext& context,
+    const std::string& fieldName,
+    ScriptFieldValue& outValue) const = 0;
+```
+
+## 作用
+
+从托管实例读取一个字段值。
+
+## 当前使用方式
+
+`ScriptEngine` 会优先尝试从运行中的托管实例读取字段；只有失败时才回退到 `ScriptFieldStorage`。
+
+## 相关文档
+
+- [TrySetManagedFieldValue](TrySetManagedFieldValue.md)
+- [ScriptEngine::TryGetScriptFieldValue](../ScriptEngine/TryGetScriptFieldValue.md)

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

@@ -0,0 +1,30 @@
+# IScriptRuntime::TrySetManagedFieldValue
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/IScriptRuntime.h`
+
+## 签名
+
+```cpp
+virtual bool TrySetManagedFieldValue(
+    const ScriptRuntimeContext& context,
+    const std::string& fieldName,
+    const ScriptFieldValue& value) = 0;
+```
+
+## 作用
+
+向一个已经存在的托管脚本实例写入字段值。
+
+## 契约要求
+
+- 调用时实例未必一定存在，因此实现应自行检查。
+- 如果字段不存在、类型不匹配或实例不可用，应返回 `false`。
+
+## 相关文档
+
+- [TryGetManagedFieldValue](TryGetManagedFieldValue.md)
+- [ScriptEngine::TrySetScriptFieldValue](../ScriptEngine/TrySetScriptFieldValue.md)