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>
This commit is contained in:
parent
f9ea2da3f4
commit
d72ffc0183
13 changed files with 579 additions and 409 deletions
104
Tools/README.md
104
Tools/README.md
|
|
@ -1,52 +1,52 @@
|
|||
# 🧰 Tools Directory - Isla Apocalypse
|
||||
|
||||
## Overview
|
||||
The `/Tools` directory houses all offline developer utilities, administrative scenes, and generation scripts.
|
||||
|
||||
**Core Philosophy:** Nothing in this folder is shipped to the end-user. These tools are used exclusively by the developers or server admins to generate the immutable "Source Data" (blueprints, prefabs, configs) that the `/Server` and `/Client` will later ingest. By keeping this logic completely isolated, we ensure the game client remains lightweight and secure from reverse-engineered world-generation exploits.
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Current Tools
|
||||
|
||||
### 1. The 2D World Generator (`MapCaptureTool.tscn` & `MapPreview.tscn`)
|
||||
**Status:** Active / Upgraded to 1:1 Scale Architecture
|
||||
|
||||
This tool handles the heavy mathematical lifting of procedural generation. It creates the topographical and logistical foundation of the island before any 3D rendering occurs.
|
||||
|
||||
* **Primary Script:** `MapGenerator.cs`
|
||||
* **Resolution:** 4096 x 4096 pixels (1:1 Scale. 1 Pixel = 1 In-Game Meter / 1 Voxel footprint).
|
||||
* **Capture Architecture:** Uses a dynamic, C#-driven offscreen `SubViewport` and a custom `MapDrawProxy`. This bypasses Godot's UI layout engine, allowing the generation of massive, high-resolution maps regardless of the developer's physical monitor size.
|
||||
* **Key Sub-Systems:**
|
||||
* *Topography:* Uses `FastNoiseLite` and distance-falloff math to guarantee a mainland island shape with cold/mountainous northern regions.
|
||||
* *Logistics:* A* Pathfinding that generates looping coastal highways, connecting branch roads, and rugged mountain trails. Pathing is dynamically scaled to the map resolution.
|
||||
* *Zoning:* Biome mapping and hierarchical Town/POI placement based on slope, temperature, and proximity.
|
||||
|
||||
**Outputs (Saved to `user://`):**
|
||||
1. **The Blueprint (`MapData_Seed_[X].dat`):** A heavily compressed binary file containing the map size, heightmap floats, biome enums, road vectors, and POI coordinates. This is the master file read by the Dedicated Server.
|
||||
2. **The Snapshot (`Map_Seed_[X].png`):** A high-resolution 1:1 visual render of the map layout (including all drawn logistical routes) for admin review and seed selection. Timestamps have been removed to prevent directory bloating.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Future Roadmap & Planned Additions
|
||||
|
||||
As we move into Phase 2 (3D Voxels) and Phase 3 (Gameplay), this directory will expand to include the following standalone utilities:
|
||||
|
||||
### 2. The Prefab Editor (Planned - Phase 3)
|
||||
A standalone 3D sandbox scene used to build custom Points of Interest (POIs) block-by-block (e.g., houses, bunkers, gas stations).
|
||||
* **Function:** Allows the developer to build structures visually and define "Loot Container" or "Zombie Spawn" block locations.
|
||||
* **Output:** Generates lightweight `.prefab` or `.json` files that the Server's Chunk Manager reads to spawn buildings at the coordinates dictated by the `MapData.dat` file.
|
||||
|
||||
### 3. Voxel Palette Manager (Planned - Phase 2)
|
||||
A data-entry tool or inspector script to map 2D Biome Enums to 3D Voxel IDs.
|
||||
* **Function:** Defines that `Biome.Jungle` at `Height 0.5` should spawn "Voxel ID 12 (Jungle Grass)", while `Height 0.2` should spawn "Voxel ID 4 (Dirt)".
|
||||
|
||||
### 4. Loot & Balance Tweaker (Planned - Phase 3)
|
||||
A simple UI tool to adjust spawn weights and loot tables without having to dig through massive JSON files manually.
|
||||
* **Output:** Bakes final configuration files for the Server to use when rolling loot table RNG.
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Directory Rules
|
||||
1. **No Client Dependencies:** Scripts in this folder must *never* reference UI, Player Controllers, or Shaders located in the `/Client` folder.
|
||||
2. **Data Agnostic:** Tools here should output raw data (`.dat`, `.json`, `.png`). They should not directly modify the live server's save state to avoid corruption.
|
||||
# /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
|
||||
1. **No client dependencies.** Nothing here may reference UI, player controllers or shaders in
|
||||
`/Client`.
|
||||
2. **Data out, nothing in.** Tools emit `.dat`/`.png`/`.json`; they never write to a live server save.
|
||||
3. **No magic numbers.** Distances and radii scale off `MapSize` or the derived `scaleFactor`, so the
|
||||
generator behaves the same at every profile.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue