## Kurzfassung

Das Script ersetzt bei einem normalen Giants-Viehtrailer die statischen Tiermodelle durch animierte Tiere. Die echte Giants-Logik bleibt erhalten: Beladen, Entladen, Tier-Cluster, Savegame und Multiplayer laufen weiter über `livestockTrailer`.

### Normale Trailer

Animierte Tiere stehen oder idlen im Trailer. Dafür ist `useSpeedAnimations="false"` sinnvoll.

### Viehtreibwagen

Tiere laufen optisch auf dem Boden mit. Dafür nimmt man `alignToTerrain="true"` und `useSpeedAnimations="true"`.

### Eigene Maps

Map-eigene Tiere funktionieren, wenn sie sauber im Giants `AnimalSystem` registriert sind.

Wichtig: Der normale `<livestockTrailer>` Block bleibt immer erhalten. Unser Block `<animatedLivestockTrailer>` kommt zusätzlich dazu.

## Einbau im Mod

### 1. Spezialisierung in der modDesc.xml registrieren

    <specialization name="animatedLivestockTrailer"
                    className="AnimatedLivestockTrailer"
                    filename="scripts/AnimatedLivestockTrailer.lua"/>

### 2. Fahrzeugtyp mit beiden Spezialisierungen anlegen

    <type name="livestockTrailerSpecial" parent="baseTipper" filename="$dataS/scripts/vehicles/Vehicle.lua">
        <specialization name="livestockTrailer"/>
        <specialization name="animatedLivestockTrailer"/>
    </type>

### 3. In der Fahrzeug-XML beide Blöcke verwenden

    <livestockTrailer>
        <animal type="cow" node="cows" numSlots="5"/>
        <animal type="sheep" node="sheeps" numSlots="12"/>
    </livestockTrailer>

    <animatedLivestockTrailer
        alignToTerrain="false"
        useSpeedAnimations="false"
        randomIdleStart="true"
        showOnHud="true"
        useAnimalSounds="true"/>

## Die XML-Blöcke

### `<livestockTrailer>`

Das ist der Giants-Block. Hier stehen die Tierarten, Slot-Nodes und Stückzahlen. Unser Script liest diese Daten mit, baut daraus die Shop-Anzeige und setzt die animierten Tiere auf die Slots.

    <livestockTrailer>
        <animal type="alpaca" node="alpacas" numSlots="1" shopTitle="$l10n_shopAnimal_alpacas"/>
    </livestockTrailer>

`shopTitle` ist optional. Wenn es fehlt, nutzt das Script den allgemeinen Tiernamen aus der Animals-XML, zum Beispiel "Alpakas" statt "Alpaka weiß".

### `<animatedLivestockTrailer>`

Das ist unser zusätzlicher Block. Hier wird gesteuert, ob Tiere laufen, ob sie auf dem Boden stehen, ob Sounds abgespielt werden, ob das HUD angezeigt wird und welche Altersgrenzen gelten.

    <animatedLivestockTrailer
        alignToTerrain="true"
        alignToGroundCollisions="true"
        groundRaycastOffset="4"
        groundRaycastDistance="12"
        useSpeedAnimations="true"
        randomIdleStart="true"
        randomMovementStart="true"
        reverseMovementAnimations="true"
        maxLoadedSpeed="7"
        minimumLoadAge="7"/>

### Tier-spezifische Overrides

Diese Einträge im `<animatedLivestockTrailer>` Block braucht man nur, wenn eine Tierart eigene Clipnamen oder eigene Dateien verwenden soll.

    <animatedLivestockTrailer useSpeedAnimations="true">
        <animal type="horse"
                idleClip="idle1Source"
                walkClip="walkFwdLSource"
                runClip="runFwdLSource"
                referenceWalkSpeed="4"
                referenceRunSpeed="12"/>
    </animatedLivestockTrailer>

### Käfig-Overrides

