AICOM Stuck Recovery V2 Reference

AICOM Stuck Recovery V2 Reference

This page documents the current Build 87 AI-commander stuck-recovery v2 system in origin/claude/build84-cmdcon36@6f2fc4bd10c8339fd13be087d327717ff58c85e8. It is the operator reference for the AICOM team recovery ladder, TARGET_ABANDON reasons, stuck-distance branches and RPT smoke tokens added around the PR #125 release-command-center work.

Scope note: line refs below cite the Chernarus source mission, Missions/[55-2hc]warfarev2_073v48co.chernarus/, on the current Build 87 branch. Maintained Vanilla/Takistan line numbers can drift and should be checked before release or source-patch wording.

This is not the player-owned AI watchdog. Player-group recovery is covered by Player AI watchdog and recovery. This page is for AI-commander combat teams driven by AI_Commander_AssignTowns.sqf, Common_RunCommanderTeam.sqf, AI_Commander_Strategy.sqf and the AICOM auto-unflip manager.

System Boundaries

Layer	File	Responsibility
Detection and retargeting	Server/AI/Commander/AI_Commander_AssignTowns.sqf	Detects parked/stalled/orbiting assault teams, bumps wfbe_aicom_stuckstrikes, blacklists bad targets and publishes fresh HC/server orders.
Local recovery execution	Common/Functions/Common_RunCommanderTeam.sqf	Runs where the team is local, reads the strike tier from the order, fires remount/reverse/lane-flip/road-snap recovery, and emits UNSTUCK_FIRED.
Relief/defense wedge release	Server/AI/Commander/AI_Commander_Strategy.sqf	Detects teams wedged in defense/move modes, releases them back to offense and resets inherited stuck strikes.
AICOM auto-unflip	Common/Functions/Common_AICOM_AutoFlip.sqf	Separate server/HC loop that rights local flipped AICOM ground vehicles after a stuck timer.
Operator telemetry	RPT diag_log	AICOMSTAT, STUCKSTAT, [AICOM ...] prose and WASPSCALE recov= together show detection, action and recovery counters.

Common_AICOM_AutoFlip.sqf is started on the server for server-local founded teams (Server/Init/Init_Server.sqf:22) and on headless clients for HC-delegated teams (Headless/Init/Init_HC.sqf:243). The strike-spawn comments in Common_RunCommanderTeam.sqf explicitly say vehicle unflip is not added to that spawn because it already ships as this server/HC loop (Common_RunCommanderTeam.sqf:954-964).

Current Defaults

