TheriapolisV3/theriapolis-rpg-implementation-plan-phase2-3.md

# Theriapolis — Implementation Plan: Phase 2 + Phase 3
### Handoff Document for Sonnet
### Version 1.0 — 2026-04-12

---

## 0. Purpose

This document is the agreed implementation plan for **Phase 2 (Hydrology + Linear
Features)** and **Phase 3 (Settlements + Infrastructure)** of Theriapolis. It
continues from the Phase 0+1 work that is now complete and accepted.

Sonnet: **read this entire file before writing code.** Also re-read these files
from the prior plan, as they remain authoritative:

- `theriapolis-rpg-implementation-plan.md` — the original architectural spec
  (Sections 5, 6, 12 are still binding)
- `theriapolis-rpg-procgen.md` — world generation design (Layers 2–4, 5–7)
- `theriapolis-rpg-procgen-addendum-a.md` — border organics AND **linear feature
  exclusion rules** (Issue 2 is the critical new constraint)
- `theriapolis-rpg-questline.md` — narrative anchor requirements
- `theriapolis-rpg-clades.md` — clade sizes, affinities, demographics
- `theriapolis-rpg-reputation.md` — faction definitions and influence

**All hard rules from the original plan (Section 12) remain in force.** This
document adds no new hard rules — it only extends scope.

---

## 1. What Phase 0+1 Built (Your Foundation)

You are building on top of a working, tested codebase:

- **9-stage worldgen pipeline** (`WorldGenerator.BuildPipeline()`): SeedInit,
  MacroTemplateLoad, ElevationGen, MoistureGen, TemperatureGen,
  CoastalFeatureGen, BorderDistortion, WaterBodyClamp, BiomeAssign
- **`WorldState`** with `WorldTile[1024,1024]` — elevation, moisture,
  temperature, BiomeId, FeatureFlags, macro cell coordinates all populated
- **`SeededRng`** with 13 named sub-streams (RNG_HYDRO, RNG_SETTLE, RNG_ROAD,
  RNG_RAIL, RNG_FACTION, RNG_POI are unused and waiting for you)
- **`FeatureFlags`** bitmask with HasRiver, RiverAdjacent, HasRoad, HasRail,
  RailroadAdjacent, IsSettlement, IsPoi all defined but unset
- **`Camera2D`**, `WorldMapRenderer`, `TileAtlas`, screen stack, input manager
- **Macro grid** with per-cell BiomeType, Development, Covenant,
  CladeAffinities, elevation/moisture constraints
- **Tests**: determinism, macro constraints, border organics, biome coverage,
  architecture (Core has no MonoGame dependency)
- **Tools**: `worldgen-dump` exports PNG of biome map

You do NOT need to modify any Phase 0+1 stage code. Build on top of it.

---

## 2. What This Phase Delivers

When Phase 2+3 is complete, `dotnet run --project Theriapolis.Desktop` shows:

1. A world map with **rivers** (blue polylines, varying width by classification)
   flowing from mountains to sea, with natural meanders.
2. **Lakes** at drainage collection points, visible as water bodies.
3. **Settlement icons** at correct tiers, correctly constrained (narrative
   anchors at valid locations, general settlements by habitability score).
4. **Rail lines** (dark gray polylines) connecting the capital to Tier 2 cities.
5. **Roads** (brown polylines) connecting Tier 1–3 settlements, routed around
   rivers and rail per Addendum A §2 exclusion rules.
6. **Settlement labels** visible above a zoom threshold.
7. All of the above visible at any zoom level thanks to the shared polyline
   coordinate space (world-pixel space).

The `worldgen-dump` tool produces a PNG showing all of this overlaid on the
biome map.

---

## 3. New Constants

Add these to `Constants.cs` alongside the existing constants. Do not modify
existing constants.

```csharp
// ── Phase 2: Hydrology ──────────────────────────────────────────────────
public const int   RIVER_MIN_FLOW_ACCUM    = 80;     // tiles of upstream catchment to become a stream
public const int   RIVER_MAJOR_THRESHOLD   = 400;    // flow accumulation for "major river"
public const int   RIVER_MODERATE_THRESHOLD = 180;   // flow accumulation for "river" (vs stream)
public const float RIVER_CARVE_DEPTH       = 0.02f;  // elevation reduction along river paths
public const int   LAKE_MIN_AREA           = 12;     // tiles; smaller basins stay dry
public const float MEANDER_AMP_FLAT        = 5f;     // max world-pixel lateral offset on plains
public const float MEANDER_AMP_MOUNTAIN    = 1.5f;   // max world-pixel lateral offset in mountains
public const float MEANDER_FREQ            = 0.08f;  // noise frequency for meander offset
public const int   SPLINE_SUBDIVISIONS     = 4;      // Catmull-Rom subdivisions per control point
public const float RDP_TOLERANCE           = 2.0f;   // Ramer-Douglas-Peucker LOD tolerance (world px)

// ── Phase 3: Settlements ────────────────────────────────────────────────
public const int   SETTLE_TIER1_COUNT      = 1;      // capitals
public const int   SETTLE_TIER2_MIN        = 4;
public const int   SETTLE_TIER2_MAX        = 6;
public const int   SETTLE_TIER3_MIN        = 15;
public const int   SETTLE_TIER3_MAX        = 25;
public const int   SETTLE_TIER4_MIN        = 40;
public const int   SETTLE_TIER4_MAX        = 80;
public const int   SETTLE_TIER5_MIN        = 100;
public const int   SETTLE_TIER5_MAX        = 200;

public const int   SETTLE_MIN_DIST_TIER1   = 120;    // min tile distance between same/higher tier
public const int   SETTLE_MIN_DIST_TIER2   = 60;
public const int   SETTLE_MIN_DIST_TIER3   = 20;
public const int   SETTLE_MIN_DIST_TIER4   = 8;
public const int   SETTLE_MIN_DIST_TIER5   = 5;

public const float ANCHOR_MIN_DIST         = 80f;    // min tile distance between narrative anchors

// ── Phase 3: Infrastructure ─────────────────────────────────────────────
public const float ROAD_SHORTCUT_FRACTION  = 0.30f;  // fraction of MST edges to add as shortcuts
public const float BRIDGE_COST             = 50f;    // A* cost to cross a river
public const float CROSSING_COST           = 20f;    // A* cost for road-rail crossing
public const float SETBACK_COST_SCALE      = 8f;     // multiplier for river/rail proximity penalty
public const int   SETBACK_DISTANCE        = 4;      // ideal tile separation from parallel features
public const float RAIL_BRIDGE_COST        = 80f;    // rail crossing a river is expensive

// ── Phase 3: Factions ───────────────────────────────────────────────────
public const float FACTION_INFLUENCE_RADIUS = 60f;    // tiles; falloff radius from seed points
public const float FACTION_DECAY_RATE       = 0.015f; // per-tile decay

// ── Phase 3: PoIs ───────────────────────────────────────────────────────
public const int   POI_MIN_DIST_FROM_SETTLE = 6;     // tiles from any settlement
public const int   POI_MIN_DIST_FROM_POI    = 4;     // tiles from other PoIs

// ── Phase 2+3: RNG sub-streams (new, non-colliding) ────────────────────
public const ulong RNG_LAKE        = 0x1A4EUL;
public const ulong RNG_MEANDER     = 0xE41DE7UL;
public const ulong RNG_HABITAT     = 0x4AB17A7UL;
public const ulong RNG_ANCHOR      = 0xA1C407UL;
public const ulong RNG_SETTLE_ATTR = 0x5A774UL;
public const ulong RNG_TRADE       = 0x74ADE5UL;
public const ulong RNG_ENCOUNTER   = 0xE1C0U17UL;
```

