docs(scripting): add baseline api reference and guide

docs/api/XCEngine/Scripting/ScriptComponent/Constructor.md

@@ -0,0 +1,27 @@
+# ScriptComponent::Constructor
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `constructor`
+
+**头文件**: `XCEngine/Scripting/ScriptComponent.h`
+
+## 签名
+
+```cpp
+ScriptComponent();
+```
+
+## 当前实现行为
+
+- 调用内部 `GenerateScriptComponentUUID()` 生成一个非零随机 `uint64_t`。
+- `m_assemblyName` 默认初始化为 `GameScripts`。
+- 命名空间、类名和字段存储初始为空。
+
+## 设计意义
+
+组件 UUID 的存在，是为了让脚本运行时实例绑定不依赖对象内存地址。这样场景序列化、反序列化和运行时重建时，脚本实例可以通过 `(GameObjectUUID, ScriptComponentUUID)` 这组键稳定识别。
+
+## 相关文档
+
+- [ScriptComponent](ScriptComponent.md)

docs/api/XCEngine/Scripting/ScriptComponent/Deserialize.md

@@ -0,0 +1,35 @@
+# ScriptComponent::Deserialize
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/ScriptComponent.h`
+
+## 签名
+
+```cpp
+void Deserialize(std::istream& is) override;
+```
+
+## 作用
+
+从文本流恢复脚本组件状态。
+
+## 当前实现行为
+
+- 先把整个流读入字符串。
+- 用 `;` 切分键值对。
+- 识别 `scriptComponentUUID / assembly / namespace / class / fields`。
+- `fields` 会先做 `UnescapeScriptString()`，再交给 `ScriptFieldStorage::DeserializeFromString()`。
+
+## 容错行为
+
+- 空 token 会跳过。
+- 没有 `=` 的 token 会跳过。
+- 未识别的键会被忽略。
+
+## 相关文档
+
+- [Serialize](Serialize.md)
+- [ScriptFieldStorage::DeserializeFromString](../ScriptFieldStorage/DeserializeFromString.md)

docs/api/XCEngine/Scripting/ScriptComponent/GetFieldStorage.md

@@ -0,0 +1,28 @@
+# ScriptComponent::GetFieldStorage
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/ScriptComponent.h`
+
+## 签名
+
+```cpp
+ScriptFieldStorage& GetFieldStorage();
+const ScriptFieldStorage& GetFieldStorage() const;
+```
+
+## 作用
+
+访问当前脚本组件的持久化字段缓存。
+
+## 当前语义
+
+- 返回内部成员对象的引用，不转移所有权。
+- 这份存储既用于场景序列化，也用于脚本运行时字段回写。
+
+## 相关文档
+
+- [ScriptFieldStorage](../ScriptFieldStorage/ScriptFieldStorage.md)
+- [Serialize](Serialize.md)

docs/api/XCEngine/Scripting/ScriptComponent/GetFullClassName.md

@@ -0,0 +1,31 @@
+# ScriptComponent::GetFullClassName
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/ScriptComponent.h`
+
+## 签名
+
+```cpp
+std::string GetFullClassName() const;
+```
+
+## 当前实现行为
+
+- 如果 `m_className` 为空，返回空字符串。
+- 如果命名空间为空，只返回类名。
+- 否则返回 `namespace + "." + class`。
+
+## 用途
+
+这个接口主要用于：
+
+- 日志描述。
+- 测试断言。
+- 错误信息里构造完整脚本类名。
+
+## 相关文档
+
+- [ScriptComponent](ScriptComponent.md)

docs/api/XCEngine/Scripting/ScriptComponent/HasScriptClass.md

@@ -0,0 +1,31 @@
+# ScriptComponent::HasScriptClass
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/ScriptComponent.h`
+
+## 签名
+
+```cpp
+bool HasScriptClass() const;
+```
+
+## 当前实现行为
+
+当前只检查 `m_className` 是否为空：
+
+```cpp
+return !m_className.empty();
+```
+
+## 含义
+
+- 这表示“是否已经绑定某个脚本类名”。
+- 不代表该类在运行时中真的可用；类是否存在要看 `IScriptRuntime::TryGetClassFieldMetadata()` 或 `MonoScriptRuntime::IsClassAvailable()`。
+
+## 相关文档
+
+- [SetScriptClass](SetScriptClass.md)
+- [ScriptEngine::TryGetScriptFieldModel](../ScriptEngine/TryGetScriptFieldModel.md)

