unity-scriptableobject

**调用本模块中的任何技能之前：**如果你准备根据技能名称或描述猜测参数来调用技能，请先停下——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已通过 recommend/schema 获取参数定义，则可以直接执行 dryRun。

触发条件

• 创建或编辑 SO 数据资产
• 查找 SO 实例
• 编写脚本管理 SO
• 创建或编辑 ScriptableObject 数据资产、查找 SO 实例、脚本化管理 SO

ScriptableObject 技能

创建和管理 ScriptableObject 资产。

操作模式

• 审批：本模块为 Mixed —— scriptableobject_get / scriptableobject_get_serialized_properties / scriptableobject_list_types / scriptableobject_find / scriptableobject_export_json 标记为 SkillMode.SemiAuto，可直接执行（注意，scriptableobject_export_json 传入 savePath 会写入磁盘，因此标记为 MutatesAssets = true，而非 ReadOnly）；写入类技能（scriptableobject_create / scriptableobject_set / scriptableobject_set_batch / scriptableobject_set_serialized_property / scriptableobject_set_serialized_property_batch / scriptableobject_duplicate / scriptableobject_import_json）标记为 SkillMode.FullAuto，需为单次执行授予权限并返回结果。
• 自动 / 绕过：FullAuto 直接执行。
• 包含 NeverInSemi 高危技能：scriptableobject_delete（Operation.Delete）。该技能在 Approval/Auto 模式下会返回 MODE_FORBIDDEN，仅在 Bypass 模式下或命中 Allowlist 时可调用。

不要（常见幻觉）：

• scriptableobject_create_type 不存在 → 使用模板 "ScriptableObject" 通过 script_create 创建 SO 脚本
• scriptableobject_get_properties / scriptableobject_read 不存在 → 使用 scriptableobject_get（反射视图）或 scriptableobject_get_serialized_properties（Inspector/序列化视图）
• scriptableobject_set_property / scriptableobject_set_field 不存在 → 使用 scriptableobject_set（顶层公共字段）或 scriptableobject_set_serialized_property（嵌套/数组/引用/私有字段）
• scriptableobject_save 不存在 → 更改会自动保存到资产

路由：

• 创建 ScriptableObject 脚本 → 使用 script 模块，模板为 "ScriptableObject"
• 导入/导出 JSON → 使用本模块中的 scriptableobject_import_json / scriptableobject_export_json
• 选择 setter：scriptableobject_set / scriptableobject_set_batch 仅适用于顶层公共简单字段（反射）。对于嵌套路径、数组/列表、对象引用、私有 [SerializeField] 字段、渐变、曲线和 [Flags] 枚举 → 使用 scriptableobject_set_serialized_property（以及 _batch）。

技能

scriptableobject_create

创建新的 ScriptableObject 资产。 参数：

• typeName（string）：ScriptableObject 类型名称。
• savePath（string）：资产保存路径。

scriptableobject_get

获取 ScriptableObject 的属性。 参数：

• assetPath（string）：资产路径。

scriptableobject_set

通过反射设置 ScriptableObject 上的顶层公共字段/属性。对于嵌套路径、数组、对象引用或私有 [SerializeField] 字段，请使用 scriptableobject_set_serialized_property。 参数：

• assetPath（string）：资产路径。
• fieldName（string）：字段或属性名称。
• value（string）：要设置的值，将根据成员类型进行解析，规则与 component_set_property 相同（布尔值支持 true/false/1/0/yes/no/on/off，其他值均会被拒绝；AnimationCurve 可使用预设或下方的 JSON 曲线）。

scriptableobject_list_types

列出项目中可用的 ScriptableObject 类型。 参数：

• filter（string，可选）：按名称筛选。

scriptableobject_duplicate

复制 ScriptableObject 资产。 参数：

• assetPath（string）：要复制的源资产路径。

scriptableobject_set_batch

一次性设置 ScriptableObject 上的多个字段。fields：JSON 对象 {fieldName: value, ...}

参数	类型	必填	默认值	描述
assetPath	string	是	-	ScriptableObject 的资源路径
fields	string	是	-	包含字段-值对的 JSON 对象，例如 {"fieldName": "value", ...}

返回： { success, fieldsSet, failed, results: [{ field, error }] }：不是可写公共字段/属性的键，或其值不符合字段类型要求时，该键会单独设置失败（并列在 results 中），其他键仍会照常设置；格式错误的 fields JSON 会在写入任何内容前被拒绝。

scriptableobject_get_serialized_properties

列出 ScriptableObject 资源在 Inspector 中序列化的属性——每个序列化字段的 propertyPath、类型和当前值，包括私有 [SerializeField] 字段以及嵌套/数组子项。使用返回的 propertyPath 值调用 scriptableobject_set_serialized_property。

参数	类型	必填	默认值	描述
assetPath	string	是	-	ScriptableObject 的资源路径
includeChildren	bool	否	true	递归遍历嵌套/数组子属性
limit	int	否	200	返回属性的最大数量

返回： { success, path, typeName, properties: [{ propertyPath, name, displayName, propertyType, type, isArray, editable, value }] }

scriptableobject_set_serialized_property

通过 propertyPath 设置单个 Inspector 序列化属性。适用于 scriptableobject_set 无法处理的属性：嵌套字段、数组/列表、UnityEngine.Object 引用、私有 [SerializeField] 字段、渐变、动画曲线和 [Flags] 枚举。

