SuperAPI AI 工具集

resource-data-patterns

编程与开发

查看项目

更新于 10-16 22:43

技能介绍

用途

本技能是一份数据导向设计的专家蓝图,用于在 Godot 中借助 Resource 与 RefCounted 类定义可复用、对 Inspector 友好的数据结构。适用于物品定义(武器、消耗品、装备)、角色属性/成长系统、技能/能力数据、配置文件、对话数据库、敌人/NPC 模板等需要保存与读取的数据系统。

主要能力

技能文档中包含三个脚本:

  • data_factory_resource.gd:带类型校验和批量实例化的资源工厂。文档标注为强制要求,在实现物品/属性数据库前应先阅读该脚本。
  • resource_pool.gd:用于 Resource 实例的对象池,可减少热路径中的分配开销。
  • resource_validator.gd:校验 Resource 文件,检查缺失的导出项与配置问题。

数据类型选择

文档给出三种类型的对比:

  • Resource:需要保存/读取的数据,可序列化、可存盘、支持 Inspector。
  • RefCounted:临时运行时数据,不可序列化、不可存盘、不支持 Inspector。
  • Node:场景层级实体,可序列化(场景文件)、可存盘、支持 Inspector。

实现模式

文档给出 7 种模式:

  1. 自定义 Resource 类:如 ItemData,包含 item_name、description、item_type(@export_enum)、icon、value、stackable、max_stack 等导出属性,以及 use() 方法。可在 Inspector 中右键 New Resource → ItemData,填写属性并保存为 .tres 文件。
  2. 角色属性 Resource:CharacterStats 包含 max_health、max_mana、strength、defense、speed 等导出属性,以及 current_health/current_mana(带 setter 使用 clampi 限制范围)、take_damage()、heal()、duplicate_stats() 方法。使用时在 _ready 中复制一份运行时副本,避免修改原始资源。
  3. 数据库模式(Resource 数组):ItemDatabase 含 Array[ItemData],提供 get_item_by_name()、get_items_by_type() 方法,可通过 preload 作为全局 autoload 使用。
  4. 纯运行时数据(RefCounted):如 DamageCalculation,用于不需要持久化的数据。
  5. 嵌套 Resource:如 WeaponData 继承 ItemData,包含 special_effects: Array[StatusEffect]。
  6. 带信号的 Resource:如 Inventory,定义 item_added/item_removed 信号,在 add_item/remove_item 中触发。
  7. 运行时加载 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,未提供其他语言版本。