# Scripting

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

**类型**: `module`

**描述**: 提供脚本组件数据模型、字段覆盖存储、运行时调度器以及可替换的托管脚本后端抽象。

## 概览

当前脚本模块已经形成一条明确的“场景数据层 -> 运行时调度层 -> 托管后端层”链路：

1. [ScriptComponent](ScriptComponent/ScriptComponent.md) 挂在 `GameObject` 上，保存程序集名、命名空间、类名、组件 UUID 和 [ScriptFieldStorage](ScriptFieldStorage/ScriptFieldStorage.md)。
2. [ScriptEngine](ScriptEngine/ScriptEngine.md) 在运行时收集场景内所有脚本组件，按 `(gameObjectUUID, scriptComponentUUID)` 跟踪实例状态，并统一驱动生命周期。
3. [IScriptRuntime](IScriptRuntime/IScriptRuntime.md) 定义“类发现、字段元数据、默认值读取、实例创建、生命周期调用、字段同步”的统一契约。
4. [NullScriptRuntime](NullScriptRuntime/NullScriptRuntime.md) 在没有真实托管后端时兜底，让脚本数据层和编辑流程仍然可工作。
5. [Mono](Mono/Mono.md) 子目录中的 [MonoScriptRuntime](Mono/MonoScriptRuntime/MonoScriptRuntime.md) 是当前唯一的真实托管后端，负责加载 `XCEngine.ScriptCore.dll` 与 `GameScripts.dll`、发现脚本类、创建托管实例并完成字段桥接。

如果从商业级游戏引擎常见的分层方式理解：

- `ScriptComponent + ScriptFieldStorage` 是可序列化的数据层。
- `ScriptEngine` 是场景运行时的调度层。
- `IScriptRuntime` / `MonoScriptRuntime` 是托管执行后端。

这种拆分和 Unity 一类引擎的设计取向很接近。核心目的不是“为了抽象而抽象”，而是把“场景持久化”“运行时生命周期”“托管语言桥接”三件本来容易互相缠死的事拆开。

## 为什么当前要这样设计

- 场景、Prefab 或 Inspector 在运行时未启动时也必须能稳定保存脚本绑定和字段覆盖值，因此 `ScriptComponent` 不能直接等价于活体托管对象。
- 生命周期顺序、场景内动态创建对象追踪、类切换重建这些规则需要由原生层统一控制，否则更换脚本后端时行为会漂。
- 类发现、字段默认值读取和真正实例化都以编译后的程序集为事实来源，能让“下拉列表里看到的类”“Inspector 里看到的默认值”“运行时真正创建出的类”尽量来自同一份元数据。
- 把 Mono API、GCHandle、internal call 注册等细节收敛在 `MonoScriptRuntime`，可以避免后端实现扩散到引擎各个模块。

## 托管桥接的当前真实语义

当前 Mono 桥接已经不是单纯“脚本能跑起来”这一层，而是直接暴露了一套和原生状态中心相连的脚本 API 面：

- `Time.deltaTime`
  - 由 `MonoScriptRuntime::InvokeMethod()` 在每次生命周期调用前写入 internal call 全局状态。
  - `FixedUpdate()` 中读到的是本次 `OnFixedUpdate(fixedDeltaTime)` 传入的参数。
  - `Update()` / `LateUpdate()` 中读到的是各自回调传入的逐帧 delta。
- `Time.fixedDeltaTime`
  - 不读取某次 fixed tick 的历史参数，而是直接走 `ScriptEngine::GetRuntimeFixedDeltaTime()`。
  - 也就是说，它反映的是“当前运行时固定步长配置值”，不是“本次 `FixedUpdate()` 实参快照”。
- `Input`
  - `Input.GetKey()` / `GetKeyDown()` / `GetKeyUp()`、`GetButton*()`、`GetAxis*()`、`anyKey` / `anyKeyDown` 都是对 [InputManager](../Input/InputManager/InputManager.md) 当前状态的直接转发。
  - `GetKeyUp()` 当前对应的是释放边沿语义，也就是原生 `IsKeyReleased()`，不是“当前键没有按住”。
  - `anyKey` / `anyKeyDown` 也会把鼠标按钮状态算进去，并继承输入系统的帧边界语义。

如果要进一步理解 `Pressed` / `Released` / `anyKeyDown` 的帧语义，应同时阅读 [Input Flow And Frame Semantics](../../_guides/Input/Input-Flow-and-Frame-Semantics.md)。

## 当前运行链路

1. `SceneRuntime` 启动场景时调用 `ScriptEngine::OnRuntimeStart(scene)`。
2. `ScriptEngine` 先通知当前运行时启动，再递归收集场景里现有的 `ScriptComponent`，同时订阅 `Scene::OnGameObjectCreated()` 以追踪运行中创建的新对象。
3. 对满足运行条件的组件，运行时创建托管实例；`MonoScriptRuntime` 会先注入 `gameObjectUUID` / `scriptComponentUUID`，再把 `ScriptFieldStorage` 中同名且类型匹配的字段写入实例。
4. `ScriptEngine` 统一按 `Awake -> OnEnable -> Start -> FixedUpdate / Update / LateUpdate` 驱动生命周期；其中 `Start` 会延后到第一次 `OnUpdate()` 前补发，而不是在 `OnRuntimeStart()` 中立即执行。
5. 每次生命周期调用后，运行时都会执行 `SyncManagedFieldsToStorage()`；当前 Mono 实现只会回写“本地已存在且类型仍匹配”的字段。
6. 编辑器或调试工具可通过 `ScriptEngine::TryGetScriptFieldModel()` / `TryGetScriptFieldSnapshots()` 看到字段默认值、覆盖值、活体值以及 `StoredOnly` / `TypeMismatch` 等诊断状态。

