EscapistsReintroduced/docs/cessna-reconnaissance.md

# Optional reconnaissance plane

A dedicated server which loads **Cessna 172** (`69BAEE0D439966FE`) and its
**Propeller Flight Core** dependency (`69A8A34027DA65C5`) can operate one enemy
reconnaissance plane. Neither addon is an Escape project dependency. Without both
loaded, Escape does not search for a plane prefab, survey its departure corridor
or spawn its crew.

Open **HQ → Configure Cessna** for the saved **Enabled / Disabled** choice
(`planeReconEnabled`, default `1`) and patrol settings. Each numeric field has
its own Apply button and saved value. All changes apply next round, including
replacement flights; editing a field alone does not save it. The same authenticated
command is `/esc mission plane set 0|1`. Enabling the setting does not install an
addon or promise that the current terrain has a usable airport.

| Setting | Default | Allowed range | Admin command option |
| --- | --- | --- | --- |
| Patrol altitude (`planeAltitudeMetres`) | 250 m | 150–500 m | `planealtitude` |
| Replacement delay (`planeReplacementSeconds`) | 60 s | 30–1800 s | `planereplacement` |
| New patrol area (`planeSectorSeconds`) | 120 s | 30–600 s | `planesector` |

Use `/esc mission <option> set <value>` with these options. Older saved profiles
receive the defaults automatically. Altitude is clearance above sampled terrain
ahead, not a guaranteed height at every instant. The plane selects a new area
when the interval expires or it reaches the current destination; departure still
uses its dedicated takeoff leg. These controls do not change the number of planes
or bypass the crew's native perception and radio reporting.

## Operation

- Airport discovery and departure clearance run in bounded background batches
  after the mission becomes active. They do not block prisoner admission.
- A clear, gently graded airport departure corridor and separation from players
  are required. No airport or no safe corridor means no plane on that terrain.
- The original Cessna prefab receives a pilot and observer from Escape's existing
  radio-equipped aircrew prefabs, assigned to the selected enemy faction.
- Each original crew agent is activated at permanent LOD 0 before boarding.
  Preparation verifies the exact assigned seat and its occupant, rather than
  treating an accepted boarding request as success. An unseated, conscious crew
  member can make at most three native seating requests, at least five seconds
  apart, within the original 45-second preparation deadline. Requests wait for
  existing entry/exit transitions and refuse occupied, inaccessible, locked or
  externally reserved seats. They never replace crew or remove other occupants.
- A server autopilot drives the addon's controls. PFC remains responsible for
  flight forces, collision, fuel, damage and replication. The patrol does not
  teleport the aircraft or write its velocity/transform during flight.
- Destinations are sampled on land, independently of player positions. Altitude
  control samples terrain ahead; bank and throttle control follow the patrol.
- The crew is registered with VirtualHQ as a reserved support group. Its native
  perception supplies sightings to the existing reporting/radio network. It
  does not reveal hidden players or inject positions straight into HQ memory.
  Normal reporting begins after the prison phase; reporting intervals, radio
  availability and travel time still apply.
- Destruction, a lost pilot or a disabled aircraft schedules a replacement after
  the configured minimum delay (one minute by default). Departure may take longer if the area is occupied or a
  new corridor must be found. Partial, unregistered allocations are rolled back.
- Three consecutive allocation or pre-service preparation failures pause the
  patrol for the remainder of the round, avoiding repeated failing aircraft
  allocations. Successfully entering service resets this streak when that
  aircraft is retired. Destruction of an operational plane still gets its normal
  replacement. Preparation failures now identify the blocked crew/seating/radio
  or engine gate.
- `PLANE CREW` journal entries record request acceptance/refusal, observed seating
  state changes and the final timeout snapshot for both crew members. They include
  actor/seat/occupant identity, ownership, consciousness, entry/exit state, seat
  availability, AI activation and LOD. Routine state changes are limited to one
  entry per crew member every five seconds; requests and final timeouts are always
  recorded. Both crew members are checked even when the first is still boarding.
- A player entering the plane or a faction/crew takeover releases the autopilot
  and restores the original input rates. The captured vehicle is retained.
- Round termination stops all autopilot callbacks. Existing force capacity and
  a 64-departure round cap bound retained aircraft/crew bookkeeping.

## Optional API boundary

Verified addon versions: Cessna 172 **1.0.0**, Propeller Flight Core **1.0.18**.
The aircraft exposes engine start publicly but its input receiver is protected.
A small, fixed `ScriptModule.CompileScript` adapter derives from the loaded PFC
controller and calls that receiver. It is compiled only on the authoritative
headless server (or Workbench). No third-party source files, project dependencies
or player input handlers are modified. Standard listen-server clients do not
provide this dynamic compiler and skip the patrol.

The adapter also temporarily holds the AI aircraft's input slew rates at zero,
so PFC's absence-of-human-input handling does not erase its autopilot commands
between simulation ticks. The original rates are restored when control ends.
An incompatible future addon API prevents startup and records the reason in the
HQ journal. The rest of the mission continues.

Native checks use an isolated Reforger 1.8.0.13 dedicated server and private addon
copies. See [native evidence](evidence/cessna-recon-2026-10-08/README.md) for the tested scenarios and their limits.

The 12 October played round failed all three departures with `crew 0 not seated`;
the scheduler then paused aircraft for that round. The boarding changes above
address a missing pre-boarding member-activation step and make incomplete native
entry observable and recoverable within fixed limits. That log alone does not
establish whether the pilot never entered or left afterward.

The [13 October boarding check](evidence/cessna-boarding-2026-10-13/README.md)
compiled the revised controller and passed 19 native assertions on isolated
Everon: US/West crew boarded and took off after the arranged prison escape;
forced dismounts exhausted the three attempts and original timeout; preparation
takeover preserved the aircraft; and a dead pilot caused normal failure and
cleanup. Focused executable regressions also cover rejected requests, pending
player control, wrong seats and blocked/reserved compartments. This does not
reproduce the original Chernarus multiplayer session. The full native report
retains unrelated engine/resource errors, and the repository-wide check stops
at the existing `ERRM_AtlasLeaf.et` saved-root-ID error. No live deployment was
performed by this repair.