EscapistsReintroduced/docs/terrain-takeover.md

Automatic Escape on added terrains

For a universal starting scenario, select Co10 Escape Reintroduced — Automatic terrain from this mod:

{C1E20667DCE324ED}Missions/ERR_Everon.conf

This is the existing full Escape scenario with its original resource ID and path, now named for its role as the universal launcher. Existing server configurations using that ID continue to work. The duplicate Base diagnostic header is no longer shipped. Servers using its retired {AD62322D5213C440} ID must select the main entry above; the diagnostic tools already use it. It starts on Everon when no terrain override is saved, so administrators can always reach the Escape menu. Add the desired terrain to the server's mods, select one of its scenarios in Terrains, save, and restart. The existing saved selection loads that map and Escape creates its mission there. No AMP-specific settings, external startup helper, connector addon or changes by the terrain author are needed.

The published scenario name and description now identify Escape itself. After a terrain switch the public browser can retain Automatic terrain; this entry intentionally does not name a map that may no longer be running. It is not a fix for dynamic backend metadata refresh. The runtime title on a taken-over terrain still follows the loaded map. Server owners currently starting with a terrain's Exploration/Game Master scenario must select the Escape entry once to use this registration identity. An addon update cannot change that choice for them.

Launcher validation reached the prison phase both on default Everon and after following a saved Nogova selection. The native title callback returned the terrain-neutral launcher name before switching. These private tests used no backend; public listing and Workshop metadata still need verification after publication.

The original direct-terrain route remains supported: add Escape and a terrain, then select an existing scenario supplied by that terrain. For Nogova that is:

{469880DFE1B48F95}Missions/Nogova_TerrainTest.conf