docs/api/XCEngine/Scripting/ScriptComponent/OnDestroy.md

@@ -0,0 +1,21 @@
+# ScriptComponent::OnDestroy
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/ScriptComponent.h`
+
+## 签名
+
+```cpp
+void OnDestroy() override;
+```
+
+## 当前实现行为
+
+直接调用 `ScriptEngine::Get().OnScriptComponentDestroyed(this)`。
+
+## 相关文档
+
+- [ScriptEngine::OnScriptComponentDestroyed](../ScriptEngine/OnScriptComponentDestroyed.md)

docs/api/XCEngine/Scripting/ScriptComponent/OnDisable.md

@@ -0,0 +1,22 @@
+# ScriptComponent::OnDisable
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/ScriptComponent.h`
+
+## 签名
+
+```cpp
+void OnDisable() override;
+```
+
+## 当前实现行为
+
+直接调用 `ScriptEngine::Get().OnScriptComponentDisabled(this)`。
+
+## 相关文档
+
+- [OnEnable](OnEnable.md)
+- [OnDestroy](OnDestroy.md)

docs/api/XCEngine/Scripting/ScriptComponent/OnEnable.md

@@ -0,0 +1,26 @@
+# ScriptComponent::OnEnable
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/ScriptComponent.h`
+
+## 签名
+
+```cpp
+void OnEnable() override;
+```
+
+## 当前实现行为
+
+直接转发到：
+
+```cpp
+ScriptEngine::Get().OnScriptComponentEnabled(this);
+```
+
+## 相关文档
+
+- [OnDisable](OnDisable.md)
+- [ScriptEngine::OnScriptComponentEnabled](../ScriptEngine/OnScriptComponentEnabled.md)

docs/api/XCEngine/Scripting/ScriptComponent/ScriptComponent.md

@@ -0,0 +1,72 @@
+# ScriptComponent
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Scripting/ScriptComponent.h`
+
+**描述**: 挂在 `GameObject` 上的脚本绑定组件，负责保存脚本类标识、组件 UUID 和字段存储。
+
+## 概览
+
+`ScriptComponent` 是脚本系统的数据入口。它本身不执行脚本逻辑，而是保存三类信息：
+
+- 这个组件绑定的是哪个程序集、命名空间和类。
+- 这个脚本组件自己的稳定 UUID。
+- 这份脚本实例的可持久化字段缓存 `ScriptFieldStorage`。
+
+这和 Unity 场景里挂着的 `MonoBehaviour` 序列化槽位很接近，但当前实现更明确地把“数据层”和“运行时实例层”拆开了。
+
+## 生命周期
+
+- 构造时会生成一个非零随机 `scriptComponentUUID`。
+- 默认程序集名是 `GameScripts`。
+- 启用、禁用、销毁回调会直接转发给 `ScriptEngine`。
+- 序列化/反序列化会持久化 UUID、脚本类绑定和字段存储内容。
+
+## 所有权
+
+- `ScriptComponent` 本身归 `GameObject` 所有。
+- `ScriptFieldStorage` 作为成员对象直接内嵌，不单独分配。
+
+## 当前实现边界
+
+- `SetScriptClass()` 只有在“之前没有脚本类，现在有了”这个转换点，才会主动通知 `ScriptEngine::OnScriptComponentEnabled()`。
+- 单纯修改已有脚本类名，不会自动触发一轮完整的重绑定流程。
+- 反序列化使用引擎私有的分号分隔文本格式，不是通用 JSON/YAML。
+
+## 常用访问器
+
+- `GetAssemblyName()` / `SetAssemblyName()`
+- `GetNamespaceName()` / `SetNamespaceName()`
+- `GetClassName()` / `SetClassName()`
+- `GetScriptComponentUUID()`
+
+这些访问器大多是简单内联函数，因此当前文档重点放在会改变生命周期或序列化语义的核心方法上。
+
+## 公开方法
+
+| 方法 | 说明 |
+|------|------|
+| [Constructor](Constructor.md) | 创建组件并生成 UUID。 |
+| [SetScriptClass](SetScriptClass.md) | 设置脚本类绑定。 |
+| [HasScriptClass](HasScriptClass.md) | 判断当前是否已经绑定脚本类。 |
+| [GetFullClassName](GetFullClassName.md) | 返回带命名空间的完整类名。 |
+| [GetFieldStorage](GetFieldStorage.md) | 访问持久化字段缓存。 |
+| [OnEnable](OnEnable.md) | 通知 `ScriptEngine` 组件启用。 |
+| [OnDisable](OnDisable.md) | 通知 `ScriptEngine` 组件禁用。 |
+| [OnDestroy](OnDestroy.md) | 通知 `ScriptEngine` 组件销毁。 |
+| [Serialize](Serialize.md) | 把组件状态写出到文本流。 |
+| [Deserialize](Deserialize.md) | 从文本流恢复组件状态。 |
+
+## 真实行为依据
+
+- `engine/src/Scripting/ScriptComponent.cpp`
+- `tests/scripting/test_script_component.cpp`
+
+## 相关文档
+
+- [ScriptEngine](../ScriptEngine/ScriptEngine.md)
+- [ScriptFieldStorage](../ScriptFieldStorage/ScriptFieldStorage.md)
+- [Scripting Runtime And Field Model](../../../_guides/Scripting/Scripting-Runtime-And-Field-Model.md)

