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.

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