ElHombreAlex--FTL-Faster-Than-Light-VR/docs/DEVELOPMENT.md

# Development and verification

[Back to README](../README.md) · [Architecture](ARCHITECTURE.md) · [Contributing](../CONTRIBUTING.md) · [Project status](STATUS.md)

Start with [installation](INSTALLATION.md) for the verified Windows tool versions and local asset import. This is a source prototype with a version-specific native bridge, not a universal drop-in game converter.

## Working on the client

Open `project.godot` in the documented Godot version. Keep `local_game_data/`, imported caches, exports, lab copies and third-party binaries out of the repository. For game-free renderer inspection, start the project with `--demo --desktop`:

```powershell
godot --xr-mode off --path . -- --demo --desktop
```

This does not launch a native campaign. Detailed ship/UI inspection still needs local extraction from an owned game archive. Live play uses `tools/launch.py`, not the demo command. Do not use stale captured state as evidence that a new native integration works.

The main implementation areas are listed in [Architecture](ARCHITECTURE.md). A focused change usually fits one of four paths:

1. **Presentation:** procedural models, effects or placement; preserve native positions/visibility and pause behavior.
2. **Controller/UI:** action mapping, ray/crop picking, contextual pages and panel priority; update the Help diagram and [controls](CONTROLS.md) together.
3. **Bridge:** schema and native command translation; verify native outcomes in a separate lab/profile.
4. **Transport/performance:** capture/read/upload timing; keep resolution-independent native picking and avoid per-frame mesh/texture allocation.

## Python checks

After installing the documented Python requirements, run from the repository root:

```powershell
python -m unittest discover -s tools -p "test_*.py"
```

The current correction passed **46 Python tests**, including empty native drone-list, portable-launcher, modal-HUD hook/preflight and native result-window regressions. The tests exercise synthetic archive/layout/font extraction, bridge schema/input translation, native-pixel filtering, raw frame publication and launcher preflight/error handling. They do not launch FTL. Temporary fixture files are created by the tests. Native beam placement/queued-shot acceptance and defeat/main-menu return pass; live native beam/miss outcomes remain unverified. Production state is restored with preserved campaign hashes; development desktop launch/exit and SteamVR preflight pass. Both standalone wrapper checks and source-only package checks pass; see the current delivery evidence in STATUS. Recorded evidence is in [STATUS](STATUS.md). Physical headset coverage remains separate.

## Godot checks

Use a **separate development checkout or disposable local-data folder** with the required extracted assets. Some suites write screenshots/test frames under `local_game_data/`; do not run them over an active production bridge or package those outputs. Create the local output folder before graphical suites if it is missing.

