# ScriptFieldStorage

**命名空间**: `XCEngine::Scripting`

**类型**: `class`

**头文件**: `XCEngine/Scripting/ScriptFieldStorage.h`

**描述**: 以字段名为键保存脚本字段覆盖值的本地缓存容器。

## 概览

`ScriptFieldStorage` 是当前脚本系统的数据缓冲层。它保存的不是“任意运行时变量”，而是需要在原生侧被识别、查询、序列化和可能回写的一组字段覆盖值。

在当前实现里它承担三种职责：

- 场景序列化时持久化脚本字段覆盖值。
- 运行前为 Inspector/工具提供可编辑的本地字段落点。
- 运行中接收 `MonoScriptRuntime::SyncManagedFieldsToStorage()` 的回写。

## 设计要点

- 用字段名映射到 `StoredScriptField`，读写简单直接。
- 用模板 `SetFieldValue` / `TryGetFieldValue` 提供方便访问，同时保留显式类型版本。
- `GetFieldNames()` 始终返回排序后的名字，保证序列化稳定性。
- 反序列化会先清空旧数据，再导入新数据，避免旧字段残留。

## 当前实现边界

- 不是线程安全容器。
- 不做类型自动转换。
- 不负责解释字段是否仍被脚本类声明；这部分语义由 `ScriptEngine::TryGetScriptFieldModel()` 结合类元数据来判定。
- 遇到非法反序列化行时会跳过，而不是抛异常中断整个恢复流程。

## 公开方法

| 方法 | 说明 |
|------|------|
| [SetFieldValue](SetFieldValue.md) | 写入字段。 |
| [TryGetFieldValue](TryGetFieldValue.md) | 读取字段。 |
| [FindField](FindField.md) | 按名称查找底层存储项。 |
| [Contains](Contains.md) | 判断字段是否存在。 |
| [Remove](Remove.md) | 删除字段。 |
| [Clear](Clear.md) | 清空所有字段。 |
| [GetFieldCount](GetFieldCount.md) | 返回字段数。 |
| [GetFieldNames](GetFieldNames.md) | 返回排序后的字段名列表。 |
| [SerializeToString](SerializeToString.md) | 序列化为文本。 |
| [DeserializeFromString](DeserializeFromString.md) | 从文本恢复。 |
| [Serialize](Serialize.md) | 写入输出流。 |
| [Deserialize](Deserialize.md) | 从输入流恢复。 |

## 相关文档

- [ScriptField](../ScriptField/ScriptField.md)
- [ScriptComponent](../ScriptComponent/ScriptComponent.md)