docs(scripting): add baseline api reference and guide

This commit is contained in:
2026-03-28 15:10:54 +08:00
parent 14c7fd69ec
commit 359fe2adb3
104 changed files with 3377 additions and 27 deletions

View File

@@ -0,0 +1,61 @@
# ScriptEngine::TryGetScriptFieldModel
**命名空间**: `XCEngine::Scripting`
**类型**: `method`
**头文件**: `XCEngine/Scripting/ScriptEngine.h`
## 签名
```cpp
bool TryGetScriptFieldModel(
const ScriptComponent* component,
ScriptFieldModel& outModel) const;
```
## 作用
构建一份融合类元数据、托管值和本地缓存值的完整字段模型。
## 当前实现逻辑
### 1. 判定类状态
- 没绑定脚本类:`Unassigned`
- 绑定了脚本类且后端能返回元数据:`Available`
- 绑定了脚本类但后端查不到:`Missing`
### 2. 为已声明字段建立快照
对于运行时可见的每个字段:
- 先用字段类型生成默认值。
- 如果本地存储里有同名字段,则记录 `storedType / storedValue`
- 若类型不匹配,标记 `TypeMismatch`
- 若托管实例可读该字段,则当前值来源记为 `ManagedValue`
- 否则若本地存储类型匹配,则当前值来源记为 `StoredValue`
### 3. 追加仅存储字段
如果本地缓存里有字段名,但类元数据里没有:
- 会以 `StoredOnly` 问题状态附加到模型末尾。
### 4. 排序规则
- 当类状态不是 `Available` 时,会按字段名整体排序。
- 类状态为 `Available` 时,已声明字段按运行时元数据顺序构建,存储遗留字段再追加。
## 为什么这很重要
这套模型不是“为了文档好看”,而是当前脚本系统里最接近商业引擎 Inspector 数据模型的一层。它让工具或调试界面能回答这些关键问题:
- 这个字段类里声明了吗?
- 当前显示的是托管值还是存储值?
- 本地存储是否已经和类定义不匹配?
## 相关文档
- [TryGetScriptFieldSnapshots](TryGetScriptFieldSnapshots.md)
- [ScriptField](../ScriptField/ScriptField.md)