# 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`:

```text
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:

```text
%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`):

```text
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):

```text
<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):

```text
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`.

| Preset | Platform | Output path | Notes |
|---|---|---|---|
| `Web` | Web | `build/Web/index.html` | Threads on (`variant/extensions_support=false`, `thread_support=true`); cross-origin isolation headers ensured. |
| `Windows Desktop` | Windows Desktop | `build/Underroot_v1.0.exe` | `binary_format/embed_pck=true`; `codesign/enable=false`. |
| `Linux` | Linux | `build/Linux/Underroot_v1.0.x86_64` | `binary_format/embed_pck=false` (ships a separate `.pck`). |

### Web export notes

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

```text
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](/docs/underroot/repository-layout-and-boot-flow)
- [Introduction and Tech Stack](/docs/underroot/introduction-amp-tech-stack)
- [Verification and CI](/docs/underroot/verification-and-ci)
- [Performance Mode](/docs/underroot/performance-mode)
- [Save System and Migration](/docs/underroot/save-system-and-migration)