Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ staged checks pass.
| Read | For |
| --- | --- |
| [Plan](docs/PLAN.md) | Game design, architecture and phased development |
| [Field-kit verification](docs/FIELD_KIT_RESULTS.md) | UI, Survey Log, numbered groups and movement checks |
| [Conventions](docs/CONVENTIONS.md) | Code structure and contribution checks |
| [Art style](docs/ART_STYLE.md) | Visual identity and Blender asset generation |
| [Audio style](docs/AUDIO_STYLE.md) | Sound identity and the synthesis pipeline |
Expand Down
9 changes: 9 additions & 0 deletions docs/ART_STYLE.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,3 +61,12 @@ slope, height and world-space noise, so any heightfield is shaded for free.
- A `-col` suffix on an object name makes Godot generate a static collider.
- Materials are swapped on import by name (`fl_palette`, `fl_terrain`) in
`game/presentation/import/model_post_import.gd`.

## Interface

Concord field equipment uses steel-blue chamfered plates, subtle outlines and
cyan instrument lamps. Orange marks warnings. `HudStyle`, `PlateStyle` and
`HudTheme` provide the shared controls; `UiTheme` applies the stock-control theme
before screens are built. Chakra Petch supplies body, button and heading weights.
Its SIL Open Font Licence is bundled under `game/assets/fonts/OFL.txt`, included
in exports and displayed in Credits.
8 changes: 4 additions & 4 deletions docs/AUDIO_STYLE.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ loudness targets and the naming, and says how to add a sound.
| `discovery_resolve_biological` | breathy reeds gliding D A B G#, the G# turning up to A in a trill, chirps around it: alive |
| `discovery_resolve_antecedent` | the whole motif on bells, chime and reed over a Lydian swell, then its answer A C# rising to the high D (−20, 6.2 s) |
| `discovery_resolve_enemy` | the motif bent: D A Bb on ring-modulated Combine saws, the last note sagging G# → G with a growl |
| `ui_codex_open` / `_close` / `_entry` | two marimba notes up / down; the motif's last step B → G# on glass with a paper flick |
| `ui_survey_log_open` / `_close` / `_entry` (files `ui_codex_*.mp3`) | two marimba notes up / down; the motif's last step B → G# on glass with a paper flick |
| `ui_intel_tick`, `ui_option_button` | a tiny glass tick on A6; a click with a glass G# above it (spending Intel) |
| `field_orbital_scan`, `field_supply_drop`, `field_antecedent_power` | a sonar sweep from orbit with data rain; a falling pod, a landing thump and a D–A chime; reversed bells swelling into a strike on D and G# |
| `advisor_discovery`, `advisor_field_option_ready` | Meridian dyads D+A → A+D (the ship heard it too); G#+D twice, lifting into A+D |
Expand Down Expand Up @@ -1116,9 +1116,9 @@ first, −9 dB after it, 0 dB when all are found), via `MusicDirector.set_layer_
keep it at 0 (explore), −3 (calm), −8 (tension), −4 (aftermath), −6 (victory), silent in
combat and defeat. `intel_changed` for the player plays `ui_intel_tick` when Intel rises (the
first report is the baseline); `field_option_used` plays `field_<id>` (ids containing
`antecedent`/`scan`/`supply`/`drop` fall back to the three effects); `codex_entry_added` plays
`ui_codex_entry`. Codex open/close and the option button are `Events.ui_feedback(&"codex_open")`,
`&"codex_close"`, `&"option_button"`. Advisor kinds `discovery` (priority 70, throttle 4 s) and
`antecedent`/`scan`/`supply`/`drop` fall back to the three effects); `survey_log_entry_added` plays
`ui_survey_log_entry`. Survey Log open/close and the option button are `Events.ui_feedback(&"survey_log_open")`,
`&"survey_log_close"`, `&"option_button"`. Advisor kinds `discovery` (priority 70, throttle 4 s) and
`field_option_ready` (45, 20 s) are raised by gameplay as ordinary `advisor_alert`s.

Base loops (`BaseLoops`) sit on the player's entities, at most six, nearest first, hums ranked
Expand Down
74 changes: 74 additions & 0 deletions docs/FIELD_KIT_RESULTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Field kit, Survey Log and control-group verification

The interface now uses shared steel-blue plates with cut corners, cyan instrument
lamps and Chakra Petch. `HudStyle` and `HudTheme` define the look; `UiTheme` applies
it to stock controls. The font's OFL notice is included in every export and Credits.

The player-facing discovery journal is the **Survey Log**. Discovery save keys and
the saved `codex` key-binding action remain unchanged so existing progress and
custom keys load. Resource paths for discovery definitions also stay the same.

## Numbered groups

- Ctrl/Cmd + 1–9 stores; the plain number recalls; a quick second press centres the camera.
- Alt/Option + number also stores when the browser reserves Ctrl/Cmd for its tabs.
- Shift + number adds the selection, or starts an empty group.
- A badge shows the group number and living count. Click recalls; right-click replaces it.

Observed in the running Godot game through real mouse/key input: select unit 43,
Ctrl+1 stores it, click unit 44, plain 1 selects 43 again. The browser test stores
multiple units with Alt+1, adds another with Shift+1, deselects and recalls the
same members with plain 1 and the badge. Unit tests also cover Ctrl/Cmd, macOS
Option characters, dead members, saved groups and sticky Shift.

## Checks observed locally

| Check | Result |
| --- | --- |
| `tools/check.sh` | Format/lint, 746 gameplay tests (7997 assertions), 416 real-time audio tests (6372 assertions), boot and all 11 mission smoke tests passed |
| Python build/deployment tools | 13 tests passed |
| Chromium hardware gameplay | 24 cases passed |
| Chromium software WebGL, explicit Performance profile | 23 cases passed |
| Screen qualification at 2000×754 | 100% and 130% UI scale passed through title, settings, help, controls, credits, missions, briefing, campaign, star map, Meridian, tech web, loadout, HUD, Survey Log and pause screens |
| Campaign browser route | Launch, save, reload and Continue passed |
| Overlay layering | Tutorial cards hide under pause and Survey Log, retain their state and return afterward; both native checks and real browser input passed |
| Exports | Web, WebDiagnostics and macOS release exports succeeded |

The hardware/software full browser suites preceded the final modal and narrow-strip
fixes; focused screen/campaign qualification and native geometry checks cover them.
After review, a blocked-segment regression failed before the guard and passed
after it (41 focused native tests, 209 assertions). Three repetitions each of
construction/save recovery and legacy graphics retention passed after their
layout/fixture timing fixes. CI gates the combined release on the latest commit.
At narrow sizes the command strip stays between selection and minimap panels;
its horizontal scrollbar keeps later commands reachable. A real browser check
selects a Fabricator at 1152×648 / 130% UI, stores all nine groups, drags the scrollbar to
Survey Lab and enters placement. Native geometry checks cover the same layout.

No game balance statistics were changed. One commander test previously required
both retrieval members to die along a particular route through gunfire. A member
can now escape, so that test forms the squad and applies losses explicitly before
checking larger squads, delay, surviving reserves and persistence.

## Movement measurements and limits

[ADR 0022](adr/0022-traffic.md) records the traffic rules, reproducible benchmark
and measurements. Contacts use the next integration positions, slow queues still
look for close blockers, idle friends make room, and route shortcuts require a
clear segment. No frame-dependent RVO callback drives ground movement.

The final stress run settled 202/202 units near their reachable endpoints in
147.6 simulation seconds; 201 were within one body radius and all were within one
body width plus clearance. Its sim tick measured mean 4.50 ms, p95 6.24 ms on M4.
This is a dense-queue stress result, not a browser FPS or exact formation-lock
promise. The old idle-only arrival counter could count a unit waiting to return
to its post, or one that had given up far away; the new report distinguishes them.

Run the optional browser screen matrix with:

```sh
WEB_UI_QUALIFY=1 WEB_CAMPAIGN=1 npm test -- ui_style.spec.cjs campaign.spec.cjs
```

Run it from `tools/web_tests` after `tools/export.sh Web WebDiagnostics`.
Evidence is retained locally under `build/evidence/field-kit/` and in CI artifacts.
12 changes: 11 additions & 1 deletion docs/PERFORMANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,8 @@ world's tick).
2.2 ms).
3. **Tell the navigation server only what changed.** Units set their RVO position,
velocity and priority only when they differ from the last value sent: most units
stand still most of the time.
stand still most of the time. (The RVO agents have since been replaced by
Traffic, ADR 0022.)
4. **Quieter signals.** A weapon re-announces its aim only when the aim point moved
more than 0.2 m (the visual eases toward it anyway).
5. **Skip idle systems.** The stealth pass does nothing when no unit hides and no
Expand Down Expand Up @@ -91,3 +92,12 @@ cut (~40): 490–710 ms in the middle of play. `NavmeshPathService.prepare_flood
now does that while the landing loads, so a switch only applies the cuts made since.
Path searches may visit up to 65 536 polygons (the server's default of 4096 cut long
detours short), which costs more only for long or unreachable targets, once per order.

