Data packs & resource packs

Two distinct, orthogonal systems. They are kept separate and are not collapsed into one "pack" concept. The decision that data packs register through the modding API rather than a parallel path is recorded in ADR-0007.

Resource packs

Client-side asset overlays: textures, sounds, models, fonts, language files. No logic.

A pack is a directory tree mirroring /assets/ that overrides files by path. The renderer/asset loader resolves logical asset IDs against a stack of pack roots (base game → installed packs by priority) and the topmost hit wins. The server has no involvement. Ownership sits with the asset pipeline (in client, or a sibling assets crate if it grows). Pack authors never touch Lua.

Data packs

Declarative content definitions in JSON (or TOML/RON, TBD): blocks, items, recipes, loot tables, biomes, tags.

No parallel registration system is built. The loader reads the declarative files and calls the same Lua API the engine and Lua mods use. One source of truth:

data/blocks/stone.json  →  loader  →  blocks.register{ id = "stone", ... }

The loader belongs in scripting (or a sibling crate if it grows). Engine first-party content may use either JSON or Lua, whichever fits. Every data-pack schema is a stable contract, the same as the Lua API, version it deliberately.

Canonical load order

Later layers override earlier ones:

base game (assets/scripts + assets/data)
  → data packs           (declarative content add/override)
  → Lua mods             (full API access)
  → resource packs       (client-only, asset overlay, always last so visuals win)

Repo layout

/assets/
  data/      # base-game declarative content
    blocks/  items/  recipes/  ...
  scripts/   # base-game Lua (behavior)
  textures/  models/  sounds/  icons/  shaders/   # base-game assets

User-data layout

Runtime, resolved via the directories / dirs crate:

<user-data>/
  mods/            # Lua mods
  datapacks/       # JSON content packs
  resourcepacks/   # asset overlays (client only)

2.1 KiB Raw Blame History