用途
本技能是一份数据导向设计的专家蓝图,用于在 Godot 中借助 Resource 与 RefCounted 类定义可复用、对 Inspector 友好的数据结构。适用于物品定义(武器、消耗品、装备)、角色属性/成长系统、技能/能力数据、配置文件、对话数据库、敌人/NPC 模板等需要保存与读取的数据系统。
主要能力
技能文档中包含三个脚本:
- data_factory_resource.gd:带类型校验和批量实例化的资源工厂。文档标注为强制要求,在实现物品/属性数据库前应先阅读该脚本。
- resource_pool.gd:用于 Resource 实例的对象池,可减少热路径中的分配开销。
- resource_validator.gd:校验 Resource 文件,检查缺失的导出项与配置问题。
数据类型选择
文档给出三种类型的对比:
- Resource:需要保存/读取的数据,可序列化、可存盘、支持 Inspector。
- RefCounted:临时运行时数据,不可序列化、不可存盘、不支持 Inspector。
- Node:场景层级实体,可序列化(场景文件)、可存盘、支持 Inspector。
实现模式
文档给出 7 种模式:
- 自定义 Resource 类:如 ItemData,包含 item_name、description、item_type(@export_enum)、icon、value、stackable、max_stack 等导出属性,以及 use() 方法。可在 Inspector 中右键 New Resource → ItemData,填写属性并保存为 .tres 文件。
- 角色属性 Resource:CharacterStats 包含 max_health、max_mana、strength、defense、speed 等导出属性,以及 current_health/current_mana(带 setter 使用 clampi 限制范围)、take_damage()、heal()、duplicate_stats() 方法。使用时在 _ready 中复制一份运行时副本,避免修改原始资源。
- 数据库模式(Resource 数组):ItemDatabase 含 Array[ItemData],提供 get_item_by_name()、get_items_by_type() 方法,可通过 preload 作为全局 autoload 使用。
- 纯运行时数据(RefCounted):如 DamageCalculation,用于不需要持久化的数据。
- 嵌套 Resource:如 WeaponData 继承 ItemData,包含 special_effects: Array[StatusEffect]。
- 带信号的 Resource:如 Inventory,定义 item_added/item_removed 信号,在 add_item/remove_item 中触发。
- 运行时加载 Resource:使用 load() 动态加载、preload() 编译期预加载,以及用 DirAccess 遍历目录加载所有 .tres 资源。
禁止事项(文档明确列出)
- 绝不直接修改资源实例而不复制:对已加载资源执行 player.stats.health -= 10 会改动磁盘上的 .tres 文件,必须先 .duplicate()。
- 绝不使用无类型数组:@export var items: Array = [] 接受任意类型,会导致运行时错误,应使用 Array[ItemData]。
- 绝不忘记为 Inspector 编辑加 @export:没有 @export 的属性在 Inspector 中不可见。
- 绝不把逻辑放在基础 Resource 中:Resource 没有生命周期(_ready、_process),运行时逻辑应使用 extends RefCounted 或挂到 Node 上。
- 绝不序列化 Node 引用:Resource 中的 @export var player_node: Node 会破坏保存/加载,应存 NodePath 或 UID。
- 绝不使用不经错误检查的 ResourceSaver.save():ResourceSaver.save(res, path) 可能因权限或无效路径失败,必须检查返回的错误码。
使用方式
文档演示的创建方式包括:在 Inspector 中创建并保存 .tres 资源;将 ItemData 资源加入 ItemDatabase 的 items 数组并保存;通过 preload/load 读取;使用 ResourceSaver.save() 存盘并用 ResourceLoader.exists()/load() 读取。同时建议按类别组织资源目录(如 res://data/items/weapons、consumables、characters、databases)。
适用场景
面向 Godot 项目中需要可存盘、可在编辑器内配置的物品、属性、技能、配置、对话、敌人模板等数据系统,以及需要减少分配开销的热路径。
限制
文档未说明具体 Godot 版本要求、性能基准数据或平台限制,这些信息暂未提供。所有代码示例均为 GDScript,未提供其他语言版本。