EscapistsReintroduced/docs/search-helicopter.md

# Search helicopter

The combined mission now owns an airport reconnaissance service adapted from the
original `EAI_AirRecon` and `ESCT_HeliBehaviourBaseComponent`. It runs on the server
through VirtualHQ's maintenance tick. The original projects are not runtime
dependencies.

Prison escape starts a 15-minute countdown. A single armed Mi-8 then departs from
a clear pad at a discovered airfield. Losing that aircraft or its usable original
pilot starts a fresh 15-minute replacement delay. Parking or player takeover does
not create a replacement. Wrecks and surviving original crew remain in the world;
there is no cleanup-driven instant replacement. Explicit native aircraft deletion
also starts the loss delay; mission teardown does not restart the service. The round retains at most 64
attempted aircraft and uses the shared finite force ledger.

Airfields are discovered incrementally from physical runway/control-tower prefab
clusters, with an optional validated `ERR_ReconAirport` marker. Pads are surveyed
35–220 m from an airfield centre, with a 14 m clear footprint, terrain tolerance,
water exclusion and a 150 m vertical clearance trace. Failed departure placement
gets three attempts 30 seconds apart; batches use the configured delay.

The aircraft uses the original server physics flight approach: vertical takeoff,
40 m/s cruise, terrain look-ahead and 120 m terrain clearance. Its four native
pilot/gunner seats are populated before departure. The original crew is locked
aboard during flight and reserved against ground HQ reassignment. The engine's
native gunners retain their weapons and combat behavior. The current stock armed
Mi-8 replaces the old custom left-gun mount that is absent from the installed game.
US/RHS_USAF select the US pilot loadout; other enemy choices select the Soviet
loadout. Aircraft, group and crew all receive the selected enemy faction.

Without a contact, it searches random dry island sectors or delivered HQ sighting
coordinates. Actual native clear visual sightings of players or their occupied
vehicles produce a 300 m shadow orbit, with an additional 180 m horizontal
standoff. Two observation snapshots estimate motion; no live hidden player
positions or velocities drive the search. After losing sight it searches around
the last observation for two minutes, then resumes sector searches. Crew reports
use the normal physical-radio call, transmission and delivery pipeline to HQ.
A missing or incapacitated radio carrier can interrupt that route.

While searching, the aircraft checks delivered HQ sightings every five seconds
and chooses the newest observation, rather than the last target in the list.
Once accepted, the reported coordinates remain its destination even after the
report expires from the fire-support feed. It approaches the area and spends two
minutes within 650 m searching before choosing another random sector. A newer HQ
observation can redirect it; a direct crew sighting takes priority. Replayed
reports cannot restart a finished search. An approach without newer information
times out after 15 minutes if the aircraft cannot reach the area. These decisions
use captured report coordinates, never the hidden player's current position.
The launch timer and scripted flight have no rain gate; crew spotting still uses
native perception. Search assignment, arrival, completion and approach timeout
are recorded in the HQ journal, and flight status includes its destination.

The October 3 regression is covered by `tests/test_recon_search.py` and an
isolated dedicated-engine search integration check retained in
`docs/evidence/helicopter-search-2026-10-03/`. This check exercises production
search decisions with controlled reports and aircraft positions; it does not
claim a full flight or weather-dependent spotting test.

Low fuel (less than 50 native fuel units) or an administrator return request sends
the same aircraft back to its departure pad. It lands and stops its engines, retaining the surviving crew for airport servicing.
HQ-controlled passenger drops, post-drop cover, reloading and a separate ammunition
helicopter are described in [HQ air support](hq-air-support.md). A player boarding, taking the crew group or
changing the aircraft's faction releases scripted flight control.

Administrator commands:

- `/esc hq heli show` — phase, launch delay and pending countdown.
- `/esc hq heli timer set 15` — save the launch/replacement delay in minutes
  (1–1440). Resets a pending countdown; an existing aircraft remains active.
- `/esc hq heli return` — return the current searching helicopter to its airfield.

The persisted key is `heliTimerMinutes`, default 15. Older settings files acquire
that default; the original settings importer preserves the original key. Normal
configuration validation and save-failure handling apply.

`tests/test_air_recon.py` executes the production launch/loss schedule and flight
geometry. `tools/headless_workbench.py --project core --smoke air-recon` is an
opt-in native fixture: it shortens the test countdown, arranges a runway encounter,
requests return, destroys the first aircraft and transfers its replacement to the
escapists faction. These
fixture actions do not change production timing or give the helicopter artificial
perception. A focused `--recon-takeover-only` variant exercises native faction handover,
control release and explicit native entity deletion without
repeating the full flight.

The full repository suite passed in `/tmp/erri-recon-check5.log`. The final
removal-notification regression and affected native lifecycle/runner checks passed
afterward. The 22 September native run
`/tmp/erri-recon-native4/logs/logs_2026-09-22_17-39-45` passed actual airfield
launch, conscious original crew, native player detection, shadow orbit, radio
sighting delivery, more than 300 m of flight, same-aircraft landing, no replacement
while parked, destruction-triggered full delay and retained-wreck replacement.
An earlier run flew more than 650 m. Both full-flight runs ended at a failing
fixture boarding call; forced player boarding also failed in `/tmp/erri-recon-takeover1`. The accessible
seat was found and the owner-routed request accepted, but no actual occupancy
followed. Player entry and its control-release branch remain unverified; the
final focused fixture instead tests the separate native faction-handover branch.
These Workbench runs are not dedicated multiplayer acceptance. No Workshop
publication or server deployment is included in this change.


The final focused native run was
`/tmp/erri-recon-ownership-final/logs/logs_2026-09-22_17-54-34`.
All 13 recon assertions completed with zero script errors: native original crew,
airfield-only departure (including a refused pad and subsequent retry), actual
faction handover/control release, and explicit entity deletion starting one full
900-second replacement delay. The final addon files were separately compared to
the launch snapshot and matched.

The strict runner result remains `cleanup-failed`, with `smoke-completed` recorded
before cleanup: an exiting `enfMain` had an empty command line. A subsequent
host-visible `assert_prefix_idle` passed. The preserved runner record has not been
relabeled as a clean strict run. Existing external localization/resource warnings
remain separate from the zero script-error count.