TheriapolisV3/theriapolis-rpg-procgen-addendum-a.md

Theriapolis — Procedural World Generation

Addendum A: Border Organics & Linear Feature Tile Rules

---

ISSUE 1: Organic Borders — No Straight Lines

The Problem

Biome-to-biome boundaries and coastline edges render as straight lines when biome assignment is done per-cell without edge treatment. A grid of cells, each tagged with a biome, produces staircase patterns at best and ruler-straight borders at worst. Neither looks natural.

The Rule

No border between any two biome types, and no border between land and ocean, may contain a straight segment longer than 2 tiles.

"Straight segment" is defined as: 3 or more consecutive border-edge tiles that form a line along any cardinal or diagonal axis without deviation.

This rule applies to:

• Biome-to-biome transitions (forest ↔ grassland, grassland ↔ mountain, etc.)
• Land-to-ocean transitions (coastline)
• Land-to-lake transitions
• Land-to-river transitions (riverbanks)

---

Implementation: Border Noise Injection

Biome borders are NOT the raw edges of macro-cell assignments. They are post-processed using a dedicated border-shaping pass.

Step 1 — Identify Raw Borders

After biome assignment (Layer 1), scan the tile grid for every tile that is adjacent (including diagonal) to a tile of a different biome type or a water tile. Tag these tiles as BORDER tiles.

Step 2 — Generate Border Distortion Map

Create a separate high-frequency Simplex noise layer (distinct from the terrain noise). This is the Border Noise Layer. Parameters:

frequency:   high (4×–8× the base terrain noise frequency)
octaves:     2–3
amplitude:   scaled to 1–3 tile displacement
seed:        world_seed + BORDER_OFFSET (constant offset to decouple from terrain)

The purpose of this layer: it tells each BORDER tile how far and in what direction to "push" the border from its mathematically derived position.

Step 3 — Apply Distortion to Border Tiles

For each BORDER tile:

1. Sample the Border Noise Layer at the tile's coordinates. This yields a displacement vector (dx, dy), each component ranging from -3 to +3 tiles.
2. The tile's biome assignment is re-evaluated: instead of asking "what biome does THIS cell belong to?", ask "what biome does the cell at (x + dx, y + dy) belong to?"
3. This effectively warps the border, creating irregular, organic-looking transitions.

The result: borders between biomes become wavy, irregular curves with peninsulas of one biome jutting into another, concavities, and natural-looking interlock patterns.

Step 4 — Coastline-Specific Treatment

Coastlines receive an ADDITIONAL distortion pass with higher amplitude (2–5 tile displacement) and lower frequency (producing broad bays and headlands rather than jagged noise). This is layered on top of the standard border distortion.

Coastline distortion parameters:

frequency:   2×–4× base terrain noise
octaves:     3–4 (more detail than biome borders)
amplitude:   2–5 tile displacement
persistence: 0.5 (each octave contributes less — smooth large shapes with fine detail)

This produces coastlines with large-scale features (bays, peninsulas, capes) and small-scale features (coves, rocky outcrops, sandbars) simultaneously.

Step 5 — Validation Pass

After distortion, run a straight-line detector across all borders:

for each BORDER tile B:
    look at the 6 consecutive border tiles in each of the 8 directions
        (N, NE, E, SE, S, SW, W, NW)
    if 3+ consecutive tiles form a collinear segment:
        flag for correction

Flagged tiles receive a forced 1-tile perpendicular displacement (randomly left or right of the border line). This is the safety net — it should rarely trigger if the noise parameters are tuned correctly, but it guarantees the rule is never violated.

---

Implementation: Biome Transition Zones

Beyond border shape, the visual and mechanical transition between biomes should never be a hard line. Implement a transition band of 2–4 tiles on each side of every biome border where tiles are assigned a MIXED biome type:

• Forest ↔ Grassland border: transition tiles are FOREST_EDGE (scattered trees, tall grass, mixed flora).
• Grassland ↔ Mountain border: transition tiles are FOOTHILLS (rocky grassland, increasing elevation, scrub).
• Forest ↔ Wetland border: transition tiles are MARSH_EDGE (muddy ground, standing water between trees).
• Any biome ↔ Coastline: transition tiles are BEACH, CLIFF, TIDAL_FLAT, or MANGROVE depending on biome type and elevation.

