islaApocalypse/Tools/Scenes

🎬 /Tools/Scenes - Developer Environments

Overview

This directory contains the standalone Godot scenes (.tscn files) used to execute our offline generation scripts. These scenes act as isolated "sandboxes" for the developers to build the world data.

CRITICAL RULE: These scenes must never be added to the main game's build export or scene tree. They are run strictly inside the Godot Editor by pressing F6 (Play Current Scene).

---

🏗️ Core Scenes

1. MapPreview.tscn

The original 2D map generation scene.

• Root Node: TextureRect
• Attached Script: MapGenerator.cs
• Function: Runs the FastNoiseLite math, builds the _heightMap, and executes the _Draw() commands to visually plot the A* road networks and town circles.

2. MapCaptureTool.tscn (The Wrapper)

The master scene used to actually execute and capture the map generation.

• Root Node: SubViewportContainer
• Child Nodes: SubViewport -> MapPreview
• Function: Acts as a massive, invisible "virtual monitor" to capture the high-resolution PNG of the map without the Godot UI layout engine interfering.

---

⚔️ The Great 4096 Struggle (Beating the UI Engine)

When we upgraded Isla Apocalypse from a 1024 to a 4096 (1:1 scale) map, we encountered a massive rendering roadblock. Godot's UI Layout Engine is designed to make things fit on a player's physical monitor.

When we asked MapPreview to render a 4096x4096 texture, Godot panicked. It saw that the developer's monitor was only 1080p, so it violently crushed the map down to fit the screen, resulting in exported PNGs that were either 1KB postage stamps or completely black.

The "Virtual Monitor" Solution

To bypass the UI engine, we had to build MapCaptureTool.tscn.

1. The Container Trap: We initially used a SubViewportContainer with "Stretch" enabled. This was a trap. It locked the resolution to the editor window. We had to forcefully disable Stretch in the C# code.
2. The SubViewport: We placed MapPreview inside a SubViewport set explicitly to 4096x4096. This acts as an offscreen virtual monitor that doesn't care about the physical screen size.
3. The MapDrawProxy: We realized that Texture.GetImage() only grabs the base pixels, completely ignoring the colored roads and towns drawn by _Draw(). We had to dynamically instantiate a Control proxy node to stamp the roads onto the virtual monitor before taking the picture.
4. The Flash Timing: Generating a 4096 map takes time. We had to implement await ToSignal(GetTree(), "process_frame"); to let Godot unlock the scene tree, and await ToSignal(RenderingServer... FramePostDraw) to force the camera to wait until the GPU physically finished painting the roads before snapping the photo.

---

🚀 How to Generate a New World

1. Open MapCaptureTool.tscn in the Godot Editor.
2. Ensure you do not click the main Play button.
3. Press F6 (Play Current Scene).
4. The editor will freeze for 10-30 seconds while the ExportMapData function writes the binary .dat file.
5. Once the console prints the success message, check your user:// folder for the massive, full-resolution .png and the .dat blueprint.