Für Geflügel kann eine Tierart statt einzelner freier Tiere eine Käfig-i3d laden. Die echten Giants-Slots bleiben erhalten, aber optisch werden mehrere Tiere in einem Käfig zusammengefasst.

    <animatedLivestockTrailer>
        <animal type="chicken"
                visualMode="cage"
                cageFilename="objects/poultryBox.i3d"
                cageAnimalSlotsPath="animalSlots"
                animalsPerCage="4"
                cageSlotStep="4"
                cageAnimalMode="animated"/>
    </animatedLivestockTrailer>

## Fertige Beispiele

### Normaler Viehtrailer

Für Trailer, in denen die Tiere nicht auf dem Boden mitlaufen sollen.

    <animatedLivestockTrailer
        alignToTerrain="false"
        useSpeedAnimations="false"
        randomIdleStart="true"
        showOnHud="true"
        useAnimalSounds="true"
        animalSoundVolumeScale="0.22"/>

### Viehtreibwagen

Für den Wagen ohne Boden, bei dem Tiere optisch auf dem Boden mitlaufen.

    <animatedLivestockTrailer
        alignToTerrain="true"
        useSpeedAnimations="true"
        randomIdleStart="true"
        randomMovementStart="true"
        reverseMovementAnimations="true"
        minimumLoadAge="7"
        unsupportedAgeWarningText="$l10n_warning_animalAgeNotSupportedByTrailer"
        maxLoadedSpeed="7"
        groundOffset="0.00"
        walkSpeed="0.5"
        runSpeed="9"
        referenceWalkSpeed="4"
        referenceRunSpeed="12"/>

### oldAnimalTrailer nur für Jungtiere

Für den kleinen Anhänger, der nur Tiere bis einschließlich 6 Monate laden darf.

    <animatedLivestockTrailer
        alignToTerrain="false"
        useSpeedAnimations="false"
        maximumLoadAge="6"
        unsupportedAgeWarningText="$l10n_warning_animalAgeNotSupportedByTrailer"
        randomIdleStart="true"
        showOnHud="true"
        useAnimalSounds="true"/>

## Käfigmodus

Der Käfigmodus ist für Geflügel gedacht. In `<livestockTrailer>` bleibt die normale Kapazität stehen, zum Beispiel 76 Hühner. Im `<animatedLivestockTrailer>` sagt `animalsPerCage="4"`, dass daraus optisch 19 Käfige werden.

Die Tiere im Käfig werden als Idle-Tiere geladen. Laufanimationen sind dort bewusst aus, weil der Käfig selbst die Ladung trägt.

Ohne eigenes `cageSlotNode` nutzt das Script automatisch jeden vierten normalen Tier-Slot als Käfigposition. Wenn eigene Käfigplätze im Fahrzeug gebaut werden, kann man stattdessen `cageSlotNode` auf eine TransformGroup mit Käfig-Slots zeigen lassen.

    <livestockTrailer>
        <animal type="chicken" node="chickens" numSlots="76"/>
    </livestockTrailer>

    <animatedLivestockTrailer alignToTerrain="false">
        <animal type="chicken"
                visualMode="cage"
                cageFilename="objects/poultryBox.i3d"
                cageAnimalSlotsPath="animalSlots"
                animalsPerCage="4"
                cageSlotStep="4"
                cageAnimalMode="animated"/>
    </animatedLivestockTrailer>

Die Käfig-i3d braucht eine Node mit inneren Tierplätzen. Beim LSFM-Geflügelkäfig ist das `animalSlots` mit `animalSlot01` bis `animalSlot04`.

## Attribute erklärt

