saumwacht-godot/assets-source/phase4/README.md

# Saumwacht · Phase 4 · Blender-Modelle

Die Lieferung enthält **59 GLB-Modelle und 59 bearbeitbare `.blend`-Dateien**: 40 Fraktionseinheiten, zehn Wellengegner, fünf Söldner, den Funkenleser, ein Lane-Segment und zwei Teamkerne. Glutpakt und Wellengegner verwenden seit Demo 0.7.0 die neue hochdetaillierte Quelle `blender/reference_high_detail.py`; das Dreiecksbudget dieser Modelle liegt bei 100.000. Neutrale Modelle und Umgebung erhielten zusätzliche Kantengeometrie. Die Farbwerte der neuen Glutpakt- und Gegnerpalette stehen in `hd_materials`; die unten beschriebenen `PALETTE_OVERRIDES` gelten für die ursprünglichen Paletten.

Wellengegner werden mit `generate_all.py -- --faction rift` erzeugt; die neun Einzeldateien decken weiterhin die ursprünglichen Rollen ab. Details und aktuelle Prüfungen: [Grafikbericht](../../../docs/phase-07-hochdetaillierte-modelle.md).

Alle Formen entstehen aus den beigefügten parametrischen Blender-Skripten. Materialien und benannte Einzelteile werden mit exportiert.

**Revision vom 15. September 2026:** Alle 46 Figuren wurden anhand der Icons aus Phase 3 neu aufgebaut. Die [Vergleichsgalerie](../../docs/screenshots/phase4/reference-gallery.html) zeigt die unveränderten Originalbilder direkt neben aktuellen Godot-Renderings. Körperbau, Konturen und Hauptmotive wurden korrigiert; kleine Verzierungen, Oberflächen und Rundungen bleiben vereinfacht. Basis und Upgrade unterscheiden sich durch zusätzliche oder veränderte Geometrie, etwa Klauen, Zinnen, Klingen, Kessel, Schilde oder Holzringe. Die Spielintegration folgt in Phase 5.

Phase 6 ergänzt beim Glutpakt Basalt-/Goldfacetten und ein verfeinertes Schildrelief; GLBs, native Szenen und eigenständige Skripte sind aktualisiert. Die Gelenkanimationen entstehen im Godot-Spiel aus den benannten Teilen.

## Dateien finden

| Inhalt | Ort, relativ zum Godot-Projekt |
| --- | --- |
| 59 fertige GLB-Dateien | `assets/models/` |
| 59 bearbeitbare Blender-Dateien | `assets-source/phase4/blend/` |
| Neun eigenständige Skripte | `assets-source/phase4/standalone/` |
| Modulare Generatorquellen und Batch-Export | `assets-source/phase4/blender/` |
| Modellmetadaten und Maße | `assets/phase4_manifest.json` |
| Einzeldatensätze der Exporte | `assets-source/phase4/records/` |
| Eigenständige Godot-Vorschau | `tools/model_gallery.tscn` |

Der [Modellkatalog](catalog.md) führt alle 59 Modelle mit Rollen, Upgrade-Status, Dreieckszahlen und Maßen auf. Jeder Eintrag verlinkt die GLB-Datei.

## Ein Modell in Blender erzeugen

1. Blender öffnen und zum Arbeitsbereich **Scripting** wechseln.
2. Im Texteditor **Text → Open** wählen und eines der Skripte aus `standalone/` öffnen, beispielsweise `create_melee.py`.
3. Im Parameterblock oben `ASSET_ID` auf die gewünschte Variante setzen, beispielsweise `"w02"`.
4. **Run Script** beziehungsweise **Alt+P** ausführen.
5. Blender zeigt die neue Szene `Saumwacht_<ID>`. Die GLB-Datei und die bearbeitbare `.blend`-Datei werden automatisch geschrieben.

Jedes Skript ist eigenständig: Es benötigt Blender mit `bpy`, aber keine benachbarten Python-Module oder JSON-Dateien. Im Projekt liegen die Standardausgaben unter `assets/models/` und `assets-source/phase4/blend/`. Wird ein Skript separat in einen anderen Ordner kopiert, verwendet es daneben `saumwacht-export/` und `saumwacht-source/blend/`.