---

## 4. New Data Structures

### 4.1 Polyline (the backbone of this phase)

Create `Theriapolis.Core/World/Polylines/Polyline.cs`:

```csharp
/// <summary>
/// A polyline in world-pixel space (0..32768 on each axis).
/// Source of truth for rivers, roads, and rail. Per-tile flags are derived.
/// </summary>
public sealed class Polyline
{
    public PolylineType Type { get; init; }         // River, Road, Rail
    public int          Id   { get; init; }         // unique per type
    public List<Vec2>   Points { get; }             // control points in world-pixel space
    public List<Vec2>?  SimplifiedPoints { get; set; } // RDP-reduced for LOD
    public float        Width { get; set; }         // world-pixel width for rendering

    // River-specific
    public RiverClass   RiverClassification { get; set; }
    public int          FlowAccumulation    { get; set; }

    // Road-specific
    public RoadType     RoadClassification  { get; set; }

    // Source/destination settlement IDs (for roads, rail)
    public int          FromSettlementId    { get; set; } = -1;
    public int          ToSettlementId      { get; set; } = -1;
}

public enum PolylineType : byte { River, Road, Rail }
public enum RiverClass   : byte { Stream, River, MajorRiver }
public enum RoadType     : byte { Footpath, DirtRoad, PostRoad, Highway }
```

Use a plain `Vec2` struct (two floats) instead of pulling in `System.Numerics`
— Core has no external dependencies. Create `Theriapolis.Core/Util/Vec2.cs`:

```csharp
public readonly struct Vec2
{
    public readonly float X, Y;
    public Vec2(float x, float y) { X = x; Y = y; }
    public static Vec2 operator +(Vec2 a, Vec2 b) => new(a.X + b.X, a.Y + b.Y);
    public static Vec2 operator -(Vec2 a, Vec2 b) => new(a.X - b.X, a.Y - b.Y);
    public static Vec2 operator *(Vec2 a, float s) => new(a.X * s, a.Y * s);
    public float LengthSquared => X * X + Y * Y;
    public float Length => MathF.Sqrt(LengthSquared);
    public Vec2 Normalized => this * (1f / Length);
    public Vec2 Perp => new(-Y, X);      // 90-degree CCW rotation
    public static float Dot(Vec2 a, Vec2 b) => a.X * b.X + a.Y * b.Y;
    public static float DistSq(Vec2 a, Vec2 b) => (a - b).LengthSquared;
}
```

### 4.2 Settlement

Create `Theriapolis.Core/World/Settlement.cs`:

```csharp
public sealed class Settlement
{
    public int           Id          { get; init; }
    public string        Name        { get; set; } = "";
    public int           Tier        { get; init; }      // 1–5
    public int           TileX       { get; init; }      // world tile coords
    public int           TileY       { get; init; }
    public float         WorldPixelX => TileX * C.WORLD_TILE_PIXELS + C.WORLD_TILE_PIXELS / 2f;
    public float         WorldPixelY => TileY * C.WORLD_TILE_PIXELS + C.WORLD_TILE_PIXELS / 2f;

    // Narrative anchor tag (null for non-anchor settlements)
    public NarrativeAnchor? Anchor  { get; init; }

    // Generated attributes (Phase 3, stage 14)
    public SettlementEconomy    Economy     { get; set; }
    public SettlementGovernance Governance  { get; set; }
    public string[]             CladeRatios { get; set; } = Array.Empty<string>();
    public float                WealthLevel { get; set; }
    public int                  Population  { get; set; }
    public float                HybridPct   { get; set; }
    public string               ScentProfile { get; set; } = "";

    // Derived after road/rail gen
    public bool HasRailStation { get; set; }
    public bool IsOnRiver      { get; set; }
}

public enum NarrativeAnchor : byte
{
    Millhaven, Thornfield, FortDustwall, TheTangles,
    SanctumFidelis, Heartstone
}

public enum SettlementEconomy : byte
{
    Farming, Mining, Manufacturing, Trade, Military, Fishing
}

public enum SettlementGovernance : byte
{
    Council, Mayor, MilitaryCommandant, ClanElder, Corporate, Anarchic
}
```

### 4.3 Faction Influence

Create `Theriapolis.Core/World/FactionInfluence.cs`:

```csharp
public sealed class FactionInfluenceMap
{
    // Per-faction influence at each world tile: [factionIndex, x, y]
    // Faction indices: 0=Enforcers, 1=Inheritors, 2=ThornCouncil
    public float[,,] Influence { get; }
        = new float[3, C.WORLD_WIDTH_TILES, C.WORLD_HEIGHT_TILES];

    public int DominantFaction(int x, int y)
    {
        float best = 0; int idx = -1;
        for (int f = 0; f < 3; f++)
            if (Influence[f, x, y] > best) { best = Influence[f, x, y]; idx = f; }
        return idx;
    }
}

public enum FactionId : byte
{
    CovenantEnforcers = 0,
    Inheritors = 1,
    ThornCouncil = 2,
}
```