参数	类型	必填	默认值	描述
assetPath	string	是	-	目标 ScriptableObject 的资源路径
propertyPath	string	是	-	序列化属性路径（见下方语法）；speed 会自动回退尝试 m_Speed / _speed
value	string	否	null	要设置的值（格式取决于属性类型）
valueAssetPath	string	否	null	对于 ObjectReference 属性：要引用的资源的资源路径
valueObjectType	string	否	null	引用资源的可选类型筛选器（例如 "Sprite"，适用于子资源）

propertyPath 语法：

• 顶层字段：speed
• 嵌套字段：stats.maxHp
• 数组/列表元素：items.Array.data[2]
• 调整数组/列表大小：使用 value: "5" 设置 items.Array.size（先调整大小，再设置元素）

值格式：

• 基本类型："3.5" / "true" / "hello"（布尔值：true/false/1/0/yes/no/on/off）；向量："1,2,3"；颜色："1,0,0,1"；枚举：名称，或 0..n-1 范围内的数字（作为成员索引；值不同时，warnings 条目会标出成员名称；较大的数字表示成员值或已声明的位，未声明的位会被拒绝）
• [Flags] 枚举：逗号分隔的名称 "Fire,Ice"（也支持 |），或大于最后一个成员索引的原始位掩码数字（"-1" = Everything；较小的数字是成员索引，与任意枚举相同）
• ObjectReference：传入 valueAssetPath: "Assets/Icons/sword.png"（可选传入 valueObjectType）；使用 value: "null" 清除
• 渐变：{"colorKeys":[{"color":"1,0,0,1","time":0},{"color":"0,0,1,1","time":1}],"alphaKeys":[{"alpha":1,"time":0},{"alpha":1,"time":1}],"mode":"Blend"}
• 动画曲线：{"keys":[{"time":0,"value":0},{"time":1,"value":1,"inTangent":2,"outTangent":2}],"preWrapMode":"ClampForever","postWrapMode":"Loop"}

返回： { success, assetPath, propertyPath, valueSet, warnings? }。被拒绝的值不会写入任何内容。未知的 propertyPath 会返回 error 以及 availableProperties（前 60 项），以便自行修正。

scriptableobject_set_serialized_property_batch

一次调用即可为一个 ScriptableObject 资源设置多个 Inspector 序列化属性。

参数	类型	必填	默认值	说明
assetPath	string	是	-	目标 ScriptableObject 的资源路径
items	string	是	-	{propertyPath, value, valueAssetPath, valueObjectType} 的 JSON 数组

items 示例：[{"propertyPath":"items.Array.size","value":"2"},{"propertyPath":"items.Array.data[0]","value":"101"},{"propertyPath":"icon","valueAssetPath":"Assets/Icons/sword.png"}]

返回： { success, totalItems, successCount, failCount, results }

scriptableobject_delete

删除 ScriptableObject 资源。

参数	类型	必填	默认值	说明
assetPath	string	是	-	要删除的 ScriptableObject 的资源路径

返回： { success, deleted }

scriptableobject_find

按类型名称查找 ScriptableObject 资源。

参数	类型	必填	默认值	说明
typeName	string	是	-	要搜索的 ScriptableObject 类型名称
searchPath	string	否	"Assets"	要搜索的文件夹路径
limit	int	否	50	返回结果的最大数量

返回： { success, count, assets }

scriptableobject_export_json

将 ScriptableObject 导出为 JSON。

参数	类型	必填	默认值	说明
assetPath	string	是	-	要导出的 ScriptableObject 的资源路径
savePath	string	否	null	写入 JSON 的文件路径；省略此参数则直接内联返回 JSON

返回： 提供了 savePath 时返回 { success, path }（不会回显 JSON）；否则返回 { success, json }。

设置 savePath 会执行写入操作。 使用此参数时，该技能会调用 File.WriteAllText，因此会标记为 MutatesAssets = true，而不是 ReadOnly，即使它仍为 SkillMode.SemiAuto（任何模式下都无需授权）。只要不设置 savePath，读取 ScriptableObject 的值就不会产生磁盘写入；请注意，两种返回结构互斥，因此若想要读取数据却传入了 savePath，就需要再调用一次。

scriptableobject_import_json

将 JSON 数据导入 ScriptableObject。接受以下两种格式：

• 纯字段对象 {"hp": 100, "title": "Boss"} —— 应用前会自动包装为 {"MonoBehaviour": {...}}
• 由 scriptableobject_export_json 生成的 {"MonoBehaviour": {...}} 外层对象

参数	类型	必填	默认值	说明
assetPath	string	是	-	目标 ScriptableObject 的资源路径
json	string	否	null	要导入的 JSON 字符串
jsonFilePath	string	否	null	要读取并导入的 JSON 文件路径

返回： { success, assetPath }。如果没有任何序列化字段发生变化（字段名称不匹配，或值已相同），则返回 success: true，并附带 warning——请将此警告视为“未写入任何内容”，并对照 scriptableobject_export_json 的输出核实字段名称。

---

精确签名

确切名称、参数、默认值和返回值以 GET /skills/schema 或 unity_skills.get_skill_schema() 为准，而非本文件。