magicciv/public/resources/items/README.md

Items

Items are equippable gear, consumables, tools, and unique relics. They live in the shared resources/ library so any game pack can subscribe to them, but the design framing in this README is anchored to Episode 1: Age of Dwarves, where items carry the entire "smithcraft" identity of the dwarven species in a magic-less world.

Files

• items.schema.json — JSON Schema all item files validate against (extends ../base.schema.json).
• item_categories.json — display labels for the four categories (weapon, armor, consumable, tool) and three charge modes (permanent, combat, use).
• <item_id>.json — one file per item, like iron_axe.json, dwarven_plate.json. The file's id field must match the filename (snake_case).

Why items exist (Episode 1 framing)

Age of Dwarves has no magic. Items are what fills that hole. Smithcraft is the dwarven dimension — the way mundanes project power, the way the player feels the personality of the species. If the dwarves of this episode are not memorable smiths, the episode has no flavor pillar. So items must matter, must be visible, and must be rare enough that each one has a name a player remembers.

This document covers Episode 1 only. Items in Kzzkyt / Elf / Magic-World episodes will be designed when those episodes are designed; their flavor will differ and their mechanics may diverge. Do not generalize this design into "the item system" — it is "the dwarven smithcraft system" and should be treated as such until a second episode forces a generalization.

Pillars

1. Rare and named, not loadout-checklist. Master of Magic artifacts on heroes is the inspiration. Civ5 Great Works is a distant cousin. Diablo and Total War equipment are explicitly not the model.
2. Soft cap ~10–20 finished items per civ at peak. Each one is an event. The cap is enforced by acquisition pacing (smithy throughput, apex-creature scarcity), not a hard counter.
3. Items equip on unit squads, reusing the existing equipped_items field on unit.gd. Squads are the model the engine already has — items do not introduce hero entities.
4. No inventory sub-game. No recipe discovery. No 12-stat tooltips. No loadout screen. The Treasury is a single tab.
5. Crafting is "pull, not push" — queued like production, not assembled like recipes.

Acquisition: dual track

Track A — Building production queues (commons)

Unlike Civ5 (one production queue per city), this engine's city management interface supports per-building production queues — each producer building has its own independent queue. Items slot into the queue of whichever building actually crafts them: a Smithy queues weapons and armor, a Tannery queues hide goods, an Alchemist's Bench queues consumables. A single city can be crafting an axe, a shield, and a healing draught simultaneously in three different buildings.

Each crafted item declares in its production block:

