# 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: ``` /assets/ # 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= FTP_USER= FTP_PASSWORD= FTP_DIRECTORY=rinkplanner ``` Optional: | Schlüssel | Bedeutung | | :--- | :--- | | `FTP_ASSET_DIRECTORY` | überschreibt `/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` | `/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", "version": 6, "kind": "character", "format": "glb", "source": "library/characters/skater_figure_glide_v006.glb", "target": "assets/external/characters/skater_figure_glide_v006.glb", "remote": "characters/skater_figure_glide_v006.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 schließen Test- und Gewichts-Assets (`weights_rings*`) und das ungenutzte, unrigged Tripo-Mesh (`skater_figure_tripo*`) sowie `assets/models/*` aus, nehmen aber beide Skater-GLB samt Quelltexturen mit (`assets/external/characters/skater_figure_glide_v006*` und `skater_figure_glide_v007*`). Fehlt die GLB auf einem frischen Checkout, baut `Skater3D` weiterhin den Platzhalter; `tools/check_export.sh` weist darauf hin und prüft die Texturen 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_v007.glb` | 2,71 MB | 222 Control / 30 Deform, 4 Einflüsse | `Glide` (2-s-Loop) | | `character.skater.figure` | `skater_figure_glide_v006.glb` | 8,59 MB | 222 Control / 30 Deform, 8 Einflüsse | `Glide` (2-s-Loop) | | `character.skater.figure_tripo` | `skater_figure_tripo_v001_30k.glb` | 7,19 MB | keins (unrigged) | – | 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 (v007, aktiv) `character.skater.figure_tripo_glide` ist die erste geriggte Fassung des Tripo-Meshes und seit 2026-11-12 die Figur, die `Skater3D` lädt: - 59.350 Dreiecke, Textur v3.5, Höhe 1,7 m, Blickrichtung `+Z`, Pivot Füße. - Tripo-Task `d8ee7a30-c1dc-4873-8770-4747d98a62ff` (Image→3D aus `flux2pro_reference_front.png`, Modell v3.1, 60k-Face-Budget, 30 Credits, über die Tripo-Pay-as-you-go-API statt fal). - 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, spitz zulaufende Ohren, Finger als verschmolzene Blobs. Bei der Vorschau-Distanz unsichtbar, bei Nahaufnahmen sichtbar. Ablauf, Stolpersteine und Messwerte: `docs/findings-2026-11-12-tripo-skater-rig.md`. ### Tripo-Mesh ohne Rig `character.skater.figure_tripo` bleibt als unrigged Zwischenstand im Manifest (Gewinner des Modellvergleichs vom 2026-11-11, Request `01a1c9c3-ce93-7cb1-8eb1-ca12dfa66c88`), ist aber **nicht** an `Skater3D` angebunden und **nicht** in den Export-Presets enthalten: - 30k-Decimation (`skater_figure_tripo_v001_30k.glb`, 29.999 Dreiecke) ist die Projektfassung; die 116k-Quelle liegt nur in der Workbench (`library/characters/skater_figure_tripo_v001.glb`). - Unrigged (`rig.type: "none"`), Blickrichtung `+X`, Höhe 1,7 m. Der Manifest-Test akzeptiert `type: "none"` mit null Bones/Einflüssen. - **Lizenz:** Erzeugt über fal (`tripo3d/h3.1/image-to-3d`); fal Support hat am 2026-11-12 bestätigt, dass der Vertrag mit fal besteht und Tripos Free-/Paid-User-AGB nicht greifen. Seit der Umstellung auf die Tripo-Pay-as-you-go-API (siehe v007) gilt: kommerzielle Nutzung ist über den bezahlten API-Zugang abgedeckt; fal erhebt keine Rechte an Outputs, garantiert aber keine Originalität oder Nichtrechtsverletzung. Details in `docs/findings-2026-11-11-ai-skater-model-comparison.md`. Aus den Export-Presets bleibt das unrigged Asset ausgeschlossen, weil es nicht an `Skater3D` angebunden ist. 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` 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.