Constant	Default	Meaning	Source
WFBE_C_AICOM_AUTOFLIP	1	Enables the server/HC AICOM auto-unflip loop.	Common/Init/Init_CommonConstants.sqf:794
WFBE_C_AICOM_STUCK_SECS	210	Breadcrumb age before a noncombat team can be considered stuck.	Init_CommonConstants.sqf:1113
WFBE_C_AICOM_STUCK_MOVED	200	Movement below this distance counts as no progress.	Init_CommonConstants.sqf:1114
WFBE_C_AICOM_STUCK_FAR	300	Team must still be farther than this from the target for the position-stuck branch.	Init_CommonConstants.sqf:1115
WFBE_C_AICOM_STUCK_ABANDON	4	Strike count above which the team abandons and blacklists the target.	Init_CommonConstants.sqf:977
WFBE_C_AICOM_BLACKLIST_COOLDOWN	600	Per-team blacklist cooldown seconds after abandon.	Init_CommonConstants.sqf:990
WFBE_C_AICOM_SIDE_BLACKLIST	1	Enables side-wide town blacklisting after repeated different-team abandons.	Init_CommonConstants.sqf:982
WFBE_C_AICOM_SIDE_ABANDON	3	Different-team abandons needed for side-wide blacklist.	Init_CommonConstants.sqf:983
WFBE_C_AICOM_SIDE_BLACKLIST_COOLDOWN	900	Side-wide blacklist cooldown seconds.	Init_CommonConstants.sqf:984
WFBE_C_AICOM_STALL_ADVANCE_SECS	420	Time parked on the same unflipped target before the stall-advance abandon bypass fires.	Init_CommonConstants.sqf:805
WFBE_C_AICOM_LADDER_DECAY	1	On real progress, decay strikes by one instead of resetting to zero.	Init_CommonConstants.sqf:831
WFBE_C_AICOM_FAILED_JOURNEYS_RECYCLE	6	Failed journey count before a team is latched for recycle.	Init_CommonConstants.sqf:832
WFBE_C_AICOM_RECOVERY_V2	1	Enables Recovery V2 additions inside the strike-spawn.	Init_CommonConstants.sqf:874
WFBE_C_AICOM_RECOVERY_REVERSE_SPEED	6	Reverse-pulse speed in m/s for stuck vehicle recovery.	Init_CommonConstants.sqf:875
WFBE_C_AICOM_RECOVERY_SLOPE_Z	0.85 Chernarus, 0.80 Takistan	Foot snap treats surface normals below this as too steep.	Init_CommonConstants.sqf:876
WFBE_C_AICOM_RECOVERY_FOOT_ROAD_R	200 Chernarus, 300 Takistan	Road search radius for slope/water foot snaps.	Init_CommonConstants.sqf:877
WFBE_C_AICOM_GRADE_DWELL	6	Seconds a grade must persist before careful-gear slope downshift.	Init_CommonConstants.sqf:334
WFBE_C_AICOM_SLOPE_Z	0.86 Chernarus, 0.80 Takistan	Careful-gear governor slope threshold for vehicle hulls.	Init_CommonConstants.sqf:1145

The stall-advance branch still has a literal fallback default of 240 if the constant is missing (AI_Commander_AssignTowns.sqf:417-423), but normal current source initializes the constant to 420 before the worker reads it.

Trigger Taxonomy

