Local Setup and Running

Open Underroot in the Godot editor, run it, and export the Web, Windows, and Linux builds. First time through, follow the steps in order; after that, skip to "Running from the editor".

Prerequisites

• Godot 4 (GDScript build — no .NET/Mono required). The project declares engine feature 4.6, and CI pins the exact version to 4.6.2 (.github/workflows/ci.yml, GODOT_VERSION: 4.6.2). Use 4.6.2 to match the verified toolchain.
• No external dependencies or plugins beyond the bundled addons/copy_all_errors editor addon, which project.godot already enables.

Opening the project

1. Install Godot 4.6.2 from the Godot download page.
2. Clone the repository.
3. In the Godot project manager, choose Import and select project.godot at the repo root.
4. Open the project. On a cold checkout there is no .godot/ cache, so the first open imports resources — let it finish before running.

Running from the editor

The main scene is set in project.godot:

run/main_scene="res://scenes/ui/IntroStory.tscn"

Press F5 (Run Project) to launch from the intro. The boot chain is IntroStory → TitleScreen → Main; the intro can be skipped with the on-screen button or Space/Enter/Esc. The default window is 1280×720 with stretch/aspect="expand".

To iterate on a specific scene instead of the full boot, open it and press F6 (Run Current Scene) — for example scenes/main/Main.tscn to skip the intro and title.

Save file location

Progress is stored as JSON flat files in Godot's per-user data directory. On Windows:

%APPDATA%\Godot\app_userdata\Underroot\

Inside: saves/slot_N.json (up to 12 slots; SaveManager.MAX_SLOTS = 12), plus the account-level config.json and settings.json. Delete these to reset local progress without touching the repo.

Verifying a change

Before pushing, run the same three headless gates CI runs (.github/workflows/ci.yml). Each expects the Godot console executable — the GUI exe detaches from the terminal and its output is lost.

Parse-check (compiles every autoload; fails on any SCRIPT ERROR / Parse Error):

powershell -ExecutionPolicy Bypass -File tools\parse_check.ps1

By default the script looks for the console exe at %USERPROFILE%\Downloads\Godot_v4.6.2-stable_win64.exe\Godot_v4.6.2-stable_win64_console.exe; override the location with the GODOT_CONSOLE environment variable. Exit codes: 0 clean, 1 parse errors, 2 exe not found.

Data validation (run after any data/*.json edit):

<godot console exe> --headless --path . --script res://tools/validate_data.gd

It passes when the last line is DATA OK.

Smoke test (save round-trip + offline-sim invariants over the real autoload stack):

printf '\n[autoload]\n\nZZSmokeTest="*res://tools/smoke_test.gd"\n' >> project.godot
<godot console exe> --headless --path .        # expect SMOKE PASS
git checkout -- project.godot

Do not leave the temporary ZZSmokeTest autoload in project.godot. Mike keeps uncommitted tweaks in that file, so restore it by copy-backup rather than a blind git checkout -- when working in a shared session.

Export targets

export_presets.cfg defines three runnable presets. All use export_filter="all_resources" and script_export_mode=2.

Web export notes

The Web preset enables threading and requests cross-origin isolation:

variant/thread_support=true
progressive_web_app/ensure_cross_origin_isolation_headers=true
html/canvas_resize_policy=2
threads/emscripten_pool_size=8
threads/godot_pool_size=4

Because threads are on, the page must be served with the COOP/COEP cross-origin isolation headers or the export will not start. The Web build also runs reduced graphics by default: Low Performance Mode defaults ON for web (PerformanceMode / PerfSetup), and World.gd shows a one-time WebGraphicsNotice when OS.has_feature("web") is true.

Desktop signing

Neither desktop preset is code-signed (codesign/enable=false on Windows; no signing on Linux). The Windows and macOS builds therefore trip the OS "unidentified developer" / SmartScreen warning on first launch — READ_ME_FIRST.txt documents the click-through for players ("More info" → "Run anyway"). On Linux, mark the binary executable first (chmod +x Underroot_v1.0.x86_64).

Key files

• project.godot — main scene, viewport, engine version feature, autoloads.
• export_presets.cfg — Web, Windows Desktop, and Linux export configuration.
• tools/parse_check.ps1 — headless parse gate and its GODOT_CONSOLE override.
• .github/workflows/ci.yml — the authoritative version pin (4.6.2) and gate commands.
• READ_ME_FIRST.txt — player-facing first-launch and save-location notes.

Related

• Repository Layout and Boot Flow
• Introduction and Tech Stack
• Verification and CI
• Performance Mode
• Save System and Migration