EscapistsReintroduced/docs/terrain-adapters.md

Universal terrain connector

Server owners normally use automatic terrain takeover: load Escape and the terrain, select the terrain's existing scenario, and start. No connector or terrain-author changes are required. The authored connector below remains an optional way to provide a dedicated Escape scenario.

The reusable connector ships in Co10 Escape Reintroduced:

{8FB1559AE3F29722}Prefabs/ERR/TerrainConnector.et

It is an Escape game-mode prefab with terrain-independent placement enabled and the shared perception, faction, loadout, radio and chat managers attached. It inherits Escape's player spawning and game rules. It contains no terrain path, airport coordinates or navigation files. All terrain scenarios reference this same resource, so updates to the setup ship with Escape.

Terrain authors can include it in a scenario inside their own terrain addon. Players then need Escape and the terrain, with no separate connector download. Adding Escape as a dependency does make it a required download for that terrain addon, including its other scenarios. Authors who want to keep the terrain independent can still publish their Escape scenario as an optional standalone addon using --standalone.

October 1 validation: the same connector loaded on Nogova and Everon, placed all 16 sites and spawned a player soldier on both. Repository checks passed. Both native runs used a frozen core snapshot, had zero script errors and retained 13 resource/schema engine errors. Terrain/source files were unchanged; Workbench rebuilt its resource database cache. These are local startup checks, not dedicated multiplayer or full-escape qualification. See the Nogova report and Everon report.

Include it in a terrain

1. Add Escape 2528466DE220D91C to the terrain project's dependencies.
2. Create a subscene of the bare terrain, then place exactly one Prefabs/ERR/TerrainConnector.et. Do not add another game mode or duplicate its managers. Keep the terrain's configured AI world, or add its navigation setup if the base terrain does not contain it.
3. Create the scenario's mission header pointing to this subscene, using {C50579A2EC48E8EF}Configs/Systems/MissionSystems.conf for systems.
4. Add airport markers only where automatic detection is insufficient, as below.
5. Publish the terrain and select this Escape scenario on the server.

The generator below creates steps 2–4 from a small terrain profile. It does not edit the terrain project or its dependency list. The ready Nogova export is in terrain-integrations/nogova/; see Nogova publishing.

Escape has a terrain-independent placement path. It uses the loaded world's bounds and navigation to place the prison, radio, caches and finite enemy sites. Extraction is surveyed on an airfield, or on a clear helicopter landing zone when no airport is detected. The existing Everon scenario keeps its authored extraction and fallback rules.

Reforger still needs a scenario subscene and mission header on each terrain. Installing a terrain addon alone does not change the world in the selected mission. The universal connector does not replace Conflict or Game Master in an existing scenario. Escape itself has no dependency on any custom terrain.

Terrain-owned navigation

Navigation belongs in the terrain addon. No navigation files are generated, copied or shipped by this change. After the terrain author publishes them, a profile can use inherit_ai_world: true if the root terrain already contains its configured AI world, avoiding a duplicate manager. Otherwise it can reference its configured SCR_AIWorld prefab (ai_world) or its Soldiers, BTRlike and LowRes resources (navigation). Each project accepts one .nmn, or a native .conf which can itself include the terrain's mesh patches. Use the bare terrain world as the parent, not another game mode's scenario. Choose exactly one navigation source: inherited AI world, prefab, or resource references.

terrain-profiles/nogova.json now inherits the configured AI world in Nogova's root navigation.layer. It requires the updated Nogova release containing Prefabs/NGR/AIWorld_Nogova.et and its three navmeshes. The mainland airport marker is at X=1525, Z=5075: the centre of the original runway texture cells covering X=1500..1550, Z=4450..5700. Height and safe pads are surveyed at runtime. This scenario deliberately selects the mainland airfield rather than the offshore northern strip. It is visible in the scenario menu.

Native startup on 2026-09-30 placed all 16 sites, qualified the fueled extraction helicopter, stocked all 10 hill scouts, reached the prison phase, and spawned a player soldier. The terrain and core source hashes stayed unchanged during that run. This is local Workbench evidence, not a dedicated multiplayer/full-escape qualification. See evidence/nogova-2026-09-30-startup/report.json and the publishing instructions.

