Update gameplay feedback and repair portable VR launchers

docs/ARCHITECTURE.md

@@ -44,13 +44,17 @@ Godot uses this state to place and animate visual actors. Native positions, curr
 
 Projectiles originate from native weapon/drone locations and follow native shot information. Rendering does not determine hits or damage. Pause freezes presentation clocks while keeping actual native paused projectiles visible and removing stale shots. Environmental animation conveys the current hazard; exact hazard timing remains a polish/verification area.
 
+The native missed flag and a post-update event feed evasion feedback so brief missed shots can produce a single MISS cue even between snapshot deliveries. Room condition colors respect native information permissions; role icons and hazards remain, without floor health/status bars or counters. Reactor snapshots distinguish raw availability from usable availability after native capacity/environmental limits; battery availability is separate. Equipped localized weapon/drone metadata is distinct from deployed drone actors, keeping wheel labels tied to actual shortcut slots. Optional collections are normalized by the bridge and parsed defensively by the wheel: Lua may encode an empty table as `{}` rather than `[]`.
+
 ## Original HUD and floating windows
 
-The game renders its original HUD into a separate native framebuffer. This retains native fonts, localization, power widgets, tooltips and values even when the normal backbuffer displays Tactical, the map or a window. The bridge removes unwanted world/enemy HUD pixels for the headset layer and preserves complete native window content for floating panels.
+The game renders its original HUD into a separate native framebuffer. This retains native fonts, localization and values even when the normal backbuffer displays Tactical, the map or a window. The bridge removes unwanted world/enemy HUD pixels and preserves complete native window content for floating panels. Gameplay crops the upper native status and crew region to a fixed-size headset-relative panel, omitting the lower strip; Power/Shortcuts/the wheel supply those actions. Main menus and desktop Tactical/map views retain full framing.
+
+[hud_anchor.gd](../scripts/hud_anchor.gd) gives the headset-relative pose priority and keeps fixed metre dimensions for readable text. Collision checks use the transformed hull/shield envelope and the panel's swept movement. Only a potential intersection engages the above-ship clamp; looking down cannot pass the HUD through the ship. The panel returns to headset-relative placement when clearance permits. Pause is attached above the same HUD panel.
 
 Transport uses atomic raw RGBA files with an `FVR1` header, dimensions, sequence and timestamp. Tactical is captured at a target **30 Hz / 960×540**; map/windows retain **1280×720**. The independent HUD targets **10 Hz / 1280×720**. Native input coordinates remain **1280×720** regardless of capture resolution. PNG previews update at about 1 Hz and are diagnostics rather than the live transport.
 
-The client reuses textures, reads only fresh frames and renders UI subviewports on changes. HUD/panel crops and alpha-aware pointing preserve native control coordinates. The hand panel receives priority over the headset HUD where they overlap. Rooms use floor intersections for targeting and crew drops, avoiding doors or miniatures blocking the intended destination.
+The client reuses textures, reads only fresh frames and renders UI subviewports on changes. HUD/panel crops and alpha-aware pointing preserve native control coordinates. The hand panel receives priority over the gameplay HUD where they overlap. Rooms use floor intersections for targeting and crew drops, avoiding doors or miniatures blocking the intended destination.
 
 ## Local assets and generated data
 

docs/CONTROLS.md

@@ -21,7 +21,7 @@ Open **Controls / Help** on the left panel for an illustrated controller diagram
 | Right stick direction | Select a wheel slot; release bumper to confirm |
 | Left Dpad Down | Open or close Tactical |
 | Left View | Pause or resume |
-| Left Dpad Up | Open or close Shortcuts |
+| Left Dpad Up | Open or close System Power |
 | Left Dpad Left / Right | Previous / next hand-screen page |
 | Left grip, held + hand motion | Move the encounter |
 | Left stick horizontal / vertical | Rotate / resize the encounter |
@@ -29,7 +29,7 @@ Open **Controls / Help** on the left panel for an illustrated controller diagram
 | Left trigger | Return crew to stations, except on System Power |
 | Right grip + left trigger | Save stations, except on System Power |
 
-The page order is **Navigation → Tactical → Shortcuts → System Power → Jump → Help**. Point at an available panel button with the right controller and pull the right trigger. Jump, Ship and Store are offered according to native game availability.
+The page order is **Navigation → Tactical → Shortcuts → System Power → Jump → Help**. Navigation includes a direct **SYSTEM POWER** button as well as Shortcuts. Point at an available panel button with the right controller and pull the right trigger. Jump, Ship and Store are offered according to native game availability.
 
 ## System Power page
 
