The Settlement Loop
Settlement play is organized around an active Settlement HUD and a daily tick. The HUD is the single source of truth for the settlement currently relevant to the player. A Location links to its HUD; during travel, the origin remains active until arrival is recorded. Builders should never make a scene depend on a settlement inferred only from narrative text.
The daily tick
A new day processes one complete, idempotent sequence:
- resolve the active settlement and travel context;
- consume Food and Water by population;
- apply income from completed Built Structures once;
- advance construction and create completed structures;
- advance Research and apply each completed effect once;
- update Map Area states;
- process Threats and Guests;
- apply demographic changes and recalculate morale and safety;
- check rank requirements without choosing the reward;
- record the day's important notice and history.
The tick must be safe to retry. Stable event keys, processedEvents, appliedEffects, lastProcessedDay, and lastIncomeAppliedDay prevent duplicate income, rewards, unlocks, or consequences. Do not advance the last-processed marker after a partial failure.
Economy and construction
Use a small, explicit resource vocabulary: Food, Water, Wood, Stone, Gold, Tools, Herbs, Ore, Mana, and Faith. A resource transaction changes resources only on the active HUD. A Blueprint defines costs, build time, upkeep, income, housing, requirements, area status, and optional adjacency or signature bonuses. Starting construction immediately records its paid costs and creates one queue entry. Pausing or damaging a project does not charge it again. Completion requires a Built Structure; the Blueprint reference alone is never a completed building.
Income must come from structured Built Structure data, not from a description or a prose summary. Adjacency effects and research effects are applied once and recorded by stable keys. A new structure should have a clear purpose: solve a shortage, open a choice, change risk, support a population, or express the settlement's identity.
Research, areas, and resources
Every Research entry must do at least one useful thing: unlock a Blueprint, grant a defined effect, or connect to a Quest. Research progress belongs to the HUD; the Research file defines the duration, costs, requirements, effects, and unlocks.
Map Areas describe permanent geography. The HUD stores mutable status such as Hidden, Known, Discovered, Accessible, Cleared, Developed, Blocked, or Contested. Resource Nodes are discovered in areas and produce resources only when their conditions, workers, tools, and remaining supply allow it. Never turn a resource node directly into a second stockpile.
Rank and population
Population, housing, infrastructure, research, safety, and story objectives can qualify a settlement for its next rank. Eligibility is not completion. Present the required choice and keep the offer pending until the player confirms the settlement's name, identity, government, districts, defense philosophy, rewards, or other consequences. Visitors do not increase population or housing. Recruitment does, and only after explicit player choice, suitable housing, a reason to stay, safety, and the Guest's agreement.
Build the loop so every gain creates a new pressure: more residents consume more supplies; more buildings need workers; improved safety may attract attention; research opens possibilities that change future costs. The settlement should feel like a living system rather than a checklist.