islaApocalypse/Tools/README.md

🧰 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.