Data.gd – JSON‑Driven Content Loader for Godot 4

Data.gd is an autoload singleton that

• Recursively discovers and loads JSON files under res://<data_path> and user://<data_path>.

• Validates each file against versioned schemas.

• Indexes the data for fast look‑ups by author, package, id, tag, type, or schema.

• Exposes a clean API for fetching data or applying it to in‑game objects.

Target engine:

Godot 4.1+

License:

MIT

Quick Start

1. In Project Settings → Plugins, set **data_path**
   (default value: ``data``).
2. Put schemas in   ``res://<data_path>/_schema/``
3. Put JSON content in ``res://<data_path>/…`` (any depth)

Example usage:

# Get all entries tagged "forest"
var forest_things: Array = Data.fetch_by_tag("forest")

# Get specific unique entry by author, package, and id
var cure_all_ability: Dictionary = Data.fetch_by_id("spells_developer.magic_mod.cure_all")

# Apply JSON data to an existing object
var sword_data: Dictionary = Data.fetch_by_id("core.weapons.broadsword")
Data.apply_json($Sword, sword_data)

Directory Layout

res://data/                 # data path & schema created on plugin install
│
├─ _schema/                 # One .json per schema (each schema may hold many versions)
│   └─ core.json
│
└─ items/
    └─ weapons/
        └─ broadsword.json

user://data/…               # Same structure, created on first run

Key Concepts

• Schema – A JSON file whose top‑level keys are semantic versions; each version maps required keys to typed default values.

• schema_register – All loaded schemas are stored here: schema_register[schema_id][version] → dict.

• Several data registers keep objects accessible by id, author, package, tag, type, or schema.

Public API (cheat‑sheet)

Method	Returns	Notes
fetch_by_id(id)	Dict	id format author.package.name
fetch_by_author(author)	Array	–
fetch_by_package(package)	Array	–
fetch_by_schema(schema_id)	Array	–
fetch_by_type(type)	Array	–
fetch_by_tag(tag)	Array	–
get_available_schema_versions(id)	Array	Registered versions
get_available_tags()	Array	–
get_available_types()	Array	–
reload_data()	–	Clears and rescans disk
apply_json(obj, json_dict)	–	Copies validated data → obj

Extending the System

1. Write a schema

   { "1.0": { "hp": 0, "damage": 0, "sprite": "" } }
   

2. Save it as res://data/_schema/creature.json.

3. Author data

   {
     "schema_id":    "creature",
     "schema_version": "1.0",
     "id_author":    "core",
     "id_package":   "monsters",
     "id_name":      "slime",
     "type":         "npc",
     "tags":         ["dungeon", "goo"],
     "data":         { "hp": 10, "damage": 2, "sprite": "slime.png" }
   }
   

4. Fetch it

   var slime = Data.fetch_by_id("core.monsters.slime")
   

Credits

Created by DanDoesAThing - https://github.com/newwby/