Capture current mission, AI, map and administration development

Include the current addon, terrain integrations, tools, regression tests and recorded development evidence.

docs/configuration.md

@@ -1,7 +1,121 @@
 # Base mission configuration
 
+Field-site population is configurable under **Forces → Configure sites**.
+`fieldCampCount` accepts 1–16 (default 12); `fieldHospitalCount` accepts 1–8
+(default 6). Both apply next round. Existing settings files missing these keys
+receive the defaults. Commands: `/esc mission camps set N` and
+`/esc mission hospitals set N`. Defaults request 26 mission sites; maximum counts
+request 32, while retaining the required objective and radio-clue sites. Actual
+placement can omit unsuitable optional sites. Sites remain hidden until discovery
+or intel, except the existing initial clue markers.
+Above eight camps and hospitals combined, sites share the original field-force
+budget of 32 fixed guards and 16 mobile soldiers. Increasing the number of sites
+adds locations and supplies without increasing that soldier budget.
+
+On added terrains, the initial airport survey processes up to eight 2 km tiles
+per generation update, yielding after 4 ms of query work (a native query already
+in progress finishes first). This avoids a separate 250 ms wait after every
+cheap tile. All airport candidates are still surveyed; ground, navigation and
+helicopter-clearance checks remain required. The main log records the survey
+duration once, followed by spawn-ready and background-completion timings.
+These timings exclude the engine's initial terrain loading and any startup
+switch from the configured scenario to the selected terrain.
+
 The independent Core scenario loads `Configs/ERR/VanillaFactions.conf` through `ERR_GameMode.m_FactionDefinition` and `Configs/ERR/EveronSites.conf` through the scenario component. Both are successor resources. Changing a configuration requires restarting the scenario; the live round is not repopulated.
 