## Ground traffic and arrival accuracy (2026-11-15)

Ground avoidance now runs on simulation ticks (ADR 0022). See
[traffic measurements](adr/0022-traffic.md) for the 26/64/202-body results and the
arrival definition. In accelerated headless runs the benchmark reports simulation
seconds; its frame monitor values are not real-time rendering FPS. Arrival also
waits for idle units to finish returning to their posts and verifies proximity to
the path endpoint, rather than treating every stopped order as success.
12 changes: 6 additions & 6 deletions docs/PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ Section 9 records the decisions taken with the project owner.
2. **Landing.** Your dropship, the Lander, sets down and *becomes your HQ*. Build a base, harvest, produce units.
3. **Explore.** The map is full of things the orbital scan could not resolve. Scanning them earns **Intel** and often changes the mission: a shortcut, a resource bonus, a dormant machine, a weakness in the enemy base.
4. **Resolve the objective** — which is not always "destroy the enemy".
5. **Return to orbit** with Intel, artefacts and codex entries. New route options open.
5. **Return to orbit** with Intel, artefacts and Survey Log entries. New route options open.

**What makes it its own game: Intel is the third resource, and you can only get it by looking.**
Alloy and Flux come from harvesting. Intel comes only from discovery. It is spent two ways:
Expand Down Expand Up @@ -77,7 +77,7 @@ Three knowledge states per map cell: **charted** (orbital scan: terrain shape on
| Antecedent | Scanning ruins, recovering caches | Tech-web branches that cannot be bought any other way |
| Enemy | Observing Combine structures unseen | Their build state, patrol routes, a weak point |

Every discovery writes a short **codex** entry. Larger finds are multi-step: a ruin points to a second site, which needs a unit you may not have yet. Some cannot be completed on the first visit, which is a reason to return to a planet.
Every discovery writes a short **Survey Log** entry. Larger finds are multi-step: a ruin points to a second site, which needs a unit you may not have yet. Some cannot be completed on the first visit, which is a reason to return to a planet.

### 2.5 Planets

Expand Down Expand Up @@ -135,7 +135,7 @@ farlanding/
campaign/ Star map, ship, tech web, persistent state
presentation/ Camera, selection visuals, VFX, fog rendering
audio/ Audio service, music director, sound-event map
ui/ HUD, menus, codex
ui/ HUD, menus, Survey Log
data/ .tres definitions: units, weapons, techs, discoveries, planets, missions, sounds
assets/ Exported models, textures, audio (generated — never hand-edited)
maps/
Expand Down Expand Up @@ -216,7 +216,7 @@ Sound gets its own track in every phase rather than a pass at the end, because i
| Movement | Engine/servo loops per chassis, footfalls for walkers |
| Buildings | Placement, construction loop, completion, idle hum, production, destruction |
| World | Planet ambience bed, positional spot sounds, weather, hazard warnings |
| Discovery | Signal pulse, scan loop, resolve stingers per type, codex entry |
| Discovery | Signal pulse, scan loop, resolve stingers per type, Survey Log entry |
| Stealth | Suspicion rising, alert, all-clear |
| Music | Adaptive score per planet (below), ship theme, victory and defeat |

Expand Down Expand Up @@ -271,8 +271,8 @@ Each phase ends in something playable and has all three tracks. A phase is done
- **Done when:** a full Conquest match against the AI is winnable, losable and fun. *Milestone: the classic loop works.*

### Phase 4 — Exploration and Intel
- **Code:** orbital-scan layer, signals, Surveyor scanning, discovery definitions and payoffs, Intel, Survey Lab field options, codex, Custodians.
- **Art:** discovery sites, Antecedent ruins kit, scan effects, codex illustrations.
- **Code:** orbital-scan layer, signals, Surveyor scanning, discovery definitions and payoffs, Intel, Survey Lab field options, Survey Log, Custodians.
- **Art:** discovery sites, Antecedent ruins kit, scan effects, Survey Log illustrations.
- **Audio:** signal pulse, scan loop, resolve stingers, the Trail motif, explore music.
- **Done when:** playtesters detour to find out what a `?` is without being told to. *Milestone: the game has its identity.*

Expand Down
20 changes: 16 additions & 4 deletions docs/PLAYER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Detailed controls and mission rules follow, including planet-specific mechanics.
shows the route of landings: hover one for its orbital scan (planet, rule, mission
type, unresolved `?` signals), click an open one and press LAUNCH. A won landing banks
the Intel you still hold when it ends (a lost one banks nothing, but its finds stay in
the codex) and opens the landings it leads to; the route branches, and taking one side
the Survey Log) and opens the landings it leads to; the route branches, and taking one side
closes the other. On the Meridian (MERIDIAN on the star map) spend banked Intel on the
tech web: clear the Survey Lab, Lancer, Sentry and Arc, upgrade Haulers, scanners and
optics; some techs need an Antecedent find from an earlier landing. Pick a loadout
Expand Down Expand Up @@ -40,11 +40,19 @@ Field notes explain each new thing the first time you meet it.
| Left click (classic scheme) | select, and command by context: move, attack, harvest, scan, build, carry, rally |
| Right click (classic scheme) | deselect, cancel placement or aiming |
| Shift | add to selection, queue orders |
| Ctrl+1–9 / 1–9 | store / recall a control group |
| Alt+1–9 (Option on a Mac) or Ctrl/Cmd+1–9 | make the selection a control group (browsers keep Ctrl/Cmd+number, and on Linux Alt+number, for their tabs) |
| Shift+1–9 | add the selection to that group, or start it: works in every browser |
| 1–9 | select the group again · twice: centre the camera on it |
| WASD, arrows, screen edge, middle drag | pan · wheel: zoom · Q/E: turn |
| C | codex · F1: all controls · F3: debug overlay |
| C | Survey Log · F1: all controls · F3: debug overlay |
| F5 / F9 (native), K / L (Web) | quicksave / quickload |
| Esc or P | pause menu: resume, save, load, settings, how to play, restart, quit |
| Esc or P | pause menu: resume, save, load, settings, how to play, controls, restart, quit |