docs/api/XCEngine/Scripting/ScriptComponent/Serialize.md

@@ -0,0 +1,39 @@
+# ScriptComponent::Serialize
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/ScriptComponent.h`
+
+## 签名
+
+```cpp
+void Serialize(std::ostream& os) const override;
+```
+
+## 作用
+
+把脚本组件的原生数据状态写到文本流。
+
+## 当前实现行为
+
+当前会按键值对形式写出：
+
+- `scriptComponentUUID`
+- `assembly`
+- `namespace`
+- `class`
+- `fields`
+
+字符串内容会经过 `EscapeScriptString()` 转义，字段存储则通过 `ScriptFieldStorage::SerializeToString()` 序列化后再整体转义。
+
+## 注意事项
+
+- 这是引擎私有格式，不承诺对外通用。
+- `fields` 本身是嵌套序列化文本，因此二次转义是必须的。
+
+## 相关文档
+
+- [Deserialize](Deserialize.md)
+- [ScriptField::EscapeScriptString](../ScriptField/EscapeScriptString.md)

docs/api/XCEngine/Scripting/ScriptComponent/SetScriptClass.md

@@ -0,0 +1,39 @@
+# ScriptComponent::SetScriptClass
+
+**命名空间**: `XCEngine::Scripting`
+
+**类型**: `method`
+
+**头文件**: `XCEngine/Scripting/ScriptComponent.h`
+
+## 签名
+
+```cpp
+void SetScriptClass(
+    const std::string& namespaceName,
+    const std::string& className);
+
+void SetScriptClass(
+    const std::string& assemblyName,
+    const std::string& namespaceName,
+    const std::string& className);
+```
+
+## 作用
+
+设置当前脚本组件绑定的托管类信息。
+
+## 当前实现行为
+
+- 两个重载都会先记录“之前是否已经有脚本类”。
+- 然后覆盖程序集名、命名空间和类名。
+- 只有在“之前没有脚本类，设置后有脚本类”时，才会主动调用 `ScriptEngine::Get().OnScriptComponentEnabled(this)`。
+
+## 设计含义
+
+当前实现把“首次绑定脚本类”视作一个启用事件，但并没有把“换到另一个脚本类”也当成完整重建流程。这是一个当前版本的真实边界，用户不应该误以为修改类名会自动完成热切换。
+
+## 相关文档
+
+- [HasScriptClass](HasScriptClass.md)
+- [OnEnable](OnEnable.md)