The commands below list twelve suites. The current correction passed eight headless suites and four graphical Vulkan suites, including the new ship-status render check. See [STATUS](STATUS.md) for evidence and remaining native/delivery limits. A fresh source checkout lacks game assets; model/input/font checks may fail until local extraction is complete. Existing installations should also rerun [asset extraction](INSTALLATION.md#5-extract-local-presentation-assets) to import the eight placed reticle PNGs, and refresh [native hooks](INSTALLATION.md#4-resolve-the-local-executable-hooks).

```powershell
godot --headless --xr-mode off --path . --script tools/test_combat.gd -- --demo
godot --headless --xr-mode off --path . --script tools/test_target_locks.gd
godot --headless --xr-mode off --path . --script tools/test_drones.gd
godot --headless --xr-mode off --path . --script tools/test_input.gd -- --demo --desktop
godot --headless --xr-mode off --path . --script tools/test_models.gd -- --demo --desktop
godot --headless --xr-mode off --path . --script tools/test_environment.gd -- --demo --desktop
godot --xr-mode off --path . --script tools/test_ui.gd -- --desktop
godot --xr-mode off --path . --script tools/test_controller_ui.gd -- --demo --desktop
godot --xr-mode off --path . --script tools/test_frame_transport.gd -- --desktop
godot --xr-mode off --path . --script tools/test_ship_status_render.gd
godot --headless --xr-mode off --path . --script tools/test_hud_layout.gd -- --desktop
godot --headless --xr-mode off --path . --script tools/test_damage_visuals.gd -- --demo --desktop
```

The UI/controller/transport/ship-status suites use actual GPU rendering, so keep their graphical mode. Headless runs of them are not equivalent verification. The ship-status suite needs owner-local extracted ship assets; its default state is a labelled synthetic renderer fixture using `rebel_long`. To inspect a recorded native enemy instead, add `-- --state=res://local_game_data/recorded-enemy.json --output=res://local_game_data/ship-status`. The corresponding layout/art must also be extracted. Neither mode drives FTL. These suites cover effects, room/beam picking, controller context/bindings, model/task distinctions, environmental presentation, original local fonts, UI priority/crops and the raw frame protocol. HUD-layout checks cover headset-relative placement, swept collision prevention and transformed ship/shield clearance. Controller checks include native empty/malformed equipment collections. Damage-visual checks cover permission-aware room colors, absence of floor status bars, native miss presentation and oxygen-dependent breach effects.

Target-lock checks cover numbered player-owned native targets, autofire color, beam endpoint direction, pinpoint beams, flak radius, transformed/pause attachment, receiver visibility and cleanup. Drone checks cover distinct Mk II hardware, shared immutable body/exhaust/emitter geometry and independent emission state. Combat checks include native drone muzzle/render-space placement, fixed bullet launch points, continuing beams and authoritative progress/pause/outcome handling. Jump checks use native `jumping` and arrival-dialog fixtures; the action-wheel context checks include resetting each opening to weapons/drones.

For the current correction, cover one-HP hull cells for differing enemy hull maxima; separate artillery mounts and native shot origins; shield shutdown/charge and native cloak restoration; forward-only miss progress; free beam deck/gap endpoints under encounter transforms; complete result-screen cleanup; 5 cm HUD clearance; and the right Pause/Menu versus left View actions. Native checks must separately establish real artillery/shield/cloak state, accepted beam endpoints, result-window detection and supplemental target isolation. Rendered fixtures establish presentation behavior and must be labelled as fixtures.

No test command above drives a native game or modifies its saves. Separate **live bridge checks** do run the game and can advance a run or change equipment/state.

## Native integration checks

Keep a disposable isolated lab/profile for automation. Back up its saves/settings and record how to restore it before interacting with FTL. Inspect the actual snapshot/input/capture result, not just a success log from the client. Do not perform live experiments in a valuable campaign.

```powershell
python tools/launch.py --check --desktop
python tools/launch.py --smoke
```

`--check` performs preflight without launching. `--smoke` launches the actual isolated game and desktop client, then requests client shutdown after a short interval and checks cleanup. It uses the configured VR save prefix, takes the normal pre-launch backup and may save game state on exit; it is not a purely synthetic test.

When adding a system or command, compare the visible native outcome and snapshot: installed-system availability, native power step, target room/ship, actual crew position, resource change or event transition. A target being accepted does not establish that its eventual effect completed. Hacking attachment/effects, native beam/bomb encounter coverage and full campaigns remain areas for further verification.

A preceding native missed-event check used a private projectile and forced `Evasion.MISS` to exercise the actual flag/event path. It is integration evidence, not a measurement of random evasion probabilities. Enemy room condition colors respect the native visibility rules; floor health/status bars are no longer rendered. Do not infer permission to reveal other hidden state from public icon color or crew-room fog alone.

For the October 5 correction, native beam aim/release and its queued-shot transition are verified. The tested newly equipped and original saved missile/burst factories queued shots without releasing live projectiles, so this session does not establish a native beam sweep or missed-shot outcome. Keep that limit explicit and do not assign a speculative cause. Graphical miss fixtures prove forward presentation/cleanup only. Controlled Victory/defeat checks prove native result-screen integration, not a completed campaign.

The preparer, resolver and launcher reject unknown executable fingerprints. To support another executable, identify a known owned build, implement and validate a complete matching route and keep the rejection path. Do not disable fingerprint checks or reuse addresses from a different build.

## Profiling and visual inspection

For a running disposable live session with Tactical open:

```powershell
python tools/profile_tactical.py
godot --xr-mode off --path . --script tools/profile_tactical.gd -- --desktop --full-main
```

These measure native transport delivery and received textures/desktop rendering. **They are not stereo headset FPS.** The observed improvements and outstanding headset gates are summarized in [STATUS](STATUS.md). Use raw sequence/timestamp freshness rather than the deliberately slow PNG previews.

Additional helpers:

| Tool | Use |
|---|---|
| `tools/benchmark_effects.gd` | Renderer effect benchmark; desktop results only |
| `tools/capture_models.gd` | Local model/weapon gallery |
| `tools/capture_drones.gd` | Procedural drone gallery; `--shots` renders explicit native-schema laser/beam fixtures |
| `tools/capture_ship_details.gd` | Explicit visual fixture for door tiers, fire/breach effects and hull bar |
| `tools/capture_environment.gd` | Environmental presentation inspection |
| `tools/capture_native_models.gd` | Inspect models from an owner-local native snapshot |
| `tools/capture_live.gd`, `tools/record_live.gd` | Capture this client's viewport with a running bridge |
| `tools/capture_input.gd`, `tools/input_harness.gd` | Simulated interaction inspection |

Fixtures illustrate behavior; label them as fixtures rather than real gameplay. Keep game-derived screenshots, snapshots and extracted resources local.

## Logs and useful evidence

- `local_game_data/logs/bridge.log`: native process/bridge errors.
- `local_game_data/logs/client.log`: client output in combined launches.
- `local_game_data/bridge_status.json`: connection, heartbeat and state/capture freshness.
- `local_game_data/xr_input.json`: tracking state, chosen pose, action profile and trigger/grip values.
- `FTLVR_XR_INPUT` client log lines: controller mapping/tracking diagnostics.
- The configured lab's `save-backups/`: pre-launch VR-profile and settings snapshots.

Include relevant redacted excerpts in bug reports. Remove personal paths, save contents and any unrelated process/account details. A frozen native event/store UI is distinct from the user's pause toggle; check both state fields when diagnosing pause effects.

## Before proposing a change

- Describe the behavior changed and the native rule it relies on.
- Run the focused checks for that area; state which assets/build/runtime were used.
- Verify graphical changes in actual rendering and interactions in their relevant UI context.
- For VR changes, report headset/controller testing separately from desktop/simulated results.
- Keep generated data, game binaries, archives, extracted assets and saves out of the diff.
- Update the Help diagram, controls, installation or status documentation when affected.

Full campaign testing, headset comfort and physical stereo performance remain community testing priorities. Passing all automated suites is useful evidence, not a declaration that these gates are complete.