Each control group shows as a badge above the selection panel (bottom left): "1 · 5" is
group 1 with five units. Click a badge to select the group (twice to centre on it),
right-click it to make the current selection that group; it
lights up when the group is stored or added to and goes away when its last unit is lost.
**Controls** (title screen and pause menu) lists every mouse button and key in one page.

These are the default keys: every one can be rebound per mouse scheme under
Settings > KEYS (a key already in use is named, and pressing it again swaps the two).
Expand All @@ -62,3 +70,7 @@ resolution scale, "Reset hints"), ACCESSIBILITY (team colour palettes for red-gr
and blue-yellow colour blindness, subtitles for the Advisor and their size, interface
size 100/115/130%, fewer flashes, sticky Shift, game speed of single missions) and
KEYS. **How to play** and **Credits** are on the title screen.

On narrow windows or larger interface scale, the command strip scrolls sideways
to keep the minimap and selection information clear. Drag its scrollbar or use
horizontal scrolling to reach later build and production options.
1 change: 1 addition & 0 deletions docs/WEB_DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ npm ci
npx playwright install chromium
npm test
WEB_BROAD=1 npm test
WEB_UI_QUALIFY=1 npm test -- ui_style.spec.cjs
WEB_AUDIO_QA=1 npm test -- --grep real-mixer
WEB_PERFORMANCE=1 npm test -- --grep 233-unit
WEB_BROWSER=firefox npm test
Expand Down
2 changes: 1 addition & 1 deletion docs/adr/0004-unit-navigation.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# 0004 — Unit navigation: navmesh + group corridors + server RVO