**Vorhandene eigene Szenen bleiben erhalten.** Der Generator erstellt eine neue Szene und exportiert deren Modell. Mit `KEEP_SCENE = True` bleibt diese neue Szene aktiv. Mit `False` wird nach dem Export zur vorherigen Szene zurückgekehrt und nur die temporär erzeugte Szene entfernt. Die `.blend`-Ausgabe enthält die erzeugte Szene mit ihren Abhängigkeiten.

Ein erneuter Lauf derselben ID schreibt deren GLB- und `.blend`-Ausgaben neu. Für eigene Varianten können getrennte Ausgabeordner gesetzt werden.

## Skripte und verfügbare IDs

Die folgenden IDs stammen aus den tatsächlich enthaltenen `ASSET_SPECS` der neun Skripte.

| Skript | Klasse | Verfügbare IDs |
| --- | --- | --- |
| [create_melee.py](standalone/create_melee.py) | Nahkampf | `g01`, `g02`, `m03`, `m04`, `n03`, `n04`, `w01`, `w02` |
| [create_tank.py](standalone/create_tank.py) | Tank | `g03`, `g04`, `m01`, `m02`, `n01`, `n02`, `w03`, `w04` |
| [create_ranged.py](standalone/create_ranged.py) | Fernkampf | `g05`, `g06`, `m05`, `m06`, `n05`, `n06`, `w05`, `w06` |
| [create_artillery.py](standalone/create_artillery.py) | Artillerie | `g07`, `g08`, `m07`, `m08`, `n07`, `n08`, `w07`, `w08` |
| [create_support.py](standalone/create_support.py) | Unterstützung | `g09`, `g10`, `m09`, `m10`, `n09`, `n10`, `w09`, `w10` |
| [create_mercenary.py](standalone/create_mercenary.py) | Söldner | `s01`, `s02`, `s03`, `s04`, `s05` |
| [create_worker.py](standalone/create_worker.py) | Arbeiter | `worker` |
| [create_lane.py](standalone/create_lane.py) | Lane-Segment | `map_lane_segment` |
| [create_core.py](standalone/create_core.py) | Saumkern | `core_team0`, `core_team1` |

Bei den vier Fraktionen bilden die aufeinanderfolgenden ungeraden und geraden IDs jeweils Basis und Upgrade. Für Söldner, Arbeiter, Lane und Kerne gibt es keine Upgrade-Paare. `core_team0` und `core_team1` sind Teamvarianten.

## Parameter anpassen

| Parameter | Wirkung |
| --- | --- |
| `ASSET_ID` | Wählt eine der oben aufgeführten Varianten des geöffneten Skripts. |
| `HEIGHT` | `None` verwendet das Katalogmaß; eine positive Zahl gibt eine Zielhöhe in Metern vor. Der maximale Zell-Footprint kann die tatsächliche Höhe begrenzen. Das Lane-Segment behält seine festen Modulmaße. |
| `PALETTE_OVERRIDES` | Ersetzt einzelne Materialfarben mit RGB-Hexwerten, etwa `{"accent": "D9A441"}`. Schlüssel: `primary`, `secondary`, `accent`, `light`; beim Wurzelbund zusätzlich `water`, `wood`, `bark_dark`, bei Neutral/Arbeiter `shadow` und bei Neutral `rift`. Nicht angegebene Farben bleiben beim Fraktionsstandard. |
| `EXPORT_DIR` | `None` verwendet den Standardordner für GLB-Dateien; alternativ einen eigenen absoluten Ordnerpfad angeben. |
| `BLEND_DIR` | `None` verwendet den Standardordner für `.blend`-Dateien; alternativ einen eigenen absoluten Ordnerpfad angeben. |
| `KEEP_SCENE` | `True` lässt das Ergebnis in Blender sichtbar; `False` kehrt nach dem Export zur vorherigen Szene zurück. |

