islaApocalypse-v2/Tools/README.md

Tools — the offline generator

Holds: the world generator and its diagnostics. Everything that produces a blueprint, and nothing that consumes one at play time.

Boundary — the tools wall:

⚠⚠ TOOLS MAY NOT REFERENCE Client/. THE DEPENDENCY RUNS ONE WAY, OR THE WALL IS NOT A WALL.

No UI, no player controllers, no shaders, no rendering code. Tools/ may use Core/.

Two reasons, both from Design - Tooling - Offline Generation.md: a lighter shipped client, and — less obviously — not handing players the world-generation logic. Shipping the generator lets it be reverse-engineered into an unfair map preview, with the whole island's layout, every settlement and every route known before anyone sets foot on the beach.

Tools emit data; they never write to a live save. A generator that could touch live server state is a corruption risk for no benefit.

Empty this phase — Phase 1 fills it

The only thing here now is Scenes/UserDirProbe.tscn + Scripts/UserDirProbe.cs, a print-and-quit diagnostic that confirms this project's user:// directory is its own and not the old prototype's. It generates nothing.

---

⭐ The conventions Phase 1's generator inherits

These were earned, not assumed — each one came out of the prototype's terrain arc. → Design - Tooling - Iteration and Batching.md.

1. xvfb-run for unattended generation — NOT --headless

⚠ --headless HANGS on a real generation run.

The snapshot capture awaits render frames, and there is no frame loop without a display. Measured, not assumed. A run left on --headless does not fail loudly; it sits there.

xvfb-run -a Godot_v4.7.2-stable_mono_linux.x86_64 --path ~/celerNexus/islaApocalypse-v2 <scene>

A windowed run on the desktop also invites being closed mid-run by whoever is using the machine.

The one exception is a job that awaits no frames — like UserDirProbe, which is why that one documents --headless explicitly:

Godot_v4.7.2-stable_mono_linux.x86_64 --headless \
  --path ~/celerNexus/islaApocalypse-v2 res://Tools/Scenes/UserDirProbe.tscn

If a job awaits a frame, it needs xvfb-run. When unsure, use xvfb-run — it is correct in both cases and costs nothing.

2. Environment overrides — safe BY CODE, not by care

Every path a tool reads or writes resolves through Core/Scripts/ToolingPaths.cs, and each has an environment override, so a batch cannot read over or write to the developer's live files:

Variable	Overrides	Default
ISLA_CONFIG_PATH	the generation config file	user://config.json
ISLA_BLUEPRINT_PATH	blueprints read/written	user://blueprints
ISLA_OUTPUT_DIR	generation output (batches live under it)	user://output

⭐ The point is that it is enforced by CODE, not by care. A rule that depends on an executor remembering it will eventually meet an executor who does not.

There is no second way to obtain these paths. Do not add one.

3. ⚠ File safety — permanent rules

Enforced by Core/Scripts/FileSafety.cs, which throws rather than advises.

1. No deletion in the runtime root or anywhere under batches/.
2. Intermediates persist in a scratch/ subfolder that is never cleaned.
3. The developer's placed files are never touched.
4. Any deletion is named explicitly in the run report.

⚠ These came from a real incident: an executor admitted it had been deleting the developer's staged test blueprint. It was owned and fixed in code. That is why these are rules and not guidance.

4. Batch layout

batches/NN_<name>/<seed>_<variant>/
batches/NN_<name>/INDEX.md
batches/NN_<name>/scratch/          ← persistent; never cleaned

A/B comparisons are browsed by a human, and a flat directory of same-named PNGs is not browsable. The INDEX.md is what makes a batch readable a week later.

⚠ Batches are OUTPUT. They live under ISLA_OUTPUT_DIR (i.e. under user://), not in this repo. The batches/ folder here carries the convention, not the data. No batches are run this phase.

5. Iteration levers, for when the generator exists

• Skip the road pass for all terrain and water iteration. In the prototype this cut a run from ~26 min to ~80 s — a 19× cut, and the difference between iterating on terrain and not iterating on terrain. Blueprints from such a run carry present-but-empty road sections, which is legitimate, not corrupt.
• ⭐ Build the oracle before the taste-iteration, not after. Because the classify path was pinned to uncurved height, every shaping iteration had a hard automatic correctness check (biome and water maps md5-identical). Five rounds of taste-iteration were safe because correctness was not being judged by eye. Where a future phase has a subjective gate, ask first what the automatic invariant is.
• Config-gate every shaping change, with the legacy behaviour surviving on the other side. It keeps changes comparable as an A/B pair, and it means a rejected change costs a flipped default rather than a reverted commit.
• The lever is variants per batch, not speed per pass. Two Phase B tasks ran ~2 hours each, which looked like the pipeline getting slower. It was not — a single pass stayed at ~2 minutes. The cost was A/B/ablation multiplication. When a batch is genuinely wide, say so up front.

6. Scaling discipline

Nothing uses a raw pixel number. Every distance, radius, threshold and noise frequency comes from Core/Scripts/GenerationScale.cs. Read its header before adding any constant — including the tightening on normalized additive noise offsets, which is a forward-guard for the Phase 1 noise port. → Design - Tooling - Scaling Discipline.md.