Transition bands are also distorted by the Border Noise Layer, so their width varies organically (wider in some spots, narrower in others).

Visual Rule: A player walking from forest into grassland should cross: dense forest → thinning forest → scattered trees with grass → tall grass → open grassland. Never a single-tile hard switch.

---

Diagram: Border Distortion Visualization

RAW BIOME ASSIGNMENT (bad — straight edges):

FFFFFFGGGGG
FFFFFFGGGGG
FFFFFFGGGGG
FFFFFFGGGGG
FFFFFFGGGGG

AFTER BORDER NOISE (good — organic edges):

FFFFfgGGGGG
FFFFFfGGGGG
FFFfggGGGGG
FFFFfgGGGGG
FFFFFfgGGGG

F = Forest (core)
G = Grassland (core)
f = Forest Edge (transition)
g = Grassland Edge (transition)

COASTLINE EXAMPLE:

Raw:                    After Distortion:

LLLLLOOOOO              LLLLllOOOO
LLLLLOOOOO              LLLLLlOOOO
LLLLLOOOOO              LLLllOOOOO
LLLLLOOOOO              LLLLlOOOOO
LLLLLOOOOO              LLLLLllOOO

L = Land
O = Ocean
l = Coastal transition (beach/cliff/tidal)

---

Additional Organic Features

Peninsula and Bay Generation:

Beyond noise distortion, explicitly generate 2–4 large-scale coastal features per continental edge:

1. Peninsulas: Select a random coastline point. Extend a noise-distorted finger of land 10–30 tiles into the ocean at a random angle. Width tapers from 5–10 tiles at base to 1–3 tiles at tip. Peninsulas are high-value settlement locations (natural harbors on the flanks).

2. Bays: Select a random coastline point. Carve a noise-distorted concavity 10–20 tiles into the land. Width varies 5–15 tiles. Bays are natural harbor sites — settlement placement scores bay interiors highly.

3. Islands: 3–8 islands generated offshore. Each is a small noise-generated heightmap (10–30 tiles diameter), placed 5–20 tiles off the nearest coast. Islands can host Tier 4–5 settlements, PoIs, or remain wilderness.

These features are placed BEFORE border distortion (they modify the raw land/ocean mask), ensuring the distortion pass treats them as natural coastline.

River Meander:

Rivers generated by drainage simulation (Layer 2) also receive meander treatment:

1. After the base river path is computed (gradient descent), apply a lateral sine-wave displacement along the river's length.
2. Amplitude: 1–3 tiles (wider in flat terrain, tighter in mountain valleys).
3. Frequency: varies by river length (longer rivers have broader, slower meanders).
4. In very flat terrain (grasslands, floodplains), meander amplitude increases and occasional oxbow lakes are generated (abandoned meander loops that became disconnected).

---

---

ISSUE 2: Linear Feature Tile Exclusivity

The Problem

Rivers, roads, and railroads are all drawn as tile-based linear features on the world map. When two or more of these features occupy the same tile and run in the same direction (parallel), they become visually indistinguishable, cause rendering conflicts, and create gameplay ambiguity (is the player on the road or in the river?).

The Rule

No tile may contain more than one linear feature running in the same direction.

Specifically:

• A river and a road may NOT occupy the same tile running parallel (same or adjacent direction).
• A river and a railroad may NOT occupy the same tile running parallel.
• A road and a railroad may NOT occupy the same tile running parallel.
• A river, road, and railroad may NEVER all occupy the same tile under any circumstances.

Crossings ARE permitted. A road may cross a river (bridge tile). A railroad may cross a river (bridge tile). A road may cross a railroad (crossing tile). These are perpendicular or near-perpendicular intersections, not parallel co-occupation.

"Parallel" Definition:

Two linear features are considered parallel on a tile if their traversal directions through that tile differ by 45 degrees or less.

PERMITTED (crossing — ~90° intersection):

    Road →→→
         ↓
    River ↓↓↓

FORBIDDEN (parallel — same direction):

    Road  →→→→→→
    River →→→→→→    (both heading east through the same tiles)

FORBIDDEN (near-parallel — ~45° on same tile):

    Road  →→↗
    River →→→    (road angling NE while river goes E — too close)

PERMITTED (diverging after cross):

    Road  →→→↗↗↗
    River →→→→→→    (road crosses river then diverges — crossing tile is fine)