Beispiel für eine veränderte Nahkampfeinheit:

```python
ASSET_ID = "g02"
HEIGHT = 1.60
PALETTE_OVERRIDES = {"accent": "D9A441", "secondary": "F27B43"}
EXPORT_DIR = "/tmp/saumwacht-varianten/models"
BLEND_DIR = "/tmp/saumwacht-varianten/blend"
KEEP_SCENE = True
```

Für Formänderungen stehen darunter kleine Funktionen für Körper, Beine, Kopf, Waffen und Zubehör bereit. Die eigenständigen Skripte sind aus den modularen Quellen generierte, vollständig eingebettete Fassungen. Die Figurenformen stehen in `blender/reference_glutpakt.py`, `reference_nietenkonvent.py`, `reference_nebelchor.py`, `reference_wurzelbund.py` und `reference_neutral.py`; gemeinsame Formwerkzeuge in `reference_geometry.py`. Projektweite Änderungen werden in `blender/` gepflegt; `tools/build_standalone_model_scripts.py` aktualisiert anschließend die Fassungen in `standalone/`.

## Export über die Kommandozeile

Die folgenden Befehle im Ordner `saumwacht-godot/` ausführen. `ALSOFT_DRIVERS=null` deaktiviert für den unbeaufsichtigten Blender-Lauf die Audioausgabe. `--factory-startup` gilt für den dafür gestarteten Hintergrundprozess.

Alle 59 Modelle samt Manifest neu erzeugen:

```bash
ALSOFT_DRIVERS=null blender --background --factory-startup \
  --python assets-source/phase4/blender/generate_all.py -- --all
```

Zwei bestimmte IDs aus den modularen Quellen exportieren:

```bash
ALSOFT_DRIVERS=null blender --background --factory-startup \
  --python assets-source/phase4/blender/generate_all.py -- --id g01 --id g02
```

Alle Tanks in getrennte Ausgabeordner exportieren:

```bash
ALSOFT_DRIVERS=null blender --background --factory-startup \
  --python assets-source/phase4/blender/generate_all.py -- --role tank \
  --export-dir /tmp/saumwacht-tanks/models \
  --blend-dir /tmp/saumwacht-tanks/blend
```

Ein einzelnes eigenständiges Skript mit Variantenwahl und Zielhöhe starten:

```bash
ALSOFT_DRIVERS=null blender --background --factory-startup \
  --python assets-source/phase4/standalone/create_melee.py -- \
  --id w02 --height 1.6 --no-keep-scene \
  --export-dir /tmp/saumwacht-varianten/models \
  --blend-dir /tmp/saumwacht-varianten/blend
```

Die Skripte unterstützen außerdem die im Parameterblock gesetzten Standardwerte. Farbänderungen werden dort über `PALETTE_OVERRIDES` vorgenommen. Der vollständige Batch-Lauf schreibt das gemeinsame Manifest neu; ein einzelner Variantenexport aktualisiert nur seinen eigenen Datensatz. Nach Teil-Exporten in die offiziellen Ausgabeordner lässt sich das Manifest aus den aktuellen Datensätzen aktualisieren, ohne die angepassten Modelle neu zu erzeugen:

```bash
ALSOFT_DRIVERS=null blender --background --factory-startup --python-exit-code 1 \
  --python-expr "import sys; sys.path.insert(0, 'assets-source/phase4/blender'); from pipeline import write_manifest; write_manifest()"
```

Ein neuer vollständiger Batch-Lauf verwendet wieder die modularen Quellen und deren Katalogwerte. Anpassungen ausschließlich in einem Einzelskript oder einer `.blend`-Datei werden dadurch überschrieben. Der Markdown-Katalog ist eine Momentaufnahme der Lieferung; aktuelle Maße stehen nach einem neuen Export im Manifest.

## Modelle in Godot ansehen

Godot importiert die GLB-Dateien beim Öffnen des Projekts. Danach `tools/model_gallery.tscn` öffnen und mit **F6** starten. Alternativ aus dem Godot-Projektordner:

```bash
godot --path . res://tools/model_gallery.tscn
```

