EscapistsReintroduced/docs/aircraft-field-route-plan.md

Field-route implementation plan

Read-only audit, 19 September 2026. This is a proposed implementation and experiment, not a flight qualification. No source, installed asset, running world or original Escapists content was changed. The retained-service normal twenty-metre native run was active when this audit began; its result is deliberately not assumed here.

The practical path is a newly authored, velocity-controlled single immutable field route, using the already consumed native actor-local inputs and the existing exclusive controller bridge. Installed scripts do not establish a usable stock helicopter waypoint autopilot. A first 100-metre open-ground route should exercise acceleration, braking and retained cancellation under one order. Increasing the current twenty-metre length constant, or repeatedly issuing twenty-metre orders, would leave important safety and ownership assumptions unsolved.

What the installed APIs actually provide

Paths in this table refer to the installed stock extraction under /tmp/erri-vanilla; they are source evidence, not successor dependencies. No stock implementation is proposed for copying.

Installed source	Supported interface and implication
scripts/Game/generated/AI/AIAgent.c:46	proto external ActionManager GetActionManager(). Provides the exact original AI pilot's action manager.
scripts/Game/generated/Components/CharacterControllerComponent.c:473–474	OnPrepareControls(IEntity owner, ActionManager am, float dt, bool player) and OnApplyControls(IEntity owner, float timeSlice). The existing bridge writes the exact AI manager before native character Prepare; it does not write the local player's manager.
scripts/Game/Components/SCR_CharacterControllerComponent_Test.c:9–13	Stock example sets an action on the supplied manager before super.OnPrepareControls. This is a supported insertion pattern, not a ready-made flight controller.
Engine ActionManager, checked with the local API index	void SetActionValue(string actionName, float value), float GetActionValue(string actionName), bool IsContextActive(string contextName), bool ActivateContext(string contextName, int duration=0). The documented return values do not specify a helicopter transfer function. Do not interpret an already-active context's activation return as failure. Official API reference.
Configs/System/chimeraInputCommon.conf:5980–6200	Real HelicopterContext directional cyclic, anti-torque and collective increase/decrease actions. The successor pairs nonnegative opposing inputs. Existing native evidence establishes signed positive/negative consumption for its exact owned pilot; a higher cyclic magnitude or faster route is still unqualified.
scripts/Game/generated/Vehicle/HelicopterControllerComponent.c:15–35	GetSimulation, Get/SetCollectiveMode, Get/SetAutohoverEnabled, and OnPrepareControls. The callback is explicitly before native input collection and intended for collective-mode changes. There is no exposed target position, desired velocity, waypoint, auto-land or autohover gain setter here. Autohover's internal control law is not published.
scripts/Game/generated/Vehicle/VehicleHelicopterSimulation.c:15–46	Native throttle/engine APIs; rotor count, local transform/radius/RPM/state; GetAltitudeAGL() documented as terrain detection. No helicopter cyclic/collective input setter or route navigation request. Rotor force/torque scaling changes physical effectiveness and must not be used as navigation.
scripts/Game/generated/Vehicle/VehicleBaseSimulation.c	Native velocity/angular velocity and ground-contact observations. Use the entity's world transform for aircraft position/basis; earlier native runs showed the simulator transform could be identity. GetAltitudeAGL alone does not establish building/tree clearance or a landable site.
scripts/Game/generated/AI/AIHelicopterMovementComponent.c:16 and AIFlyingMovementComponent.c:16	Both exposed class bodies are empty. Their existence does not establish configured operational helicopter navigation.
scripts/Game/generated/AI/AIBaseMovementComponent.c:18–24	HasCompletedRequest(bool), RequestFollowPathOfEntity(IEntity), GetCurrentPath(array<vector>), GetPathfindingComponent(), OnPathSet(). No documented helicopter takeoff/landing destination request.
scripts/Game/generated/AI/AIPathfindingComponent.c:18–30	Ray tracing and navmesh APIs, including GetClosestPositionOnNavmesh. A ground navmesh point is not a rotor clearance or flight-path qualification.
scripts/Game/generated/Components/HelicopterAutopilotHelperComponent.c:16 and BaseAutopilotHelperComponent.c	Explicitly obsolete, “Do not use. Will be removed entirely.” No exposed helper methods. Not a supported migration dependency.