## 脚本类发现与重绑定

当前“脚本类下拉列表”和“运行中改类名”的语义已经明确落在源码里：

- `MonoScriptRuntime` 只扫描应用程序集，也就是 `GameScripts.dll` 这一侧的非抽象 `MonoBehaviour` 子类，不会把 `XCEngine.ScriptCore.dll` 里的基础类型暴露成可绑定脚本类。
- `ScriptEngine::TryGetAvailableScriptClasses()` 在运行时列表之上追加两步规范化：
  - 可选的按程序集过滤
  - 按 `assemblyName -> namespaceName -> className` 排序，并剔除空类名条目
- `ScriptComponent::SetScriptClass()` / `ClearScriptClass()` 是显式重绑定入口。
- 运行时里真正执行“停掉旧实例 -> 重新跟踪 -> 视情况立即创建新实例”的，是 [ScriptEngine::OnScriptComponentClassChanged](ScriptEngine/OnScriptComponentClassChanged.md)。

这套设计和商业引擎里常见的 Inspector 行为一致：类切换不是随便改几个字符串，而是走一条受控的重绑定链路。

## 项目程序集来源

当 `XCENGINE_ENABLE_MONO_SCRIPTING` 打开时，`managed/CMakeLists.txt` 会构建两类程序集：

- 引擎脚本核心程序集: `XCEngine.ScriptCore.dll`
- 游戏脚本程序集: `GameScripts.dll`

除了测试用的 `build/managed` 输出，同一套 CMake 还会把项目 `project/Assets/**/*.cs` 编译到 `project/Library/ScriptAssemblies/GameScripts.dll`。如果项目暂时没有任何 `.cs` 文件，还会生成占位源文件，确保 `GameScripts.dll` 仍然存在。

`MonoScriptRuntime::Settings` 可以直接指向 `project/Library/ScriptAssemblies`，因此项目资产脚本、它们的字段默认值、类发现结果，已经进入当前文档的真实行为范围，而不是“未来规划”。

## 当前实现边界

- 当前公开支持的脚本字段类型是有限集合: 标量、字符串、`Vector2/3/4` 和 `GameObject` 引用。
- 生命周期覆盖 `Awake / OnEnable / Start / FixedUpdate / Update / LateUpdate / OnDisable / OnDestroy`。
- `NullScriptRuntime` 只是桥接占位，不会真正执行脚本代码，也不会返回脚本类列表或字段默认值。
- `MonoScriptRuntime` 目前只发现应用程序集中的非抽象 `MonoBehaviour` 子类，不做热重载、域增量刷新或完整编辑器脚本生态。
- `Time.fixedDeltaTime` 的配置值与 `OnFixedUpdate(fixedDeltaTime)` 的回调参数当前仍是两条通道，上层时间系统需要自己保持一致。
- 字段同步目前不会自动把“运行中新增但本地没有声明”的字段持久化下来。

## 头文件

- [IScriptRuntime](IScriptRuntime/IScriptRuntime.md) - `IScriptRuntime.h`
- [NullScriptRuntime](NullScriptRuntime/NullScriptRuntime.md) - `NullScriptRuntime.h`
- [ScriptComponent](ScriptComponent/ScriptComponent.md) - `ScriptComponent.h`
- [ScriptEngine](ScriptEngine/ScriptEngine.md) - `ScriptEngine.h`
- [ScriptField](ScriptField/ScriptField.md) - `ScriptField.h`
- [ScriptFieldStorage](ScriptFieldStorage/ScriptFieldStorage.md) - `ScriptFieldStorage.h`
- [Mono](Mono/Mono.md) - `Mono/`

## 相关指南

- [Scripting Runtime And Field Model](../../_guides/Scripting/Scripting-Runtime-And-Field-Model.md) - 把场景、脚本字段缓存、运行时调度和 Mono 后端放回同一条真实链路里解释清楚，并补上设计理念。
- [Project Script Assembly And Field Sync](../../_guides/Scripting/Project-Script-Assembly-And-Field-Sync.md) - 解释 `project/Assets/**/*.cs` 如何进入 `GameScripts.dll`，哪些类会被发现，以及默认值、存储覆盖和活体字段如何相互覆盖。
- [Input Flow And Frame Semantics](../../_guides/Input/Input-Flow-and-Frame-Semantics.md) - 解释托管 `Input` API 当前所继承的原生输入帧语义。

## 相关文档

- [SceneRuntime](../Scene/SceneRuntime/SceneRuntime.md)
- [Scene](../Scene/Scene.md)
- [上级目录](../XCEngine.md)
- [API 总索引](../../main.md)