Trigger	Detection	What changes	RPT cue
Position-stuck far from target	After WFBE_C_AICOM_STUCK_SECS, not airborne, not in COMBAT, moved less than WFBE_C_AICOM_STUCK_MOVED, and still farther than WFBE_C_AICOM_STUCK_FAR.	Bumps wfbe_aicom_stuckstrikes; if above WFBE_C_AICOM_STUCK_ABANDON, adds per-team blacklist, resets strikes and may tally side-wide abandons.	`STUCKSTAT
Combat orbiter	In COMBAT, if distance to target fails to close by at least 100m for three watch windows.	Bumps the same strike ladder, then resets the orbiter no-progress window.	`AICOMSTAT
Assault stranded	Dispatch stays open past the assault timeout.	Emits moved/stuck telemetry, closes the dispatch, increments failed-journey count and may latch recycle.	`AICOMSTAT
Uncapturable parked target	Team is within assault-arrive radius of the target, but the town remains enemy-held.	Refreshes breadcrumb without clearing strikes, bumps the strike ladder and records uncap context.	`STUCKSTAT
Stall-advance bypass	Same target has been booked longer than WFBE_C_AICOM_STALL_ADVANCE_SECS without a flip.	Blacklists the target for this team, resets strikes, marks _needs=true so the selector retargets the same tick, and counts a failed journey.	`AICOMSTAT
Uncapturable abandon	Uncap-parked strike count exceeds WFBE_C_AICOM_STUCK_ABANDON.	Same per-team blacklist/reset path as position-stuck, with failed-journey tally.	`AICOMSTAT
Side-wide repeated abandon	Several different teams abandon the same town while side blacklist is enabled.	Adds the town to the side logic's side-wide blacklist.	`AICOMSTAT
Real progress after strikes	Team moves enough while still on the same goto.	With ladder decay on, strike count decrements by one; with it off, strikes reset to zero. Stall clock restarts.	No dedicated line; infer from lower later strike tiers (AI_Commander_AssignTowns.sqf:488-501).
Wedge in defense/move	Strategy sees a noncombat defense/move team with no progress for WFBE_C_AICOM_STUCK_SECS.	Clears relief/strike state, sets move mode back to towns, clears wfbe_aicom_townorder, resets wfbe_aicom_stuckstrikes, and republishes an HC order if needed.	[AICOM INFORMATION] ... WEDGE-WATCHDOG released ... plus `AICOMSTAT

Recovery Order Publish

The detector does not directly shove the vehicle. It publishes a fresh order with the strike tier embedded:

1. AI_Commander_AssignTowns.sqf builds a road-node route for long legs, reading the current strike count as _hcStrk (:696-715).
2. The worker broadcasts wfbe_aicom_route and wfbe_aicom_unstuck to the team (:715-716).
3. If _hcStrk > 0, it emits UNSTUCK_STRIKE (:717-720).
4. The new wfbe_aicom_order is [nextSeq, "towns-target", destPos, _hcStrk], so the strike tier is tied to the same order sequence the executor accepts (:721).
5. The publish path emits CAPTURE_TRACE|ORDER_PUBLISHED with route= and strike= fields (:722).

This fourth order slot matters. Common_RunCommanderTeam.sqf reads the tier from _order select 3, not from the out-of-band wfbe_aicom_unstuck flag, because a later commander cycle could reset the flag before the fresh-seq branch runs (Common_RunCommanderTeam.sqf:933-945).

Recovery Actions

Common_RunCommanderTeam.sqf runs the action where the group and hulls are local. Recovery V2 is gated by WFBE_C_AICOM_RECOVERY_V2 inside the fresh-order strike spawn (Common_RunCommanderTeam.sqf:954-965).

Action	When it runs	Effect	Evidence
UNSTUCK_FIRED marker	Any fresh order with tier > 0.	Emits action telemetry and bumps wfbe_waspscale_recov on the local machine.	Common_RunCommanderTeam.sqf:968-973
Re-mount	Any strike tier.	Foot members with live assigned vehicles get orderGetIn true.	Common_RunCommanderTeam.sqf:974-979
Dead-driver swap	Recovery V2, lead hull alive/canMove but driver missing/dead and a live non-player crewman exists.	Moves the first live non-player crewman into the driver seat.	Common_RunCommanderTeam.sqf:986-998
Reverse pulse and lane flip	Recovery V2 on a live lead hull.	Zeroes velocity, applies two reverse velocity pulses using WFBE_C_AICOM_RECOVERY_REVERSE_SPEED, then flips wfbe_aicom_lanejit so the next road route uses the opposite lateral lane.	Common_RunCommanderTeam.sqf:1000-1023
Vehicle road snap	Tier >= 3, or Recovery V2 water guard at any tier, on a live hull.	If no player is within 100m, snaps the hull to the nearest non-water road node within 150m. If a player is near at tier >= 3, gives a small upward velocity hop instead of a visible teleport.	Common_RunCommanderTeam.sqf:1025-1044
Foot/dead-hull road snap	Tier >= 3, or Recovery V2 water guard, when leader is on foot or hull is null/dead/immobile.	Snaps the leader to a nearest non-water road node, widening the search radius when slope/water conditions justify it, then reforms foot squad members on the leader.	Common_RunCommanderTeam.sqf:1045-1083
Careful-gear governor	Same-seq follow-up while team remains on the order.	Downshifts to LIMITED while slope dwell is active or a stuck strike is active; restores FULL once both clear.	Common_RunCommanderTeam.sqf:1287-1348

AICOM auto-unflip is separate from the strike actions. Common_AICOM_AutoFlip.sqf watches local AICOM ground vehicles on server/HC, skips Air/Ship/Motorcycle, requires tilted, slow, grounded, dry and off cooldown, then sets vector up, lifts slightly, bumps the same local recovery counter, and emits AICOMSTAT|v1|EVENT|<isServer>|<min>|AUTOFLIP|righted=<type> (Common_AICOM_AutoFlip.sqf:21-75).

Operator Token Reference

Token	Prefix	Meaning	Where to look
`STUCKSTAT	...	stuck`	STUCKSTAT
`STUCKSTAT	...	uncap-parked`	STUCKSTAT
ORBITER_STUCK	`AICOMSTAT	v2	EVENT`
ASSAULT_STRANDED	`AICOMSTAT	v2	EVENT`
TARGET_ABANDON	`AICOMSTAT	v2	EVENT`
SIDE_BLACKLIST	`AICOMSTAT	v2	EVENT`
UNSTUCK_STRIKE	`AICOMSTAT	v2	EVENT`
`CAPTURE_TRACE	ORDER_PUBLISHED`	`AICOMSTAT	v2
UNSTUCK_FIRED	`AICOMSTAT	v2	EVENT`
AUTOFLIP	`AICOMSTAT	v1	EVENT`
WEDGE_RELEASE	`AICOMSTAT	v2	EVENT`
RALLY_FALLBACK	`AICOMSTAT	v2	EVENT`
RECYCLE_FLAG	`AICOMSTAT	v2	EVENT`
WASPSCALE recov=	WASPSCALE	Cumulative server-local recovery actions; HC-local recoveries remain visible on HC UNSTUCK_FIRED lines.	Periodic AICOM supervisor summary (AI_Commander.sqf:915-917).