+## Starting weapons and ammunition
+
+The admin menu **Mission** page has **Starting pistols** (0–12, default 5)
+and **Starting spare magazines** (0–48, default 8). These are totals in the
+shared prison/crash supply backpack, not per-player allowances. Magazines are
+the existing PM 8-round type; the count excludes ammunition loaded in weapons.
+The map remains in the backpack, including when both counts are zero.
+
+Press **Apply** to save each value for the next round. Existing backpacks are
+not refilled. Older configurations receive the original defaults automatically.
+The values are `mission.startWeaponCount` and `mission.startMagazineCount` in
+`$profile:Escapists.json`. Chat equivalents are `/esc mission startweapons set N`
+and `/esc mission startammo set N` (also `show` and `help`).
+
+## Roadblocks
+
+The admin menu **Settings → Roadblocks next round** sets `mission.roadblockCount`
+in `Escapists.json`: **0–12**, default **4**; **0 disables** them. The chat equivalent
+is `/esc mission roadblocks set N` (also `show` and `help`). Changes apply on the
+next round/restart, leaving current units and cover in place.
+
+These are simple roadside checkpoints: two sandbag positions and four soldiers
+from the selected enemy faction. They use normal equipment rules and physical
+radio reporting to VirtualHQ; HQ can send their squad to respond to contacts.
+They do not reveal player locations to HQ merely by being created. Soldiers and
+cover are owned by the round; killed guards are not replaced.
+
+Placement uses the loaded terrain's road network and Soldiers navmesh before
+player admission. Posts stay at least 600 m apart, 700 m from the prison and any
+controlled player body, 150 m from mission sites and outside settlement centres.
+Elevated bridge segments, narrow roads, steep or obstructed shoulders are rejected.
+Cover stays outside the travelled road to preserve vehicle passage. The requested
+count is a maximum: a bounded search skips unsuitable posts and logs placed versus
+requested totals instead of preventing mission startup. The admin Status page
+also shows these totals. This is an interim checkpoint system, independent of the
+existing HQ-directed road interceptions.
+
+## One server configuration
+
+All mission preferences now live in **`$profile:Escapists.json`** on the server.
+It is created automatically on the first start of this build. The admin menu
+reads and saves this same file; changing a setting preserves the other sections.
+Edit the file while the mission is stopped, then restart to load manual changes.
+
+| Section | Contents | Imported from on first start |
+| --- | --- | --- |
+| `mission` | Gameplay, HQ, time, weather, view distance, helicopter timer | `rereintroduced.json` |
+| `mods` | Content and faction-pack switches | `EscapistsContent.json` |
+| `factions` | Player, enemy and independent role choices | `EscapistsFactions.json` |
+| `terrain` | Selected next-start scenario | `EscapistsTerrain.json` |
+| `items` | Item rules and named presets, including dormant rules for absent mods | `EscapistsItems.json` |
+| `voice` | Original welcome clip (`welcomeUrl`), speech bridge URL/token (`briefingUrl`, `briefingToken`), optional `ttsEnabled` | `EscapistsWelcomeVoice.json` |
+
+The admin mission menu's **TTS** page can test and save the speech bridge settings
+without a restart. Only a successful test enables the new settings; an empty or
+disabled setup leaves the original welcome behavior unchanged. Google credentials
+stay on the speech host. See [speech setup](welcome-voice-test.md).
+
+During an active Escape round, the original surviving player body is reserved
+for at least 15 minutes after a disconnect, including a client crash. A longer
+native `operating.slotReservationTimeout` is respected, as is its unlimited
+setting. Rejoining with the same authenticated account returns control of that
+body, keeping its inventory, injuries and vehicle seat. It stays vulnerable while
+the player is away. Expiry, death or a different round does not grant a replacement
+life or duplicate equipment. This is recovery within the running mission, not
+saved characters across server restarts. Reconnect reservation, rejection and
+successful handoff are logged without account identifiers.
+
+The root has `"configVersion": 1`. Missing legacy files get defaults. Existing
+valid values are imported, using a valid `.bak` if the old primary is damaged.
+If neither copy is valid, migration logs the filename and leaves the originals
+untouched; repair that file before retrying. Legacy files are retained for
+rollback, but are ignored once `Escapists.json` exists. They can be archived after
+verifying the migration. Do not edit them expecting the new build to reload them.
+
+`Escapists.json.bak` is the last valid configuration before a successful update;
+`.tmp` is only a write staging file. Neither is a separate configuration to
+maintain. Writes are read back before and after promotion, and a valid backup
+allows recovery from a damaged primary. Unsupported schema versions are kept
+read-only. Unknown fields and preferences for absent mods are retained.
+
+A malformed known section also prevents unrelated menu changes from being saved.
+This preserves the last valid backup instead of replacing it with damaged data.
+Repair invalid sections while the mission is stopped; a valid replacement for the
+only damaged section can also be saved through its existing menu. Successful repair
+keeps the good backup, and subsequent ordinary saves resume normal backup rotation.
+Missing optional sections still use defaults, and unknown fields remain intact.
+
+Server host settings (ports, passwords and the Workshop mod list), cloud
+credentials, and authored faction/site assets remain with their respective
+systems. The welcome helper serves its cached clip independently; only its
+public audio URL belongs in the mission configuration.
+
 ## Factions and assets
 
 The catalog explicitly selects the player faction, enemy faction, prisoner character, guard group and extraction helicopter. Current defaults are unarmed US prisoners, Soviet guards and the vanilla unarmed Mi-8 transport. Both factions must exist in the world's faction manager and consider one another hostile. Required prefab resources must resolve. The extraction resource must be a helicopter with a pilot position and at least twelve pilot/passenger seats; invalid extraction setup rolls back prepared sites before players spawn. Guard groups must have the catalog's enemy affiliation; an incompatible group is rejected rather than relabelled.
@@ -20,14 +134,15 @@ Open the normal game chat and enter a command. Core provides:
 | `/esc killais` | Server administrator | Kill AI characters within 1,000 m of your living character; preserve players and vehicles |
 | `/esc settings` | Server administrator | Current shared settings and values |
 | `/esc mission keepweapon set 0` / `1` | Server administrator | Disable/enable retaining the held firearm while unconscious and equipping it after revival; applies from the next knockout |
+| `/esc mission traffic set N` | Server administrator | Set 0–6 civilian traffic cars, default 3; 0 disables new traffic. Also on the Factions menu page. Distant-only cleanup and claimed-car preservation remain active. |
 | `/esc mission radio show` | Server administrator | Radio defence duration in seconds |
 | `/esc mission radio set N` | Server administrator | Save a whole-number duration from 30 to 1800 seconds |
 | `/esc mission time show` | Server administrator | Current clock and saved next-round time/speed |
 | `/esc mission time set HH:MM` | Server administrator | Save next-round start time, 00:00–23:59 |
 | `/esc mission speed show` | Server administrator | Current clock and saved next-round time/speed |
 | `/esc mission speed set N` | Server administrator | Save next-round time progression, 1–24× |
-| `/esc spectate next` | Spectating player | Select the next surviving friendly player |
-| `/esc spectate previous` | Spectating player | Select the previous surviving friendly player |
+| `/esc spectate next` | Spectating player | Select the next friendly teammate; use round-owned bodies when no eligible survivor remains |
+| `/esc spectate previous` | Spectating player | Select the previous friendly teammate or fallback body |
 
 The server derives administrator status from the requesting controller's authenticated player ID. Clients cannot send an administrator flag through the RPC. Requests are limited in length and rate; malformed numbers and out-of-range values leave the previous setting intact. Saved values belong to the server profile, not client profiles. Changing radio duration affects the current defence calculation, so configure it before starting the transmission.
 
