godot-resource-data-patterns

资源设计中绝对不能做的事

• 绝对不要直接修改资源实例 —— 如果不使用 .duplicate()，修改某个值（如 HP）就会修改所有人共用的 .tres。
• 绝对不要在 Resource 中使用无类型数组 —— @export var items: Array 会导致逻辑错误。始终使用 Array[ResourceClass] 来确保类型安全。
• 绝对不要在 Resource 中存储 Node 引用 —— 仅存在于特定 SceneTree 中的对象无法序列化。请存储 NodePath 或 UID。
• 绝对不要在 Resource 的 getter/setter 中执行繁重计算 —— Resource 应当是数据容器。将逻辑交给 Node 或专用的 RefCounted 类处理。
• 绝对不要跳过 ResourceSaver.save() 的错误检查 —— 保存可能因权限、磁盘空间或路径问题而失败。始终检查返回码。
• 绝对不要将 Resource 用于高频运行时数据 —— 如果某个值每秒变化 60 次（如速度），使用标准变量会比 Resource 属性更快。
• 绝对不要允许循环 Resource 引用 —— 如果 A.tres 引用 B.tres，而 B.tres 又引用 A.tres，引擎可能会在加载时崩溃。
• 绝对不要忘记 _init 默认值 —— 通过 new() 或在 Inspector 中创建的 Resource，需要在构造函数中设置默认值才能进行编辑。
• 如果实体需要唯一状态，绝对不要让它们共用同一个 Resource —— 对组件使用 resource_local_to_scene = true 或 duplicate()。
• 绝对不要用 .tres 存储海量数据集 —— 如果有 10,000 个项目，JSON 或自定义二进制格式可能比逐个存储 Resource 文件更高效。

---

决策树：Resource、RefCounted 还是 Node

类型	使用场景	磁盘 / Inspector
Resource	共享定义、可保存数据、通过 @export 创建	.tres/.res，Inspector ✅
RefCounted	临时运行时计算、非持久化辅助工具	无磁盘存储 / Inspector 支持较弱
Node	场景树中带有 process/signals 的场景实体	场景文件

使用 Resource 的场景： 物品定义、属性模板、能力、对话表、敌人配置。 使用 RefCounted 的场景： 伤害计算临时数据、短暂状态机、无需保存的工具。

可用脚本 — 按场景必须阅读

场景	必须阅读
多个实例共享基础 .tres，并且各自具有可变属性（HP）	resource_local_to_scene.gd
嵌套的 Item → Weapon → StatusEffect 树 / 保存整个对象图	nested_resource_serialization.gd
多个实体共享同一配置（享元模式）	resource_flyweight_caching.gd / flyweight_enemy_config.gd
自定义 @export 数据容器	custom_data_resource.gd
带信号的响应式属性	character_stats_resource.gd
由 Resource 组成的库存数组	resource_based_inventory.gd
将 Resource 树保存到磁盘	resource_save_system.gd — 检查 Error
游戏开始前预加载 / 建立 O(1) 缓存	resource_preloading_strategy.gd
运行时生成 Resource.new() 战利品	dynamic_resource_generation.gd
验证 / 对象池 / 工厂	resource_validator.gd / resource_pool.gd / data_factory_resource.gd

专家须知（关键）

**CAUTION：**如果在共享的 .tres 上运行时修改 HP/法力值，却未调用 duplicate(true) 或设置 resource_local_to_scene，就会修改磁盘上的资源文件——这就是 “伤害一个，所有对象都受影响” 的 bug。

• **.res 与 .tres：**生产环境使用二进制 .res；设计差异对比使用 .tres；嵌套树会通过 ResourceSaver 与父资源一起保存。
• **缓存：**外部编辑后使用 ResourceLoader.CACHE_MODE_REPLACE，以绕过过时缓存。
• **场景本地化 / 复制：**每个实例的组件必须使用此方式——resource_local_to_scene.gd。
• **10k+ 行：**单独的 .tres 文件不如 JSON/二进制格式——参见官方文档中的二进制序列化。

深入了解（按需加载）

模式 1–7 的演练（ItemData、数据库、RefCounted 计算、目录扫描、O(1) 缓存）——references/resource-patterns-deep.md。请参考 nested_resource_serialization.gd 实现嵌套武器，而非凭记忆操作。

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；需要切换到相邻领域时再加载相关技能——不要预先加载整个技能网络。

官方文档

• 资源 — 自定义资源脚本、.tres/.res、共享与 duplicate()，以及用于实例级状态的 resource_local_to_scene。
• 数据偏好 — 根据检查器和序列化需求，了解何时应将数据存储在资源、字典、ConfigFile 或普通脚本中。
• Resource — 本文各种数据容器模式都会用到的 duplicate、emit_changed、resource_path 和场景本地化标记。
• ResourceLoader — 为轻量级对象共享和预加载缓存提供支持的缓存 load / 线程化请求。
• ResourceSaver — 将自定义资源持久化到 user:// 或 res://，并始终检查返回的 Error。
• RefCounted — 当你需要引用计数，却不需要磁盘序列化或检查器导出时使用的轻量级运行时对象。
• 保存游戏 — 更广泛的存档策略，可与 ResourceSaver 配合使用，以保存基于存档槽的 .tres 状态。
• 后台加载 — 线程化的 ResourceLoader 轮询，避免数据库和 VFX 包卡顿主线程。
• GDScript 导出 — 使用类型化的 @export / Array[T]，确保物品和任务资源兼容检查器。
• 二进制序列化 API — 当数千行数据不适合存放在单独的 .tres 文件中时，使用紧凑的 FileAccess 打包方式。
• 场景组织 — 了解共享资源为何位于场景树之外，以及组件场景如何组合导出的数据。

相关技能

前置要求

• godot-project-foundations — 在编写共享 .tres 数据库前，了解项目布局、导入和 res:// 规范。
• godot-gdscript-mastery — 每个自定义资源脚本都依赖的 class_name、类型化数组、setter 和 @tool 使用规范。

配套内容

• godot-signal-architecture — 管理 changed / 自定义信号的所有权和扇出，这些信号用于驱动响应式 UI 和属性。
• godot-save-load-systems — 负责存档槽版本控制、迁移和安全路径，用于封装 ResourceSaver/ResourceLoader 的存档流程。
• godot-scene-management — 通过预加载的 Resource 缓存使用场景打包和线程化加载，避免卡顿峰值。
• godot-ability-system — 能力/增益效果定义属于 Resource 数据；此技能负责容器和序列化模式。
• godot-dialogue-system — 对话图和台词表是嵌套的 Resources，可复用此处的类型化数组和存档模式。
• godot-performance-optimization — 飞锤共享、池化 RefCounted 有效负载，以及大规模场景下 .res 何时优于文本 .tres。

下游 / 使用者

• godot-inventory-system — 物品堆叠、装备和背包会使用此处定义的 ItemData / 库存 Resource 数组。
• godot-procedural-generation — 在运行时通过 Resource.new() 实例化战利品、任务和配置的生成器。
• godot-monte-carlo-balancer — .tres 属性和经济数据表是首选的提取来源——应先构建数据层，再进行正则表达式批量处理。

主入口

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。