islaApocalypse/Scenes/README.md

🌍 /Scenes - The Playable Game

Overview

This directory contains the core runtime scenes for Isla Apocalypse. Unlike the /Tools directory, the scenes here are exactly what the end-user (or the Dedicated Server) will run.

Core Philosophy: These scenes do not generate the world from scratch. They strictly load and interpret the immutable MapData.dat blueprint provided by the developers. This ensures lightning-fast server boot times and complete parity between the server and the clients.

---

🏗️ Core Scenes

Main.tscn (The Entry Point)

Status: In Transition (Prepping for 1:1 Scale Ingestion)

This is the master root scene. Currently, it acts as the Dedicated Server environment, responsible for reading the 2D blueprint and translating it into a physical 3D voxel world using the ServerChunkManager.

⚔️ The Great 4096 Struggle (The 3D Ramifications)

Our decision to upgrade the master blueprint from 1024x1024 to a massive 4096x4096 (1:1 scale) fundamentally changed how Main.tscn must operate.

While the 2D generator struggled with math and UI layouts, the 3D server must now deal with Memory Management.

• The Scale Shift: In the old 1024 version, 1 data pixel equaled 4 meters of 3D space. Now, 1 pixel = 1 meter. This perfectly accommodates human-scale base building (like 7 Days to Die), but it means the total data footprint of the world is 16 times larger.
• The Chunking Mandate: Main.tscn can no longer afford to load the entire map into RAM at startup. The ServerChunkManager must operate strictly on a localized, dynamic grid—only loading the 1-meter chunks immediately surrounding active players.

🛡️ The Arsenal is Ready

Despite the massive scale increase, Main.tscn is structurally prepared for the 4096 blueprint thanks to heavy engine optimizations built during Phase 1:

1. The EdgeKey Welder: Completely eliminates floating-point drift and mesh seams across the new high-density chunk borders.
2. Analytical Normals: Bypasses Godot's slow native normal calculation, using mathematical gradients to light the massive 1:1 voxel world instantly.
3. The +1 Border Fix: Chunk arrays are padded by exactly 1 unit to flawlessly sample neighbor data without requiring expensive cross-chunk blurring.

---

🚀 The Immediate Roadmap

When Phase 2 resumes, Main.tscn will undergo the following upgrades to ingest the new 4096 map:

1. Re-syncing the Parser: Uncommenting the Logistical Network logic in MapDataParser.cs so the server can read the newly fixed roads and towns.
2. Dynamic Chunk Loading: Scrapping the hardcoded 10x10 test grid in favor of a proximity-based chunk loader.
3. Terrain Flattening: Implementing logic for the voxel engine to read the road and town data and automatically flatten the 3D terrain beneath them.