docs(scripting): add baseline api reference and guide
This commit is contained in:
@@ -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)
|
||||
Reference in New Issue
Block a user