Manual Combine Unloader — Call Unloader button for player-driven combines

[antler22]

This feature adds a "Call Unloader" button to manually-driven combines (i.e. combines that the player is driving themselves, not Courseplay-controlled). When activated, a nearby Courseplay-managed grain cart automatically:

1. Approaches the combine via pathfinding
2. Positions itself under the combine's unloading pipe
3. Follows the combine while it harvests (including through gentle curves and S-bends)
4. Leaves when the player closes the pipe (2-second debounce prevents false exits)
5. Automatically re-approaches if it loses position

The design goal is that the player only touches the button once — the grain cart handles everything until the pipe is closed.

Note: This PR replaces #1243, which was closed because it included unrelated personal preferences (US unit display). This branch contains only the manual unloader feature.

---

Files Changed

File	Status	Summary
scripts/ai/CpManualCombineProxy.lua	New	Proxy class mimicking AIDriveStrategyCombineCourse interface
scripts/specializations/CpAIFieldWorker.lua	Modified	cpToggleManualUnloader / cpIsManualCombineCallingUnloader toggle and proxy lifecycle
scripts/specializations/CpAIWorker.lua	Modified	Disable button/keybind for forage harvesters
scripts/ai/strategies/AIDriveStrategyUnloadCombine.lua	Modified	Core unloader steering, off-track recovery, proximity fixes
scripts/ai/PurePursuitController.lua	Modified	Soft-recovery hook before hard CP shutdown
scripts/pathfinder/PathfinderUtil.lua	Modified	Defensive windrow filtering in hasFruit()
config/VehicleSettingsSetup.xml	Modified	Lower minimum for "Call Unloader At" setting to 20%
scripts/events/CpManualUnloaderEvent.lua	New	Multiplayer sync event for the toggle

---

Key Design Decisions

CpManualCombineProxy implements the full AIDriveStrategyCombineCourse interface so AIDriveStrategyUnloadCombine can interact with a manual combine using identical method calls — no nil checks or special-casing scattered through the unloader code.

isManualProxy() → true — marker method used to gate manual-only behavior in AIDriveStrategyUnloadCombine without re-querying the vehicle.

getFillLevelPercentage() → 1 — always reports full so fill level never causes the cart to leave. The only valid exit is isUnloadFinished() (pipe closed for 2+ seconds).