@@ -42,7 +42,7 @@ This page changes the contextual controls below. **Steam Frame X/Y are on the ri
 | Left trigger | Add one native power step to the selected system |
 | Left bumper | Remove one native power step |
 
-The game decides whether a change is allowed. One engine step changes one power bar; one shield step normally changes two. Damage, ion locks, capacity, bonus power and battery power follow the actual game state. The reactor column shows available power. A stationary pointer does not continuously override X/Y selection.
+The game decides whether a change is allowed. One engine step changes one power bar; one shield step normally changes two. Damage, ion locks, capacity, bonus power and battery power follow the actual game state. The reactor column shows **usable free reactor power after environmental limits**: storm/capped bars are marked separately, and battery availability remains a separate counter. A stationary pointer does not continuously override X/Y selection.
 
 ## Crew, doors and room targeting
 
@@ -59,7 +59,7 @@ Enemy inspection reveals room roles; it does not reveal crew or hazards that FTL
 
 Hold the **right bumper**, move the right stick toward a slot and release the bumper to activate it. Returning the stick to the center cancels. Right trigger confirms immediately; B cancels. Right A changes the category.
 
-The wheel starts with weapon slots 1–4 and drone slots 5–8. Other categories provide system power and system actions. Uninstalled or unavailable entries cannot activate. When a choice event is open, the wheel becomes a choice selector for entries 1–8; original dialog controls remain pointable.
+The wheel starts with weapon slots 1–4 and drone slots 5–8. Equipped weapons/drones show their native localized names; weapon-family silhouettes and ammo captions distinguish similar equipment. Long names are clipped inside their sector, with a wider selected-name caption below. Numbers remain the original native shortcuts. Other categories provide system power and system actions. Uninstalled or unavailable entries cannot activate. When a choice event is open, the wheel becomes a choice selector for entries 1–8; original dialog controls remain pointable.
 
 Shift and Ctrl also apply when confirming relevant wheel or shortcut commands.
 
@@ -82,7 +82,9 @@ These are native key equivalents shown on buttons, not extra physical controller
 
 **Jump** opens the actual sector map above and ahead of the installed piloting room. Point at a beacon using the right controller and use the original confirmation controls. The map follows the ship's cockpit and orientation. **Close Map** returns to the encounter.
 
-Events, Store (including BUY/SELL), upgrades, crew and equipment windows float above the player ship. Their original localized controls stay interactive. Main menus remain 2D. The original HUD follows the headset; the hand panel has visual and pointing priority where it overlaps the HUD.
+Events, Store (including BUY/SELL), upgrades, crew and equipment windows float above the player ship. Their original localized controls stay interactive. Main menus remain complete, head-relative 2D views.
+
+Gameplay uses a **compact HUD anchored to the headset**, retaining native upper status and the crew roster while removing the lower weapons/reactor/system/subsystem strip. Use Power, Shortcuts or the wheel for those lower-strip actions. The HUD keeps a fixed readable size and follows the headset whenever there is room. If that movement would carry the panel into the ship or shield, it stops above the ship until clearance permits headset-relative placement again. A raised or oversized table can therefore raise the panel during overlap. The hand panel retains visual and pointing priority where it overlaps the HUD. Desktop Tactical/map inspection keeps the complete native view.
 
 To rename a ship or crew member, click its original name-edit field. A floating **QWERTY keyboard** appears:
 

docs/DEVELOPMENT.md

@@ -29,13 +29,13 @@ After installing the documented Python requirements, run from the repository roo
 python -m unittest discover -s tools -p "test_*.py"
 ```
 
-The last development revision passed **27 Python tests**. They exercise synthetic archive/layout/font extraction, bridge schema/input translation, native-pixel filtering and raw frame publication. They do not launch FTL. Temporary fixture files are created by the tests.
+The current prepared source passed **38 Python tests**, including empty native drone-list and portable-launcher 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. Godot suites and focused native checks are recorded 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 seven suites below passed in the previous configured development environment. A fresh source checkout lacks game assets; model/input/font checks may fail until local extraction is complete.
+The nine suites below passed for the current prepared source in the configured development environment, including the latest HUD/wheel/bar corrections. See [STATUS](STATUS.md) for evidence and limits. A fresh source checkout lacks game assets; model/input/font checks may fail until local extraction is complete.
 
 ```powershell
 godot --headless --xr-mode off --path . --script tools/test_combat.gd -- --demo
