# 0005. Namespaced content IDs

- **Status:** Accepted
- **Date:** 2026-06-27

## Context

Every single piece of registered content (blocks, items, recipes, biomes, entities, etc.) needs a perfectly stable identifier. This identifier has to be completely unambiguous across the engine, data packs, Lua mods, recipe references, and save files. First-party content and third-party content must be able to coexist without ever colliding, and these identifiers must be able to survive being written to disk and read back later.

## Decision

We identify all content using a **namespaced string** in the exact format `"namespace:id"`.

- We strictly reserve the `core:` namespace for first-party content (e.g., `"core:stone"`, `"core:iron_sword"`). Modders must choose their own short namespace (e.g., `"mymod:weird_dirt"`).
- This format is absolutely mandatory. A bare ID with no `:` is an **immediate error at registration or parse time**. We will never silently coerce it to `core:`. This exact rule applies everywhere: engine scripts, data packs, Lua mods, recipe references, and save files.
- **Charset rules:** Both the namespace and the ID must match `[a-z0-9_-]+` and have exactly one `:` sitting between them. We only allow lowercase ASCII. No uppercase letters, no Unicode, no spaces, no dots, and no slashes.
- At registration time, we intern each ID string into a small integer handle (for example, `BlockId(u32)`). All hot paths compare these integer handles for speed. We only keep the original string around for display purposes, save/load routines, and the Lua API.

Notice that the reserved namespace is deliberately called `core:` rather than naming it after the project itself. This ensures the namespace stays completely stable regardless of any future rebranding.

## Consequences

- Identifiers are highly greppable, inherently filesystem-safe, and totally unambiguous in both logs and save files.
- First-party and mod content simply cannot collide. By refusing to provide a silent default namespace, we ensure mistakes blow up immediately rather than silently corrupting data.
- We pay a tiny runtime cost at registration to intern the strings, but in exchange, we get lightning-fast handle comparisons on all hot paths.
- This strict formatting is a permanent contract. If we relaxed it later (for example, by defaulting bare IDs), we would fundamentally change the meaning of existing save files, making such a change effectively irreversible.