EscapistsReintroduced/docs/convoy-migration.md

Finite physical convoy controller

Independent adaptation of owned escapists-ai/Scripts/Game/EscapistsAI/EAI_SupplyConvoys.c, SHA-256 a896fdacfd9c0f2db52e588642623545a3a5d6e8041fb72000a68e720fc2b7a5. Reused responsibilities are the six-vehicle catalog/order, native seat creation, independent native crew groups, finite cargo and owned-waypoint release. Original Escapists/ScrtCore helpers, original game mode hooks and EAI_GroupLookup are excluded. Native BaseCompartmentSlot.SpawnCharacterInCompartment, group vehicle manager and waypoint APIs replace those dependencies.

The round owns one ERR_ConvoyPool(mode,maxConvoys) and one ERR_ConvoyService(mode,pool). Reserve a unique authored source ID; dispatch its canonical one-use receipt with six authored positions/angles and a sealed, nonlooping Core ERR_ForceRoute. Resource, terrain/water/obstacle, faction and shared budget validation precede consumption. Consumption precedes native entity creation. Partial native startup consumes the slot and preserves every successfully created group, vehicle and actor; there is no refund or automatic retry/replacement.

The exact composition is PKM UAZ, ammunition Ural, troop Ural, PKM UAZ, BMP-1, PKM UAZ. It allocates 19 bodies: three UAZ driver/gunner pairs, one ammunition-truck driver, troop-truck driver plus eight infantry, and BMP driver/gunner/commander. Capacity failure does not shrink this plan. The selected own memberless USSR group and vanilla character catalog are explicit; other factions require a reviewed catalog. BMP driver, gunner and commander seat declarations were independently inspected in the installed WCS PAK; convoy-bmp-seat-audit.json records resource-byte hashes and declarations without redistributing assets.

Outstanding receipts plus physical, noneliminated Core ledger strength must fit 60 bodies; ledger records plus outstanding convoy groups must fit 128 formations. The same exact group moves from outstanding budget to its CONVOY record before normal mode registration. A 40-body world can reserve one full 19-body convoy, giving 59. Use one allocator for the round; creating independent pools would not share outstanding reservations. The fixed convoy limit and consumed source IDs survive losses within that pool.

The controller waits up to 30 seconds for exact original native crew membership and vehicle registration. Once ready it issues native move waypoints along the supplied finite road route. Each vehicle retains one owned waypoint at a time; arrival advances once, a ten-minute leg deadline releases stalled orders. Death, captured/reparented crew, destroyed vehicles and explicit Stop release orders without deleting physical entities. A player entering any convoy vehicle or crew releases the convoy task. Native combat may interrupt movement. No perception information or reinforcements are invented here.

The ammunition truck receives one bounded pass of eight AK74 and 48 matching magazines. Native capacity or failed operations may reduce actual cargo. Accepted asynchronous operations are never repeated or replenished. Status separates native insertion completions, failures and pending callbacks; completions are not an inventory snapshot after looting. Native accepted insertions cannot be cancelled by these callbacks, including after a controller Stop.

This is a partial convoy migration. HQ now exposes opt-in preparation/dispatch for the authored supply seed; native vehicle driving and physical cargo evidence remain separate requirements. Original two-team infantry dismount/flank/reboard tactics, delivery/unloading, rearming, route/base selection and Cylon gunner specialization are not claimed by this slice. No autonomous convoy spawn timer or unsupported convoy setting is installed.

Tests execute actual shared-budget, dispatch, seat allocation, readiness admission, cargo request and waypoint lifecycle bodies against native API doubles. They prove bounded/idempotent policy and partial-failure ownership; they do not prove native seats, AI driving or multiplayer replication.

Road preparation and clearance

ERR_ConvoyRoadPlan.Build(seed, out positions, out angles, out route) selects deterministically among actual native roads within a 500m query. It refuses more than 128 road candidates, widths below 4m, polylines over 1024 points, and roads shorter than 390m. Each road gets at most 33 candidate formations: the preferred projection followed by offsets +35m, −35m, +70m, −70m, up to ±560m along that same polyline. Offsets outside the valid start interval are refused rather than clamped into duplicate formations. Every one of the six starts and the sampled formation center must lie within 500m of the explicit seed. Eligible candidates are ranked by formation-center distance and deterministic geometry ties before expensive clearance queries when a better clear candidate already exists. This bounded scan can find clear alternatives to an obstructed initial projection; it is not an exhaustive search of all possible formations.

Six starts remain 35m apart along the actual polyline with a 15m rear margin and at least 200m forward route; every intermediate bend is retained, with refusal at the Core route's 64-point limit. Tight bends that place any two starts less than 18m apart are rejected. Native terrain grounding preserves the road XZ coordinates. There is no random, offroad or scenery-removal fallback.