Attribut | Standard | Erklärung
--- | --- | ---
`enabled` | `true` | Schaltet die animierten Tiere für dieses Fahrzeug ein oder aus.
`showOnHud` | `true` | Zeigt den Tier-Füllstand rechts im HUD.
`hudText` | leer | Optionaler HUD-Text oder l10n-Key.
`alignToTerrain` | `true` | Setzt Tiere auf Terrain-Höhe. Wichtig für den Viehtreibwagen.
`alignToGroundCollisions` | `false` | Sucht per Raycast nach Brücken und statischen Boden-Collisions, bevor auf Terrain-Höhe zurückgefallen wird.
`groundRaycastOffset` | `4` | Start-Höhe des Boden-Raycasts über dem Tier-Slot.
`groundRaycastDistance` | `12` | Länge des Boden-Raycasts nach unten.
`useSpeedAnimations` | `true` | Wechselt je nach Geschwindigkeit zwischen Idle, Walk und Run.
`randomIdleStart` | `true` | Idle-Animationen starten zufällig, damit Tiere nicht synchron wackeln.
`randomMovementStart` | `true` | Laufanimationen starten zufällig.
`reverseMovementAnimations` | `true` | Beim Rückwärtsfahren laufen Walk/Run Clips rückwärts.
`maxLoadedSpeed` | leer | Begrenzt die Fahrzeuggeschwindigkeit, sobald Tiere geladen sind.
`minimumLoadAge` | `0` | Mindestalter in Monaten. 0 bedeutet keine Grenze.
`maximumLoadAge` | `0` | Höchstalter in Monaten. 0 bedeutet keine Grenze.
`filterMissingAnimalTypes` | `true` | Überspringt Tierarten, die auf der aktuellen Map nicht im AnimalSystem registriert sind.
`walkSpeed` | `0.5` | Ab dieser Geschwindigkeit startet Walk.
`runSpeed` | `9` | Ab dieser Geschwindigkeit startet Run.
`idleClip` | `idle1Source` | Standard-Idle-Clip.
`walkClip` | `walkFwdLSource` | Standard-Walk-Clip.
`runClip` | `runFwdLSource` | Standard-Run-Clip.
`playbackScale` | `1` | Allgemeiner Multiplikator für die Animationsgeschwindigkeit.
`referenceWalkSpeed` | `4` | Geschwindigkeit, bei der Walk mit 1x abgespielt wird.
`referenceRunSpeed` | `12` | Geschwindigkeit, bei der Run mit 1x abgespielt wird.
`visualMode` | `animal` | Pro Tierart: `animal` lädt einzelne Tiere, `cage` lädt Käfige mit inneren Tierplätzen.
`cageFilename` | leer | Pfad zur Käfig-i3d, relativ zum Mod.
`cageSlotNode` | leer | Optionale TransformGroup im Fahrzeug mit Käfigpositionen. Ohne diesen Wert nutzt das Script die normalen Tier-Slots.
`cageAnimalSlotsPath` | `animalSlots` | Node-Pfad in der geladenen Käfig-i3d, unter dem die inneren Tierplätze liegen.
`animalsPerCage` | `4` | Wie viele echte Tiere optisch in einen Käfig gesetzt werden.
`cageSlotStep` | `4` | Fallback-Abstand in normalen Tier-Slots, wenn kein eigenes `cageSlotNode` angegeben ist.
`cageAnimalMode` | `animated` | `animated` lädt Tiere in den Käfig. `none` zeigt nur den Käfig.

## Altersregeln

Altersregeln werden beim Beladen geprüft. Das funktioniert beim Händler, beim Stall und beim Umladen aus einem anderen Trailer.

### Nur ältere Tiere

    minimumLoadAge="7"

Blockiert 0 bis 6 Monate.

### Nur Jungtiere

    maximumLoadAge="6"

Blockiert alles über 6 Monate.

### Altersspanne

    minimumLoadAge="3"
    maximumLoadAge="12"

Erlaubt nur 3 bis 12 Monate.

Die Meldung kommt aus `unsupportedAgeWarningText`. Für internationale Mods sollte dort ein l10n-Key stehen, zum Beispiel `$l10n_warning_animalAgeNotSupportedByTrailer`.

## Shop-Anzeige

Das Script ersetzt die festen weißen Giants-Tiersymbole in der Kaufübersicht durch die bunten FillType-HUD-Icons. Dadurch können auch eigene Tierarten aus Maps angezeigt werden.

### Woher kommt der Name über dem Icon?

1. Zuerst aus `shopTitle`, wenn im `<animal>` Eintrag gesetzt.
2. Dann aus `animalType.groupTitle` der Animals-XML.
3. Danach als Fallback aus dem FillType-Titel.
4. Ganz zuletzt aus dem rohen Tier-Typnamen.

    <animal type="alpaca" node="alpacas" numSlots="1" shopTitle="$l10n_shopAnimal_alpacas"/>