---

Implementation: Linear Feature Priority and Exclusion Zones

Linear features are generated in a fixed priority order. Higher-priority features claim tiles first. Lower-priority features must route around claimed tiles.

Priority Order:

1. Rivers (highest — water flows where gravity dictates; it was here first)
2. Railroads (second — expensive infrastructure, routes are surveyed and committed)
3. Roads (third — roads are the most flexible and can divert most easily)

Step 1 — River Generation (Layer 2, unchanged)

Rivers are generated first via drainage simulation. Each river tile is tagged with:

• feature: RIVER
• direction: [N, NE, E, SE, S, SW, W, NW] (flow direction through this tile)
• exclusion_zone: true

The exclusion zone for a river tile extends to all 8 adjacent tiles. These adjacent tiles are tagged:

• river_adjacent: true
• river_direction: [inherited from the river tile's direction]

This means: no other linear feature may enter a river-adjacent tile traveling in the same direction (±45°) as the river. They CAN enter the tile traveling perpendicular (crossing).

Step 2 — Railroad Generation

Railroads are generated using A* pathfinding between rail-connected settlements (Layer 4). The pathfinding cost function is modified:

cost(tile) = base_terrain_cost
           + (if tile.feature == RIVER: INFINITY)                    // never on river
           + (if tile.river_adjacent AND direction_parallel: INFINITY) // never parallel adjacent
           + (if tile.river_adjacent AND direction_perpendicular: BRIDGE_COST) // cross OK, expensive

Where:

• INFINITY = impassable (pathfinder routes around)
• BRIDGE_COST = high but finite (bridges are expensive but buildable; the pathfinder will cross rivers when routing around is worse)
• direction_parallel = the railroad's proposed direction through this tile is within 45° of river_direction
• direction_perpendicular = the railroad's proposed direction is 60°+ different from river_direction

When a railroad tile is placed, it receives the same treatment as rivers:

• feature: RAILROAD
• direction: [direction]
• exclusion_zone: true
• Adjacent tiles tagged railroad_adjacent, railroad_direction

Step 3 — Road Generation

Roads are generated last, using the same modified A* pathfinding but now respecting BOTH river and railroad exclusion zones:

cost(tile) = base_terrain_cost
           + (if tile.feature == RIVER: INFINITY)
           + (if tile.feature == RAILROAD: INFINITY)
           + (if tile.river_adjacent AND direction_parallel: INFINITY)
           + (if tile.railroad_adjacent AND direction_parallel: INFINITY)
           + (if tile.river_adjacent AND direction_perpendicular: BRIDGE_COST)
           + (if tile.railroad_adjacent AND direction_perpendicular: CROSSING_COST)

Where CROSSING_COST is lower than BRIDGE_COST (road-rail crossings are cheaper to build than bridges).

---

Crossing Tile Types

When a linear feature crosses another, the intersection tile receives a special type that handles both features:

Crossing	Tile Type	Visual	Gameplay
Road crosses River	BRIDGE	Road surface over water, bridge supports visible	Traversable on road; river continues beneath. Bridge can be a chokepoint.
Railroad crosses River	RAIL_BRIDGE	Rail tracks on bridge structure over water	Rail travel continues; river flows beneath.
Road crosses Railroad	RAIL_CROSSING	Road surface with rail tracks crossing it, warning markers	Both traversable. Possible train-encounter event at crossing.
Road crosses Road	CROSSROADS	Intersection	Standard crossroads — signpost, possible encounter point.

Crossing Angle Constraint:

Crossings must occur at 60°–120° angles (near-perpendicular). If the pathfinder produces a crossing at a shallower angle, the crossing tile is nudged: the lower- priority feature's path is locally adjusted to approach the crossing more perpendicularly.

BAD CROSSING (too shallow, ~30°):

    River →→→→→→→
    Road    ↗↗↗↗

CORRECTED (road approaches at ~80°):

    River →→→→→→→
    Road     ↑↑↗
             ↑

This local adjustment affects only the 2–3 tiles immediately before and after the crossing point. The rest of the road's path is unchanged.

---

River-Following Roads: The Setback Rule

In real geography, roads often follow river valleys because valleys are flat and rivers indicate gentle terrain. The generation system should produce roads that travel NEAR rivers (in the same valley) without occupying the same tiles.

The Setback Rule:

When road pathfinding produces a path that would run parallel to a river (same general direction, within exclusion zone), the road is pushed to a setback distance of 3–5 tiles from the river centerline. The road follows the river valley's general direction but maintains visual and mechanical separation.

Implementation:

// During road A* pathfinding, for tiles near a river:

if (tile.river_adjacent AND proposed_direction is parallel to river):
    // Don't use INFINITY — we WANT the road nearby, just not ON the river
    // Instead, add a moderate cost that pushes it a few tiles away
    cost += SETBACK_COST × (1 / distance_to_river)
    // Closer to river = higher cost, pushing the path outward
    // But the valley terrain is still cheaper than mountains,
    // so the road stays in the valley, just offset

Visual result:

Terrain Cross-Section (valley):

    Mountains    Road    River    Meadow    Mountains
    /\/\/\      ====    ~~~~     ........   /\/\/\
                  ↑        ↑
            3-5 tiles separation

The player sees: a road running through a valley with a river visible 3–5 tiles to one side. Realistic, readable, no tile conflicts.

---

Railroad-Following Roads: Same Principle

Railroads and roads frequently follow the same corridors (both seek flat, direct routes). The same setback rule applies:

• Railroad is placed first (higher priority).
• Road pathfinding applies SETBACK_COST near railroad tiles, pushing the road 2–4 tiles to one side.
• The road and railroad travel the same general corridor but on parallel paths with clear tile separation.

Visual result:

Top-Down View:

    ====  Railroad
    ....  (2-4 tile gap, terrain visible between)
    ----  Road

---

Edge Case: Convergence Points (Settlements)

All three linear features may converge at settlement tiles. Settlements are special:

• Settlement tiles are multi-layer. A town can have a river running through it, a rail station, and roads entering from multiple directions.
• Within settlement boundaries (the tile cluster that forms the town), the exclusion rules are RELAXED. Rivers, roads, and rail can coexist within a town's footprint because the settlement's own infrastructure (bridges, crossings, canal walls, station platforms) handles the overlap.
• The exclusion rules resume at the settlement boundary. As features exit the town, they must separate to compliant distances within 2 tiles.

Implementation:

if (tile.is_settlement):
    // All linear feature costs revert to base terrain cost
    // No exclusion zones within settlement boundaries
    // Crossing types still apply (bridges, rail crossings)
else:
    // Full exclusion rules in effect

This means: a river, road, and railroad can all enter the same town (because towns form at resource convergence points), but they must diverge onto separate tile paths once they leave.

---

Validation Pass

After all three linear feature layers are generated, run a validation sweep:

for each tile T on the map:
    features_on_tile = list of linear features present on T
    if len(features_on_tile) > 1:
        if T.is_settlement:
            PASS (settlements are exempt)
        else:
            for each pair (A, B) in features_on_tile:
                angle_diff = abs(A.direction - B.direction)
                if angle_diff < 60°:
                    FLAG AS VIOLATION
                    // Reroute the lower-priority feature around this tile
                    // using local A* with the violating tile set to INFINITY

Rerouting is local (affects 3–5 tiles around the violation). The global path is not recomputed — only the immediate conflict area is adjusted. This keeps the validation pass cheap.

Violation Logging:

In development builds, log all violations with coordinates, feature types, and directions. Target: 0 violations after the validation pass. Any logged post- validation violation indicates a bug in the exclusion cost functions.

---

Summary: Tile Content Rules (Quick Reference)

Tile State	River	Railroad	Road	Valid?
Empty	—	—	—	Yes
River only	✓	—	—	Yes
Railroad only	—	✓	—	Yes
Road only	—	—	✓	Yes
River + Road parallel	✓	—	✓	NO
River + Road crossing	✓ (beneath)	—	✓ (bridge)	Yes
River + Railroad parallel	✓	✓	—	NO
River + Railroad crossing	✓ (beneath)	✓ (bridge)	—	Yes
Road + Railroad parallel	—	✓	✓	NO
Road + Railroad crossing	—	✓	✓ (crossing)	Yes
River + Road + Railroad	✓	✓	✓	NO (never, outside settlements)
Any combination in settlement	✓	✓	✓	Yes (settlement exempt)

---

Addendum A, Version 1.0 — Border Organics & Linear Feature Tile Rules Compiled by ENI for LO