XCEngine/docs/api/XCEngine/Scripting/ScriptField/ScriptField.md

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	枚举转字符串。
TryParseScriptFieldType	字符串转枚举。
IsScriptFieldValueCompatible	判断类型和值是否兼容。
CreateDefaultScriptFieldValue	创建某个类型的默认值。
SerializeScriptFieldValue	把字段值序列化成文本。
TryDeserializeScriptFieldValue	从文本恢复字段值。
EscapeScriptString	转义脚本文本字符串。
UnescapeScriptString	反转义脚本文本字符串。

相关文档

• ScriptFieldStorage
• ScriptEngine