- Status: accepted
- Status: accepted; decision 3 (server-side RVO) was replaced by ADR 0022 (Traffic)
- Date: 2026-11-12

## Context
Expand Down
13 changes: 7 additions & 6 deletions docs/adr/0009-discovery-and-intel.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

PLAN §1 and §2.4 make Intel the third resource, earned only by looking: Surveyors scan
discovery sites, each discovery type pays out something felt in play, every discovery
writes a codex entry, and Intel is spent at the Survey Lab on field options. Custodians
writes a Survey Log entry, and Intel is spent at the Survey Lab on field options. Custodians
(§2.1) guard Antecedent sites. All of it must follow §3.3: data-driven definitions, one
command path, sim talks outward only through `Events`, saveable state, and an enemy
commander that gains nothing from what the player finds.
Expand All @@ -17,7 +17,7 @@ commander that gains nothing from what the player finds.

| Resource | File | Holds |
|---|---|---|
| `DiscoveryDef` | `core/defs/discovery_def.gd`, `data/discoveries/*.tres` | type (`geological`, `biological`, `antecedent`, `enemy`), Intel reward, scan time, radius, `leads_to` (chain), codex title/text, one payoff kind with its numbers, glow colour |
| `DiscoveryDef` | `core/defs/discovery_def.gd`, `data/discoveries/*.tres` | type (`geological`, `biological`, `antecedent`, `enemy`), Intel reward, scan time, radius, `leads_to` (chain), log title/text (`log_title`, `log_text`), one payoff kind with its numbers, glow colour |
| `FieldOptionDef` | `core/defs/field_option_def.gd`, `data/field_options/*.tres` | effect (`reveal`, `supply_drop`, `strike`), Intel cost, cooldown, `requires_unlock`, effect numbers |
| `UnitDef` additions | `scan_rate`, `scan_range`; `starts_dormant`, `wake_radius`, `guard_radius` | Surveyor scanning; Custodian dormancy |
| `BuildingDef.field_options` | `data/buildings/concord_survey_lab.tres` | Options a building offers |
Expand All @@ -41,8 +41,8 @@ kind is a few lines in `Discovery._apply_payoff()`.
anything that ends the order (new order, stop, death, being pushed aside); with no
scanner left the progress is lost. Several scanners add up.
- `Discovery` (`sim/systems/discovery/discovery.gd`, service `discovery`) is a SimWorld
child ticked after units: it resolves sites (Intel, codex, `discovery_made`,
`codex_entry_added`, payoff, chain), runs heal fields and the player's view of sites.
child ticked after units: it resolves sites (Intel, Survey Log, `discovery_made`,
`survey_log_entry_added`, payoff, chain), runs heal fields and the player's view of sites.
`FieldOptions` (same folder) keeps unlocks and cooldowns per faction and applies
effects; `FieldOptionCommand` (receiver: an operational lab offering the option) is the
only way to use one. `field_option_used` fires on use, the Advisor's
Expand Down Expand Up @@ -78,8 +78,9 @@ commands and when a click selects or deselects). The cursor is drawn in code
## Consequences

- Discoveries are cheap to add; payoff kinds are deliberately few and need code.
- A scan in progress is not saved (it starts over); sites, the codex, unlocks, cooldowns
and heal fields are. Reveals that follow an entity end on load.
- A scan in progress is not saved (it starts over); sites, the Survey Log (saved under
the key `codex`), unlocks, cooldowns and heal fields are. Reveals that follow an
entity end on load.
- The Custodian faction joins the vision round robin, so with three factions each grid
updates about 3.3 times a second instead of 5. Acceptable at this scale; revisit if the
fog feels sluggish.
Expand Down
Loading
Loading