Additional negative evidence is concrete but bounded. Prefabs/Vehicles/Core/Helicopter_Base.et:21–23 sets m_bCanBePiloted 0; stock SCR_AIOccupyDriversInUsedVehicles.c:128–133 skips unpilotable helicopters, and the available-compartment selectors explicitly exclude their pilot slots. Flipping this flag would enable an unqualified planner, not implement flight. The apparent SCR_AIFlyHelicopterBehavior reference in SCR_AIGetActionParameters.c:9–14 is inside a documentation example. A fresh installed-PAK filename search found no corresponding behavior implementation. This is evidence about the installed exposed scripts, not a claim about unavailable engine internals or future game versions.

Current successor bottlenecks

The existing route comparison measured 20 m translation plus hold in 69.293 s, with sampled cruise progress about 0.322 m/s after the route-only gain change. This proves physical movement and improvement in that one run; it cannot justify a 100 m duration estimate from a requested speed alone. At the observed cruise speed, 100 m already takes about 311 seconds before startup and landing, exceeding the unchanged 240-second flight lease.

Concrete dependencies in addons/core/Scripts/Game/ERR/10_AI/:

• ERR_AircraftRouteEnvelope.c:4–17 accepts 18–20.05 m, requests at most 0.5 m/s horizontal speed, uses velocity-error gain 0.10 and caps cyclic demand magnitude at 0.03. Autohover remains active. There is no identified autohover velocity-response model, so simply raising desired speed may only saturate demand.
• ERR_AircraftRouteEnvelope.c:44–98 qualifies a near-level rectangle, including possible cancellation landings, with terrain variation at most 0.3 m and at most 35×35 samples. Destination height is rebased to the original home height. This is intentionally incompatible with general Everon terrain.
• ERR_AircraftRouteFlight.c:35–43, 68–118 freezes the current landing centre on cancellation and starts descent using the original short-translation landing controller. That policy has not been qualified from higher travel speeds. It must not descend immediately while appreciable horizontal speed remains.
• ERR_AircraftFlight.c:11, 16–27, 339–366 sets a maximum 240-second absolute lease, an 8 m hover height, fixed home-relative landing height, and airborne Cancel→Landing. Higher speed needs a bounded braking stage before descent, while preserving the same captured order and deadline.
• ERR_AircraftService.c:61–114 registers only current physical assets and specifically constructs/retains ERR_AircraftRouteFlight. A field controller cannot be slipped into that path by replacing a range constant; it needs an explicit typed entry point and lifecycle tests.
• ERR_HQ.c:78–86, 154–175, 341–383 has support reservations, delivered contact snapshots and radio downlinks, but presently ticks mortars/logistics, not an aircraft dispatcher. Core ERR_GameMode.c:364–389 pauses normal mission work on an empty server. An airborne retained service must continue ticking independently of that pause.

The physical control API is therefore available. Missing work is our navigation/control policy, its measured braking behavior, useful site qualification, and real HQ integration. AI passenger transport, cargo transfer and armed-aircraft targeting are additional features; they do not follow from a pilot successfully flying an empty Mi-8.

Smallest useful next experiment

Add a separate opt-in aircraft-field-route fixture, initially restricted to one authored 100 m straight, open, nearly level corridor. Refuse a failed survey; do not search increasingly permissive terrain or replace the aircraft. The fixture owns one stock transport Mi-8, original group, pilot, seat, fuel inventory, one qualification and one immutable token. Use the production bridge exclusively. Keep the existing twenty-metre controller and regressions unchanged.

This is a proposed engineering experiment, not a claim that the suggested numerical control settings are supported native constants or known stable gains:

Quantity	Initial proposed limit / acceptance
Route	100 m ±0.05 m, original endpoint fixed before takeoff; no chained orders or new home
Overall authority	Existing absolute maximum 240 s; no deadline renewal; existing 300 s fixture / 330 s outer bounds
Airspace	Existing measured complete footprint; 40 m corridor clearance margin; origin within 8 m of the immutable clamped segment; original -3..18 m height and uprightness limits
Terrain	Original near-level ±0.3 m ground-height condition across the whole possible landing corridor, sampled at ≤2 m, with an explicit total cap of 4,096 samples; reject work beyond the cap
Normal altitude	Existing 8 m home-relative hover, only because the entire first field is near-level; never describe this as terrain following
Cruise reference	Ramp from 0 to at most 2 m/s, horizontal acceleration reference ≤0.2 m/s²; actual horizontal speed >2.5 m/s refuses successful qualification
Native input	Field-only cyclic vector cap 0.08, candidate velocity P gain 0.10 plus bounded integral gain 0.02/s, anti-windup; existing native action pairing, fresh readback, signed collective proof and ownership guards retained
Approach	Start braking no later than 25 m remaining; monotonically reduce desired speed; then use unchanged slow position-hold/landing demand only after actual horizontal speed <0.25 m/s for 2 continuous seconds
Arrival	Original ≤0.75 m endpoint error, original hover criteria, five continuous seconds held; actual stable native contact and engine-off shutdown afterward
Cancellation	Freeze one qualified landing centre; brake while holding altitude before descent; keep the same controller, token, reservation and absolute deadline until terminal

The proposed integral is a specific response to the measured nonzero velocity error under autohover, not an assertion about its internals. Clamp total vector demand, freeze/back-calculate the integrator when saturated, reset it only on a genuine phase transition, and do not carry cruise integral into landing. Document units and execute the actual equations in regression tests. Both 0.08 cyclic and the integral are new candidate behavior. If the run saturates without gaining speed, develops oscillation or cannot brake within bounds, record failure and use the telemetry to decide the next controller change; do not extend its lease or silently increase the cap.

A stopping-distance model is a testable admission hypothesis, not a proven safety bound. For planning, reserve v²/(2a) + v*latency + margin, initially using a=0.15 m/s², latency=1 s, margin=3 m; at the 2.5 m/s hard speed limit this is about 26.3 m. Start the soft braking schedule at 25 m only while current speed gives a smaller reserve; otherwise brake earlier using that formula. Record actual world-position progress and velocity throughout braking and require the measured stop to fit the reserved distance. Never claim the assumed deceleration has been demonstrated before that observation. A full landable corridor remains necessary for conservative cancellation; an endpoint-only pad does not suffice.

Cancellation should freeze a landing point selected once within the already qualified corridor using the current velocity and conservative braking reserve, with a refusal if it would lie outside the route's qualified endpoint caps. Keep altitude during braking; descend only after low horizontal speed and position control are observed. This is different from instantly freezing the current point and starting the existing descent at 2 m/s. A changed obstacle, loss of capability, ownership capture or deadline expiry remains an explicit failed/relinquished outcome; the controller cannot promise a safe emergency landing after every physical fault. Start the abort decision while at least 85 seconds remain for braking/landing/shutdown, within the original lease, rather than waiting for hard expiry. The exact allocation of that reserve must be checked against the candidate stage limits before admitting the order.

For this experiment, retain the original fuel and require a declared preflight reserve (for example 50 native fuel units, not an asserted litre quantity); no refuel or repair. Log starting/ending fuel and fuel rate, with a low-fuel abort threshold sufficient for the bounded abort phase. The earlier gain run consumed about 5.68 native units by engine-off; one run does not establish an operational range or reserve model for wind, payload or damage.

Implementation boundary and decisive tests

Prefer new ERR_AircraftFieldEnvelope, ERR_AircraftFieldFlight, ERR_AircraftFieldRules and one native fixture. Reuse the base single-claim qualification and exclusive aircraft registry. A field flight should derive from the shared base flight, with its own explicit StartField contract; route-specific StartRoute currently rejects other lengths, so a cast is not a legitimate escape hatch. Preserve original public Start/StartTranslation refusal on a field subclass.

The smallest necessary service change is an explicit StartField entry point sharing the existing registration/token/attempt/deadline bookkeeping. Its retained controller reference can use the common base type; do not add a second service registry or let callers pass an arbitrary pre-started flight. Keep existing StartRoute and normal/cancel twenty-metre fixtures as regressions. New flight stages must be appended, preserving the existing COMPLETE..RELINQUISHED terminal interval. Every callback still validates exact mode/world/pilot/seat/group, no player capture, original qualification, health, readback and both deadlines before a write.

