beezm d72ffc0183 docs: bring all READMEs current with actual code (post-sweep-10 truth pass)

Every README was read first, checked against the code in its directory, then
rewritten to describe what the code actually does now.

Corrected throughout: map size is config-driven (8192 default) not a fixed
4096; chunks are 24x24x256 not 32x32; road carving is implemented for all four
tiers, not a 'next step'; Data/ and Resources/ are empty, not populated.

Also fixed MATH_MARCHING_CUBES.md, which documented the density sign convention
exactly backwards — it claimed positive was underground, where the code treats
positive as above the surface and counts a corner inside when density < iso.
Getting that backwards inverts every normal, a bug this project has hit before.

The root README now carries accurate run steps: F5 runs the map generator (not
the game), F6 on Scenes/Main.tscn runs the 3D world, and ChunkRadius is a load
radius that should be dropped to 4-8 while iterating.

Docs only. No code changed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-05 05:23:58 -04:00

2.8 KiB

Raw Blame History

/Tools

Offline developer utilities. Nothing here ships. These generate the source data that /Server and /Client later consume, which keeps world-generation logic out of the shipped client.

The 2D world generator

Script: Tools/Scripts/MapGenerator.cs · Scenes: Tools/Scenes/MapPreview.tscn and Scenes/MapCaptureTool.tscn

Builds the topographical and logistical foundation of the island before any 3D exists.

Resolution is config-driven, from ServerConfig.json's MapProfile: 4K/6K/8K/10K → 4096 / 6144 / 8192 / 10240. Shipped default is 8K. 1 pixel = 1 in-game metre = 1 voxel footprint. (The MapSize field initialiser in the script says 4096, but it is overwritten from config before use.)
Topography: FastNoiseLite plus distance-falloff maths for a guaranteed mainland island, a mountain spine, dynamic temperature-driven sea level, and an impact crater pushed into the northern coast (carved at 80 % of its radius so a landbridge always survives).
Logistics: AStarGrid2D pathfinding producing a looping continental highway, a branch to the mountain hub, and county roads daisy-chained outward with Prim's algorithm. Paths are decimated (Ramer–Douglas–Peucker) then smoothed (4 Chaikin passes).
Zoning: biome mapping and tiered town/POI placement by slope, temperature and proximity.

⚠️ A* is the known bottleneck

The grid is one node per pixel — 67 million nodes at 8K — and the weight-setup pass walks every one of them. A full generation can stall long enough that runs get abandoned. await yields are sprinkled through the road stage, but they cannot interrupt a single engine-side GetPointPath call, so they only help between paths. Expect a regeneration to take minutes, or to need abandoning.

Outputs — written to `user://`, not into the project

File	What it is
`MapData_Seed_<seed>.dat`	The binary blueprint the server reads (~512 MB at 8K)
`Map_Seed_<seed>.png`	Visual snapshot of the map, for reviewing and picking seeds

On Linux: ~/.local/share/godot/app_userdata/islaApocolypse/.

Running it

Open Tools/Scenes/MapPreview.tscn and press F6. It is also the project's main scene, so pressing F5 anywhere runs this — which is why F5 regenerates your world instead of starting the game. Use Scenes/MapCaptureTool.tscn when you specifically want the full-resolution PNG.

Rules

No client dependencies. Nothing here may reference UI, player controllers or shaders in /Client.
Data out, nothing in. Tools emit .dat/.png/.json; they never write to a live server save.
No magic numbers. Distances and radii scale off MapSize or the derived scaleFactor, so the generator behaves the same at every profile.

2.8 KiB Raw Blame History Unescape Escape