EscapistsReintroduced/docs/civilian-traffic.md

Civilian road traffic

Unarmed civilians drive ordinary S105 cars and S1203 vans along the terrain's roads. This is ambient life, separate from enemy convoys and VirtualHQ: drivers receive no enemy loadouts, intelligence or pursuit orders.

The admin menu's Factions page has Civilian traffic (0–6 cars). The default is 3. Set 0 to stop new traffic; existing unclaimed cars retire only when the normal distance and visibility checks allow it. The same setting is available as /esc mission traffic set N and mission.civilianTrafficCount in the unified server Escapists.json. Old configurations receive the default automatically.

After the prison phase, the server tries one new car every 30 seconds, with at most eight route candidates per attempt. Each fixed route starts on a clear road at least 1,000 m from every controlled player body and known spectator target, passes a road near the selected player area, then leaves along another road. Exit candidates include both sides of the area so a coastal road does not require an endpoint across water. It is not redirected to follow moving players. Positions come from the current terrain's road network; terrain-specific adapters are unnecessary. Roads and usable native vehicle navigation are still required.

Creation requires blocked sight lines to the vehicle's roof and ends. Terrain/collision and all observer checks are repeated after resource loading. A missing observer/controller, an unknown spectator target, or any open editor camera suspends spawning and cleanup. Vehicle occupants are excluded from their own sight-line obstruction checks.

Completed, stalled, failed or excess traffic is deleted only when both car and driver are at least 1,500 m from all observers and hidden for a sampled 60-second grace period. Moving traffic beyond 2,200 m can also retire. Managed cars and drivers are protected from native garbage collection until the traffic service safely retires them or releases ownership. A dead driver still uses the distant-cleanup rules. The service samples every five seconds. A nearby observer, visible car or unknown view resets the grace period. No timeout teleports or deletes a nearby car. With no connected players, unclaimed traffic can retire after the same grace period.

Entering a car permanently releases it from traffic control and automatic deletion, even if the player immediately gets out. Unexpected crew, group/faction changes or additional passengers also release it. Released cars retain their population slot for that round, bounding accumulated vehicles and preventing continual replacement of taken cars. The fleet has a hard six-record limit and at most 64 attempts that reach native entity creation per round. Road-planning failures consume neither a slot nor a creation allowance. Round shutdown clears orders and leaves physical entities for world teardown.

A ready car that makes no 10 m of progress gets at most two route retries per lifetime: the first after 60 seconds without progress, the second after 120 seconds. Retries recreate only the remaining fixed stops, preserve the old orders if replacement creation fails, and reactivate the native group. The car retires after 180 seconds without progress; distance and visibility safeguards still apply. The progress clock starts when driving orders are ready, rather than consuming that allowance during driver admission.

CIVILIAN TRAFFIC journal events record the car number and prefab, readiness problems, assigned orders, movement, retry destinations and retirement reasons, as well as created routes, player entry and distant deletion. No new timer, network request or player-position report is sent to HQ.

Validation: tests/test_civilian_traffic.py executes the production ownership, observer, update, distance and cleanup methods. Native evidence is recorded separately under docs/evidence/civilian-traffic-2026-10-04; the isolated fixture supplies a stationary observer rather than a real multiplayer client. Native driving and retirement do not qualify multiplayer camera rendering or every terrain.

Final 2026-10-04 validation: all 315 registered checks passed. The final isolated Nogova run compiled with no script errors, verified native garbage protection and a neutral unarmed seated driver, observed more than 25 m of real road driving, and completed unclaimed retirement after the observer left and the production grace period elapsed. Earlier three-car runs verified physical fleet creation and recorded-claim preservation. Other terrain/resource warnings remain; no clean-all-logs or multiplayer claim. See evidence.

2026-10-05 driver readiness: native AI is activated before waiting for asynchronous compartment seating. The original living civilian driver can receive a native boarding task if still outside the car; vehicle registration precedes that recovery. No driver replacement or teleport is used. Boarding is cancelled on readiness, failure or player claim. The existing 120-second readiness deadline and distant-only retirement policy remain. Logs distinguish missing/incapacitated drivers, group admission, vehicle registration, and boarding. A hidden native comparison on Everon confirmed that deliberately unseated drivers stayed idle with the old preparation path, then boarded and drove with the updated path; the exact trigger of the live server’s initial seating failure remains unproven.