## Zweck

`PlayerLivestockDriver.lua` macht den Spieler zu einem virtuellen Tiertransporter. Das Script nutzt weiterhin das normale Giants-Tiermenue, bewegt die AnimalCluster aber nicht in ein echtes Fahrzeug, sondern in einen unsichtbaren Player-Carrier.

Dadurch koennen Tiere realistischer von Stall zu Stall oder vom Trigger weggetrieben werden, ohne dass dafuer ein Trailer angekuppelt sein muss.

Die Tierdaten kommen aus dem aktiven `AnimalSystem` der Karte. Eigene Map-Tiere funktionieren deshalb grundsaetzlich, solange sie korrekt als AnimalType/SubType im Spiel registriert sind.

## Bedienung im Spiel

- Der Spieler stellt sich in Reichweite eines `AnimalLoadingTrigger`.
- Wenn Tiere vorhanden sind, wird das normale Tiermenue mit dem Player als Ziel/Quelle geoeffnet.
- Mit `Zum Spieler treiben` werden Tiere in den virtuellen Player-Carrier geladen.
- Mit `In den Stall bringen` werden die Tiere wieder an den aktiven Trigger abgegeben.

### Tastenbelegung

Aktion | Standard Taste | Beschreibung
--- | --- | ---
`LSFM_PLAYER_LIVESTOCK_TOGGLE_WAIT` | `ALT + H` | Tiere warten lassen oder wieder rufen.
`LSFM_PLAYER_LIVESTOCK_TOGGLE_DRIVE_MODE` | `ALT + J` | Zwischen Folgen und Treiben umschalten.

Solange Tiere beim Spieler aktiv sind, blockiert das Script das Einsteigen in Fahrzeuge und das Speichern. Die Tiere sollen zuerst wieder in einen Stall gebracht werden.

## Einbindung im Mod

Das Script wird ueber die `extraSourceFiles` der `modDesc.xml` geladen.

    <extraSourceFiles>
        <sourceFile filename="scripts/AddStoreCategory.lua" />
        <sourceFile filename="scripts/PlayerLivestockDriver.lua" />
    </extraSourceFiles>

Die beiden Aktionen werden ebenfalls in der `modDesc.xml` registriert.

    <actions>
        <action name="LSFM_PLAYER_LIVESTOCK_TOGGLE_WAIT" category="ONFOOT" axisType="HALF" />
        <action name="LSFM_PLAYER_LIVESTOCK_TOGGLE_DRIVE_MODE" category="ONFOOT" axisType="HALF" />
    </actions>

## Kapazitaeten

Die maximale Anzahl wird im Script definiert. Wenn ein AnimalType nicht in der Tabelle steht, gilt der Standardwert `MAX_ANIMALS = 12`.

AnimalType Name | Max. Tiere
--- | ---
`COW` | 6
`WATER_BUFFALO`, `BUFFALO` | 4
`HORSE` | 2
`PIG` | 16
`SHEEP`, `GOAT` | 24
`CHICKEN`, `DUCK`, `GOOSE` | 40
`TURKEY` | 30

Optisch werden maximal `MAX_VISIBLE_ANIMALS = 25` Tiere dargestellt. Das haelt die Darstellung beherrschbar, auch wenn intern mehr Tiere bewegt werden.

## Technischer Ablauf

- `PlayerLivestockDriverCarrier` simuliert ein Fahrzeugziel fuer das Giants-Tiermenue.
- `PlayerLivestockDriverClusterSystem` verwaltet die geladenen AnimalCluster.
- Die Funktionen der `AnimalScreenTrailerFarm` werden ueberschrieben, damit Quelle und Ziel zwischen Stall und Spieler wechseln koennen.
- Die sichtbaren Tiere verwenden die Visual-/Animationslogik aus `AnimatedLivestockTrailer`, wenn diese vorhanden ist.
- Die Tierpositionen folgen dem Spieler oder werden im Treibmodus vor dem Spieler gehalten.
- Terrainhoehe und Bodenanpassung laufen ueber die vorhandene Ground-Alignment-Logik.

## l10n Texte

Alle sichtbaren Texte sind l10n-faehig und liegen in den `translations/l10n_*.xml` Dateien.

Text-Key | Verwendung
--- | ---
`button_playerLivestockMoveToPlayer` | Button im Tiermenue: Tiere zum Spieler treiben.
`button_playerLivestockMoveToFarm` | Button im Tiermenue: Tiere in den Stall bringen.
`playerLivestockDriver_confirmMoveToPlayer` | Bestaetigung fuer mehrere Tiere zum Spieler.
`playerLivestockDriver_confirmMoveToPlayerSingular` | Bestaetigung fuer ein Tier zum Spieler.
`playerLivestockDriver_confirmMoveToFarm` | Bestaetigung fuer mehrere Tiere in den Stall.
`playerLivestockDriver_confirmMoveToFarmSingular` | Bestaetigung fuer ein Tier in den Stall.
`playerLivestockDriver_playerTargetName` | Name des virtuellen Ziels im Tiermenue.
`button_playerLivestockWait` | Action-Event: Tiere warten lassen.
`button_playerLivestockFollow` | Action-Event: Tiere rufen.
`button_playerLivestockModeDrive` | Action-Event: Treibmodus aktivieren.
`button_playerLivestockModeFollow` | Action-Event: Folgemodus aktivieren.
`input_LSFM_PLAYER_LIVESTOCK_TOGGLE_WAIT` | Name der Tastenbelegung fuer Warten/Folgen.
`input_LSFM_PLAYER_LIVESTOCK_TOGGLE_DRIVE_MODE` | Name der Tastenbelegung fuer Treiben/Folgen.
`playerLivestockDriver_vehicleBlocked` | Warnung beim Versuch, mit aktiven Tieren in ein Fahrzeug zu steigen.
`playerLivestockDriver_saveBlocked` | Warnung beim Versuch, mit aktiven Tieren zu speichern.

## Assets und Sounds

Pfad | Verwendung
--- | ---
`store/store_playerLivestockDriver.dds` | Fake-StoreItem-Bild fuer den virtuellen Carrier.
`sounds/playerLivestock_call.ogg` | Ruf-/Action-Sound beim Umschalten von Warten/Folgen.
`sounds/anmlDogSitBreath_01.ogg` usw. | Zufaellige Sounds fuer den Huetehund, wenn er aktiv ist.

Fehlende Sounds werden bewusst als Warning in die Log geschrieben. Das sind keine Debugmeldungen, sondern echte Asset-Hinweise.

## Hinweise zur Pflege

- Neue Tierarten muessen nicht zwingend im Script eingetragen werden. Ohne speziellen Eintrag greifen Standardkapazitaet und die Map-Registrierung des Spiels.
- Wenn eine Tierart eine abweichende sinnvolle Kapazitaet braucht, wird sie in `MAX_ANIMALS_BY_TYPE_NAME` ergaenzt.
- Die Log enthaelt im Release keine Debug-Infos fuer Menueaufrufe, Animationswechsel oder Follow-Slots.
- Warnings fuer fehlende Sounds, fehlende Visuals oder blockierte Aktionen sollten erhalten bleiben, weil sie bei echten Fehlern helfen.