• building — the producer building the item slots into (smithy, forge, alchemist_bench, mithril_forge, …).
• secondary_building (optional) — a co-requisite building that must also exist in the same city. This is how crafting interactions are expressed without a recipe sub-game (e.g., Master Hammer requires Mithril Forge and Runesmith's Hall).
• hammer_cost — production charged against the producing building's throughput.
• materials — stockpile inputs (ore from mines, hide/bone/ivory from fauna kills).
• requires_tech — same gating model as units.

There is no recipe discovery and no combinatorial blueprint search. Items are unlocked by tech, period. The interesting decision is which item to queue given finite stockpiles, not figuring out what combines with what.

Stockpile materials come from two places:

• Mine deposits (existing system) — ore, stone, coal.
• Fauna part drops — kills contribute hide, bone, ivory, shell, sinew into the civ stockpile. The garden snail does not drop a finished snail-shell-shield; it contributes snail_shell × 1 to the stockpile, and the Smithy can later queue a shield that requires shells.

The Taxidermist building (stubbed in ../buildings/ecology_buildings.json) is the throughput multiplier for fauna parts: it converts raw kills into more usable material units, and unlocks the rarer parts (e.g., direwolf alpha pelts).

Track B — Apex relics (uniques)

Named apex creatures (per ROADMAP M3: "multi-turn engagement, unique relics") drop finished, named, unique items directly on death. No crafting step. These items are pre-authored, hand-named, and account for the upper end of the civ's ~10–20 item cap. They are the trophies the player tells stories about. See direwolf_alpha_pelt.json for the exemplar.

Apex relics are not balanced against smithy items on stat-budget alone — they have characterful effects (a unique combat keyword, a small aura, a single special charge) that smithy items deliberately do not. This keeps Track B narratively distinct from Track A.

Tiers (T1–T10)

Items use the universal T1–T10 scale that the rest of the project uses for content tiers. Tier is the dominant balance dimension and the primary way the game communicates "how powerful is this thing." The same tier system already governs units, spells, buildings, and ecological maturity.

Tier band	Meaning	Producer buildings	Source
T1–T2	Basic dwarven gear (iron, leather)	Smithy, Tannery	Track A only
T3–T4	Refined gear (steel, hardened hide)	Forge, Hardening Pit	Track A; rare apex T3
T5–T6	Master craft (mithril, dragonhide)	Mithril Forge, Runesmith's Hall	Track A (rare materials); apex T5–T6
T7–T8	Legendary	(Track B only — apex relics)	Track B
T9–T10	Mythic, named, civilization-defining	(Track B only — apex relics)	Track B

Track A (crafted) tops out around T6 in Episode 1. Track B (apex relics) is the only path to T7+. This is what makes apex hunting matter: nothing in your city queues will ever produce a T9 item — you have to go kill the named beast that wears it.

Tier interacts directly with the building requirement chain: each tier band's items demand their producer building be of matching tier or higher. The player upgrades their crafting capacity by upgrading buildings, not by unlocking abstract crafting levels.

Categories and charge model

Category	Typical charge mode	Episode 1 examples
weapon	permanent	iron axe, mithril hammer, apex-relic blade
armor	permanent	scale mail, dwarven plate, shell shield
consumable	use	healing draught, throwing oil, smoke flask
tool	combat or permanent	climbing spikes (terrain bonus), grappling hook (siege bonus)

• permanent — destroyed only on unit death, or via a deliberate durability event (rare, narrative-driven, never turn-counter erosion).
• combat — consumed inside a battle, refreshes between battles.
• use — gone when spent.

Episode 1 has no wands (no magic). Wand-style spell-charge items belong to Episode 3 and are out of scope.

Stat surface

Items have at most three stat lines. This is a hard cap enforced in items.schema.json (stats.maxItems = 3), not a soft suggestion. The unit panel has limited room and the goal is comprehension, not optimization.

The existing _get_item_stat() helper on unit.gd already destructures bonus fields — the data side is just authoring the JSON.

Ground loot and decay

The drop_all_loot() and process_loot_decay() stubs in item_system.gd:

• When a unit dies in the field, its non-permanent equipped items (consumables, charged tools) drop on the tile as a ground_loot entity.
• Ground loot decays after N turns (proposed: 5) and disappears. Forces decisions, prevents post-war hoarding sweeps.
• Permanent items (weapons, armor) on a dead unit are destroyed with the unit by default. Lore: dwarven gear is buried with its bearer. Also avoids stat creep from battlefield scavenging.

Apex relics never drop on the ground — they go directly into the killer's civ Treasury, with a notification.

UI surface

Three touch-points only. There is no inventory screen.

1. Unit panel — shows currently equipped items with their ≤3 stat lines. Clicking an item slot opens a single equip modal.
2. Civ Treasury tab — one screen, two columns: Finished items (with which squad they're on, or "unequipped") and Stockpiled materials (counts).
3. Crafting completion modal — single popup: "Mithril Hammer forged. Equip on which squad?" with a short list of eligible squads and a "Store in Treasury" option. No deeper screen.

Pacing targets (balance reference, not contracts)

• Early game (turns 1–80): 0–3 finished items per civ. Mostly basic gear, no apex relics yet.
• Mid game (turns 80–200): 4–10 items. First apex relics start appearing as players push into wild biomes.
• Late game (turns 200+): 10–20 items soft cap. Each is named and remembered.

If live numbers exceed 20 in playtests, throttle Smithy throughput before throttling apex spawns — apex relics are the fun track.

Reference points in code

• src/game/engine/src/modules/management/item_system.gd — charge tracking, loot decay/drop stubs.
• src/game/engine/src/entities/unit.gd — equipped_items field and _get_item_stat() bonus helpers.
• public/resources/buildings/ecology_buildings.json — Hunting Lodge / Taxidermist (material throughput).