driveBesideCombine() direct goal point — for manual combines, a live goal point is computed every frame from the combine's AI direction node at the pipe's lateral offset, normalLookAheadDistance meters ahead. As the combine turns, the node rotates and the cart follows naturally through curves and gentle S-bends. The placeholder course (built from combine's current heading) exists only to satisfy PPC initialisation and is never consulted for steering.

PPC soft-recovery hook — onOffTrackShutdown() in AIDriveStrategyUnloadCombine transitions the cart to IDLE instead of calling stopCurrentAIJob. The proxy's callUnloaderWhenNeeded() re-summons within ~2.5 s. The user never has to manually restart the grain cart.

Off-track grace period — offTrackGracePeriodMs = 10000 (class default, unchanged). During active unloading, disableStopWhenOffTrack(5000) is called each tick, fully suppressing off-track detection while the cart is under the pipe.

Forage harvesters excluded — button and keybind are hidden when pipeSpec.numAutoAimingStates > 0. Their auto-aim spout geometry requires a separate implementation.

---

Backward Compatibility

All changes are backward-compatible with CP-driven combines:

• Manual-only steering code is gated by combineStrategy:isManualProxy()
• Shared fixes (proximity terrain ignore, PPC soft-recovery hook) benefit CP-driven unloaders as well
• The callUnloaderPercent slider change (min 60% → 20%) applies to all combines

---

Known Limitations

• Sharp turns (>~60°) cause the cart to lose tracking; soft recovery re-approaches within a few seconds
• Forage harvesters are explicitly unsupported (button hidden)
• Requires the grain cart to be running a Courseplay Combine Unloader job

[antler22]

@pvaiko — reopening as a clean feature-only PR replacing #1243. All of your review feedback has been addressed:

• Naming updated throughout: cpIsManualCombineCallingUnloader, cpToggleManualUnloader, CpManualUnloaderEvent, and the HUD button now reads "Call Unloader"
• PurePursuitController.lua rebuilt on the current upstream base — diff is now ~36 lines showing only the actual additions (grace-period constant, offTrackShutdownSince state, and the soft-recovery block)
• CollisionAvoidanceController / ProximityController guards removed — both are now direct instantiation
• MotorController.lua reverted to upstream — it was included by mistake in the previous commit
• US unit changes (AIParameterSettingList.lua) are not in this branch — that stays in my personal fork only

Happy to discuss anything further or make adjustments.

[pvaiko]

Thank you for addressing the comments so far, will continue the review as work permits...

[pvaiko]

Can we move this to checkCombineRelocatedAndRepath() so everything is in one place?

[pvaiko]

On a second thought, I don't think this is even needed, the logic is already in checkCombineRelocatedAndRepath

[antler22]

Off-track shutdown should now be disabled for manual unloads.

[pvaiko]

Still should be moved checkCombineRelocatedAndRepath()

[Tensuko]

For adding Translations, please refer to our automatic translation:
https://github.com/Courseplay/Courseplay_FS25/wiki/Translations

[Tensuko]

One thing I found thats a bit problematic.
When the unloader approaches the player driven combine, that line appears as a small course. When you drive arround with the unloader on your side and you are too far away from that line and let the unloader go, it will report "left course".
That needs to be changed for manual unloading. Disable that check for left course for manual unloading.
Try it out.

[Tensuko]

When call an unloader:
2026-05-28 19:57:37.852 Error: Running LUA method 'update'.
E:/Dokumente/My Games/FarmingSimulator2025/mods/FS25_Courseplay/scripts/ai/CpManualCombineProxy.lua:69: attempt to call missing method 'getCpDriveStrategy' of table

[Tensuko]

2026-05-28 20:40:21.738 :21 [ppc controller lp1946] 7R 350 (Ernten 21)/211: PPC: prev 8 curr 9
2026-05-28 20:40:21.738 LUA call stack:
=E:/Dokumente/My Games/FarmingSimulator2025/mods/FS25_Courseplay/scripts/CpUtil.lua:215 error
=E:/Dokumente/My Games/FarmingSimulator2025/mods/FS25_Courseplay/scripts/debug/CpDebug.lua:64 isChannelActive
=E:/Dokumente/My Games/FarmingSimulator2025/mods/FS25_Courseplay/scripts/CpUtil.lua:173 debugVehicle
=E:/Dokumente/My Games/FarmingSimulator2025/mods/FS25_Courseplay/scripts/ai/CpManualCombineProxy.lua:244 willWaitForUnloadToFinish
=E:/Dokumente/My Games/FarmingSimulator2025/mods/FS25_Courseplay/scripts/ai/strategies/AIDriveStrategyUnloadCombine.lua:1438 startUnloadingCombine
=E:/Dokumente/My Games/FarmingSimulator2025/mods/FS25_Courseplay/scripts/ai/strategies/AIDriveStrategyUnloadCombine.lua:2016 driveToCombine
=E:/Dokumente/My Games/FarmingSimulator2025/mods/FS25_Courseplay/scripts/ai/strategies/AIDriveStrategyUnloadCombine.lua:479 getDriveData
=E:/Dokumente/My Games/FarmingSimulator2025/mods/FS25_Courseplay/scripts/specializations/CpAIWorker.lua:410 onUpdate
=dataS/scripts/specialization/SpecializationUtil.lua:56 raiseEvent
=dataS/scripts/vehicles/Vehicle.lua:2041 update
=dataS/scripts/network/NetworkNode.lua:181 updateActiveObjects
=dataS/scripts/network/Server.lua:64 update
=dataS/scripts/BaseMission.lua:1023 update
=dataS/scripts/utils/Utils.lua:690
=dataS/scripts/FSBaseMission.lua:1914 update
=dataS/scripts/mission00.lua:683 update
=dataS/scripts/main.lua:1262 update
2026-05-28 20:40:21.738 :21 [error lp1946] Error: debug channel nil not found!

[antler22]

Had a few hiccups with some of the fixes recently, as of this comment it should be repaired and ready to test again. I believe I have accounted for all comments above, except translations which will be handled at the end.

[Tensuko]

Left the course issue is still there.

[Tensuko]

Still the same.

[Tensuko]

You need to call it, drive far away enough and release it then.

[Tensuko]

Now it is working, nice.
But we need to figure something out for the HUD.
The translations are not correct yet and maybe an Icon with color on/off would be better to not have overlapping text.

[antler22]

Glad to hear it, I think I found a better setup for the HUD, moving it to the bottom. Also added translations now.

[Tensuko]

Edit: If you did copy a course, the place is also used.
But it seems like MP is not working, it just crashed the Server.

[antler22]

On the copy course, yes. But I had the unloader text hidden if copy course is being used. Copy Course is priority, and often temporary, but Unloader text is supposed to hide in that case.

I'll look into the MP, I don't play it myself. I assume no leads via errors?

[Tensuko]

The log was gone because the Server did a complete restart.
I can check if I can get the same problem in local host, but I doubt that.

[antler22]

Please read, I'm hesitant to mess with the code outside of this feature, but this is what AI is finding for me...

MP Crash Diagnosis

Confidence: High. I can trace the crash to a specific code path.

---

Root Cause: Infinite Event Echo Loop (Broadcast Storm)

The crash is caused by a re-entrant call pattern between CpManualUnloaderEvent:run() and cpToggleManualUnloader(). The infrastructure is pre-existing upstream code that was never actually tested because the CpManualCombineProxy was a stub. Our feature fleshed out the proxy, making the button functional — and triggering the latent bug.

The loop, step by step:

In a dedicated server or listen server with 3+ players, when Client B receives a broadcast of the toggle event from the server:

1. CpManualUnloaderEvent:run() is called on Client B
2. It calls self.vehicle:cpToggleManualUnloader() ([CpAIFieldWorker.lua:309](scripts/specializations/CpAIFieldWorker.lua))
3. Inside cpToggleManualUnloader, the guard is if not self.isServer then CpManualUnloaderEvent.sendEvent(self) end
4. self.isServer = false on any client → sends the event right back to the server
5. Server processes the event again → toggles the proxy back off → broadcasts to original clients
6. Clients receive → call cpToggleManualUnloader() → re-send → repeat forever

The proxy is toggled on/off at network speed, the event queue is flooded, and the server crashes.

---

Why it triggers only in specific topologies

Setup	Crash?
Single-player	No
Listen server, 2 players (host + 1 client)	No — host's press has isServer=true, no event; client's press broadcasts to nobody else
Listen server, 3+ players	Yes — a third player receives the server broadcast and echoes it back
Dedicated server, 2+ clients	Yes — any client's press causes Client B to echo

This explains why local testing (single player / listen server 2-player) seemed fine but a real multiplayer server crashed immediately.

---

Secondary Bug: Host's Toggle Never Syncs to Clients

On a listen server, when the host player presses the button:

• self.isServer = true → CpManualUnloaderEvent.sendEvent() is never called
• Clients never receive the toggle event → their HUD and proxy state are out of sync

The proxy works on the server but clients can't see it's active.

---

Our Code Changes Are Not the Source

The three code changes we made to the strategy and proxy are safe in MP:

• AIDriveStrategyUnloadCombine:update() / call() / releaseCombine() — strategy runs self.isServer-guarded in CpAITaskCombineUnloader:start(), so only executes on server
• CpManualCombineProxy:update() PPC disable — the unloaderVehicle:getCpDriveStrategy() path is nil-guarded; on clients the strategy is nil so it silently no-ops
• isActiveCpCombine simplification — no crash possible, just returns false for manual combines

---

Fix Plan

File: [scripts/specializations/CpAIFieldWorker.lua](https://claude.ai/epitaxy/scripts/specializations/CpAIFieldWorker.lua)

Add a noEventSend parameter to cpToggleManualUnloader. Replace the current guard:

-- CURRENT (buggy):
if not self.isServer then
    CpManualUnloaderEvent.sendEvent(self)
end

-- FIXED:
if not noEventSend then
    CpManualUnloaderEvent.sendEvent(self)   -- sendEvent already routes: server→broadcast, client→send-to-server
end

Remove the not self.isServer guard entirely — CpManualUnloaderEvent.sendEvent() already handles both cases correctly (g_server ~= nil → broadcast, else → send to server). The guard was over-restricting and broken.

File: [scripts/events/CpManualUnloaderEvent.lua](https://claude.ai/epitaxy/scripts/events/CpManualUnloaderEvent.lua)

Pass noEventSend = true when calling toggle from the event handler, so it applies state without re-triggering network sends:

function CpManualUnloaderEvent:run(connection)
    if self.vehicle and self.vehicle.cpToggleManualUnloader then
        self.vehicle:cpToggleManualUnloader(true)   -- noEventSend=true: apply state, don't echo
    end
    if not connection:getIsServer() then
        g_server:broadcastEvent(CpManualUnloaderEvent.new(self.vehicle), nil, connection, self.vehicle)
    end
end

This is the same two-file pattern the upstream VehicleSettingsEvent already follows.

[Tensuko]

It works in MP.
But needs one more MP test, what if 2 Player call the unloader.

As a later addition, make this possible with chopper would be the next big request from users, pretty sure.
But that can be addressed in another PR later.

[antler22]

I've been testing with 1 CP combine, 1 Manual combine. Logic is supposed to be whichever unloader calls first. If I am running the combine, I make sure to call before the unload threshold approaches for the CP combine. Sometimes, because it predicts fill level for the CP combine, I miss the chance but that is ok.

First called, first served.

For Silage choppers, field logistics work a bit differently as you know, since unloader often drives away to bunker instead of overloading at the field. Courseplay's big advantage is locating trailers at the field automatically, but that's not usually needed here. Plus, you have a moving spout, and user preferences on unloader side, crop detection, etc. It gets messy. My personal preference is using AutoDrive in this case. But, if there's enough demand I'm sure it wouldn't take much to ID the silage choppers for this feature and turn it on. I think users would start to demand preferences on unload side or extra controls if that happened.

For now, my preference is to leave silage choppers alone.

[Tensuko]

Thats totaly fine :)
It is cool that this is working.

Have you tried CP unloader in combination with AutoDrive? So when an unloader is full and/or you release it, AD takes over?
Else ofc overloader are perfect for this.

[Tensuko]

The MP sync is messed up.
The active/inactive display is switched at some point.
Helpers stay active even it is shown that they are not.

Don't know if that is only the HUD sync or something more.