Systems Index: Iron & Timber — The Muster

Status: Draft
Created: 2026-09-12
Last Updated: 2026-09-14 (design review: concept revised, 5 blockers resolved)
Source Concept: design/gdd/game-concept.md

Overview

Iron & Timber is a real-time strategy colony builder whose central mechanical claim is that "the economy IS the militia" — every unit of military capability traces back to a production decision, with no separate recruitment system. Mechanically, this means three normally-independent subsystems (economy, settler simulation, and combat) must share state tightly: the same settler who works a job also becomes a defender, the same smith output that becomes a tool could have become a weapon, and the same stockpile that feeds the population also arms it.

The systems below decompose into four families: Foundation (time, camera, resources — nothing game-specific yet), Economy (production chains, recipes, the dual-purpose output split, the armory), Settler Simulation (job assignment, pathfinding, role switching — the architecture research's central concern), and Threat (raiders, telegraphed danger, the muster itself, and combat resolution). The MVP's single hypothesis — does the displaced-cost muster feel weighty? — requires nearly all of these families to exist in at least a minimal form, which is why the MVP tier is large (18 systems) relative to the concept doc's short "Required for MVP" list (5 items). Short feature lists always imply more supporting systems once dependencies are made explicit; this is normal, not scope creep.

Systems Enumeration

Categories

Priority Tiers

Dependency Map

Foundation Layer (no dependencies)

• Camera & Input — a strategy game's most basic interaction layer (rotatable, zoomable three-quarter camera per the 2026-09-13 art revision); nothing else is playable without it
• Calendar/Time System — the clock everything else's timing reads from; a bottleneck system
• Resource/Stockpile System — the ledger every economic decision routes through; a bottleneck system

Core Layer (depends on foundation)

• Pathfinding & Movement — depends on: Camera & Input
• Building Placement & Construction — depends on: Camera & Input, Resource/Stockpile System
• Settler Job Assignment — depends on: Pathfinding & Movement, Resource/Stockpile System (a bottleneck system — see High-Risk Systems)

Feature Layer (depends on core)

• Recipe/Crafting System — depends on: Resource/Stockpile System, Building Placement & Construction
• Production Chains — depends on: Recipe/Crafting System, Settler Job Assignment, Resource/Stockpile System
• Dual-Purpose Output System — depends on: Recipe/Crafting System, Production Chains
• Armory / Gear Storage — depends on: Dual-Purpose Output System, Resource/Stockpile System
• Settler Role State Machine — depends on: Settler Job Assignment, Armory / Gear Storage
• Enemy/Raider AI — depends on: Pathfinding & Movement, Calendar/Time System
• Telegraphed Threat System — depends on: Calendar/Time System, Enemy/Raider AI
• Settler Needs — Food (Vertical Slice) — depends on: Production Chains, Calendar/Time System
• Save/Load (Alpha) — depends on: all stateful systems above

Presentation Layer (depends on features)

• The Muster — depends on: Settler Role State Machine, Armory / Gear Storage, Telegraphed Threat System
• Alarm/Notification System — depends on: The Muster, Telegraphed Threat System
• Combat Resolution — depends on: The Muster, Enemy/Raider AI
• Threat Forecasting UI — depends on: Telegraphed Threat System, Calendar/Time System, Camera & Input (threat is directional; the indicator must stay correct under arbitrary camera yaw — added 2026-09-14)
• Armory/HUD Readout — depends on: Armory / Gear Storage, Dual-Purpose Output System

Polish Layer (depends on everything)

• Seasonal Cycle (Vertical Slice) — depends on: Calendar/Time System, Production Chains, Telegraphed Threat System. Functionally a content/tuning layer over the Calendar (different rates, timing, and visuals per season) rather than a new mechanical system.

Recommended Design Order

[Effort estimates: S = 1 session, M = 2-3 sessions, L = 4+ sessions. A "session" is one focused design conversation producing a complete GDD.]

Circular Dependencies

One cycle, broken by tick ordering *(corrected 2026-09-14 — this section previously claimed "none found", which stopped being true the moment Core Mechanic #6 made the muster halt production)*.

The cycle: Armoury stock gates who can muster → mustering removes settlers from jobs → fewer workers means less smith output → less smith output means less armoury stock. Closed loop.

How it is broken: production resolves each tick against **last tick's roster**. Read-before-write, staged as:

• Production Chains resolve using the previous tick's worker assignment
• Settler Role State Machine applies muster/stand-down changes
• Armoury stock updates from step 1's output

The contract GDD authors must share (added 2026-09-14 per TD-PHASE-GATE): a single phase enum, defined once in the settler-simulation ADR and consumed by all three systems rather than reimplemented in each — ResolveProduction → ApplyRoleChanges → UpdateArmoury → EvaluateMuster. Two things must be pinned there before GDD #14 (The Muster) is drafted: where each system's writes sit in that order, and how it reconciles with the raid-resolution evaluation order in the concept doc's Failure State section (compute losses → remove settlers → check floor → stand down). Those are two similar-looking orderings and an author will merge them wrong if they are not reconciled in one place.

This is an enforceable invariant, not an implementation detail — any engineer building these systems in a different order will hit a bug whose cause is not local to the file they are editing. It belongs in the ADR for settler simulation.

One tight cluster worth designing together, though not circular: The Muster, Settler Role State Machine, and Armory / Gear Storage all reference each other conceptually — a settler's available role depends on armory stock, which is read by the muster, which changes settler roles. Data flows one direction per tick (Armory → Muster → Settler Role), so there is no cycle, but these three GDDs will cross-reference each other constantly. Consider drafting them in the same session even though they're listed as three separate design-order steps.

High-Risk Systems

Progress Tracker

Next Steps

• [x] Review and approve this systems enumeration
• [ ] Design MVP-tier systems first (use /design-system [system-name])
• [ ] Run /design-review on each completed GDD
• [ ] Run /gate-check pre-production when MVP systems are designed
• [ ] Validate the highest-risk systems with /vertical-slice before committing to Production
• [ ] Camera & Input: run /design-review design/gdd/camera-input.md in a fresh session — the reviewing agent must be independent of the authoring context.
• [x] Re-prototype the muster — v2 was built and independently playtested 2026-09-15. Verdict PIVOT (narrow): the muster mechanic itself is validated (forge lead time is load-bearing and produced traceable regret), but the surrounding economy has a dead zone. See prototypes/muster-v2-concept/PLAYTEST-independent.md — that file is authoritative, not REPORT.md.
• [ ] Resolve mail's purchase order before writing the muster GDD. Mail fixes the dead zone (42% → 2.5% dead turns) but every configuration tested so far has a 4.7–28pp gap between buy-spears-first and buy-mail-first. A second sink with an obviously correct order is a second sink, not a second decision. See prototypes/muster-v2-concept/TUNING-ROUND-2.md.
• [ ] Combat Resolution (#16) remains unprototyped and still carries the Bellwright competence risk.