EscapistsReintroduced/docs/configuration.md

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–30, 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.

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 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 after terrain/site preparation. The initial search yields after 12 seconds; unfinished placement continues in small background steps while players are connected, including while the prison is locked and after escape. 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. All prop footprints preserve a straight vehicle passage at least four metres wide. 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.

Šárka special-forces hunters

Under Forces → Šárka hunters, set Anger points per Šárka from 1 to 30. The default is 3. Each wave requests the current anger divided by this value, rounded down: a value of 5 gives no car below 5 anger, one at 5–9, and two at 10–14. Zero disables new waves; already deployed cars and crews remain. Each car carries four special-forces soldiers, including a medic. Changes apply to the next wave; the existing interval and placement rules remain unchanged.

The saved key is mission.sarkaAngerPerCar in $profile:Escapists.json. The command is /esc mission sarkapoints set N (also show and help). Older sarkaCarsPerAnger settings migrate to the new default of 3 when enabled; an old zero remains disabled. An explicit new key takes precedence. The old sarkacars command is retired to avoid silently reversing its meaning.

Mission restarts

The admin menu Mission page includes two independent settings:

• Restart after last disconnect: Enabled or Disabled, default Enabled.
• Restart while empty (hours): 0 disables the idle timer; 1–168 sets the number of real hours continuously empty. Default 5. Press Apply to save.

Both apply immediately and persist in $profile:Escapists.json as mission.restartOnEmpty and mission.emptyRestartHours. Older configurations receive the enabled/five-hour defaults. The idle interval starts with a new mission or the last disconnect and resets whenever players connect. Connected spectators and players loading in also prevent an empty-server restart. Changing the interval uses the time already spent empty. Normal victory/defeat and no-survivor endings still apply when these options are disabled.

Chat equivalents are /esc mission restartempty set on|off and /esc mission emptyhours set N; both also support show and help.

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, bundledSpeech (default true), recordingsEnabled (default true; TTS menu prerecorded speech On / Off)	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.

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.

This provides an injection boundary, not automatic support for arbitrary addons. A different faction also needs matching characters, inventories, world manager configuration and companion support compositions. The current mortar crew remains a vanilla Soviet composition and rejects a different enemy faction.

Supply/guard placement and finite stock are described in site authoring.

Administration

Open the normal game chat and enter a command. Core provides:

Command	Access	Effect
/esc status	Server administrator	Current objective or startup failure cause; adds HQ status when Chat is loaded
/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 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.

Clock settings apply once at the next round startup; changing them does not jump the current clock. Older valid settings files load the new defaults (14:00, 1×) without being rewritten. See mission time.

AI and Intel register their own providers with the Core command service; the full Chat scenario loads both. Existing HQ interval/squad/radius and Intel carrying/reveal aliases remain available, as do hq show and hq log. They use the same authenticated authorization path.

Additional AI commands:

Command	Effect
/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
/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, 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
/esc convoys set 0..20 / /esc convoys set random	Save the next round’s convoy count; default 3; also available on the Mission page

Convoys automatically deploy after prison escape by default, travel between friendly military bases, and use the original infantry dismount/flank/reboard behavior. Each has six vehicles, 25 soldiers and finite random faction-arsenal cargo. Startup and losses consume slots permanently. The existing automaticConvoyEnabled=0 preference remains respected. See Supply convoys for configuration, timing and validation limits.

The command parser and setting mutations have native service tests. Actual remote RPC ownership, chat usability and pre-spawn presentation still need multiplayer/UI acceptance.

Failed preparation

If the faction/catalog setup or authored site preparation fails, the mode retains the reason, stops its services and refuses progression or spawning. It does not fall back to a partially prepared mission. A local hint describes the failure and /esc status gives administrators the cause. Correct the resource/configuration and restart the scenario. There is no automatic retry that recreates stock or forces after failure.

Waiting for normal site preparation does not consume a player's spawn retry budget. Once ready, actual failed spawn requests are bounded. This does not remove the one-life or identity requirements.

Core also provides /esc mission abandon: an administrator-only explicit defeat and normal restart for an active round. See recovery policy.

Mission menu

Esc → Co10 Escape Reintroduced opens one administrator menu. Its top navigation stays visible on every page:

Page	Controls
Mission	Radio defence duration, next-round convoy count and unconscious weapon retention
World	Start time, Random day, time speed, date and weather
Factions	Escapists, enemy and independent faction choices; Random all
Mods	Content pack and individual faction switches
HQ	Report interval, support squad limit, response radius, anti-air percentage and AP-mine percentage
Intel	Document frequency, exact-reveal chance, summary and reroll
Status	Scrollable live mission and service status
Journal	Readable HQ activity, technical-detail toggle, pause/resume and jump to latest

Changing pages preserves drafts and never applies them. Escape returns to Mission; a second Escape closes the menu (an active text edit consumes Escape first). Server authorization and capability checks still control every mutation.

Each of the thirteen value fields includes a short explanation of its effect and when it applies. Equipment percentages affect newly equipped soldiers; time, weather and convoy settings apply next round. The faction page distinguishes your 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, received reports and delivered orders. Show technical details also displays the original records, including elapsed seconds, coordinates, identifiers and diagnostic fields; switching views preserves history and the live cursor. The server journal file contains each readable summary followed by its unchanged technical record. Status labels explicitly identify mortar readiness, identified-body aggression and the total UAZ deployment allowance.