Parser caution: STUCKSTAT is not AICOMSTAT, but it is part of the same operator story and carries the strike number. AUTOFLIP uses str isServer as its fourth field, not a side string. HC-delegated recovery actions can appear only in the HC RPT because the units and hulls are local there.

Reading A Stuck Episode

Sequence	Healthy interpretation
STUCKSTAT ... stuck ... strike=1 then UNSTUCK_STRIKE tier=1 then UNSTUCK_FIRED tier=1	Team was far from target, not in combat, barely moved, and the executor fired tier-1 recovery. Expect reverse/remount/lane-flip cues.
Repeated STUCKSTAT with rising strike, then UNSTUCK_FIRED tier=3	Chronic wedger reached terminal recovery. Expect road-snap or player-near hop guard.
STUCKSTAT ... uncap-parked then TARGET_ABANDON reason=uncapturable	Team reached the target but the town would not flip; it blacklisted that town and should choose another.
TARGET_ABANDON reason=stall-advance without terminal strike tier	Time-based bypass fired before the ladder completed; this is intentional for unflippable parked targets.
ASSAULT_STRANDED ... stuck=false	Dispatch timed out, but the moved/stuck fields say it was not the pure no-movement case; look for route length, combat, target flip or order churn.
WEDGE_RELEASE followed by new offense dispatch	A defense/move/relief team wedged and was reset to a clean towns leg with strikes cleared.
UNSTUCK_STRIKE without matching UNSTUCK_FIRED on the server RPT	Check the HC RPT if the team was delegated; local executor telemetry is emitted where the team runs.

Smoke Checklist

Scenario	Expected result
Far no-progress convoy	STUCKSTAT ... stuck appears after the breadcrumb window; fresh order publishes with strike=, and the local executor emits UNSTUCK_FIRED.
Chronic wedge with ladder decay on	Progress reduces strike count by one rather than zeroing it, so repeated wedges can reach tier 3 over time.
Flipped AICOM vehicle	Server/HC auto-unflip emits `AUTOFLIP
Water-stuck hull or leader	Recovery V2 forces the road-snap path even below tier 3.
Player near tier-3 vehicle	No visible teleport; expect the small upward velocity hop instead.
Uncapturable depot/center	uncap-parked or stall-advance cues lead to TARGET_ABANDON and a different target, not an idle team.
HC-delegated team	Pair server UNSTUCK_STRIKE / ORDER_PUBLISHED with HC-side UNSTUCK_FIRED; do not require server RPT to show HC-local execution.

Continue Reading

Runtime map: AI runtime/HC loop map | Telemetry schema: AI Commander logging and AICOMSTAT telemetry | Team executor: Commander-team driver | Player-side recovery: Player AI watchdog and recovery | Vehicle unflip context: AutoFlip vehicle recovery