A Godot 4 plugin for managing and querying collections of resources through a dedicated editor interface and runtime API.

Overview

YARD has two complementary aspects:

A table-based resource editor. The YARD editor tab lets you create and manage registries: catalogues of resources grouped by class. Each registry provides a spreadsheet-like view of your resources and their properties.

A lightweight runtime API. At runtime, a Registry is just a small .tres file holding UIDs and string IDs. It does not load the resources it references. _You_ control when loading happens, and how.

Features

• 🏷 Reference resources by stable, human-readable string IDs instead of file paths or UIDs lying around in some autoload
• 🔒 Restrict a registry to a specific class — only matching resources can be added
• 🔄 Sync a registry from a directory — entries are added and removed automatically as resource files appear or disappear, recursively or not
• 🥧 Bake a property index in the editor for zero-cost runtime queries by resource property values
• 📦 Load entries individually, all at once (blocking), or asynchronously via threaded loading
• ⚡ No runtime overhead beyond what you explicitly request, all expensive operations happen in the editor

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

If you didn't specify a scan directory, you can add entries manually by dragging and dropping resources from the FileSystem dock into the registry table, or use the resource picker at the bottom.

Loading an entry

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

func _on_fight_started() -> void:
    var skeleton: Enemy = ENEMIES.load_entry(&"skeleton")

Loading all entries

# Blocking
var all_enemies := ENEMIES.load_all_blocking()

# Threaded
var tracker := ENEMIES.load_all_threaded_request()

Querying the index

The property index can be baked while in the editor. At runtime, queries run without loading any resource.

# All entries where rarity == LEGENDARY
var legendaries := WEAPONS.filter_by_value(&"rarity", Rarity.LEGENDARY)

# All entries where level >= 10
var high_level := WEAPONS.filter_by(&"level", func(v): return v >= 10)

# AND query across multiple properties
var legendary_swords := WEAPONS.filter_by_values({
    &"rarity": Rarity.LEGENDARY,
    &"type": &"sword",
})

API Reference

Full API documentation for Registry is available in the in-editor class reference.

Lookup

Loading

Filtering

Filtering methods require the relevant properties to have been indexed in the editor.

How the property index work

The index is simply a nested dictionary stored inside the registry .tres file :

_property_index = {
    &"rarity": {
        Rarity.LEGENDARY: { &"excalibur": true, &"mjolnir": true },
        Rarity.COMMON: { &"stick": true },
    }
    &"level": {
        1: { &"stick": true },
        10: { &"excalibur": true },
        12: { &"mjolnir": true },
    }
}

Contributing

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

License

MIT