rinkplanner/docs/assets.md
torsten fd597fd350 chore: Build verschlanken und Windows 0.2.1 veröffentlichen
Alte Skater-Fassungen sind aus Manifest, assets/external und den
Export-Presets entfernt; im Workbench-Archiv bleiben sie erhalten.

- Manifest nur noch mit character.skater.figure_tripo_glide (v008)
- v006, v007, Tripo-30k und weights_rings aus assets/external gelöscht
- Export-Presets schließen die alten Figuren zusätzlich aus
- check_export.sh prüft, dass keine alte Fassung im Build landet
- rotoscope.sh und manuelle Skripte auf die aktive Asset-ID bzw. v008 gezogen
- Version 0.2.1 in project.godot und export_presets.cfg
- Installer 29 MB statt 32 MB, per FTP hochgeladen und per SHA-256 geprüft
- version.json 0.2.1 mit Windows-Eintrag veröffentlicht; macOS bleibt 0.2.0
2026-11-12 06:31:38 +01:00

316 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 3D-Assets (extern)
Stand: 2026-11-11
Die 3D-Assets liegen bewusst außerhalb des Git-Repos. Das Repo enthält nur
ein Manifest, ein Sync-Werkzeug und die Dokumentation. Die Binärdateien
bleiben im Workbench-Archiv.
## Verzeichnisse
```
/home/torsten/Dokumente/workbench_rinkplanner/
├── inbox/ # Eingang, unverändert lassen
├── library/ # kuratiert, vom Manifest referenziert
│ └── characters/
├── source/ # .blend, Rig, Rohdaten
│ └── characters/skater/
└── archive/ # alte Stände, Videos, Bilder
```
```
rinkplanner/
├── assets/
│ ├── asset_manifest.json # versioniert
│ └── external/ # gitignored, per Sync befüllt
└── tests/run_asset_manifest_tests.gd
tools/sync_assets.sh
```
`assets/external/` wird nie committet. Ein frischer Checkout braucht einmal
`./tools/sync_assets.sh --sync`, sonst fehlen die 3D-Dateien.
## Workflow
1. Neue Datei in `inbox/` ablegen.
2. Prüfen, bei Bedarf konvertieren und als versionierte Datei nach
`library/` legen (`..._v001.glb`, `..._v002.glb`).
3. Die bearbeitbare Quelle (`.blend`, Rig, Referenzvideo) nach `source/`.
4. Eintrag in `rinkplanner/assets/asset_manifest.json` ergänzen:
ID, Quelle, Ziel, FTP-Pfad, SHA-256, Größe, Platzierung, Rig, Animationen.
5. `./tools/sync_assets.sh --sync` kopiert und importiert.
6. Bei geänderter Datei `./tools/sync_assets.sh --publish` für den Spiegel.
7. Vor dem Commit `./tools/sync_assets.sh --check` laufen lassen.
### Befehle
```bash
./tools/sync_assets.sh --check # Standard: nur lokal prüfen
./tools/sync_assets.sh --sync # kopieren/laden + Godot-Import
./tools/sync_assets.sh --sync --force # abweichendes Ziel überschreiben
./tools/sync_assets.sh --publish # Workbench-Dateien auf den FTP-Spiegel laden
```
`--sync` arbeitet in dieser Reihenfolge:
1. Ziel in `assets/external/` ist vorhanden und hat den Manifest-Hash → OK.
2. Workbench-Quelle ist vorhanden → kopieren.
3. Sonst vom FTP-Spiegel laden.
Damit funktioniert ein frischer Checkout auf einem Rechner ohne
Workbench-Archiv, sofern die FTP-Zugangsdaten vorliegen.
### FTP-Spiegel
Der vorhandene FTP-Server der Kür-Synchronisation dient als
Verteilungskopie. Die Dateien liegen dort unterhalb des App-Verzeichnisses:
```
<FTP_DIRECTORY>/assets/<remote>
# z. B. rinkplanner/assets/characters/skater_figure_rigged_deform_v002.glb
```
`FTP_DIRECTORY` ist das Verzeichnis aus `docs/credentials.txt` (aktuell
`rinkplanner`). Der Unterordner `assets` wird beim ersten Upload automatisch
angelegt (`--ftp-create-dirs`).
Zugangsdaten kommen aus `docs/credentials.txt` (gitignored) oder aus
`RINKPLANNER_FTP_*`-Umgebungsvariablen. Das Format ist dasselbe wie für die
App:
```
FTP_URL=<host>
FTP_USER=<benutzer>
FTP_PASSWORD=<passwort>
FTP_DIRECTORY=rinkplanner
```
Optional:
| Schlüssel | Bedeutung |
| :--- | :--- |
| `FTP_ASSET_DIRECTORY` | überschreibt `<FTP_DIRECTORY>/assets` |
| `FTP_VERIFY=1` | TLS-Zertifikat prüfen (Standard: 0) |
Der Server verwendet explizites FTPS (`AUTH TLS`, Port 21). Sein Zertifikat
hat keinen passenden Hostnamen, deshalb ist die Prüfung standardmäßig aus.
Die Integrität hängt nicht am Zertifikat, sondern am SHA-256 aus dem
Manifest: Nach jedem Upload wird die Datei zurückgeladen und gehasht; nach
jedem Download wird vor dem Verschieben gehasht.
`--publish` ist bewusst ein eigener Befehl. Ein normaler `--sync` lädt nichts
hoch und überschreibt keine Serverdatei.
Auf einem neuen Rechner:
```bash
cp /pfad/zu/credentials.txt docs/credentials.txt
./tools/sync_assets.sh --sync
```
Weitere Umgebungsvariablen:
| Variable | Standard | Zweck |
| :--- | :--- | :--- |
| `RINKPLANNER_WORKBENCH` | `~/Dokumente/workbench_rinkplanner` | Archivpfad |
| `RINKPLANNER_CREDENTIALS` | `<repo>/docs/credentials.txt` | FTP-Konfiguration |
| `GODOT` | `/opt/godot/Godot_v4.7.2-stable_linux.x86_64` | Import-Binary |
Das Skript prüft beim Kopieren, Laden und Veröffentlichen die jeweilige
Datei gegen den Hash aus dem Manifest. `--check` prüft nur das lokale Ziel;
eine still veränderte Workbench-Datei wird nicht kopiert, sondern gemeldet.
## Manifest
```json
{
"id": "character.skater.figure_tripo_glide",
"version": 6,
"kind": "character",
"format": "glb",
"source": "library/characters/skater_figure_glide_v008.glb",
"target": "assets/external/characters/skater_figure_glide_v008.glb",
"remote": "characters/skater_figure_glide_v008.glb",
"sha256": "3b49dc76…",
"bytes": 8584300,
"source_scene": "source/characters/skater/skater_rig_v006.blend",
"placement": {
"up_axis": "Y",
"facing": "+Z",
"pivot": "feet",
"height_m": 1.898,
"ground_offset_m": 0.0
},
"rig": {
"type": "humanoid",
"control_bones": 222,
"deform_bones": 30,
"vertex_influences": 8,
"bind": "PSEUDO_VOXELS"
},
"animations": [
"Glide"
]
}
```
| Feld | Bedeutung |
| :--- | :--- |
| `id` | stabile Kennung; Code und Szenen referenzieren die ID, nicht den Dateinamen |
| `version` | Zähler der kuratierten Fassung |
| `source` | Pfad relativ zum Workbench-Archiv |
| `target` | Pfad relativ zum Godot-Projekt, immer unter `assets/external/` |
| `remote` | Pfad relativ zum FTP-Asset-Verzeichnis |
| `sha256` / `bytes` | Integritätsprüfung |
| `source_scene` | bearbeitbare Quelle (`.blend`) für Rig/Animation |
| `placement` | Up-Achse, Blickrichtung, Pivot und Höhe für die 3D-Szene |
| `rig` | Control-/Deform-Bones und Bind-Verfahren |
| `animations` | Liste der exportierten Clipnamen |
## Versionierung
- Dateinamen tragen `_vNNN`; vorhandene Versionen werden nicht überschrieben.
- Eine neue Fassung ist eine neue Datei plus neuer Manifest-Eintrag bzw.
aktualisierte `version` und `sha256`.
- Alte Versionen bleiben in `library/` und im Archiv nachvollziehbar.
- Nicht parsebare oder verworfene Experimente gehören nicht ins Manifest.
## Godot und Export
- `assets/external/` ist gitignored und wird nach dem Sync importiert.
- `asset_manifest.json` wird über `include_filter="*.json"` mit exportiert.
- Die Export-Presets nehmen nur die aktive Skater-GLB samt Textur mit
(`assets/external/characters/skater_figure_glide_v008*`). Alles andere ist
ausgeschlossen: Test- und Gewichts-Assets (`weights_rings*`), das unrigged
Tripo-Mesh (`skater_figure_tripo*`), die alten Figuren
(`skater_figure_glide_v006*`, `..._v007*`) sowie `assets/models/*`. Die
alten Fassungen liegen weiter im Workbench-Archiv, aber nicht mehr im
Manifest und nicht mehr in `assets/external/` – das hält den Build klein.
Fehlt die GLB auf einem frischen Checkout, baut `Skater3D` weiterhin den
Platzhalter; `tools/check_export.sh` weist darauf hin und prüft die Textur
im Build.
- Phase 1 bleibt unberührt: Der 2D-Code lädt keine 3D-Ressourcen.
## Aktueller Bestand
| ID | Datei | Größe | Rig | Clips |
| :--- | :--- | ---: | :--- | :--- |
| `character.skater.figure_tripo_glide` | `skater_figure_glide_v008.glb` | 3,08 MB | 222 Control / 30 Deform, 4 Einflüsse | `Glide` (2-s-Loop) |
Das Manifest enthält nur noch diesen einen Eintrag. Die früheren Fassungen
(`skater_figure_glide_v006.glb`, `skater_figure_tripo_v001_30k.glb`) und die
Zwischenstufe v007 bleiben im Workbench-Archiv unter
`library/characters/`, werden aber nicht mehr synchronisiert und nicht mehr
exportiert.
Die 3D-Vorschau lädt `character.skater.figure_tripo_glide` über die
Manifest-ID. Fehlt sie, erscheint ein Platzhalter aus Kapsel und Kopf, damit
ein frischer Checkout und die Tests laufen.
### Tripo-Skater mit Glide (v008, aktiv)
`character.skater.figure_tripo_glide` ist seit 2026-11-12 die Figur, die
`Skater3D` lädt. Version 2 (v008) entstand im Ultra-Modus und trägt ein
petrolfarbenes Kürkleid mit Pailletten statt des Trainingskleids:
- 59.488 Dreiecke, Textur v3.5, Höhe 1,7 m, Blickrichtung `+Z`, Pivot Füße.
- Referenzbild per Tripo-Image-Edit aus `flux2pro_reference_front.png`
erzeugt (Task `316752d8-16e7-49c8-beb1-d2223afc9f79`, 20 Credits).
- Mesh: `geometry_quality=detailed`, 60k-Face-Budget, Task
`834f0e29-65db-49d2-a02b-7a6239a4d07a`, 50 Credits.
- Rig lokal in Blender mit AutoRigPro: 222 Control-Bones, 30 Deform-Bones,
Bind `PSEUDO_VOXELS`, 4 Einflüsse pro Vertex.
- `Glide` per reinem Rotations-Retargeting von `skater_figure_glide_v006`
übernommen (2-s-Loop, 48 Frames bei 24 fps).
- Klingenabstand in der Vorschau: ±0,154 m (Konstante
`BLADE_LATERAL_OFFSET_M` in `skater_3d.gd`).
- Bekannte Schwächen: Lider ohne Augengeometrie, Finger als verschmolzene
Blobs. Im Ultra-Modus sind Ohren und Gesichtsform deutlich besser, die
Finger bleiben aber ungetrennt.
Der komplette Weg vom Mesh zum geriggten Export ist als ein Befehl
reproduzierbar:
```bash
blender --python tools/blender/build_skater.py -- \
model.glb skater_figure_glide_v008.glb \
--source-rig rinkplanner/assets/external/characters/skater_figure_glide_v008.glb
```
Ablauf, Stolpersteine und Messwerte:
`docs/findings-2026-11-12-tripo-skater-rig.md`.
### Frühere Skater-Fassungen (nur im Archiv)
Die erste Tripo-Fassung ohne Rig (`skater_figure_tripo_v001_30k.glb`) und die
Zwischenstufe mit Trainingskleid (`skater_figure_glide_v007.glb`) sind seit
dem 2026-11-12 nicht mehr im Manifest. Sie liegen weiter im Workbench-Archiv
unter `library/characters/` und lassen sich bei Bedarf als neuer
Manifest-Eintrag zurückholen; im Build und in `assets/external/` sind sie
nicht mehr enthalten.
Details und verworfene Kandidaten:
`docs/findings-2026-11-11-ai-skater-model-comparison.md`.
Testdateien (nicht im Manifest): `skater_figure_anim_test_v001.glb` mit dem
2-Sekunden-Clip `TestWave`.
## Rotoscoping-Clips
Die Blender-Werkbank für neue Animationsclips ist separat dokumentiert:
`docs/rotoscoping.md`. Kurzfassung:
```bash
./tools/rotoscope.sh setup
./tools/rotoscope.sh open
./tools/rotoscope.sh export --out /tmp/clips.glb
./tools/rotoscope.sh promote --version 4 [--publish]
```
`promote` exportiert nach `library/characters/`, aktualisiert Version,
Quelle, Ziel, FTP-Pfad, Hash und die Liste der Clips im Manifest und
synchronisiert nach `assets/external/`. Die 3D-Vorschau lädt die GLB über
die Manifest-ID `character.skater.figure_tripo_glide` und spielt derzeit `Glide`.
## Rig-Pipeline (AutoRigPro)
1. GLB in Blender importieren, Füße auf Z=0, Transform anwenden.
2. ARP Smart Rig: Marker für Neck, Chin, Shoulder, Hand, Root, Foot setzen.
3. `PSEUDO_VOXELS` als Bind-Engine; das Mesh hat 37 Inseln und offene Kanten,
Heat-Map-Weighting ist dafür ungeeignet.
4. **`Match to Rig` ist Pflicht:** Erst danach sitzen Knie, Füße und Arme
exakt auf dem Mesh. Der erste Auto-Rig-Lauf hatte die Füße bei x = 0,24
statt 0,10.
5. Animationen auf dem Control-Rig erstellen (IK/FK, Fußrollen, Root Motion).
Der erste Clip ist `Glide`: Arme unten, 2-s-Loop, im `.blend`
`skater_rig_v006.blend`.
6. **Armgewichte gelenkgenau und ringweise** setzen (Ellbogen bei
x ≈ 0,37, Handgelenk bei x ≈ 0,65, siehe
`docs/findings-2026-10-31-arm-gewichte.md`). Die PSEUDO-VOXELS-Gewichte
bleichten sonst in `spine_03`/`head`; die offenen Ärmelflächen
kollabierten.
7. Export mit `export_def_bones=True` und **`export_all_influences=True`**;
der Exporter backt Constraints automatisch. Im GLB landen nur die 30
Deform-Bones, aber **8 Bone-Influences pro Vertex**. Mit dem Standard-
Export (4 Einflüsse) kollabieren die Ärmel in Godot.
8. Ergebnis in Godot prüfen (`tests/manual/inspect_rig.gd`,
`tests/manual/capture_rig.gd`); die 3D-Vorschau mit
`tests/manual/capture_3d.gd`.
Details und Messwerte: `docs/findings-2026-10-31-arp-rig.md`.
## Backup und Lizenz
- Das Workbench-Archiv liegt außerhalb des Repos und wird **nicht** vom
Git-Remote gesichert. `library/` und `source/` separat sichern
(restic/rsync).
- Die Skaterin ist ein eigenes GenAI-Asset; das Rig wurde mit AutoRigPro
erstellt. Vor einer Veröffentlichung die Lizenz der Basistexturen prüfen.
## Tests
`tests/run_asset_manifest_tests.gd` prüft Schema, Pfade, FTP-Pfade, Hashes,
Animationen und – falls synchronisiert – Größe, SHA-256 sowie die
8-Bone-Gewichte der Zieldatei. Fehlt das Asset (z. B. in CI), wird der
Dateicheck übersprungen, der Schema-Test bleibt aktiv. Aktuell: 57
Assertions.