Housing System

Architecture overview and key file map for the housing subsystem.

Overview

The housing subsystem handles all 20 tiers of residential buildings — from Crude Hut to Palatial Estate. It spans four distinct layers that need to stay in sync:

Config layer (src/scripts/houses.js) — defines all per-tier thresholds, risk values, and goods requirements for every difficulty level.
Data layer (building_house.h, building_house_model.h) — C++ structs that mirror the config and the per-instance runtime state.
Logic layer (building_house.cpp) — 20 tier classes, each implementing evolution, devolution, merge, and split logic.
Integration layer (city/city_houses.cpp, figure/service.cpp) — connects walkers to houses, aggregates service scores, drives the monthly update cycle.

Key Files

File	Purpose
`src/building/building_house.h`	Base class `building_house`, `runtime_data_t` definition, 20 tier class declarations.
`src/building/building_house.cpp`	Evolution logic for all 20 tiers — `evolve()`, `check_requirements()`, `merge()`, `split()`, `decay_services()`, food/goods consumption.
`src/building/building_house_model.h`	`model_house_t` struct — the C++ mirror of a single `model{}` block from `houses.js`. All thresholds, divisors, risk values.
`src/building/building_house_demands.h`	`house_demands` — per-update accumulator tracking which services/goods are being demanded by houses that cannot yet evolve.
`src/city/city_houses.cpp`	Monthly housing update driver: calls `evolve()` on every house, runs `house_service_calculate_culture_aggregates()`, updates city-wide prosperity and population counts.
`src/figure/service.cpp`	Service walker callbacks — how figures of type Teacher, Priest, Physician, etc. register their presence with nearby houses.
`src/scripts/houses.js`	Canonical source of truth for all housing data. Every threshold, multiplier, and risk value lives here. Changes here affect gameplay immediately without a recompile.

Data Flow

The housing update runs once per month (game time). The sequence is:

city::house_process_evolve()          ← monthly driver in city_houses.cpp
  │
  ├─ house_service_calculate_culture_aggregates()
  │    for each house:
  │      entertainment = weighted sum of juggler/musician/dancer/senet coverage
  │      education     = 0..3 based on school / library / academy flags
  │      health        = 0..2 based on apothecary / physician flags
  │      num_gods      = count of distinct temples with walker coverage
  │
  └─ for each house:
       house->evolve(&demands)         ← virtual, implemented per tier
         │
         ├─ merge()                    ← attempt 1×1 → 2×2 merge
         ├─ check_requirements()       ← compare state vs model thresholds
         │    → e_house_progress:  EVOLVE / NONE / DECAY
         └─ change_to() / expand_to_*() / split()

Subsystem Pages

Class Hierarchy Base class, 20 tier classes, runtime_data_t fields.

Evolution Algorithm How houses decide to evolve, stay, or devolve each month.

Service Coverage Walker registration, decay, and aggregate computation.

Config Format Annotated houses.js schema — every field explained.

Adding a Tier Step-by-step guide for adding or modifying a housing tier.