A Godot 4 plugin for managing and querying collections of resources, with a spreadsheet-like editor and a lightweight runtime API.

Overview

YARD builds on Godot's resource system. The editor tab lets you create and manage registries: collections of resources backed by a small .tres file that stores only IDs, not the resources themselves. You control if and when resources are loaded.

Features

• 📊 Browse and edit resources as entries in a spreadsheet-like table, right in the editor
• 🏷 Reference resources by stable string IDs instead of file paths or autoloads
• 🔒 Restrict entries to a specific Resource subclass
• 🔄 Keep a registry in sync with a directory as files appear or disappear
• 🔍 Filter entries by property value at runtime, without loading a single resource
• 🔽 Pick a registry entry from an inspector dropdown using @export_custom in your scripts

Installation

1. Copy the addons/yard folder into your project's addons/ directory
2. Enable the plugin in Project > Project Settings > Plugins

Usage

Creating a registry

Open the Registry tab in the editor, click File > New Registry, and configure:

• Class restriction: only resources of this class (or its subclasses) will be accepted
• Scan directory: the registry will stay in sync with resource files in this folder
• Indexed properties: property names to bake into the index for runtime filtering

Adding entries

If a scan directory is set, entries are managed automatically. Otherwise, you can add entries manually in two ways:

• Drag and drop resources from the FileSystem dock into the registry table. They must match the class restriction.
• Create a new resource on the spot using the resource picker at the bottom of the table. When you press Add Entry, it creates and saves the file, then immediately registers it.

Inspector dropdown with @export_custom

Registry.PROPERTY_HINT_CUSTOM enables a dropdown in the inspector for any StringName, String, Array[StringName], or Array[String] property, populated with the string IDs of a given registry.

@export_custom(Registry.PROPERTY_HINT_CUSTOM, "res://data/item_registry.tres") var item: StringName

Loading entries at runtime

const ENEMIES: Registry = preload("res://data/enemy_registry.tres")

# Load a single entry by string ID
var skeleton: Resource = ENEMIES.load_entry(&"skeleton")

# Load all entries at once (blocking)
var all_enemies: Dictionary[StringName, Resource] = ENEMIES.load_all_blocking()

# Load all entries via background threads
var tracker: RegistryLoadTracker = ENEMIES.load_all_threaded_request()

To look up the string ID of an already-loaded resource:

var string_id := ENEMIES.get_string_id_of(loaded_resource)

Querying entries through the property index

Set up indexed properties in Registry Settings and press Reindex to bake the index. At runtime, queries run without loading any resource.

# Single property (exact value or predicate)
var legendaries := WEAPONS.filter(&"rarity", Rarity.LEGENDARY)
var high_level  := WEAPONS.filter(&"level", func(v): return v >= 10)

# AND query across multiple properties (exact values or predicates)
var forest_without_boss := ROOMS.where({
    &"biome": Biome.FOREST,
    &"tier": func(t): return t != RoomData.Tier.Boss,
})

Properties support dot notation for nested resources: &"weapon.rarity" resolves the rarity property of the subresource stored in weapon.

The full Registry API is documented in the in-editor class reference: Help > Search Help > Registry.

Contributing

Contributions are welcome. See CONTRIBUTING.md before opening a pull request.

For major changes, open an issue first to discuss what you have in mind.

AI Policy

The YARD codebase may contain code generated with the help of LLMs, as contributors aren't required to disclose their use of AI tools. Every change is reviewed on its own merits regardless of how it was produced.

However, AI-generated text is not allowed in PR descriptions or issue bodies. Contributors must write these themselves, as reviewers should not be expected to spend time reviewing text that the contributor did not write.

If, for legal or ethical reasons, you can't use software that may contain AI-generated content, please refrain from using YARD or integrating it into your team's workflow.

This policy may be revised as the volume of PRs requiring review increases.

License

MIT