Die Galerie bietet Fraktions- und Modellauswahl, Maße und Dreieckszahlen sowie die zugehörige Iconreferenz. Ziehen dreht das Modell, das Mausrad ändert den Zoom; die automatische Drehung lässt sich zuschalten. Alle Modelle werden proportional auf eine gemeinsame Vorschaubühne eingepasst.

Die Kontaktbögen mit echter Godot-Beleuchtung entstehen nach abgeschlossenem Import über:

```bash
godot --path . res://tools/model_gallery.tscn -- --capture
```

Direkte Bildvergleiche entstehen mit `-- --compare --faction=nebelchor` (auch `glutpakt`, `nietenkonvent`, `wurzelbund`, `neutral`). Nach dem Rendern aller fünf Gruppen aktualisiert `python3 tools/build_phase4_reference_gallery.py` die lokale HTML-Galerie und den Katalog. Die Vergleichsszene liest die nativen PNGs direkt und ist für die lokale Entwicklungsumgebung vorgesehen.

Die Aufnahmen werden unter `docs/screenshots/phase4/` gespeichert. Dafür ist ein grafischer Godot-Lauf erforderlich.

## Maße und Weiterverwendung

Eine Einheit entspricht einem Meter. Blender verwendet **+Z oben und −Y vorne**; die GLB-Dateien verwenden in Godot **+Y oben und +Z vorne**. Einheiten stehen mit ihrem Ursprung auf dem Boden. Beim Lane-Segment liegt die begehbare Oberkante bei Y = 0.

Die Modelle bestehen aus benannten Einzelteilen und matten Materialien. Sie enthalten keine externen Texturen, Kameras, Lichtquellen oder Animationsclips. Die Vorschau fügt ihre eigene Bühne, Kamera und Beleuchtung hinzu. Die vollständigen Exportmaße stehen im Manifest als `bounds_godot`; B/H/T im Katalog sind die daraus berechneten Ausdehnungen entlang X/Y/Z.

**Geprüft mit Blender 5.2.1 LTS und Godot 4.7.2:** 59/59 GLB-Dateien, 59/59 Godot-Imports und alle neun in einen unabhängigen Ordner kopierten Einzelskripte. Weitere Ergebnisse und die sieben gerenderten Modellübersichten stehen im [Liefer- und Prüfbericht](../../../docs/phase-04-3d-pipeline.md).

Die vorige Modellfassung liegt reproduzierbar in `revisions/before-icon-match.tar.gz`. Die Originalicons wurden für die Korrektur nicht geändert.

### Phase 9 · Lebende Formen und Basis

`blender/reference_living_detail.py` erstellt alle zehn Wurzelbund-Figuren sowie Arbeiter und beide Kristalle neu. Blätter sind geschlossene Körper mit modellierten Adern; Wurzeln, Borke, Jahresringe, Kelche, Mineralspitzen und Arbeitsgeräte besitzen eigene benannte Teile. `LegL`, `LegR` und zusätzliche Wurzelgruppen sind Animationsgelenke; `Core_Crystal*` bildet die schwebende Mineralgruppe. Die Palette verwendet eigene Materialnamen `SW_HD_W_*`, damit Glutpakt-Materialien nicht überschrieben werden.

```bash
ALSOFT_DRIVERS=null blender --background --factory-startup --python-exit-code 1 --python blender/generate_all.py -- --faction wurzelbund
ALSOFT_DRIVERS=null blender --background --factory-startup --python-exit-code 1 --python blender/generate_all.py -- --id worker --id core_team0 --id core_team1
```

Nach einzelnen Exporten den gemeinsamen Manifest-Schritt ausführen und die eigenständigen Skripte über `../../tools/build_standalone_model_scripts.py` neu bündeln (Pfad vom Projektwurzelverzeichnis: `tools/build_standalone_model_scripts.py`). Die tatsächlichen Dreieckszahlen stehen in `assets/phase4_manifest.json`. Höchstens 100.000 Dreiecke pro neuem Modell; die Topologieprüfung wird unverändert angewendet.