One native normal experiment must show actual 100 m displacement, material cruise speed increase (e.g. ≥1 m/s sustained for at least 10 s), measured braking inside the declared reserve, the unchanged endpoint hold, physical landing and engine shutdown on the original assets. Record time, position, horizontal/vertical velocity, demand, saturation/integral, along/cross-track error, native consumed inputs, stage and lease remaining, fuel and physical contact at bounded intervals. A second explicit Stop variant should stop during measured ≥1 m/s travel, keep the service and callback control alive, then prove its frozen in-corridor landing and CANCELLED/drained state; it must not claim destination arrival. Failed runs, refused terrain and every engine/script error remain visible.

Source-local tests must execute actual demand/braking/admission methods: vector caps and zero vertical cyclic, acceleration slew, anti-windup, opposing-velocity braking, reserve before an endpoint, no cruise integral in landing, one cancellation landing point, no repeated Stop reset, exact immutable token/deadline, capture before a write, fuel/health refusal, and bounded survey work. Fake boundaries prove policy only. Native geometry, motion and braking still need their own evidence.

From that experiment to real HQ support

The next deliverable after field-route qualification should be one radio-authorized finite transport/resupply order between authored sites, not another unrelated hovering demonstration. Register an existing server-owned aircraft/pilot in the retention service and reserve that group against ordinary patrol assignment. An existing physical unit's report must traverse the real HQ radio uplink; HQ chooses a compatible available airframe and authored destination, then a real downlink must complete before its unique flight token is admitted. Lost/interrupted delivery starts no flight. A fresh order may select a known safe support site; it must not read a target entity's current origin or retarget a committed route from an undelivered report.

The order should carry an immutable route/site identity and actual cargo or passenger identities. Availability is current physical health, fuel, native seat and ownership, not a historical COMPLETE event. Make one useful effect observable at the destination: native disembarkation of the original finite reinforcement squad or native transfer of a finite ammunition payload. Only the successful real transfer/disembarkation completes that support objective; a helicopter landing alone does not. Loss of pilot/rotor/airframe/cargo retires that physical capacity. Returning requires a new unique order and a freshly qualified route plus enough real fuel; no automatic replacements.

This requires an owner that continues the service Tick when no players are connected, and retains airborne cancellation through terminal before mission cleanup. The present global NoPlayers ownership guard also excludes human passengers; enemy AI support can use that boundary, but player extraction transport would need a separate reviewed passenger contract. Keep the existing player-operated extraction loop independent.

A 100 m open-field result will still not provide arbitrary 500–2,000 m Everon service. That later step needs an immutable terrain/obstacle-aware altitude profile, authored landable abort sites or a verified recovery route, real stopping performance across the chosen speed/payload/wind range, and a fuel/range model. Profiles may have multiple surveyed segments inside one original order and lease; they must not reset authority by chaining twenty-metre controllers. Native APIs above allow the necessary observations and inputs, but provide no documented planner that removes this implementation work. This is the specific remaining flight-feasibility barrier, separate from already implemented base prison→intel→radio→player-helicopter escape.

Audit source identities

SHA-256 of the exact local files read for the main API and controller findings. The staged service candidate is identified separately; these hashes do not qualify any native run.

Source	SHA-256
installed: scripts/Game/generated/AI/AIHelicopterMovementComponent.c	e4f392ab0560dd7729caeadbe8eb7ab70ffa56a2392ac3c7ddd4678a1c771fe7
installed: scripts/Game/generated/AI/AIBaseMovementComponent.c	d21db84a7158bb8207fb1e3a26a9f8f9e6429cc95ab4d3e34427d0af6886bc27
installed: scripts/Game/generated/Components/HelicopterAutopilotHelperComponent.c	1fed97a2f0dc3063cb6f86687305ec2824527078d1b6a552db60af4bbd33d678
installed: scripts/Game/generated/Vehicle/HelicopterControllerComponent.c	951495d96470347af1520641a0e4c7ca7aea8722e4ad5eb06d45f6f3da25040d
installed: scripts/Game/generated/Vehicle/VehicleHelicopterSimulation.c	af5a7b44d7303a0eec458478d4049a49546df1f3801b7295966d8d0a10c26c57
installed: scripts/Game/AI/ScriptedNodes/Behavior/SCR_AIGetActionParameters.c	7ed819265aa2b3b82960a3d2c4dbc83160dd10c2116c44f9c3e52776524fecf8
actual successor: addons/core/Scripts/Game/ERR/10_AI/ERR_AircraftRouteFlight.c	1d8d92bf6d97429d68a9f62018232e90cc124cc8d7445efeabe863706a31e2b9
actual successor: addons/core/Scripts/Game/ERR/10_AI/ERR_AircraftRouteEnvelope.c	e8fcef844239c47a1f2f36be420afe943bc450091b05859435406b46c87fa511
staged successor: addons/core/Scripts/Game/ERR/10_AI/ERR_AircraftService.c	bf52361c9d07b2c632d6ad755cbca76683f5ad4a8208e6eec690c367efa44549