Validated on 2026-09-23 with the complete repository checks and the isolated native prisoner-kit fixture (359 assertions, no script/runtime failures). Native checks cover all thirteen description bounds using DPI-correct measurements, eight-page navigation and the readable/technical journal toggle without cursor/history loss. The fixture still reports existing installed-content resource/keyword errors; this is local Workbench validation, not a dedicated-server multiplayer test.

Optional content

Use Esc → Co10 Escape Reintroduced → Mods for server-admin RHS and individual faction switches. Selections apply after mission restart, while Workshop dependencies remain loaded. See content packs and the modder registry.

Random settings

The numeric and world settings on Mission, World, HQ and Intel have a Random button. It selects the draft; press Apply to save it. You can still enter a fixed value. The start-time row also offers Random day.

• Random start time: any whole minute from 00:00 through 23:59.
• Random day: a whole minute strictly between the island's sunrise and sunset, calculated after the selected date is applied. If no daylight interval is available, preparation fails rather than silently starting at night.
• Random date: any valid date in the world's authored year (1900–2050), including leap days where applicable.
• Random weather: clear, overcast or rain, with equal probability.
• Other fields: a uniformly selected integer within the range displayed beside the field, including zero where allowed. Random speed uses 1–24×.

The server retains the Random choice in its profile and selects a fresh value for each mission instance. Reads and menu polling reuse that value. Applying the same Random choice again does not reroll it; changing to a fixed value and then back to Random does. Live settings retain their existing apply timing; clock, calendar, weather and speed still apply only on the next round. Saved Random values for live settings also show the resolved number in the menu.

Text commands accept random in place of any of these ten values, for example /esc hq squads set random or /esc mission weather set random. Time additionally accepts /esc mission time set random day (or random-day). Existing numeric, clock, date and named-weather values remain supported. Storage uses -1 for Random and -2 exclusively for Random day; these are saved modes, never concrete values passed to gameplay or the world clock. Existing settings files keep their fixed choices without migration or an automatic rewrite.

Generated camps and map discovery

Everon generates a fresh clear-terrain prison, radio camp and four mortar sites each round. Partial intel shows question marks; exact discoveries use site icons. The prison is never marked. See generated sites and debug commands for placement limits, authoring fields, failure behavior and validation.

/esc cheat intel is an administrator-only command that places six fresh intel folders on clear ground within about 4.3 metres of the current living prisoner. It requires being on foot on terrain with enough nearby space. All six positions are checked first; a spawn failure removes the partial batch. Picking up the folders uses normal intel discovery and the configured reveal chance.

The initial prison patrol contains 3–5 soldiers, chosen once during preparation from the selected enemy faction roster. An existing RTO is retained. If that roster has no large radio, one soldier is equipped with a physical manpack (US/USAF: AN/PRC-77; otherwise R-107M). Preparation waits for that radio to be present. The guards start at separate random clear positions 12–24 m around the prison and remain frozen until it is unlocked; other site squads keep their configured size.

Airfield extraction and site icons

Everon extraction uses the airfield pad at 4800.953 / 11487.412. Site authors set RequireAirfield 1 and AircraftOffset 0 0 0 on that extraction definition. Preparation checks airfield anchors, terrain and clearance before creating the aircraft, and refuses an invalid pad without relocating it elsewhere.

Identified sites use helicopter, radio, artillery, building, medical and supplies icons. Partial intel shows a question mark at an approximate position; the prison remains hidden regardless of discovery. The western guarded UAZ/crate site is removed; the medical stash provides the second radio-intel source. See implementation and validation.

See mortar intel, original messages and perimeter guards for the four-site configuration and validation.

Permanent radio security

Radio sites require a guard squad. HQ permanently reserves that squad for the radio's 20 m defend area; it cannot be dispatched on searches, reinforcements or courier work. The generated Everon radio and table sit inside a full-size tent, with standing room for interaction. See radio camp security.

Everon also sets ScoutCount 10 in its scenario definition. This creates ten finite hilltop sniper/scout posts with radio-equipped ammunition packs; see hill scouts for terrain criteria, loadouts and reporting. Other authored scenarios default to zero.

Search helicopter: heliTimerMinutes defaults to 15 minutes after prison escape and after aircraft loss. Use /esc hq heli show, /esc hq heli timer set 15, or /esc hq heli return. See search-helicopter.md.

Enemy equipment percentages affect soldiers whose initial loadout has not yet been rolled. They do not replace authored equipment or replenish dropped/looted items. Mines are carried, not automatically planted. See enemy loadouts for faction launcher selection and fallback.

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 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.

Starting backpack contents

Open Items → Starting backpack in the admin menu. Select a loaded mod, choose Show items, browse its catalog pages, choose an item and save its total quantity. Saving the same item again replaces its quantity; zero or Remove item removes it. Weapons, matching magazines and medical supplies can be selected explicitly. The saved-content dropdown lists every selected item and its quantity.

Select Custom loadout to use that list for the next prison or crash start. The shared field map is always included. Default loadout restores the existing pistol and magazine count settings without erasing your custom list. Existing backpacks are never refilled or changed by these edits. Enemy item permissions and probability weights do not change this explicit starting loadout.

The list permits up to 32 different items, 48 of one item and 64 total items, plus the map. The physical backpack still has limited capacity: unavailable items and items that cannot be inserted are omitted and logged. Add matching magazines explicitly; selecting a weapon does not automatically add spare ammunition. Settings persist in the startBackpack section of Escapists.json. Older configurations keep the default loadout.