FS25 Harvester Unloader Sync - Version 1.2.6.0
Author: Sherman
================================================

Purpose
-------
Synchronizes an unloading tractor and its attached trailer with a nearby combine
or forage harvester while unloading on the move. While sync is active, the mod
controls only the tractor cruise-control speed and continuously corrects the
forward/back distance to the harvester. Steering remains fully manual.

Realistic retrofit system
-------------------------
The synchronization hardware must now be installed on BOTH machines:
- Follower vehicle / unloading tractor retrofit: 4,990 EUR
- Leader vehicle / combine or forage harvester retrofit: 5,990 EUR

The configuration is automatically added to suitable motorized shop vehicles,
including compatible mod vehicles. Existing vehicles can be retrofitted through
the workshop where normal vehicle reconfiguration is available.

The prices are intentionally based on real precision-ag retrofit costs. Current
John Deere Precision Essentials hardware is around 2,990 EUR before tax and the
Automation licence containing Machine Sync is around 1,990 EUR per year; extra
components and installation can apply. The in-game one-time prices bundle those
costs into a practical gameplay price.

IMPORTANT: The left HUD/help entry appears only when BOTH the unloading vehicle
and a nearby combine/forage harvester have the sync system installed. If either
side does not have the system, nothing is shown and sync cannot be activated.

Savegame / update compatibility
-------------------------------
The existing vehicle configuration identifiers remain permanently unchanged:
- Configuration name: husSyncSystem
- Not installed: OFF
- Follower retrofit: FOLLOWER
- Leader retrofit: LEADER
- Runtime indices: OFF = 1, INSTALLED = 2

No additional savegame conversion or special loader logic is used. The mod relies on
GIANTS' normal vehicle configuration persistence. Future updates must keep these IDs.

Controls
--------
Default: Left Alt + U
The binding can be changed in the Farming Simulator controls menu.

How to use
----------
1. Configure the unloading tractor with the follower retrofit kit.
2. Configure the combine or forage harvester with the leader retrofit kit.
3. Attach a compatible grain/silage trailer to the tractor.
4. Drive alongside the equipped harvester (within about 35 m).
5. The left help entry appears. Press Left Alt + U to activate sync.
6. Sync takes over cruise-control speed and longitudinal distance correction.
7. Steer the tractor manually so the trailer remains under the discharge point.
8. Press Left Alt + U again, or manually switch cruise control off, to cancel.

HUD / Help entry
----------------
No custom status is rendered on the right side of the screen.
Only the standard left-side help/action entry is used.
It is visible only when both vehicles are equipped and a suitable harvester is
nearby. It switches between UNLOADER SYNC: OFF and UNLOADER SYNC: ON.

Performance
-----------
- HARD GATE: tractors without the follower retrofit perform no harvester scan, no distance check, no trailer/fill-node search and no sync HUD logic.
- The harvester cache is not built at map start; it is created lazily only when an equipped follower tractor actually needs it.
- Tractors without the retrofit do not receive the sync action event.
- Harvester-only candidate cache.
- GIANTS MessageCenter marks the cache dirty only when vehicles are added/removed.
- Nearby equipped harvester is cached and distance-checked until it leaves the area.
- No square-root distance calculation for proximity searches.
- Trailer fill target and discharge node remain cached while valid.
- Active cruise/distance controller runs at 10 Hz to reduce periodic control/physics writes.
- Heading threshold avoids expensive acos() calculations.
- Redundant cruise-control and motor-limit writes are suppressed.

Notes
-----
- Steering always remains completely manual.
- The trailer fill target is used for longitudinal positioning, not just the tractor body.
- Uses GIANTS FillUnit exact fill root / auto-aim nodes when available.
- Full trailers are skipped.
- Author field is Sherman only.