Dormant implementation checkpoint

The three new FieldRules, FieldEnvelope and FieldFlight classes now implement the bounded prototype and pass source-method regressions and independent review. They have no normal-mission, HQ, retained-service or native-fixture entrypoint. Native compilation and100m physical flight remain pending at this checkpoint. Braking uses a frozen90% entry-reference ceiling and the inverse full modeled stopping reserve, with unchanged vector slew. Candidate fuel admission is50native units and low-fuel abort20units; neither establishes reserve adequacy or units as litres. The softabort begins at86.5s remaining to reserve85s phases plus the maximum1.5s caller cadence. Phase3 cancellation retains settling control, and pre-CLIMB airborne cancellation now enables/reads back autohover before entering braking. Both issues were found before integration and covered through the actual inherited Cancel path. No prior native flight archive qualifies this prototype.

First integrated native attempt,20:57

The typed service and optional Chat field fixture compile in Enfusion at the201-file snapshot. The fixed airport corridor4850.953→4950.953X fails its original complete survey before fixture allocation (full evidence). No fallback point or aircraft is allocated. First-refusal diagnostics must identify the failed original predicate before changing route geometry or attempting flight. The stopping reserve remains a hypothesis: source review also identifies that approach travel can exceed the instantaneous reserve because the controller continues positioning after braking entry. Keep the strict measured check and resolve against explicit policy and actual telemetry.

Immediate-stop correction and terrain diagnosis

The 21:09 diagnostic confirms first refusal at terrain grid x=0,z=1: sample X4810.95/Z11749.4 has height28.375 against start28.6938, a0.31875m difference beyond the unchanged0.3m limit. No fixture assets were allocated. A separately gated read-only terrain audit is being prepared to inform one newly authored candidate; it grants no qualification and cannot replace the original failed survey.

The reviewed controller correction targets zero horizontal velocity immediately when braking starts, retains the0.2m/s² vector slew and resets cruise integral only once. Normal braking now begins at the declared reserve derived from actual speed; phase3 additionally requires reference speed at most0.01m/s alongside two continuous actual low-speed seconds. The original point, order,45s combined braking/positioning budget and strict measured-reserve fixture remain unchanged. Source tests cover lag, opposing velocity, repeated cancellation and threshold jitter. Native deceleration and useful100m completion remain unqualified; a lagging body can still accelerate while a larger reference slews toward zero.

Third authored corridor after obstacle evidence

The northbound candidate passed the complete terrain grid, but the original high-volume sweep found Warehouse_01 at X4928.577/Z11893.940 (21:23 archive). That run allocated no fixture aircraft and retains its initial cleanup failure; a separate locked idle recheck confirmed the already-exited test process without sending any signal.

The next single authored candidate runs east from X4870/Z11760 to X4970/Z11760. Its original expanded rectangle ends at Z11800,94m south of the warehouse origin, and the prior coarse terrain data stays within0.2563m of the lifted start reference. This geometric separation is not obstacle clearance; the full original terrain and object predicates still decide admission. There is no runtime fallback or change to margins, height tolerance, sampling or controller limits.

The 21:30 eastbound trial passes terrain but finds a poplar at X4963.823/Z11737.644. The fourth authored candidate is northbound X4890/Z11730→11830: its40m volume shifts south of the prior warehouse encounter and west of that tree, while coarse terrain deviation is0.2876m. Full native clearance still decides admission; first-hit world bounds are now logged to avoid treating an entity origin as its complete footprint. No obstacle is removed and no constraint is loosened.