119 lines
3.7 KiB
Markdown
119 lines
3.7 KiB
Markdown
# ScriptField
|
|
|
|
**命名空间**: `XCEngine::Scripting`
|
|
|
|
**类型**: `utility header`
|
|
|
|
**头文件**: `XCEngine/Scripting/ScriptField.h`
|
|
|
|
**描述**: 定义脚本字段类型系统、字段快照模型、批量写入状态以及序列化/反序列化辅助函数。
|
|
|
|
## 概览
|
|
|
|
`ScriptField.h` 是当前脚本字段系统的核心协议头。它既定义“允许持久化哪些字段类型”，也定义“如何把字段值在文本、原生缓存和托管运行时之间搬运”。
|
|
|
|
## 公开类型
|
|
|
|
### ScriptFieldType
|
|
|
|
当前支持：
|
|
|
|
- `None`
|
|
- `Float`
|
|
- `Double`
|
|
- `Bool`
|
|
- `Int32`
|
|
- `UInt64`
|
|
- `String`
|
|
- `Vector2`
|
|
- `Vector3`
|
|
- `Vector4`
|
|
- `GameObject`
|
|
|
|
### ScriptFieldValue
|
|
|
|
当前是一个 `std::variant`，可持有：
|
|
|
|
- `std::monostate`
|
|
- `float`
|
|
- `double`
|
|
- `bool`
|
|
- `int32_t`
|
|
- `uint64_t`
|
|
- `std::string`
|
|
- `Math::Vector2`
|
|
- `Math::Vector3`
|
|
- `Math::Vector4`
|
|
- `GameObjectReference`
|
|
|
|
### ScriptFieldMetadata / ScriptFieldDefaultValue
|
|
|
|
- `ScriptFieldMetadata` 表示类里声明了一个什么字段。
|
|
- `ScriptFieldDefaultValue` 表示该字段在托管类初始状态下的默认值。
|
|
|
|
`MonoScriptRuntime::TryGetClassFieldDefaultValues()` 会直接构造托管对象并读取这一层数据，因此它可以反映 C# 字段初始化表达式。
|
|
|
|
### ScriptFieldSnapshot / ScriptFieldModel
|
|
|
|
它们用于字段面板、字段模型比对和“已声明字段 vs 已存储字段”诊断。`ScriptEngine::TryGetScriptFieldModel()` 会把默认值、存储值和活体托管值融合到这组结构里。
|
|
|
|
相关状态枚举：
|
|
|
|
- `ScriptFieldClassStatus`
|
|
`Unassigned / Available / Missing`
|
|
- `ScriptFieldValueSource`
|
|
`None / DefaultValue / StoredValue / ManagedValue`
|
|
- `ScriptFieldIssue`
|
|
`None / StoredOnly / TypeMismatch`
|
|
|
|
### ScriptFieldWriteRequest / ScriptFieldWriteResult
|
|
|
|
这组结构用于 `ScriptEngine::ApplyScriptFieldWrites()` 的批量写接口。
|
|
|
|
`ScriptFieldWriteStatus` 当前包括：
|
|
|
|
- `Applied`
|
|
- `EmptyFieldName`
|
|
- `UnknownField`
|
|
- `InvalidValue`
|
|
- `TypeMismatch`
|
|
- `StoredOnlyField`
|
|
- `ApplyFailed`
|
|
|
|
### ScriptFieldClearRequest / ScriptFieldClearResult
|
|
|
|
这组结构用于 `ScriptEngine::ClearScriptFieldOverrides()` 的批量清理接口。
|
|
|
|
`ScriptFieldClearStatus` 当前包括：
|
|
|
|
- `Applied`
|
|
- `EmptyFieldName`
|
|
- `UnknownField`
|
|
- `NoValueToClear`
|
|
- `ApplyFailed`
|
|
|
|
## 设计要点
|
|
|
|
- 字段类型集合是显式白名单，而不是任意模板反射。
|
|
- 文本序列化逻辑集中在这个头对应的实现里，保证 `ScriptFieldStorage` 和脚本组件共用同一套规则。
|
|
- `StoredOnly`、`TypeMismatch`、`DefaultValue / StoredValue / ManagedValue` 这些状态被直接编码进快照模型，便于编辑器或调试工具解释当前字段状态。
|
|
- 批量写入/清理结果也被做成显式状态枚举，避免 UI 只能拿到一个粗糙的布尔值。
|
|
|
|
## 公开函数
|
|
|
|
| 函数 | 说明 |
|
|
|------|------|
|
|
| [ScriptFieldTypeToString](ScriptFieldTypeToString.md) | 枚举转字符串。 |
|
|
| [TryParseScriptFieldType](TryParseScriptFieldType.md) | 字符串转枚举。 |
|
|
| [IsScriptFieldValueCompatible](IsScriptFieldValueCompatible.md) | 判断类型和值是否兼容。 |
|
|
| [CreateDefaultScriptFieldValue](CreateDefaultScriptFieldValue.md) | 创建某个类型的默认值。 |
|
|
| [SerializeScriptFieldValue](SerializeScriptFieldValue.md) | 把字段值序列化成文本。 |
|
|
| [TryDeserializeScriptFieldValue](TryDeserializeScriptFieldValue.md) | 从文本恢复字段值。 |
|
|
| [EscapeScriptString](EscapeScriptString.md) | 转义脚本文本字符串。 |
|
|
| [UnescapeScriptString](UnescapeScriptString.md) | 反转义脚本文本字符串。 |
|
|
|
|
## 相关文档
|
|
|
|
- [ScriptFieldStorage](../ScriptFieldStorage/ScriptFieldStorage.md)
|
|
- [ScriptEngine](../ScriptEngine/ScriptEngine.md)
|