In a standard server configuration, the selected entry is game.scenarioId. Select a mission header (Missions/*.conf), not the terrain's world resource. Installing multiple terrains does not choose one automatically. With no saved selection, the server's configured scenario remains the default; only the Automatic terrain entry defaults to Everon. Workshop 0.0.45 predates automatic takeover. Publish the updated Escape core to expose the new launcher name and description; the mission resource ID is unchanged.

Before publishing the updated core, reopen/rescan the project in Workbench so Prefabs/ERR/TerrainTakeover.et and its metadata enter the resource index. An old cache can include the script but still fail to register the replicated prefab. This is a publishing check, not a server-admin setup requirement.

In-game terrain selection

Game Master keeps Reforger's normal administrator permissions after takeover. Escape transfers the editor core's player registration, disconnect, spawn, death, deletion and role-change listeners from the original game mode to the replacement before replaying admissions. Without this transfer, an admin on an exploration scenario could have a disabled Game Master button because the editor still listened to the removed mode. The transfer retains existing editor managers and does not grant Game Master to ordinary players. After replaying admissions, Escape also checks already-connected players, creates only missing editor managers, and reapplies native role-derived modes. This covers registration that happened before the new game mode attached its listeners. The repair now waits for a valid, distinct controller replication identity (a dedicated server’s temporary local identity is not a player). Editor creation is idempotent during takeover, so the subsequent native registration event reuses the manager instead of registering it twice. Missing managers are retried up to 80 times at 250 ms intervals; retries touch only missing editors and are cancelled at detach/world shutdown. A later registration may start another repair window. The pause menu refreshes the Game Master button from native editor availability: vanilla can leave it disabled when an administrator's mode arrives while the menu is already open. These repairs do not assign administrator roles or preserve a login that the server revoked during restart.

The native loading-screen updater also follows the replacement respawn manager. This keeps the spinner and mission-preparation text updating after takeover, including when the original scenario disabled its deploy-menu updater. A pending spawn-loading overlay releases on victory/defeat and cannot hold the result screen underneath it.

Escape's default end-of-round reload delay is ten seconds. The native server -autoreload override still applies, including disabling automatic reload. Terrain loading and procedural preparation happen after that delay and can take substantially longer on large islands.

The editor handover check passed five native Nogova checks and the focused regression tests. It exercises event delivery on a playerless server; a connected administrator clicking the pause-menu button remains an in-game verification step.

Open the Escape administration menu and choose Terrains. Select a scenario and press Save terrain. Saving leaves the current round running; the saved scenario takes effect after a normal mission restart or a full server restart. Changing terrain disconnects connected players without a ban: rejoin after the new map has loaded. Reforger otherwise makes connected clients reload the old world while the server loads the new one. Restarting on the same terrain does not use this extra disconnect.

The list is discovered on the server from enabled mods' scenario catalog and mounted Missions/*.conf resources. It lists scenario entry points, so an island can appear several times. Prefer an exploration or Escape scenario; discovery alone does not certify its navigation or compatibility. The selector does not download or enable additional mods. Add the terrain to the server first.

Use server default, then Save terrain, removes the override. With no selection, Escape continues using the server's configured scenario, including Nogova; its administration menu remains available after takeover. For a fresh server, select Co10 Escape Reintroduced — Automatic terrain as the initial entry point:

{C1E20667DCE324ED}Missions/ERR_Everon.conf

The server still needs a valid initial scenario to start the engine. A script cannot provide a menu if startup fails before a world loads. Forcing Everon on all unconfigured servers would also replace an administrator's valid existing terrain selection unnecessarily.

The override is stored as terrain.scenario in $profile:Escapists.json (with a shared .bak backup). Only authenticated administrators can save a discovered scenario. A removed or unavailable saved scenario falls back to the configured server scenario and shows a warning. Corrupt preferences are preserved for inspection; removing or repairing the terrain section, then restarting, restores editing. See unified configuration for migration and backup recovery; do not remove the whole file just to clear a terrain choice. Startup redirects are bounded and do not repeatedly reload an unreachable destination.

Native test evidence covers discovery, save authorization, persistence, restart, disconnect and rejoin on Everon. The menu screenshot uses a labeled offline presentation fixture.

Placement and requirements

Escape prefers detected airfields. If there are no airport markers, standard runways or control towers, it surveys a clear helicopter landing zone instead. Nogova's painted runway therefore needs no administrator coordinates. Every candidate still passes terrain, navigation, slope and aircraft-clearance checks; a missing airport does not allow an unsafe spawn. Searches have finite time and attempt budgets and never fall back to coordinates from another map.

Terrain-generated placement allows up to 48,000 candidates or 120 seconds per site, whichever comes first, keeping the existing cooperative 8 ms work slices. Airport-only extraction searches broaden after 12,000 candidates or 30 seconds without resetting that total budget. The fallback surveys the terrain for a helicopter landing zone and retains the normal primary/secondary aircraft clearance and navigation checks.

Extraction pads do not use the camp-only 12 m road exclusion, and their initial ground survey uses the same 0.8 m height variation limit as the landing-zone survey. Camp footprints retain their 0.6 m limit and road exclusion. Aircraft clearance is tested at the centre's actual terrain height, matching pickup registration, rather than the lowest point sampled across the camp grid. Water, physical obstacles, guard/patrol ground and navigation, the 28 m landing footprint, overhead clearance and additional transport-pad checks still apply.

Dry ground is determined from the terrain's actual water surface, not a fixed world-altitude minimum. Site clearance queries water at every sampled terrain height instead of testing placeholder candidate heights. Dry terrain below one metre (including negative map elevations) can qualify; submerged terrain, invalid heights, excessive slopes and physical obstructions remain rejected. Site creation, character spawn slots, airfield pads and mortar setup use the same terrain-height water check, without the 10 cm character spawn lift.

On terrain-generated maps, prison-to-airport separation is 15% of the shorter world axis, clamped to 200–1,500 m (300 m on a 2 km map). This changes tactical spacing, not the physical footprint or slope allowance. Original authored Everon placement retains its 1,500 m airport buffer and existing search/fallback rules. Maps without sufficient clear ground or a working Soldiers navigation mesh can still fail preparation. See placement validation.

Search diagnostics use the Reintroduced [placement search] log prefix. Each summary identifies the site, attempts and elapsed milliseconds, with counts for failed or deferred checks: water, uneven ground, obstacles, road/airport distance, site spacing, navigation and aircraft clearance. Summaries appear on completion, exhaustion and airport fallback, plus every 30 seconds during a long search. Counts describe checks rather than unique candidates: a candidate awaiting a navigation tile can be checked repeatedly. Mandatory placement failures also include the site and rejection summary directly on the loading screen, so no chat command is needed. The same detail remains available in mission status.

On startup failure, a local ChimeraMenuBase error menu provides Return to main menu and Pause menu (Esc / Back). The loading placeholder is hidden while an interactive menu or dialog is available, so it cannot cover native pause/exit controls. Existing menus keep focus; ordinary preparation retains its loading overlay. Returning uses the native local gameplay-end transition and does not admit players or change the failed mission state. If the custom menu cannot open, the native pause menu is the fallback.

The selected scenario must supply SCR_BaseGameMode, a usable Soldiers navmesh, world bounds spanning 1–100 km on both axes, and enough clear navigable ground. Navigation remains the terrain author's responsibility. A plain exploration scenario is the recommended starting point. Arbitrary scripted scenarios can retain their own tasks and entities; saved campaigns and every third-party game mode are not qualified. Escape disables further saving when taking over; it does not delete existing saves. Existing authored Escape scenarios and editor worlds are left on their normal startup path.

Displayed mission name

Automatic takeover reports Co10 Escape Reintroduced - through the native server mission-name callback, for example Co10 Escape Reintroduced - Armenhof. Once takeover is confirmed, the running world and its root scene supply the terrain name, even if the source header still refers to the original island. Before confirmation, an incoming header cannot pick up the outgoing world’s name. Before loading, the header's world resource is used: parent containers are followed where available, with conventional scenario prefixes/suffixes removed when packed resources hide their parents. Internal Eden is displayed as Everon. Unknown custom naming can fall back to the world filename; the selected next-round terrain never replaces the current round's label. Once takeover succeeds, the server and clients receiving the Escape bootstrap also display that mission name and game mode Escape in their runtime header. The terrain's scenario ID, world, imagery and Workshop entry stay unchanged; those still identify the terrain scenario used to load the map. Existing authored Escape titles are preserved.

Presentation is refreshed every half second after confirmation, including when the same header already says Escape and its root scene only becomes available later. The native mission-name callback refreshes it too. Repeated refreshes compare world paths as strings: GetWorldFile() can return $Addon:Worlds/..., and calling ResourceName.GetPath() on that path each tick caused repeated zero-GUID resource warnings. GUID prefixes are stripped as text, and parent-resource resolution runs only when the cached terrain input changes. The native comparison reproduced 80 repeated warnings over 20 seconds before this correction and zero afterward, with the same terrain title and scenario resource. The loading screen refreshes its existing title widget, so copying the header before the Escape bootstrap no longer leaves the original scenario name on screen. It accepts the current header or another copy of that same scenario; other incoming scenarios retain their own titles. Loading progress, descriptions, imagery and hints keep their native lifecycle.

The original runtime name and game-mode label are restored on world cleanup, so restarting with takeover disabled cannot inherit the Escape label. Clients wait for the actual Escape bootstrap instead of guessing from locally enabled mods. The public server-browser listing can retain the startup terrain after an in-process terrain redirect. A live RKS #2 check on 2026-10-04 confirmed Chernarus was loaded and its runtime title updated, while the browser still showed the initial Nogova scenario. The earlier runtime and loading-title checks did not prove public listing refresh. Starting the server directly with the selected terrain in game.scenarioId avoids this initial-terrain redirect; verify the public listing after changing it. See live browser follow-up. The name-change evidence records server and client metadata across restart, including the retained respawn-order diagnostic. Terrain suffix validation checks the real Armenhof callback, Nogova/Everon resolution and title restoration. Live-title refresh evidence adds native Nogova checks for an already-presented stale title and a stale Everon world header, plus executable loading-widget and late-root regression checks. This later run is headless; it does not visually qualify the loading screen or verify the public backend cache.

A subsequent registration investigation ran two isolated native experiments. Rehosting with RequestPublicServerTransition from gameplay was explicitly rejected as an unsupported transition. Writing a replacement World through a cloned header container did not change the engine's selected world. Neither experiment provides a universal registration fix. No supported scenario-registration setter was found in the inspected script interfaces. A portable pre-launch integration remains an external setup option to investigate; it is not implemented here and would not by itself replace the loader scenario's published Workshop metadata.

Optional overrides

To keep the original scenario while Escape remains loaded, pass -errTerrainTakeover 0, or set the mission-header field m_bERR_EnableEscape to false, then restart. The CLI override takes precedence; only its exact value 1 enables takeover when explicitly supplied. With no overrides, takeover is enabled.

Optional airport-centre hints use -errAirfields "1525 5075" or the header field m_sERR_Airfields. Use X/Z pairs separated by semicolons, up to 16 centres. Hints must be on dry land inside the terrain and do not bypass clearance checks. An explicitly supplied CLI hint takes precedence over the header. Empty hints use automatic discovery and the landing-zone fallback.

Validation of the automatic default

Production-method regressions exercise default activation, editor/authority protection, opt-out precedence, airport discovery and bounded placement. Native Nogova server/client evidence is recorded in evidence/automatic-terrain-takeover-2026-10-02. The no-flags Nogova test completed two takeovers and two prison phases across a connected restart, with all 16 sites and a supported, fueled helicopter in each round. Client manager checks passed with no client script errors. The evidence report retains server authentication refusals and installed-resource diagnostics; it is not a clean-release verdict. A freshly built package also reached the prison phase on Nogova without flags, loose Escape source, test probes or script errors. Its 351 payload files matched the authored source. Packaging's strict resource/shutdown failures remain recorded separately. Authenticated prisoner spawning, late joining and reconnecting still require a published-build multiplayer check; offline backend-disabled tests cannot prove account admission. Publication and live-server changes remain with the owner.

Handover behavior and earlier validation

• Invalid airport syntax, terrain bounds, navigation or missing bootstrap assets are rejected before the original mode is stopped.
• The old mode ends before deletion. Its catalog and data-collector references are released. Once native registrations clear, the replacement is created in the same update, avoiding a period with no mode to create joining players' controllers. A 10-second deadline bounds unexpectedly deferred registrations.
• The original radio manager is retained, detached first if its parent is being removed. A missing radio manager is created from the standard game prefab.
• The private Prefabs/ERR/TerrainTakeover.et triggers client cleanup. It releases only the captured original singleton components, waits for the new factions before catalog/identity initialization, and receives the server's faction delegates. The terrain's native chat service is retained on both peers, detached from any removed entity/replication parent, and never replaced or attached to the new mode. The ordinary authored connector retains its own chat service. If the terrain has no chat service, TerrainTakeoverWithChat.et supplies a non-streaming replicated chat child instead. Selection depends on service presence, not terrain name; both variants share the same takeover mode.
• Arsenal, group, support-station and task managers release the original mode's cached instances on both peers. Task, map-marker and respawn getters resolve the current takeover mode even if an old destructor clears a shared cache.
• Faction delegates use a paired serialization prefix to bind their faction before the base deserializer reads faction data. Both peers must load the same Escape build, including when using an ordinary authored Escape scenario.
• Old faction delegates are removed explicitly because vanilla creates them as standalone entities. The new mode, managers and delegates are linked in the replication hierarchy so delegates cannot arrive before their prerequisites.
• Native player admission events received during handover are held and replayed only for the same connected controller and account. No backend identity or authentication event is fabricated. Disconnect and world cleanup clear the queue.
• Existing controllers resolve spawn handlers on the replacement Escape mode.
• World cleanup clears the handover state and configured centres. Local native restart has passed in Workbench, on an empty Linux dedicated server, and with a separate connected Windows client. The connected test recreates the player's controller and verifies the replacement managers in both rounds.

On 14 October, the original Everon client log showed delayed removal of the original ScriptedChatEntity after the replacement registered, followed by Cannot send message - ChatEntity is missing. This blocked native chat commands, including administrator login, before authentication. test_terrain_chat_retention.py checks shared-service retention, nested parent detachment and fallback selection. The revised scripts compiled in Workbench; the authored-world native restart smoke completed two rounds and 21 assertions with no script/runtime failures. That run still reported existing engine/dependency errors, and the full repository check stopped on the existing missing root ID in ERRM_AtlasLeaf.et. Live remote login and takeover of both chat variants remain separate verification steps; the authored-world smoke does not exercise those paths.

The earlier isolated prototype passed a Nogova Workbench prisoner-spawn test with 16 generated sites and zero script errors. See prototype evidence. The current feature has additional configuration, readiness and admission checks. It passed native offline spawning and an actual scenario restart: two prisoner spawns, 16 sites per round, zero script errors, and all handover state cleared between rounds. Invalid configuration was also rejected before stopping the original mode. Repository checks passed. See the feature test report.

Earlier opt-in builds required enable flags and airport hints. The following results describe those builds, before the automatic default and landing-zone fallback.

The command-line listen-server route did not apply either custom mission-header overrides or the standard m_eSaveTypes override. Its diagnostic read the original defaults and left Nogova's mode running. Consequently the example server JSON used in those tests still needs testing through the actual dedicated-server route. A read-only copy of the RKS 2 engine executables was subsequently authorized and completed. The dedicated JSON route could not complete addon/backend initialization with external networking disabled. The explicit CLI route did load Nogova, generate 16 sites and reach the prison phase with zero script errors on the Linux server. The dedicated server also passed an actual scenario restart, cleared the takeover state and reached the prison phase again, with zero script errors. Both dedicated checks used an empty server.

Subsequent tests used the final takeover files on the same frozen core baseline, with a real Windows client joining the isolated Linux server through a localhost relay. Client manager replication, catalog/identity faction references and radio retention passed. A real scenario restart cleared both peers' takeover state, recreated the client's controller and reached the prison phase again. No client script errors occurred. The backend-disabled server correctly withheld soldier spawning for missing account identity, so these checks do not prove authenticated prisoner spawning. Native delayed-unregistration diagnostics and existing resource errors remain in the raw logs. No RKS 2 configuration or running process was changed.

A separate disconnect/reconnect test passed with two successive client launches against the same server and no client script errors. That run preceded the final replication-hierarchy change; the final hierarchy was then tested through a fresh client join and a connected restart. Radio preservation when attached to the old mode, and creation when missing, passed separate authority-only fixtures. These fixtures change the loaded test world in memory, not the terrain's source files.

The separate Nogova connector and authored integration remain available in the existing integration instructions. Do not delete them from a deployment that still selects their mission header.