@@ -45,9 +45,11 @@ godot --headless --xr-mode off --path . --script tools/test_environment.gd -- --
 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 --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 suites use actual GPU rendering, so keep their graphical mode. Headless runs of them are not equivalent verification. 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.
+The UI/controller/transport suites use actual GPU rendering, so keep their graphical mode. Headless runs of them are not equivalent verification. 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.
 
 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.
 
@@ -64,6 +66,8 @@ python tools/launch.py --smoke
 
 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.
+
 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

docs/INSTALLATION.md

@@ -62,6 +62,15 @@ This creates `.venv`, installs `requirements.txt` there and copies the example c
 
 You can inspect its actions first with `SETUP.cmd --dry-run`. If the Windows `python` command opens the Microsoft Store, install Python from python.org with the Python launcher, reopen the terminal and retry.
 
+The scripts keep setup and launch failures visible when double-clicked. `SETUP.cmd` ignores the Microsoft Store Python alias. If you already have a real Python installation without a launcher or PATH entry, select it for this terminal session:
+
+```powershell
+$env:FTLVR_PYTHON = "C:\Tools\Python312\python.exe"
+.\SETUP.cmd
+```
+
+Each checkout needs its own `.venv` and `local_game_data/` configuration/assets. Cloning the repository or copying the source does not copy that ignored local setup. You may reuse the same verified isolated lab and Godot installation in the new configuration, then rerun extraction for the new checkout. Close the previous client before launching another checkout against that lab.
+
 ## 3. Prepare and activate the isolated game
 
 Check that the unpacked Hyperspace release contains:
