Feat: Troop transport retreats to closest owned tile

[bijx]

If this PR fixes an issue, link it below. If not, delete these two lines.
Resolves #1139

Description:

Adds logic to troop transport retreat behaviour which retreats a transport to the closest owned tile instead of the source. Realized we can use the existing closestShoreFromPlayer() function here without adding any additional logic. Now if no shores are detected (you lost all your shoreline while the transport was out) we handle the return case same as if the original source was no longer your territory.

Screen.Recording.2026-01-04.031913.mp4

Please complete the following:

• I have added screenshots for all UI updates
• I process any text displayed to the user through translateText() and I've added it to the en.json file
• I have added relevant tests to the test directory
• I confirm I have thoroughly tested these changes and take full responsibility for any bugs introduced

Please put your Discord username so you can be contacted if a bug or regression is found:

bijx

[coderabbitai]

Walkthrough

TransportShipExecution enhanced to track and reuse retreat destinations. When boats retreat, the system now computes the nearest owned shore tile once using closestShoreFromPlayer and stores it to avoid repeated calculations during the retreat sequence.

Changes

Cohort / File(s)	Summary
Retreat destination tracking src/core/execution/TransportShipExecution.ts	Added retreatDst field to cache computed retreat destination. Updated imports to include closestShoreFromPlayer. Enhanced retreat tick logic to find nearest shore tile once per retreat sequence, reuse cached destination, and return troops if no valid shore found.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• fix(2388): troop penalty applied to boat retreat #2389: Also modifies retreat-handling logic in TransportShipExecution.ts, adjusting how retreats are processed and destinations are set
• Boat retreat #705: Modifies retreat handling for transport ships with retreat-related logic adjustments
• Landing boats always conquer shore tile #790: Changes landing and arrival behavior in TransportShipExecution.ts, including retreat destination computation using closestShoreFromPlayer

Suggested labels

Backend Feature - New

Suggested reviewers

• scottanderson
• evanpelle

Poem

⛵ Boats beat a hasty retreat to shore,
No longer lost like days before,
Closest tile now shows the way,
Safe harbor waits—hip hip hooray! 🏝️

Pre-merge checks

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding logic for troop transport to retreat to the closest owned tile instead of the source.
Description check	✅ Passed	The description clearly explains the feature addition, references the resolved issue, and details the implementation approach using the existing closestShoreFromPlayer() function.
Linked Issues check	✅ Passed	The PR implements the core requirement from issue #1139: redirecting retreating boats to the closest owned tile with proper handling for lost shoreline scenarios.
Out of Scope Changes check	✅ Passed	All changes are focused on the retreat behavior feature for transport ships; no out-of-scope modifications detected in the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6d1e2f5 and 2428422.

📒 Files selected for processing (1)

• src/core/execution/TransportShipExecution.ts

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: VariableVince
Repo: openfrontio/OpenFrontIO PR: 2396
File: src/core/execution/TransportShipExecution.ts:180-189
Timestamp: 2025-11-06T00:56:21.251Z
Learning: In OpenFrontIO, when a player conquers a disconnected player, transport ships and warships are only transferred to the conqueror if they are on the same team. If an enemy (non-teammate) conquers a disconnected player, the ships are deleted (described as "boated into a sea mine"), not captured.

📚 Learning: 2025-05-19T06:00:38.007Z

Learnt from: scottanderson
Repo: openfrontio/OpenFrontIO PR: 784
File: src/core/game/StatsImpl.ts:125-134
Timestamp: 2025-05-19T06:00:38.007Z
Learning: In StatsImpl.ts, unused parameters in boat/stats-related methods are intentionally kept for future use and shouldn't be removed.

Applied to files:

• src/core/execution/TransportShipExecution.ts

🧬 Code graph analysis (1)

src/core/execution/TransportShipExecution.ts (2)

src/core/game/GameMap.ts (1)

• TileRef (3-3)

src/core/game/TransportShipUtils.ts (1)

• closestShoreFromPlayer (123-140)

🔇 Additional comments (3)

src/core/execution/TransportShipExecution.ts (3)

13-16: LGTM!

The import additions are clean and necessary for the new retreat logic.

---

42-42: LGTM!

The field correctly tracks the retreat destination to avoid repeated calculations.

---

202-232: Clean retreat logic implementation.

The code correctly:

• Calculates the nearest owned shore once per retreat sequence using closestShoreFromPlayer
• Handles the case where no owned shore exists by returning troops and deleting the boat
• Updates this.attacker to match the boat owner before finding the shore, ensuring the ownership check at line 237 works correctly

The retreat destination is cached in retreatDst and not recalculated, even if boat ownership changes (e.g., through teammate conquest at lines 193-200). This design is sound—it prevents direction changes mid-journey. The ownership check at line 237 properly handles both cases: if the destination is now owned, troops return home; if not owned, the boat attempts conquest.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}