EscapistsReintroduced/docs/terrain-adapters.md

# Universal terrain connector

Server owners normally use [automatic terrain takeover](terrain-takeover.md):
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**:

```text
{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](evidence/universal-connector-2026-10-01/nogova/report.json) and
[Everon report](evidence/universal-connector-2026-10-01/everon/report.json).

## 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](nogova-publishing.md).

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](nogova-publishing.md).

## 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:

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