Der FillType-Titel ist oft zu genau, zum Beispiel "Alpaka weiß". Darum nutzt das Script standardmäßig den AnimalType-Gruppennamen, also eher "Alpakas".

## HUD-Anzeige

Wenn `showOnHud="true"` gesetzt ist, zeigt das Script rechts im HUD einen Tier-Füllstand an. Das funktioniert ähnlich wie bei FillUnits: Icon, Text und Balken.

- Der Balken zeigt geladene Tiere im Verhältnis zur Gesamtkapazität.
- Das Icon kommt aus dem Tier-FillType.
- Die Einheit nutzt Giants `unit_pieces`.

## Tier-Sounds

Das Script liest die Soundgruppen aus der jeweiligen `animals.xml`. Es nutzt nicht einen Sound pro Slot, sondern eine gemeinsame zufällige Soundquelle pro Trailer. Dadurch überlagern sich die Geräusche nicht so stark.

Attribut | Erklärung
--- | ---
`useAnimalSounds` | Schaltet zufällige Tiergeräusche ein oder aus.
`animalSoundNode` | Optionaler Node als Soundposition.
`animalSoundVolumeScale` | Lautstärke-Multiplikator.
`animalSoundMinInterval` | Minimale Zeit zwischen Sounds in Millisekunden.
`animalSoundMaxInterval` | Maximale Zeit zwischen Sounds in Millisekunden.
`animalSoundMinimumInterval` | Harte Untergrenze nach Mengen-Skalierung.

## Eigene Tierarten

Eigene Tierarten sind nicht hart im Script eingetragen. Das Script fragt das Giants `AnimalSystem` ab. Dadurch funktionieren auch Map-eigene Tiere, wenn die Map ihre Tiere vollständig registriert.

### Voraussetzungen

- Die Tierart muss in der Map-Animals-XML registriert sein.
- Der `type` im `<livestockTrailer>` muss zu diesem AnimalType passen.
- Die Tier-`animals.xml` braucht `assets#filename`, `assets#filenamePosed`, `assets#animation` und `assets#skeletonIndex`.
- Für Animationen sollte `locomotion#filename` vorhanden sein.

### Clip-Fallbacks

Wenn Clipnamen abweichen, sucht das Script nach typischen Giants-Namen:

Idle `idle1Source`, `idleSource`, `idle01Source`, `idleBabySource`

Walk `walkFwdLSource`, `walkFwdSource`, `walkFwdLBabySource`, `trotFwdLSource`

Run `runFwdLSource`, `runFwdSource`, `runFwdLBabySource`, `trotFwdLSource`

## Fehlersuche

### Trailer taucht nicht im Shop auf

- Prüfen, ob die `<category>` in der Fahrzeug-XML zur Kategorie in der `modDesc.xml` passt.
- Prüfen, ob der Fahrzeugtyp in der `modDesc.xml` registriert ist.
- Log nach dem Fahrzeugnamen oder der XML-Datei durchsuchen.

### Tiere sind unsichtbar

- Prüfen, ob der Tier-`type` im AnimalSystem existiert.
- Prüfen, ob die Slot-Node im `<livestockTrailer>` existiert.
- Prüfen, ob in der Tier-`animals.xml` ein animiertes `assets#filename` vorhanden ist.

### Tiere stehen in T-Pose

- Prüfen, ob `assets#animation` und `assets#skeletonIndex` vorhanden sind.
- Bei Sondertieren Clipnamen über `<animatedLivestockTrailer><animal .../></animatedLivestockTrailer>` überschreiben.

### Shop-Icon fehlt oder ist schwarz

- Prüfen, ob der passende FillType ein `image#hud` Icon hat.
- Prüfen, ob eigene FillTypes vor dem Shop geladen werden.

### Alterswarnung erscheint nicht

- `minimumLoadAge` oder `maximumLoadAge` muss größer als 0 sein.
- `unsupportedAgeWarningText` sollte auf einen vorhandenen l10n-Key zeigen.