godot-resources

Godot リソース（4.x）

再利用可能でインスペクターから編集できる Resource オブジェクトとしてゲームデータをモデル化し、ハードコードされた値の代わりに使用して、.tres／.res として読み込み／保存します。対象は Godot 4.7 です。

使用する場面

• アイテム、ステータス、敵の設定、会話のセリフ、レベルのメタデータなどをデータとして表現するとき、インスペクターで .tres ファイルを作成するとき、またはカスタムリソースを読み込み／保存するときに使用します。

使用しない場面： ノード／シーン構造 → godot-nodes-scenes。プレイヤーの実行時の進行状況の保存（エンジンに依存しない保存形式／スロット） → save-systems。このパターンの C# 版 → godot-csharp。

基本的なワークフロー

1. class_name と @export フィールドを使用して Resource をサブクラス化します。これにより、「New Resource」ダイアログと @export 型として表示され、インスペクターで編集できるようになります。
2. ファイルシステムドックでインスタンスを .tres（テキスト形式で差分を確認しやすい）または .res（バイナリ形式で、より小さく高速）として作成します。コードを書かずに、インスペクターでフィールドを編集できます。
3. @export var data: ItemResource、または @export var loot: Array[ItemResource] のような配列を使って、ノードからリソースを参照します。
4. 実行時には、preload（定数パス）または load／ResourceLoader.load（可変パス）で読み込みます。大きなアセットにはスレッド読み込みを使用します。
5. 実行時に共有リソースを変更する前に複製します。そうしないと、それを使用しているすべてのノードも変更されます（リソースは共有参照です）。
6. 生成または編集したリソースは ResourceSaver.save で保存します。

パターン

1. カスタムデータリソース

# item.gd
extends Resource
class_name ItemResource

@export var id: StringName = &""
@export var display_name: String = "Item"
@export_multiline var description: String = ""
@export var icon: Texture2D
@export var max_stack: int = 99
@export var value: int = 0

ファイルシステムドックでこのクラスから sword.tres を作成し、インスペクターで値を設定します。

2. ノードからリソースを使用する

extends Node
@export var starting_items: Array[ItemResource] = []   # drag .tres files in the Inspector

func _ready() -> void:
    for item in starting_items:
        print("Have: %s (x%d max)" % [item.display_name, item.max_stack])

3. 共有データを変更する前に複製する

func give_unique_copy(template: ItemResource) -> ItemResource:
    # true = deep copy sub-resources too; false = shallow (shares sub-resources).
    var copy: ItemResource = template.duplicate(true)
    copy.value += 5                # mutating the copy won't touch the template .tres
    return copy

4. 実行時にリソースを保存して読み込む

func save_config(cfg: Resource) -> void:
    ResourceSaver.save(cfg, "user://config.tres")   # user:// = writable app data dir

func load_config() -> Resource:
    if ResourceLoader.exists("user://config.tres"):
        return ResourceLoader.load("user://config.tres")
    return null

注意点

• リソースは参照によって共有されます。 多数のノードに割り当てられた同じ .tres は、すべて同一のオブジェクトです。変更すると、すべてのノードに反映され（ファイルを再保存した場合はファイルも変更され）ます。インスタンスごとの状態には duplicate(true) を呼び出してください。
• エディターからインスタンス化するには class_name が必要です。 指定しない場合、このクラスは「New Resource」ダイアログや @export 型として表示されません。
• エクスポートしたゲームでは res:// は読み取り専用です。 実行時データは res:// ではなく user:// に書き込みます。res:// への ResourceSaver.save はエディターでのみ機能します。
• Resource にノードを格納してもシリアライズされません。 リソースが保持するのはデータであり、実行中のシーンノードではありません。ノードインスタンスではなく、PackedScene を使ってシーンを参照してください。
• 循環するリソース参照（A が B を保持し、B が A を保持する）は、正しく保存／読み込みできないことがあります。データグラフは非循環にするか、ID／ルックアップを使用してください。
• preload と load の違い。 preload には定数パスが必要で、スクリプトと一緒に読み込まれます。load は実行時に可変パスを受け取ります。ファイルが見つからない場合のエラーを避けるため、load の前に ResourceLoader.exists() を使用してください。
• 秘密情報を .tres に入れないでください。 エクスポート内にプレーンテキストで含まれます。

参考資料

• スレッド／バックグラウンド読み込み（load_threaded_request）、カスタム設定を使う @tool リソース、カスタム ResourceFormatLoader／Saver、シーンにローカルなリソース、リソース UID については、references/resource-patterns.md を参照してください。

関連スキル

• godot-gdscript — リソースフィールドの定義に使用する @export アノテーション。
• godot-nodes-scenes — シーンのインスタンス化とリソースデータの共有。
• save-systems — 実行時の進行状況の永続化（静的データとは別）。
• unity-scriptableobjects — Unity における同等のデータアセットパターン。