feat(caravans): trade caravan escort, bandit ambush, and cargo delivery payout engine

[angelTomo9]

Summary

Implements a trade caravan escort, route waypoint progression, bandit raider ambushes, and cargo delivery payout engine for OpenAO MMORPG.

Features

• Caravan tiers catalog (Merchant Supply Cart, Royal Treasury Carriage, Silk Road Convoy)
• Waypoint route progression state machine
• Bandit ambush encounters with guard defense mitigation
• Wagon cargo durability loss and plundering failure state
• Depot delivery gold bounty scaled by intact cargo health percentage
• Full unit test coverage under Vitest

[gitar-bot]

Code Review ✅ Approved 2 resolved / 2 findings

Implements trade caravan escort mechanics with waypoint progression, bandit ambush encounters, and cargo delivery payouts scaled by intact cargo health. Fixes AMBUSH_ENGAGED state transition assignment and removes the arbitrary 10% health payout floor to properly reflect cargo condition.

✅ 2 resolved

✅ Bug: AMBUSH_ENGAGED status is never assigned, guard is dead code

📄 api/src/lib/caravanEscortRobbery.ts:8 📄 api/src/lib/caravanEscortRobbery.ts:77-79 📄 api/src/lib/caravanEscortRobbery.ts:113-114
The CaravanStatus union declares AMBUSH_ENGAGED and advanceWaypoint blocks progression when caravan.status === "AMBUSH_ENGAGED", but no method ever sets that status — triggerBanditAmbush only ever transitions to IN_TRANSIT or PLUNDERED_FAILURE. As a result the state machine never actually locks a caravan during a raid, so the intended "cannot advance while ambushed" rule can never fire and a caller can freely advance waypoints mid-ambush. Set caravan.status = "AMBUSH_ENGAGED" at the point the ambush begins (e.g. a dedicated engage step, or keep the status until the encounter is resolved) so the guard becomes reachable.

✅ Edge Case: Depot payout floors health ratio at 10% even for near-destroyed cargo

📄 api/src/lib/caravanEscortRobbery.ts:128-134
completeDepotDelivery computes healthRatio = Math.max(0.1, currentHp / maxHp), so a caravan delivered with almost no intact cargo still pays out 10% of the base gold, and the returned cargoHealthRatio misreports the true condition. If a minimum bounty is intended this is fine, but the floor is silent and untested; if not intended, remove the Math.max(0.1, ...) clamp so payout scales truthfully with remaining HP.

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change the behavior for this request:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

---

Important

Your trial ends in 4 days — upgrade now to keep code review, CI analysis, auto-apply, custom automations, and more.

_{Was this helpful? React with 👍 / 👎 | Gitar}