Airfield identification

The mission detects standard physical runway and control-tower prefabs. Custom meshes, painted runway textures and arbitrary map labels are not reliable airport identifiers. For such maps, put a GenericEntity at each airport centre and name it ERR_Airfield_0, ERR_Airfield_1, up to ERR_Airfield_15. Gaps in numbering are allowed. The existing ERR_ReconAirport name remains supported.

Markers can be in the terrain itself. Alternatively, put coordinates in the adapter profile's airfields list, for example [[1234, 0, 5678]]; the generator creates the same named entities in the adapter. These example coordinates are not Nogova coordinates. Do not duplicate a marker name in both layers. Heights are sampled from the terrain; underwater or out-of-bounds centres are ignored.

Explicit centres take priority over automatic discovery. They guide both extraction and enemy air support. A marker identifies an airport, not a guaranteed spawn position: dry ground, slope, obstructions, overhead clearance and navigation are still checked. If the terrain has no identifiable airfield, preparation fails with a marker-configuration message instead of using Everon's coordinates or moving the helicopter into an arbitrary field.

Exporting a terrain scenario

Copy terrain-profiles/nogova.json and supply a unique lowercase id, display title, terrain addon GUID, root .ent resource, and its navigation references. Set airfields only if automatic detection/terrain-owned markers are insufficient. For example, after updating the real resource references:

python3 tools/terrain_adapter.py terrain-profiles/nogova.json \
  --output .build/terrain-integrations/nogova

Output must be a new directory, so regeneration cannot overwrite authored work. The tool writes stable world/scenario GUIDs, metadata, a reference to the shared connector and a terrain-adapter.json report. By default it creates no addon project. Copy its Missions/ and Worlds/ contents (including .meta files and layer directories) into the terrain addon, preserving existing files, and add Escape to that project's dependencies. The report is informational, not a mission resource. For Nogova the stable scenario ID remains {681921DC9921F915}Missions/ERR_nogova.conf.

To create a separate optional scenario addon, add --standalone; this also writes an addon.gproj with dependencies on Escape and the selected terrain. The older terrain-adapters/nogova/ project is retained for that workflow and now uses the same universal prefab. Load only one owner of the generated scenario resources: do not enable the standalone addon alongside an embedded copy in the terrain. Publish/package the chosen project, install it and its dependencies on the server, and select its scenario ID. The report's navigation_configured means references were supplied, not that native loading or multiplayer was tested.

Placement constraints and validation

Required sites are accepted only after safe geometry and infantry navigation checks. Streaming navigation candidates have a bounded wait; the search has per-frame, attempt and time limits. No authored Everon coordinates are used as fallbacks by this path. Optional camps may be omitted only if the remaining scenario still has the required independent radio-intel sources. Flat maps may use fewer hill scouts. The map must still have enough accessible dry land, an airfield and room for the mission within its configured escape radius (currently 9 km by default); this is not a promise that every arbitrary terrain is playable.

Automated regressions cover scheduling/streaming, unsafe fallback refusal, marker detection and adapter generation. Dedicated multiplayer and a complete escape on Nogova remain outstanding.

Validation on 2026-09-30: repository checks passed, followed by the updated terrain scheduling/navigation, marker and adapter regressions. Native Everon preparation using the generic adapter placed all 16 sites and reached the prison phase with an explicit airport marker; launch/end source hashes matched and the private process cleaned up. It did not test completed player admission or escape. See evidence/terrain-2026-09-30-startup/report.json and its raw console/adapter. The first diagnostic attempt failed because it gated static navigation on a streaming-tile validity check; the corrected path checks loaded/static navigation with GetReachablePoint and only waits when a streaming request is accepted.

The separate existing Everon airfield smoke completed 59 assertions without script/runtime failures (evidence/native-2026-09-30-terrain-airfields). Both native logs retain resource/schema engine errors; the strict native report is therefore not clean and this evidence does not constitute release qualification.