islaApocalypse/Tools/Scripts/README.md

📜 /Tools/Scripts - Generation Logic

Overview

This directory contains the raw C# backend logic for all of our offline developer tools. These scripts are strictly for generating source data (Maps, Prefabs, Balance Configs) and are completely decoupled from the live game server and client.

---

🏗️ Core Scripts

MapGenerator.cs

The Master World Builder. This script is responsible for generating the 2D topographical and logistical blueprint of Isla Apocalypse. It runs FastNoiseLite math, calculates distance falloffs, plots A* road networks, and zones the biomes.

⚔️ The Great 4096 Struggle (The 1:1 Scale Transition)

Originally, this script generated a 1024x1024 map where 1 pixel equaled 1 chunk (4 meters). To accommodate industry-standard human-scale base building, we transitioned the engine to a 1:1 scale (1 pixel = 1 meter), effectively quadrupling the map size to 4096x4096.

This transition broke almost everything, requiring a massive architectural overhaul:

1. The "TV Static" Math Fix: Multiplying the map size by 4 caused the noise generator to pack 4 kilometers of terrain into 1 kilometer of space, creating visual static. We introduced a dynamic scaleFactor (MapSize / 1024f) to stretch the noise frequency back out, preserving the massive, sweeping "chonky" biomes while maintaining the 1:1 scale.
2. Eradicating Magic Numbers: Hardcoded pixel checks (e.g., "check 10 pixels for water") were completely broken by the upscaling. We refactored the logic to use dynamic map percentages for slope checking, water detection, and A* highway repulsion.
3. The 1KB Postage Stamp (Defeating the UI Engine): Trying to capture a 4096 image inside a standard Godot UI layout node resulted in the engine crushing the map into a tiny 1KB square. To fix this, SaveMapSnapshot() was rewritten to build an invisible, offscreen SubViewport entirely in C#.
4. The Draw Proxy: Because raw Texture.GetImage() does not capture Godot's _Draw() functions, we created MapDrawProxy. This stamps the colored roads and towns onto the offscreen monitor. We then implemented asynchronous thread-locking (await ToSignal(RenderingServer...)) to force the code to wait for the GPU to physically paint the roads before snapping the PNG.

Outputs:

• MapData_Seed_[X].dat - The binary map data for the Server.
• Map_Seed_[X].png - The 4096 high-resolution visual render.

---

⚠️ Scripting Rules

1. No Magic Numbers: Any distance, radius, or length must be calculated as a percentage of MapSize or use the scaleFactor.
2. GPU Respect: Any script exporting visual data must use CallDeferred or await frames to ensure the Godot rendering engine has finished processing.