@@ -146,6 +155,8 @@ Checks verify dependencies, local extraction, the recorded original archive, the
 .\RUN-DESKTOP.cmd
 ```
 
+`RUN-FTL-VR.cmd` and `RUN-FTL-DESKTOP.cmd` are aliases for these launchers. Options are forwarded, so `RUN-DESKTOP.cmd --check` checks the same paths and assets used by a normal launch without starting the game. For scripted checks, set `$env:FTLVR_NO_PAUSE = "1"` to disable the pause after an error.
+
 The launcher backs up the separate VR save files and lab settings, starts the isolated FTL bridge, waits for fresh live state/capture and starts Godot. It can take up to roughly one minute to establish the bridge; failure details appear in the local logs.
 
 Closing the client requests a graceful native save/exit and stops the bridge. Pre-launch VR backups are in the lab's `save-backups/` folder. Allow shutdown to finish before starting another session. Logs are in `local_game_data/logs/`. See [troubleshooting](TROUBLESHOOTING.md) and [controls](CONTROLS.md).

docs/STATUS.md

@@ -1,6 +1,6 @@
 # Project status
 
-**Prepared source snapshot:** `0.1.0-alpha.1`, 2026-10-03.
+**Prepared source snapshot:** `0.1.0-alpha.1`, 2026-10-03, with subsequent gameplay refinements described below.
 
 This is a playable experimental client connected to the real game. It is suitable for technical enthusiasts who can follow the source setup instructions and help test supported versions. A broad public release and a portable compiled installer are still future work.
 
@@ -10,21 +10,42 @@ This is a playable experimental client connected to the real game. It is suitabl
 | --- | --- |
 | Campaign | FTL runs its normal campaign, events, difficulty, combat rules, audio and saves |
 | Ships | Dynamic local layouts, extruded hull presentation, rooms, weapon mounts, opposing bows in combat and stable movable encounter placement |
-| HUD | Original native HUD follows the headset; native enemy HUD region is removed in gameplay; hand screen and pointer draw above it |
+| HUD | Compact original status/crew panel follows the headset first at a fixed readable size; lower strip removed; clamps above the transformed hull/shield only when its movement would intersect the ship; full main menus remain head-relative |
 | Navigation | Available actions only; actual sector map appears above/ahead of the pilot room and faces the viewer |
 | Menus/dialogs | Main menus remain 2D; native shop/ship windows and event choices float in the encounter; BUY/SELL panels are retained |
 | Crew | Native positions/tasks/selection, animated procedural race models, grab preview and native move orders; occupied crew face the viewer |
 | Targeting | Weapon and beam room targeting, plus native mind-control, teleporter and hacking target routing |
-| Systems | Installed-system shortcuts, modifier support and a System Power page using native allocation rules |
+| Systems | Dpad Up and a Navigation button open System Power; native capped reactor availability, storm loss and battery availability remain separate |
 | Doors | Open/closed, locked, damaged/hacked state and thin tier-dependent armor driven by native strength |
-| Combat visuals | Shields/super shields, weapon charge strips/pips, native firing/impact/projectile paths and enemy hull bar using locally imported vanilla art |
+| Combat visuals | Shields/super shields, weapon charge strips/pips, native firing/impact/projectile paths, native miss cues/pass-by presentation and enemy hull bar using locally imported vanilla art |
 | Drones | Distinct procedural space/interior families with deployment/power state and placement by native render space |
-| Hazards | Room fire/breach tiles and surrounding asteroid, sun, nebula/storm and pulsar presentations |
-| Input | Steam Frame actions, generic fallback profiles, controller infographic, action wheel and QWERTY rename keyboard |
+| Hazards | Room fire and cross-shaped breach tiles, oxygen-dependent air wisps and surrounding asteroid, sun, nebula/storm and pulsar presentations |
+| Room feedback | Native role icons and permission-aware condition colors; no floor health/status bars or counters; normal sensor fog still applies |
+| Input | Steam Frame actions, generic fallback profiles, controller infographic, equipment-name/family/ammo action wheel and QWERTY rename keyboard |
 | Lifecycle | Isolated game copy, fingerprinted hooks, separate `hs_ftlvr_` saves, pre-launch backup and graceful save/exit |
 
 ## Verification recorded during development
 
+### Latest HUD, wheel and launch corrections
+
+The gameplay HUD uses a headset-relative pose whenever it has room. Collision checks include the transformed hull/shield envelope and the panel's swept movement, so looking down cannot carry it through the ship. The wheel now handles empty native drone lists without losing equipped weapon entries. Room-floor bars and counters are removed. Launcher corrections expose failures and keep runtime files local.
+
+The current source passed **38 Python tests and nine Godot suites** in the prepared `FTL-Tabletop-VR` folder. The suites include native empty-drone-list normalization, defensive wheel parsing, headset-relative HUD placement/collision checks and removal of room-floor bars. UI, controller and frame-transport suites used actual GPU rendering on the RTX 4060 Ti.
+
+Actual `RUN-DESKTOP.cmd --smoke` and `RUN-VR.cmd --smoke` launched the isolated FTL process and Godot client, then exited successfully with clean client logs and no bridge errors. The GitHub Desktop checkout's `RUN-FTL-VR.cmd --smoke` alias passed the same combined launch/exit check. These smoke tests use desktop rendering; VR preflight passed separately. A copied save profile opened the current campaign, paused it and supplied actual Artemis Missiles and Burst Laser Mark II entries to a GPU-rendered wheel check; the drone-equipment collection was normalized to a list and bridge errors remained empty.
+
+All four original campaign hashes remained unchanged; the original save prefix/settings were restored and Steam/lab executable fingerprints remained unchanged. These checks establish the desktop-wrapper and native wheel paths. Physical Steam Frame comfort, stereo performance and clean-machine setup remain unverified for these changes.
+
+### Preceding gameplay refinements
+
+This revision introduced a compact spatial gameplay HUD retaining native status/crew controls, direct Power access, localized equipment wheel metadata, storm-aware free-power presentation, native miss feedback, cross-shaped breaches and per-room system condition presentation. Enemy system condition colors follow native information permissions. Detailed floor bars introduced in that revision have since been removed.
+
+That revision passed **27 Python tests and nine Godot suites**, including HUD-layout and damage-visual checks. Headless and Vulkan HUD checks covered crop/picking, fixed-size placement and transformed-envelope clearance; damage checks covered condition visibility, misses and breaches. Controller UI checks included localized equipment/ammo, bounded names, unchanged-content redraws and capped power/battery separation.
+
+Actual native ion-storm state was checked: **8 installed / 4 usable reactor bars, 4 raw available / 0 usable free**. Native equipped Burst Laser/Artemis titles and ammo metadata, enemy system damage/repair and breach tiles were checked. The real missed flag/event path was verified using a private native projectile and forced `Evasion.MISS`; this verifies integration, not random evasion rates.
+
+Production combined Vulkan launch/save/exit smoke passed: exit 0, clean client log, no bridge errors and a disconnected bridge. All four campaign file hashes match the fresh pre-test backup; source and packed Lua match, QA fixtures are absent, both original/lab executable hashes remain unchanged and final process inventory shows no owned FTL/Godot processes. Physical Steam Frame comfort and complete campaigns remain open.
+
 | Check | Evidence and limits |
 | --- | --- |
 | Real-game startup | Main menu, hangar, new game, event choices and combined client/bridge startup checked |
@@ -35,9 +56,9 @@ This is a playable experimental client connected to the real game. It is suitabl
 | Hacking | Enemy room targeting accepted; attachment/effect completion remains unverified |
 | UI | Native HUD during Tactical/map/store/event/ship modes; enemy-region transparency; BUY/SELL content; rename input and original fonts checked across development revisions |
 | Drones | Native equipment/special/global lists deduplicated; actual combat and interior battle-drone state inspected |
-| Automated tests | Latest source revision passed 27 Python tests and seven Godot suites before this packaging task |
+| Automated tests | Current prepared source passed 38 Python tests and nine Godot suites; UI/controller/transport checks used actual GPU rendering |
 | Desktop graphics | Vulkan rendering and model/UI inspection checked on RTX 4060 Ti 8 GB |
-| Save handling | Normal combined launch/exit and preservation of backed-up campaign data checked |
+| Save handling | Current desktop-wrapper launch/exit and copied-profile native checks preserved all four original campaign hashes |
 | Steam Frame play | Maintainer confirmed playability and substantial partial runs; latest changes need further hardware coverage |
 
 The automated suite uses synthetic fixtures for many edge cases. A passing test does not establish that every race, layout, weapon, drone, hazard or boss encounter has been exercised in a campaign.
@@ -65,6 +86,7 @@ The automated suite uses synthetic fixtures for many edge cases. A passing test
 - GOG PKG extraction works; the complete GOG executable/loader route is not verified.
 - Other headsets/controller profiles, Linux/macOS and FTL overhaul combinations are not verified.
 - Native game rules remain authoritative. VR hazard animation and some projectile/drone presentations are approximations, rather than complete reproductions of their 2D appearance or timing.
+- HUD follows the headset until a collision would occur; a raised or oversized table can then push the panel above the ship. Retest that transition physically when moving/resizing the encounter.
 - A source setup is supplied; compiled client distribution, export packaging and an end-user installer are not yet validated.
 - Python uses pinned Frida/Capstone and minimum Pillow/NumPy versions. Other combinations need testing.
 

docs/TROUBLESHOOTING.md

@@ -6,6 +6,7 @@ Start with `CHECK-SETUP.cmd`, or `CHECK-SETUP.cmd --desktop` if testing without
 
 | Symptom | What to check |
 |---|---|
+| Double-clicking the launcher does nothing | Failure output now stays open. Read the error above the prompt. Every checkout needs its own `.venv`, `local_game_data/launcher.json` and locally extracted assets; a Git clone contains source only. Complete Installation for that checkout. |
 | `python` opens Microsoft Store, or Python cannot be found | Install Python 3.10+ from python.org with its launcher, reopen your terminal and rerun `SETUP.cmd`. |
 | Missing `frida`, `PIL`, `numpy` or `capstone` | Run `SETUP.cmd` and use the repository's `.venv` Python. Installing into another Python environment will not satisfy the launch wrappers. |
 | Package installation fails | Check the pip output and internet connectivity. Python 3.12 is the development baseline. Setup does not download game dependencies. |
@@ -19,6 +20,8 @@ Start with `CHECK-SETUP.cmd`, or `CHECK-SETUP.cmd --desktop` if testing without
 | Resolver reports a missing/ambiguous signature | Use the matching win32/1.6.9 signature directory from Hyperspace source, with all neighboring `.zhl` files. Do not use other people's hook addresses. |
 | Recorded original installation unavailable | The bridge still reads the original `ftl.dat` for newly encountered ships. Restore that location or rebuild the lab/config against the new installation. |
 
+To use a real Python installation outside PATH, set `FTLVR_PYTHON` to its executable before running `SETUP.cmd` (see Installation). These scripts do not use the Microsoft Store alias. Set `FTLVR_NO_PAUSE=1` only when calling the launchers from an automated script that captures their output; otherwise failures remain open so they can be read.
+
 ## Launch and VR
 
 | Symptom | What to check |