Each oriented start checks nine terrain/water samples across a conservative 4m by 9m footprint. Terrain must be above 0.3m, vary by no more than 0.75m across the footprint, and agree with the starting altitude. The enclosing volume extends from 0.05m above the lowest grounded sample to 3.5m above the highest. A filled native TraceBox checks that volume with a 0.01m upward sweep against entity and ocean geometry; a nonfinite result or trace fraction below one refuses placement. An entity AABB query remains bounded diagnostic context only: overlapping bounding boxes or its visit cap no longer veto a geometrically clear footprint. These admission rules do not guarantee that native drivers can negotiate the whole road.

The focused road/placement tests execute the installed method bodies with geometry and native API doubles. They cover exact minimum geometry, reversed direction, offset ordering/refusal, locality of all selected starts, an obstruction requiring an alternative formation, degenerate and dense polylines, bend retention, tight-hairpin rejection, deterministic ties, rotated footprint bounds, terrain/water rejection and filled-volume collision results. Native-query doubles distinguish a tree's overlapping broad bounding box from an actual blocking shape.

The first native convoy run compiled all scripts but refused the authored supply seed before spawning entities (native-2026-09-20-020706-convoy-road-refusal). Road diagnostics subsequently found valid long roads. The placement diagnostic archive native-2026-09-20-021626-convoy-placement-diagnostic identified broad tree bounding boxes 6–12m outside the pavement and overhead power-line bounds as false positives; actual sampled road terrain spans were 0.10–0.73m. That evidence motivated the filled-geometry check without relaxing terrain limits. The later crew/cargo run below validates selection and a real-vehicle collision positive control; full convoy driving remains unproved.

Preventing queued default crew

Native readiness archive native-2026-09-20-023545-convoy-readiness-regression exposed at least six native agents in every group, including vehicles intended to have only one, two or three crew. The vanilla faction group Group_USSR_Base.et authors six soldier slots (inspected resource SHA-256 77a7c5caee98e13ba45204d1084636f4bf50f9414e2b048e43a60e1966535e96), and native SCR_AIGroup.EOnInit queues those slots asynchronously. Checking that group for zero agents immediately after spawn did not exclude its pending default allocation.

The convoy now uses independently authored {7A968AB297475FA7}Prefabs/ERR/ConvoyCrew.et, inheriting the memberless vanilla {000CD338713F2B5A}Prefabs/AI/Groups/Group_Base.et (inspected SHA-256 a8defc28500877cdd215f9c41d1eb003359f9455b1b063c5b8f15c644958c889). It declares USSR faction, disables immediate spawning and has no authored slots before native initialization. A strict runtime template guard checks all three conditions—no immediate spawn, no agents and no authored slots—before finite seat allocation. It neither deletes unexpected soldiers nor cancels another group's spawn queue. Actual-method and resource regressions pass. The subsequent engine run confirms exact post-initialization membership as described below.

Native crew and cargo checkpoint

02:40:35 crew/cargo run passed 109 assertions before a deliberate interruption, with no script/runtime failures. All six original vehicles retained exactly 2/1/9/2/3/2 native seated members, totaling nineteen, and six new Core ledger records. The actual truck inventory contained eight new AK74 rifles and at least forty-eight matching magazines after the single finite cargo batch. Repeated dispatch and a second reservation were rejected. A filled collision query against the actual lead UAZ returned a blocking fraction of zero, while road placement had accepted the empty formation positions.

The lead drove approximately 51.8m, but the minimum vehicle displacement stalled at 8.0m. This does not satisfy the fixture requirement of every vehicle moving20m and the lead100m. The run was interrupted through the runner's cleanup handler after sustained stagnation; it has no completed smoke round. Four external localization errors remain. Source and external files were unchanged and owned process cleanup was confirmed. Per-vehicle driving diagnosis is the next step; this checkpoint does not qualify delivery, combat, unloading or multiplayer.

Matching native waypoint completion

02:46:43 movement diagnostics identified the stall: the lead, troop truck and BMP had no current native waypoint and had switched to idle, while their retained owned waypoints still reported native group completion. Vehicle-origin distances were35.5m,38.5m and37.7m. The controller's separate vehicle-centre test against35m therefore missed valid native completion. It now uses the owned waypoint's IsWithinCompletionRadius(Group), matching the stock group waypoint decorator. The authored35m radius, original-crew validation, finite route and one-owned-order rules stay in place. Focused actual-method regression verifies progression after native removal, exactly one next waypoint and no duplicate advancement; updated native driving validation is recorded below.

Completed native driving check

02:50:35 convoy driving completes one scripted round with181 passed assertions and no script/runtime failures. All six original vehicles drove at least20m and the lead over100m, without fixture movement. Exact original seated membership, all six Core records, the finite eight-rifle/48-magazine cargo batch and repeated-dispatch rejection were verified again. The result includes subsequent native prisoner death, spectator transition and mission cleanup. Source/external inputs stayed unchanged and hidden, muted process cleanup was confirmed.

The same four external string-table errors keep the strict native qualifier failed. This single short road run establishes the initial physical controller; it does not prove full-route reliability, native combat/dismount/reboarding, logistics delivery/unloading, multiplayer or FPS improvements.