islaApocalypse/Tools/Scripts/MapGenerator.md

MapGenerator.cs - Architecture & Historical Decisions

Date: March 2026 Purpose: Generates the 2D topographical blueprint (Topography, Biomes, Cities, and Road Networks) to be parsed and translated into a 3D Voxel World.

⚠ Historical document — read it as a record of decisions, not as current spec. It was written when the map was 4096², and references to that size throughout should be read as "the map size of the day". Map size is now config-driven (MapProfile in ServerConfig.json; 8192 by default), and the reasoning it describes — scaling everything off MapSize rather than hardcoding — is exactly what makes that work.

For the current behaviour see Tools/Scripts/README.md. For design rationale and the decisions behind the project, see the design vault.

---

1. Topography & The Impact Crater

• Base Generation: Uses FastNoiseLite to generate standard heightmaps and temperature maps, which drive dynamic biomes.
• Dynamic Sea Level: Sea level is calculated based on the temperature map (simulating ice caps/equatorial swelling).
• The Crater: A massive (radius 400) blast zone is forced along the northern coast. Surrounding it is a Biome.Wasteland with a noise-driven "fray" on its borders.
• Design Choice: We allowed the crater to occasionally spawn slightly inland rather than strictly on the beach. This creates natural topographical "pinch points" that will result in highly memorable, claustrophobic 3D driving mechanics.

2. City Placement & The Capitol Tether

• The Challenge: The Capitol City must spawn inside the radioactive Wasteland, but it MUST be connected to the contiguous mainland for the A* highway to reach it. Early iterations spawned the Capitol underwater or stranded it on offshore islands caused by the Wasteland noise bleeding over the ocean.
• The Solution (Smart Tiered Spawner): We abandoned a rigid while loop in favor of a tiered attempt system.
  • Tier 1: Searches for ideal (Wasteland + Coastal + Mainland).
  • Tier 2: Relaxes the coastal requirement.
  • Tier 3: Scans the entire array for the closest valid pixel to the impact center.
  • Tier 4 (Doomsday): Walks strictly south until it hits the mainland.

3. The Pathfinding Wars (A* Road Optimization)

The road network generation was the hardest logistical hurdle. Standard grid-based AStarGrid2D math does not scale cleanly to a 4096 map.

Phase 1: The 16-Minute Bottleneck

• The Flaw: To force the highway to create a large loop connecting our 3 Hubs, we used an ApplyRepulsion function that penalized pixels in a 400px radius around the first drawn road.
• The Math: Repelling a 2,000-point path with a 400px radius resulted in over 1.3 Billion nested loop iterations. The CPU choked, and generation took 11–16 minutes.
• The Result: Unusable generation times, extreme stair-stepping (zig-zagging), and roads cutting straight over mountains.

Phase 2: The Speedrun & The Double-Back

• The Flaw: We ripped out the repulsion completely to save CPU time, dropping the render to 1 minute.
• The Result: Because A* is deterministic, the pathfinder just used the exact same pixels to return to the start, completely breaking the 3-point loop and causing the highway to double back on itself.

Phase 3: The Over-Engineered Spaghetti (The LLM Trap)

• The Flaw: We brought in an external LLM to fix the pathing. It introduced a "Midland Sweet Spot" to force roads off the coast, and a "Daisy-Chain" mechanic for branch roads.
• The Result: The highway started tracing narrow elevation contour lines like a drunk driver. The branch roads turned into a game of "Snake," meandering wildly to connect to each other instead of taking logical paths to the highway. Furthermore, adding a soft weight to the crater combined with our loop repulsion created a "Wasteland Phobia" where the A* algorithm mathematically folded and refused to complete the loop.

Phase 4: The Tactical Revert (Our Final State)

We executed a deliberate tactical revert, stripping out the over-engineered LLM spaghetti and keeping only robust, simple math:

1. Direct Branches: Black roads path directly to the closest highway pixel. No daisy-chaining.
2. The Iron Curtain Repulsion: We restored a +10000f penalty to old highway segments with a radius of 120px to physically force the 3-point loop. We optimized it by only applying the penalty to every step (half the radius) pixel. Render time remains at ~1 minute.
3. Simple Elevation Weights: Instead of a complex U-curve, we use Mathf.Pow(normalizedElevation, 3.0f) * 400.0f to aggressively punish mountains, and a flat +15.0f penalty to gently push roads off the beach sand.

4. The AAA Smoothing Pipeline

Standard A* creates jagged, octagonal stair-steps that look terrible in a 3D voxel world. We completely eradicated this using a 2-step geometric smoothing pipeline:

1. Ramer-Douglas-Peucker (RDP): Decimates the raw A* path, removing thousands of useless straight-line grid points and leaving only the major turns.
2. Chaikin's Algorithm: Performs 4 passes of corner-cutting on the decimated points, resulting in buttery-smooth, sweeping, AAA-style highway curves ready for 3D mesh generation.