@@ -41,8 +156,9 @@ Additional AI commands:
 | --- | --- |
 | `/esc hq memory` | Show bounded delivered-report beliefs, confidence, uncertainty and travel estimates |
 | `/esc hq aa show` / `/esc hq aa set N` | Enemy MANPADS grant chance, 0–100% or Random; default 7% |
+| `/esc hq equipment show` / `/esc hq equipment set N` | Automatic catalog equipment attempt chance, 0–100% or Random; default 25%; [details](enemy-loadouts.md#automatic-equipment-from-installed-mods) |
 | `/esc hq mines show` / `/esc hq mines set N` | Enemy AP-mine grant chance, 0–100% or Random; default 60%, up to two carried mines |
-| `/esc hq stinger show` / `/esc hq stinger set N` | Legacy alias for anti-air percentage, now 0–100 rather than one-in-N |
+| `/esc hq stinger show` / `/esc hq stinger set N` | Legacy alias for anti-air percentage, 0–100 or `set random`; `show` displays Random; no reroll of existing soldiers |
 | `/esc hq convoy show` | Show the finite deployment task, retained vehicles, native cargo insertion results and stop reason |
 | `/esc hq convoy start` | Deploy the next unused slot in this round’s configured convoy allowance after physical force admission |
 | `/esc convoys show` | Show the saved count and active fleet |
@@ -87,6 +203,24 @@ faction, the enemy that controls HQ, and the other hostile faction.
 
 **Keep weapon when unconscious** has explicit Enabled/Disabled buttons on Mission. It defaults to Enabled and applies from each player’s next knockout. With it enabled, the same gun is retained and re-equipped after revival; Disabled restores the normal ground drop. Unconscious and dead spectators use **Left/Right arrows** to change teammates.
 
+When no eligible living teammate remains, arrows cycle through the current
+round's surviving corpses, including your own, until the round ends. Corpses are
+selected from the authenticated round roster even after their controllers detach;
+AI corpses and bodies from other rounds are excluded.
+
+**Enter** switches between orbit and the living teammate's actual camera pose.
+Their client supplies position, look direction, roll, vertical field of view and
+near clipping distance; the server forwards samples only to their current
+authorized spectators. This follows whichever normal player camera the teammate
+uses, including their own third-person selection. It does not copy their HUD,
+picture-in-picture scope rendering or player-only weapon animation.
+
+Samples are sent at up to 20 Hz only while requested, interpolated relative to the
+replicated body, and discarded after a 350 ms gap. Corpses, unavailable streams
+and other camera modes such as Game Master use the orbit fallback. Native head
+and helmet fading prevents looking through the target's face and is restored on
+view changes. This is a synchronized camera view, not a latency-free video feed.
+
 The Journal normally shows sentences with real server-local clock time
 (`HH:MM:SS`), event numbers and radio message numbers. Timestamps are captured
 when events occur and stay unchanged when history is opened or resumed. It distinguishes local sightings, reports awaiting transmission,
@@ -186,3 +320,15 @@ Enemy equipment percentages affect soldiers whose initial loadout has not yet be
 **Factions → Random all** immediately saves Random for all three roles; no second Apply is needed. Random remains saved after closing the menu and is resolved afresh at each round startup. Current factions stay unchanged until the next round. Individual dropdown edits still use **Apply factions**.
 
 The 2026-09-23 native `prisoner-kit` fixture verified that Random all saves via the authenticated owner RPC, survives a fresh settings load and menu reopen without Apply, and preserves current-round faction roles. It completed 357 assertions without script/runtime failures; installed external resource errors still make the engine report non-clean. Regression coverage is in `test_faction_menu.py` and `test_faction_selection.py`.
+
+Civilian traffic uses `mission.civilianTrafficCount` in the same configuration. See [civilian traffic](civilian-traffic.md) for routes, observer distances and vehicle ownership.
+
+## Optional Cessna patrol
+
+`planeReconEnabled` defaults to `1`: use Cessna 172 only when it and Propeller
+Flight Core are loaded on a dedicated server. **HQ → Configure Cessna** provides
+Enabled/Disabled buttons and Apply fields for patrol altitude (150–500 m, default
+250), replacement delay (30–1800 s, default 60), and new patrol area interval
+(30–600 s, default 120). All save for the next round. `/esc mission plane set 0|1` uses
+the same admin authorization. No loaded addon or no safe airport means no plane.
+See [reconnaissance plane details](cessna-reconnaissance.md).