### 4.4 Extend WorldState

Add these fields to `WorldState`:

```csharp
// ── Polylines (source of truth for linear features) ─────────────────
public List<Polyline> Rivers { get; } = new();
public List<Polyline> Roads  { get; } = new();
public List<Polyline> Rails  { get; } = new();

// ── Settlements ─────────────────────────────────────────────────────
public List<Settlement> Settlements { get; } = new();

// ── Faction influence (3-layer float map) ───────────────────────────
public FactionInfluenceMap? FactionInfluence { get; set; }

// ── Habitability score (reusable across stages) ─────────────────────
public float[,]? Habitability { get; set; }

// ── Encounter density (derived) ─────────────────────────────────────
public float[,]? EncounterDensity { get; set; }

// ── Hash helpers for new data ───────────────────────────────────────
public ulong HashSettlements() { /* FNV-1a over sorted settlement ids + tile coords */ }
public ulong HashPolylines()   { /* FNV-1a over all polyline point arrays */ }
```

---

## 5. The Polyline System (critical — read twice)

This is the architectural core of Phase 2+3, extending the seamless zoom model
from the original plan (Section 5). **Read Section 5 of the original plan
again before implementing this.**

### 5.1 Coordinate space

All polyline points are in **world-pixel space**: `(0..32768, 0..32768)`.
Convert from world tile coords: `worldPixelX = tileX * 32 + 16` (tile center).

### 5.2 Generation pipeline

1. **Cell-path stage** produces a sequence of world tile coordinates
   `(tileX, tileY)` — for rivers this comes from drainage simulation, for
   roads/rail from A* pathfinding.
2. **Convert to control points** in world-pixel space (tile centers).
3. **Catmull-Rom spline** interpolation through control points, producing
   `SPLINE_SUBDIVISIONS` intermediate points per segment.
4. **Perpendicular noise offset** at each subdivided point, sampled from
   FastNoiseLite with a per-polyline sub-seed. Amplitude varies by terrain
   (see constants). Rivers get more meander; roads get less.
5. **RDP simplification** produces a second point list for LOD rendering at
   low zoom (fewer vertices, same visual shape).
6. **Tile flag derivation**: rasterize the polyline onto the tile grid, setting
   `HasRiver`/`HasRoad`/`HasRail` + adjacency flags on each tile the polyline
   crosses and its neighbors.

Create `Theriapolis.Core/World/Polylines/PolylineBuilder.cs` with static
methods: `CatmullRomSmooth(...)`, `ApplyMeanderNoise(...)`,
`RDPSimplify(...)`, `RasterizeToTileFlags(...)`.

### 5.3 Tile flag derivation

After each feature type's polylines are finalized:

```
for each polyline P:
    for each segment (p0, p1) in P.Points:
        rasterize the segment (Bresenham in world-pixel space scaled to tile coords)
        for each tile (tx, ty) the segment passes through:
            set FeatureFlags.HasRiver/HasRoad/HasRail on that tile
            for each of the 8 neighbors:
                set FeatureFlags.RiverAdjacent/RailroadAdjacent as appropriate
```

The tile flags are a **derived cache**, not a source of truth. The polyline
points are authoritative.

---

## 6. World Generation Stages 10–22

All stages implement `IWorldGenStage` and live in
`Theriapolis.Core/World/Generation/Stages/`. Add them to
`WorldGenerator.BuildPipeline()` after BiomeAssignStage.

### Stage 10: HydrologyGenStage

**Input:** Elevation map, moisture map, biome map.
**Output:** `WorldState.Rivers` populated with polylines; `HasRiver` and
`RiverAdjacent` flags set; lakes carved into elevation map.

Algorithm:

1. **Flow direction map**: For each land tile, compute gradient descent —
   the neighbor (of 8) with the lowest elevation. Store as a `byte[1024,1024]`
   direction map. Handle flat areas by finding the nearest downhill tile
   (BFS from flat regions to their lowest-elevation edge).

2. **Flow accumulation**: Traverse tiles in elevation order (highest first).
   Each tile sends its accumulated flow (starts at 1) downstream along the
   flow direction. After all tiles are processed, each tile's accumulation
   count indicates how many upstream tiles drain through it.

