Add configurable nearby garage vehicles and fix roadblocks and fuel pumps; record Workshop 0.0.131

docs/configuration.md

@@ -44,9 +44,10 @@ in `Escapists.json`: **0–30**, default **4**; **0 disables** them. The chat eq
 is `/esc mission roadblocks set N` (also `show` and `help`). Changes apply on the
 next round/restart, leaving current units and cover in place.
 
-Each checkpoint has two defensive bays built from eight sandbag walls, four
-approach barriers, two anti-vehicle obstacles, two stop signs, a small rest tent
-and an inspection table. Four soldiers come from the selected enemy faction. They use normal equipment rules and physical
+Each compact checkpoint has four sandbag walls, two approach barriers and two
+stop signs. The props span about 9 m across a 6 m road and 17.8 m along it;
+four guard positions sit immediately behind the sandbags. Four soldiers come
+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.
@@ -413,3 +414,28 @@ arrive while the screen is open. Different maps are counted separately using
 their loaded world resources. Startup failures, empty restarts and interrupted
 sessions are excluded. Community totals show unavailable if reporting is disabled
 or delivery fails; local round statistics still work.
+
+### Parked civilian vehicles
+
+Open **Admin menu → Mission → Civilian vehicles**. Each garage control has an **Apply** button and saved-value display; changes apply next round.
+
+| Control | Range | Default |
+| --- | --- | --- |
+| Nearby garage vehicles | 0–24; 0 disables | 16 |
+| Garage selection chance | 0–100%; 0 disables | 70% |
+| Spawn radius | 250–1500 metres | 1000 m |
+| Time between spawns | 5–60 seconds | 5 s |
+
+The additional saved keys are `mission.garageChancePercent`, `mission.garageRadiusMetres` and `mission.garageSpawnIntervalSeconds`. Chat equivalents are `/esc mission garagechance set N`, `/esc mission garageradius set N`, and `/esc mission garageinterval set N`.
+
+In **Mission → Civilian vehicles**, set **Nearby garage vehicles** (or `/esc mission garagevehicles set N`). `mission.garageVehicleCount` defaults to 16, accepts 0–24, and applies next round. Zero disables placement. This is a shared limit on **unclaimed nearby vehicles**, not a lifetime limit of 16 across the island. Every fourth vehicle attempts an optional unarmed WCS motorbike when its dependencies are loaded; otherwise cars fill the slots.
+
+As players explore, the server discovers native `Garage_E_01` and `HouseAddon_Garage_E_01` buildings within the configured radius. Each garage uses the configured selection chance, rolled once on discovery. A bay must be at least 35 metres from every player body/spectator target, hidden by scenery from all of them, dry and collision-free. Open editor cameras or unknown observer targets suspend spawning and retirement. Adjacent suitable garages can both contain vehicles; the old 150-metre spacing and whole-island survey are gone. Custom garage models are not currently supported.
+
+Discovery, candidate checks, prefab loading and creation run as separate updates, every 250 ms. Each update scans at most one 500-metre cell, maintains one vehicle, checks one physical bay, loads one prefab, or creates one vehicle. Native creations respect the configured delay, with a minimum of five seconds. Prefabs stay cached for later spawns. Native resource loading and entity creation are indivisible calls, so this limits bursts rather than guaranteeing zero frame spikes.
+
+Vehicles have 30–80% fuel and no AI crew. Entering a vehicle permanently preserves it, including after exiting. Occupants or movement beyond three metres also protect it as a fallback for missed entry callbacks or towing. Its original garage is then consumed for the round, preventing repeated vehicle farming. Used vehicles do not occupy the nearby unclaimed allowance. A separate limit of 128 retained-plus-current vehicles bounds accumulation during unusually long rounds; it never deletes used vehicles.
+
+An untouched vehicle can be retired only when it is at least 1,400 metres from every known observer (or the configured spawn radius plus 400 metres, whichever is larger) and hidden for a sampled 60-second grace period. Returning nearby, gaining visibility or losing observer information cancels that grace period. Retirement frees a nearby slot for the players' new area; an unused garage can become eligible again on a later visit. Unclaimed cars are maintained one at a time. The discovery cache is capped at 16,384 cells and 2,048 garages per round. Vehicles still incur ordinary physics and replication costs.
+
+Validation: [menu settings and round persistence](evidence/garage-vehicles-2026-10-30/menu/report.json), [nearby garage spawning and retention](evidence/garage-vehicles-2026-10-30/nearby/report.json), plus production-method observer, lifecycle, settings and menu tests.