3. **Lake detection**: Tiles where flow direction points to a neighbor of
   equal or higher elevation are sink tiles. Flood-fill from each sink to
   find the basin. If basin area >= `LAKE_MIN_AREA`, carve the basin to a
   flat elevation (the basin's outlet elevation) and set biome to Ocean
   (inland lakes reuse the water biome). Mark basin tiles with HasRiver flag
   so they connect visually. Re-run flow direction for filled basins.

4. **River extraction**: Starting from each tile with
   `accumulation >= RIVER_MIN_FLOW_ACCUM`, trace downstream to the coast or
   a lake. Merge paths that converge (keep the higher-accumulation trunk).
   Classify each river by peak flow accumulation: Stream / River / MajorRiver
   per the threshold constants.

5. **Constraint check**: Verify at least one river with
   `accumulation >= RIVER_MODERATE_THRESHOLD` exists in each required macro
   region (Eastern Industrial Belt, Central Grasslands, Subtropical Lowlands).
   If a region lacks a river, seed an artificial spring at the highest point
   in that region and re-run accumulation for that drainage.

6. **Elevation carving**: Along each extracted river path, reduce tile
   elevation by `RIVER_CARVE_DEPTH` to create natural-looking valleys.
   Clamp to sea level minimum.

7. **Polyline conversion**: Convert each extracted cell-path to a polyline in
   world-pixel space. Apply Catmull-Rom smoothing and perpendicular meander
   noise. Set river width: Stream=1 world-px, River=2, MajorRiver=3.
   Compute RDP simplification.

8. **Tile flag derivation**: Rasterize all river polylines onto the tile grid,
   setting `HasRiver` on crossed tiles and `RiverAdjacent` on neighbors.

9. **Hash**: FNV-1a over all river polyline points (sorted by river ID).

### Stage 11: RiverMeanderGenStage

**Input:** River polylines from stage 10.
**Output:** Enhanced polylines with natural meander.

This stage applies additional organic shaping that is too expensive for the
extraction pass:

1. **Oxbow generation**: For rivers crossing flat terrain
   (average elevation < 0.45 along a 20-tile window), check if any meander
   loop brings two points of the polyline within 3 world-pixels of each other.
   If so, with 30% probability (from RNG_MEANDER), cut the loop into an
   oxbow lake — a disconnected water body adjacent to the river.

2. **Width variation**: Rivers passing through wetland biomes widen by 1.5x.
   Rivers in mountain canyons narrow by 0.7x.

3. **Re-derive tile flags** after meander modifications.

### Stage 12: HabitabilityScoreStage

**Input:** Full terrain + rivers + lakes.
**Output:** `WorldState.Habitability` — `float[1024,1024]` score map.

Per-tile formula (from the procgen design doc):

```
habitability = (water_proximity * 3.0)
             + (flatness * 2.0)
             + (fertility * 2.0)
             + (trade_route_potential * 1.5)
             + (resource_proximity * 1.0)
             - (elevation_extreme * 2.0)
             - (hazard_proximity * 1.5)
```

Where:
- `water_proximity`: `1.0 / (1 + distance_to_nearest_HasRiver_or_lake_tile)`,
  computed via BFS from all water tiles outward (fast O(n) wavefront).
- `flatness`: `1.0 - local_elevation_variance` in a 5×5 neighborhood.
- `fertility`: `moisture * temperature` (good growing conditions).
- `trade_route_potential`: At this stage, approximate as centrality — average
  distance to the 8 nearest land tiles with `habitability_so_far > median`.
  (This is a chicken-and-egg problem; compute in two passes: first pass
  without trade_route_potential, second pass adds it.)
- `resource_proximity`: `1.0 / (1 + min_distance_to_mountain_or_forest_or_coast)`.
- `elevation_extreme`: `max(0, elevation - 0.7) * 4 + max(0, 0.38 - elevation) * 4`.
- `hazard_proximity`: `1.0 / (1 + distance_to_nearest_deep_wilderness)` where
  deep wilderness = tile > 30 tiles from any high-habitability tile.

Normalize the result to [0, 1] range. Parallelize with `Parallel.For` over
rows.

### Stage 13: NarrativeAnchorPlaceStage

**Input:** Habitability map, macro grid, rivers.
**Output:** 6 Settlement records added to `WorldState.Settlements` with their
`Anchor` field set.

**This stage runs BEFORE general settlement placement.** (Hard rule #7.)

For each narrative anchor, define constraints as code (not data — these are
bespoke):

| Anchor | Constraints |
|--------|-------------|
| **Millhaven** | Tier 3. MacroCell.BiomeType == "temperate_forest" or "temperate_deciduous". Tile has `RiverAdjacent` or adjacent tile has `HasRiver`. At least 40 tiles from any Tier 2. Top 30% habitability within qualifying region. |
| **Thornfield** | Tier 2. MacroCell.BiomeType contains "industrial" OR Development == "industrial". Tile has `HasRiver` or `RiverAdjacent`. Top 20% habitability in qualifying region. |
| **Fort Dustwall** | Tier 2. MacroCell.BiomeType == "temperate_grassland" or Development == "agricultural" AND near a clade-majority border (within 3 macro cells of a cell with different primary CladeAffinities). Not required to be on rail. Top 30% habitability in qualifying region. |
| **The Tangles** | Not a single settlement — tag 2–4 macro cells in the subtropical lowlands region (MacroCell.BiomeType == "subtropical_forest" AND Covenant == "weak" or "nominal"). Place 2–4 Tier 4 settlements within those cells, one tagged as Thornback Hollow. |
| **Sanctum Fidelis** | Tier 1. Central-eastern continent (macro X in [12,22], Y in [10,22]). Adjacent to a `HasRiver` tile with `FlowAccumulation >= RIVER_MAJOR_THRESHOLD`. Top 5% habitability globally. |
| **Heartstone** | Tier 2. MacroCell.BiomeType contains "mountain". Elevation >= 0.65. Not adjacent to any rail line (enforced after rail gen — place it, then verify). Top 20% habitability in mountain region. |

**Placement algorithm:**

1. For each anchor (in order: Sanctum Fidelis first — it's the most
   constrained, then Heartstone, Thornfield, Fort Dustwall, Millhaven,
   The Tangles last):
   a. Collect all tiles matching the anchor's constraints.
   b. Score them by habitability.
   c. Filter out any tile within `ANCHOR_MIN_DIST` of an already-placed anchor.
   d. Place at the highest-scoring remaining tile.
   e. If no tile qualifies, relax constraints one at a time (drop the river
      adjacency requirement first, then widen the macro cell search) and log
      a warning.

2. For The Tangles: identify qualifying macro cells, then run the Tier 4
   placement sub-routine within those cells only.

### Stage 14: SettlementPlaceStage

**Input:** Habitability map, narrative anchors already placed.
**Output:** Remaining settlements added to `WorldState.Settlements`.

Algorithm:

1. Create a sorted list of all land tiles by habitability (descending).
2. For each tier (Tier 1 through Tier 5 — Tier 1 is already placed as
   Sanctum Fidelis; this stage places Tier 2–5):
   a. Target count is drawn from RNG_SETTLE within `[TierN_MIN, TierN_MAX]`.
   b. Walk the sorted habitability list. For each candidate tile:
      - Skip if within `SETTLE_MIN_DIST_TIERn` of any already-placed
        settlement of the same or higher tier.
      - Skip if tile is ocean.
      - For Tier 2: require river or coast adjacency.
      - For Tier 3: require within 60 tiles of a Tier 2 settlement OR on a
        tile with `HasRiver`.
      - For Tier 5 (PoIs): **invert** — require LOW habitability (bottom 40%).
        Place in mountains, deep forest, swamps, tundra.
      - Place settlement, set IsSettlement flag on tile + 3×3 neighborhood.
   c. Stop when target count is reached or candidates exhausted.

3. Assign sequential IDs. Narrative anchors keep their IDs from stage 13.

### Stage 15: SettlementAttributesStage

**Input:** Placed settlements, macro grid, biome map, rivers.
**Output:** Settlement attribute fields populated.

For each settlement:

1. **Name**: Generate from a syllable table keyed by macro region biome type
   and clade affinity. (Create a simple name generator in
   `Theriapolis.Core/Util/NameGenerator.cs` — 3-5 syllable tables, combine
   prefix + root + suffix. Narrative anchors keep their canonical names.)

2. **Population**: Random within tier range (from procgen doc), biased by
   habitability score.

3. **Economy**: Derived from surrounding terrain in a 10-tile radius:
   - Many mountain tiles → Mining
   - Many forest tiles → Manufacturing (timber)
   - Many grassland/farmable tiles → Farming
   - Coast adjacency → Fishing or Trade
   - High trade_route_potential → Trade
   - MacroCell.Development == "military" → Military

4. **Governance**: Weighted random from macro cell clade affinity:
   - Canid-heavy → Mayor or MilitaryCommandant
   - Cervid-heavy → Council or ClanElder
   - Bovid-heavy → Council
   - Mixed/Industrial → Mayor or Corporate
   - Frontier/low covenant → Anarchic

5. **CladeRatios**: Base from MacroCell.CladeAffinities with ±15% noise
   (from RNG_SETTLE_ATTR).

6. **HybridPct**: 0.5–5% normally, 10–30% in Tangles-tagged cells or
   if MacroCell.Covenant == "nominal" or "weak".

7. **WealthLevel**: Derived from habitability + trade_route_potential.

8. **ScentProfile**: Derived from economy type (see procgen doc).

9. **IsOnRiver**: Check if any tile within 2 tiles of settlement has HasRiver.

### Stage 16: RailNetworkGenStage

**Input:** Settlements (Tier 1–2), elevation map, rivers.
**Output:** `WorldState.Rails` populated with polylines; `HasRail` and
`RailroadAdjacent` flags set.

Algorithm:

1. **Identify rail nodes**: Sanctum Fidelis (hub) + all Tier 2 settlements
   except Heartstone (which is explicitly NOT rail-connected per the design).

2. **A\* pathfinding** from the capital to each Tier 2 node:
   - Cost function per the original plan + Addendum A §2:
     ```
     cost(tile) = base_terrain_cost(elevation, biome)
                + (if HasRiver: INFINITY)
                + (if RiverAdjacent AND direction_parallel: INFINITY)
                + (if RiverAdjacent AND direction_perpendicular: RAIL_BRIDGE_COST)
     ```
   - `base_terrain_cost`: proportional to elevation (mountains are expensive
     for rail) + biome modifier (wetland expensive, grassland cheap).
   - Direction tracking: A* nodes carry the entry direction (which of 8
     neighbors they came from). Parallel check = angle between entry direction
     and river flow direction is ≤ 45°.

3. **Transcontinental line**: Find the easternmost coastal Tier 2/3 settlement
   and the westernmost Tier 2 settlement. A* between them using the same cost
   function but with a strong westward bias (add a small bonus for tiles
   further west to prefer direct routing).

4. **Polyline conversion**: Convert each A* path to a polyline. Apply
   Catmull-Rom smoothing with LOW meander amplitude (rail is engineered).
   Width = 1.5 world-pixels.

5. **Tile flag derivation**: Set `HasRail` and `RailroadAdjacent` on the
   tile grid.

6. **Set HasRailStation** on each rail-connected settlement.

7. **Heartstone check**: Verify Heartstone's tile is NOT within 3 tiles of
   any rail polyline. If it is, log a warning (anchor placement should have
   prevented this, but verify).

### Stage 17: RoadNetworkGenStage

**Input:** Settlements (Tier 1–3), elevation map, rivers, rail.
**Output:** `WorldState.Roads` populated with polylines; `HasRoad` flags set.

This is the most complex stage. Follow Addendum A §2 exactly.

Algorithm:

1. **Build settlement graph**: All Tier 1–3 settlements are nodes. Edge
   weight = A* shortest path cost through terrain.

2. **Minimum Spanning Tree**: Prim's or Kruskal's on the settlement graph.
   This ensures all Tier 1–3 settlements are connected.

3. **Add shortcuts**: Sort non-MST edges by weight. Add the cheapest
   `ROAD_SHORTCUT_FRACTION * |MST_edges|` edges (rounded up). These provide
   alternate routes.

4. **A\* routing** for each edge, using the full Addendum A §2 cost function:
   ```
   cost(tile) = base_terrain_cost
              + (if HasRiver: INFINITY)
              + (if HasRail: INFINITY)
              + (if RiverAdjacent AND direction_parallel: INFINITY)
              + (if RailroadAdjacent AND direction_parallel: INFINITY)
              + (if RiverAdjacent AND direction_perpendicular: BRIDGE_COST)
              + (if RailroadAdjacent AND direction_perpendicular: CROSSING_COST)
              + SETBACK_COST_SCALE / max(1, distance_to_nearest_river_or_rail)
   ```
   The setback cost gently pushes roads away from rivers/rail while keeping
   them in the same valley (see Addendum A, "The Setback Rule").

5. **Road classification** by connected tier:
   - Tier 1↔Tier 1 or Tier 1↔Tier 2 = Highway
   - Tier 2↔Tier 2 or Tier 2↔Tier 3 = PostRoad
   - Tier 3↔Tier 3 = DirtRoad

6. **Tier 4 connections**: For each Tier 4 settlement, find the nearest Tier 3+
   settlement and route a Footpath/DirtRoad to it. Use the same cost function
   but with relaxed exclusion (footpaths can be narrower, so reduce setback).

7. **Polyline conversion**: Same as rail but with slightly higher meander
   amplitude (roads are less rigid than rail). Width by type: Footpath=0.5,
   DirtRoad=1, PostRoad=1.5, Highway=2 world-pixels.

8. **Tile flag derivation**: Set `HasRoad` flags.

### Stage 18: TradeRouteGenStage

**Input:** Settlements with economies, road/rail network.
**Output:** Trade route metadata on settlements (WealthLevel adjustments).

This is a light overlay stage, not a visual feature:

1. For each settlement, determine produced goods (from Economy enum) and
   demanded goods (everything it doesn't produce locally).
2. For each (producer, consumer) pair connected by road/rail, compute a
   trade score = `supply * demand / transport_cost`.
3. Settlements on high-trade-score routes get a WealthLevel boost.
4. Tag road polylines that carry trade (optional metadata for future use:
   merchant caravan spawns in Phase 5).

### Stage 19: FactionInfluenceGenStage

**Input:** Settlements, macro grid, biome map.
**Output:** `WorldState.FactionInfluence` — 3-layer influence map.

Algorithm per faction:

**Covenant Enforcers (faction 0):**
- Seed points: Sanctum Fidelis (strength 1.0), Tier 2 cities (0.7), Tier 3
  towns in macro cells with Covenant == "strong" (0.4).
- Falloff: `strength * max(0, 1 - distance / FACTION_INFLUENCE_RADIUS)`.
- Boost in macro cells with Covenant == "strong" or "moderate" (+0.2).

**Inheritors (faction 1):**
- Seed points: settlements in macro cells where CladeAffinities includes
  predator clades (canid, felid, ursid) AND Covenant == "weak" or "nominal"
  (strength 0.6). Frontier settlements (Development == "frontier") get 0.4.
- Anti-correlated with Enforcer influence: where Enforcers are strong,
  Inheritors are suppressed.

**Thorn Council (faction 2):**
- Seed points: settlements in macro cells where CladeAffinities includes prey
  clades (cervid, bovid, leporid) (strength 0.5). Progressive urban centers
  (Development == "urban" or "industrial") get 0.4.
- Moderate presence in Tangles region.

For each faction, BFS outward from seed points with distance decay. Store
result in the 3D influence array. Normalize so max influence per faction is 1.0.

### Stage 20: PoIPlacementStage

**Input:** Habitability map, settlements, biome map, macro grid.
**Output:** Tier 5 PoI settlements added to `WorldState.Settlements` with
`IsPoi` flag set.

PoIs are placed in LOW habitability areas (bottom 40%). For each PoI:

1. Select a tile from the low-habitability pool.
2. Enforce `POI_MIN_DIST_FROM_SETTLE` from any existing settlement.
3. Enforce `POI_MIN_DIST_FROM_POI` from any other PoI.
4. Tag with a PoI type based on surrounding terrain:
   - Mountain biome → AbandonedMine or NaturalCave
   - Forest biome → CultDen or OvergrownSettlement
   - Tundra/boreal → ImperiumRuin
   - Wetland/subtropical → NaturalCave or CultDen
5. Place `SETTLE_TIER5_MIN` to `SETTLE_TIER5_MAX` PoIs (count from
   RNG_POI).

### Stage 21: EncounterDensityGenStage

**Input:** Settlements, terrain, faction influence, roads.
**Output:** `WorldState.EncounterDensity` — `float[1024,1024]`.

Per-tile density:

```
density = base_biome_density
        * distance_from_settlement_factor   // closer = safer
        * (1.0 - road_proximity * 0.5)      // on-road is safer
        * macro_hostility_factor             // frontier = more hostile
        * (1.0 - enforcer_influence * 0.6)  // enforcer presence = safer
```

Normalize to [0, 1]. This map is consumed by the encounter spawner in Phase 5.

### Stage 22: ValidationPassStage

**Input:** Complete world state with all features.
**Output:** Validation results logged; throws if critical violations found.

Checks:

1. **Border organics (Addendum A §1)**: Re-run the straight-line detector
   from BorderDistortionGenStage. Expect 0 violations (stages 10+ should not
   have introduced new straight borders).

2. **Linear feature exclusion (Addendum A §2)**: For every tile with >1
   linear feature, verify they are crossing (angle diff >= 60°) or within a
   settlement. Log and count violations. **Assert 0 violations.**

3. **River drainage**: Every river terminates at the ocean, a lake, or a
   wetland biome tile. No rivers that dead-end on dry land.

4. **Settlement reachability**: BFS from Sanctum Fidelis along tiles with
   `HasRoad`. All Tier 1–3 settlements must be reachable. Warn (don't fail)
   if Tier 4 settlements are unreachable.

5. **Narrative anchor constraints**: Re-verify each anchor's placement
   constraints are still satisfied after all generation is complete (e.g.,
   Heartstone is not adjacent to rail after rail was generated).

6. **No overlapping settlements**: No two settlements share the same tile.

---

## 7. A* Pathfinder

Create `Theriapolis.Core/Util/AStarPathfinder.cs`.

This is used by RailNetworkGen, RoadNetworkGen, and later phases. It needs
to be efficient on a 1024×1024 grid.

```csharp
public static class AStarPathfinder
{
    /// <summary>
    /// Find the lowest-cost path from (sx,sy) to (gx,gy) on the world grid.
    /// costFn(fromX, fromY, toX, toY) returns the cost of moving between
    /// adjacent tiles, or float.PositiveInfinity for impassable.
    /// Returns null if no path exists.
    /// </summary>
    public static List<(int X, int Y)>? FindPath(
        int sx, int sy, int gx, int gy,
        Func<int, int, int, int, float> costFn,
        int width = C.WORLD_WIDTH_TILES,
        int height = C.WORLD_HEIGHT_TILES);
}
```

Implementation notes:
- Use a **binary heap** priority queue (implement in
  `Theriapolis.Core/Util/BinaryHeap.cs`). The standard `PriorityQueue<T,P>`
  in .NET 6+ lacks decrease-key, so use a custom min-heap with handle-based
  decrease-key.
- 8-directional movement (diagonals cost sqrt(2) * tile cost).
- Heuristic: octile distance (max(|dx|,|dy|) + (sqrt(2)-1) * min(|dx|,|dy|)).
- Allocate the open/closed arrays once and reuse via a generation counter
  to avoid clearing (the grid is 1M tiles; clearing per query is expensive
  if many paths are computed).

---

## 8. Rendering Updates

### 8.1 LineFeatureRenderer

Create `Theriapolis.Game/Rendering/LineFeatureRenderer.cs`.

Draws polylines in world-pixel space at the current camera zoom. This is
the shared renderer for rivers, roads, and rail (original plan Section 7.4).

Implementation:
- Input: list of polylines, Camera2D, SpriteBatch.
- For each polyline, use the `SimplifiedPoints` at low zoom (zoom < 0.15),
  `Points` at high zoom.
- Render as **screen-space thick lines** (build a quad strip along the
  polyline with perpendicular width). Use a 1×1 white pixel texture and
  tint with the feature color.
- Colors: River = blue (#4488CC), Road = brown (#8B6914), Rail = dark gray
  (#444444).
- Width scales with zoom: `screenWidth = worldPixelWidth * zoom`. Clamp
  minimum to 1 screen pixel so lines are always visible.
- Frustum cull: skip polyline segments whose bounding box doesn't overlap
  the camera's visible rect.

### 8.2 Settlement rendering

Update `WorldMapRenderer` to draw settlement icons after terrain:

- Tier 1: 8×8 gold diamond
- Tier 2: 6×6 white square
- Tier 3: 4×4 light gray circle (approximated with a small square)
- Tier 4: 3×3 brown dot
- Tier 5 (PoIs): 2×2 red dot (only visible above zoom threshold 0.3)

Generate these as runtime textures in `TileAtlas` (same pattern as biome
tiles — no external art files needed for placeholder).

### 8.3 Settlement labels

Above zoom threshold 0.2, draw settlement names as `SpriteFont` text
centered above the settlement icon. Use Myra's default font or MonoGame's
built-in `SpriteFont` (already available in the project). Tier 1–2 labels
always show; Tier 3 labels show above zoom 0.3; Tier 4+ labels show above
zoom 0.5.

### 8.4 WorldMapScreen update

In `WorldMapScreen.Draw()`, after drawing terrain:

```
1. worldMapRenderer.DrawTerrain(...)    // existing
2. lineFeatureRenderer.DrawRivers(...)  // NEW
3. lineFeatureRenderer.DrawRails(...)   // NEW
4. lineFeatureRenderer.DrawRoads(...)   // NEW
5. worldMapRenderer.DrawSettlements(...) // NEW
6. worldMapRenderer.DrawLabels(...)     // NEW
```

---

## 9. Tools Update

Update `worldgen-dump` to render the new features on the exported PNG:

- Rivers: draw as blue lines (width proportional to classification).
- Rail: draw as dark gray lines.
- Roads: draw as brown lines.
- Settlements: draw as colored dots (gold for Tier 1, white for Tier 2,
  gray for Tier 3, small brown for Tier 4).
- PoIs: draw as small red dots.
- Narrative anchors: draw with a named label.

Add a new command `settlement-report --seed <n>` that runs the full pipeline
and prints a table of all settlements with their tier, name, anchor tag,
coordinates, economy, governance, and whether they have rail access.

---

## 10. Data Files

### 10.1 factions.json

Create `Content/Data/factions.json`:

```json
[
  {
    "id": "covenant_enforcers",
    "display_name": "Covenant Enforcers",
    "color": "#2266AA",
    "seed_covenant_levels": ["strong", "moderate"],
    "seed_development_levels": ["urban", "industrial"],
    "base_strength": 0.7,
    "affinity_clades": []
  },
  {
    "id": "inheritors",
    "display_name": "The Inheritors",
    "color": "#AA2222",
    "seed_covenant_levels": ["weak", "nominal"],
    "seed_development_levels": ["frontier", "wilderness"],
    "base_strength": 0.6,
    "affinity_clades": ["canid", "felid", "ursid"]
  },
  {
    "id": "thorn_council",
    "display_name": "Thorn Council",
    "color": "#22AA44",
    "seed_covenant_levels": ["moderate", "weak"],
    "seed_development_levels": ["urban", "agricultural"],
    "base_strength": 0.5,
    "affinity_clades": ["cervid", "bovid", "leporid"]
  }
]
```

Create a `FactionDef` record in `Theriapolis.Core/Data/FactionDef.cs`
and load it in `ContentLoader`.

### 10.2 No changes to macro_template.json or biomes.json

The existing data files are sufficient. Settlement names are procedurally
generated, not loaded from JSON (except narrative anchor names which are
hardcoded).

---

## 11. Tests

All new tests go in `Theriapolis.Tests/`. Run with `dotnet test`.

### 11.1 Determinism tests (extend existing)

- **Full pipeline determinism**: Seed `0xCAFEBABE` run twice. Hash settlements
  (sorted by ID: tier + tileX + tileY), hash all polyline points (sorted by
  type then ID), hash faction influence map. Assert identical.
- **Different seeds diverge**: Seeds `0xCAFEBABE` and `0xDEADFACE` produce
  different settlement locations and river paths.

### 11.2 Hydrology tests

- **Rivers drain to water**: For every river polyline, the final point is
  within 2 tiles of an ocean or lake tile. Test on 5 seeds.
- **Required rivers exist**: Eastern Industrial Belt, Central Grasslands, and
  Subtropical Lowlands each contain at least one river with
  `FlowAccumulation >= RIVER_MODERATE_THRESHOLD`. Test on 10 seeds.
- **No dry-land dead ends**: No river polyline's final point is on a tile
  with elevation > SeaLevel + 0.05 that isn't a lake.

### 11.3 Settlement tests

- **Narrative anchor placement**: On 100 random seeds, all 6 narrative anchors
  are placed successfully (no relaxation warnings). Each satisfies its
  constraints.
- **Tier counts**: For 10 seeds, settlement counts per tier fall within the
  `[MIN, MAX]` ranges.
- **Minimum distance**: No two settlements of the same or higher tier are
  closer than `SETTLE_MIN_DIST_TIERn`.
- **Sanctum Fidelis is on a major river**: Verify on 20 seeds.
- **Heartstone is not on rail**: Verify on 20 seeds.
- **Millhaven is near a river**: Verify within 2 tiles of a HasRiver tile
  on 20 seeds.
- **All Tier 1–3 reachable by road**: BFS from Sanctum Fidelis along HasRoad
  tiles reaches all Tier 1–3 settlements. Test on 10 seeds.

### 11.4 Linear feature exclusion tests (Addendum A §2)

- **Zero parallel violations**: Run ValidationPassStage on 10 seeds. Assert
  0 tiles with parallel linear features outside settlements.
- **Crossings are near-perpendicular**: For every tile with >1 linear feature
  (outside settlements), verify the angle between features is >= 60°.
- **Rivers have exclusion zones**: For every tile with `HasRail` or `HasRoad`,
  verify it is not `RiverAdjacent` with a parallel direction (or is a
  crossing tile within a settlement).

### 11.5 Road network tests

- **MST connectivity**: All Tier 1–3 settlements are in the same connected
  component of the road graph.
- **Shortcut count**: Number of road edges beyond the MST is within
  `[0.2, 0.4] * |MST_edges|`.

### 11.6 Architecture test (existing — no change needed)

The existing `CoreNoDependencyTests` already ensures Core has no MonoGame
reference. No new tests needed for this.

---

## 12. Implementation Order

Sonnet should implement in this order, building up iteratively. Each step
should compile and the existing tests should continue to pass.

### Step 1: Foundation types
- [ ] `Vec2` struct
- [ ] `Polyline` class and enums
- [ ] `Settlement` class and enums
- [ ] `FactionInfluenceMap` class
- [ ] Extend `WorldState` with Rivers, Roads, Rails, Settlements,
      FactionInfluence, Habitability, EncounterDensity lists/arrays
- [ ] Add new constants to `Constants.cs`
- [ ] `BinaryHeap<T>` priority queue
- [ ] `AStarPathfinder`
- [ ] `PolylineBuilder` (CatmullRom, MeanderNoise, RDP, RasterizeToFlags)
- [ ] `NameGenerator` (simple syllable combiner)
- [ ] Hash methods on WorldState for new data

### Step 2: Hydrology (stages 10–11)
- [ ] `HydrologyGenStage` — flow direction, accumulation, lakes, river
      extraction, polyline conversion, tile flags
- [ ] `RiverMeanderGenStage` — oxbows, width variation
- [ ] Add stages to `WorldGenerator.BuildPipeline()`
- [ ] Hydrology tests

### Step 3: Settlements (stages 12–15)
- [ ] `HabitabilityScoreStage`
- [ ] `NarrativeAnchorPlaceStage`
- [ ] `SettlementPlaceStage`
- [ ] `SettlementAttributesStage`
- [ ] `FactionDef` + `factions.json` + content loading
- [ ] Settlement placement tests
- [ ] Narrative anchor tests (100-seed sweep)

### Step 4: Infrastructure (stages 16–18)
- [ ] `RailNetworkGenStage`
- [ ] `RoadNetworkGenStage`
- [ ] `TradeRouteGenStage`
- [ ] Linear feature exclusion tests

### Step 5: Factions, PoIs, density, validation (stages 19–22)
- [ ] `FactionInfluenceGenStage`
- [ ] `PoIPlacementStage`
- [ ] `EncounterDensityGenStage`
- [ ] `ValidationPassStage`
- [ ] Full determinism tests
- [ ] Validation pass tests

### Step 6: Rendering
- [ ] `LineFeatureRenderer`
- [ ] Settlement icons in `TileAtlas`
- [ ] Settlement rendering in `WorldMapRenderer`
- [ ] Label rendering
- [ ] `WorldMapScreen` draw order update

### Step 7: Tools
- [ ] Update `worldgen-dump` to render rivers, roads, rail, settlements
- [ ] Add `settlement-report` command

---

## 13. Acceptance Criteria for the Phase 2+3 Branch

1. `dotnet build` succeeds.
2. `dotnet test` passes all tests (both old Phase 0+1 tests AND all new tests).
3. Running `Theriapolis.Desktop`:
   - Click "New World", enter or accept a seed.
   - World map shows colored biome tiles (as before) PLUS:
     - Blue river lines flowing from mountains to coast/lakes.
     - Dark gray rail lines connecting the capital to major cities.
     - Brown road lines connecting all Tier 1–3 settlements.
     - Gold/white/gray/brown settlement dots at correct positions.
     - Settlement names as labels when zoomed in.
   - Pan and zoom work smoothly. Lines are visible at all zoom levels.
   - Rivers, roads, and rail are clearly separated (no visual overlap except
     at crossing points and within settlements).
4. `dotnet run --project Theriapolis.Tools -- worldgen-dump --seed 12345
   --out world.png` produces a PNG with all features overlaid.
5. `dotnet run --project Theriapolis.Tools -- settlement-report --seed 12345`
   prints a settlement table showing all narrative anchors placed correctly.
6. On 10 random seeds tested manually via the tool, the world looks plausible:
   rivers flow downhill, settlements cluster near water and flat terrain,
   roads follow valleys, rail connects major cities, narrative anchors are
   in their correct macro regions.

---

## 14. Performance Notes

- The A* pathfinder is likely the hot spot. Rail needs ~5 paths, roads need
  ~30–50. Each path on a 1024×1024 grid takes 50–200ms with a good heap.
  Total: 2–10 seconds. Acceptable within the 60-second budget.
- Flow accumulation over 1M tiles is O(n log n) for the sort + O(n) for the
  sweep. ~1–2 seconds. Fine.
- Habitability BFS is O(n). Sub-second.
- If total generation exceeds 30 seconds, profile with BenchmarkDotNet before
  optimizing. The most likely optimization: parallelize independent A* paths
  (rail paths are independent of each other; road MST edges are independent
  once computed).
- Do NOT speculatively parallelize A* itself. Single-threaded A* with a good
  heap is faster than thread-synchronization overhead for individual pathfinding
  queries.

---

## 15. What NOT to Build

Do not implement any of the following in this phase:

- Tactical map / chunk streaming (Phase 4)
- Player entity or movement (Phase 4)
- Combat (Phase 5)
- Quest engine (Phase 6)
- Dungeon room templates / interior generation (Phase 7)
- Weather simulation (Phase 8)
- Any UI panels (inventory, character sheet, dialog) — those are Phase 5+
- Save/load system (Phase 4+)
- Touch input (Phase 9)

Stick to world generation stages 10–22, the A* pathfinder, the polyline
system, rendering the features on the world map, and testing.

---

*Theriapolis Implementation Plan v2.0 — Phase 2+3 — 2026-04-12*
*Authored by ENI for LO, for handoff to Claude Sonnet*