# 3D-Assets (extern) Stand: 2026-10-31 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/Documents/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, SHA-256, Größe, Platzierung, Rig, Animationen. 5. `./tools/sync_assets.sh --sync` kopiert und importiert. 6. Vor dem Commit `./tools/sync_assets.sh --check` laufen lassen. ### Befehle ```bash ./tools/sync_assets.sh --check # Standard: nur prüfen ./tools/sync_assets.sh --sync # fehlende Dateien kopieren + Godot-Import ./tools/sync_assets.sh --sync --force # abweichendes Ziel überschreiben ``` Umgebungsvariablen: | Variable | Standard | Zweck | | :--- | :--- | :--- | | `RINKPLANNER_WORKBENCH` | `~/Documents/workbench_rinkplanner` | Archivpfad | | `GODOT` | `/opt/godot/Godot_v4.7.2-stable_linux.x86_64` | Import-Binary | Das Skript prüft **Quelle und Ziel** gegen den Hash aus dem Manifest. Eine still veränderte Workbench-Datei wird nicht kopiert, sondern gemeldet. ## Manifest ```json { "id": "character.skater.figure", "version": 2, "kind": "character", "format": "glb", "source": "library/characters/skater_figure_rigged_deform_v002.glb", "target": "assets/external/characters/skater_figure_rigged_deform_v002.glb", "sha256": "1c1f0646…", "bytes": 8345424, "source_scene": "source/characters/skater/skater_rig_v002.blend", "placement": { "up_axis": "Y", "facing": "+Z", "pivot": "feet", "height_m": 1.898, "ground_offset_m": 0.0 }, "rig": { "type": "humanoid", "control_bones": 226, "deform_bones": 30, "bind": "PSEUDO_VOXELS" }, "animations": [] } ``` | 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/` | | `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 aktuellen Phase-1-Export-Presets schließen `assets/external/*` aus. Für einen 3D-Build muss bewusst ein eigenes Preset die Dateien einschließen. Desktop kann die GLB einbetten; für Android sind 1K-Texturen oder ein separater Asset-Pack vorgesehen. - Phase 1 bleibt unberührt: Der 2D-Code lädt keine 3D-Ressourcen. ## Aktueller Bestand | ID | Datei | Größe | Rig | Clips | | :--- | :--- | ---: | :--- | :--- | | `character.skater.figure` | `skater_figure_rigged_deform_v002.glb` | 8,35 MB | 226 Control / 30 Deform | keine (Produktion) | Testdateien (nicht im Manifest): `skater_figure_anim_test_v001.glb` mit dem 2-Sekunden-Clip `TestWave`. ## 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). 6. Export mit `export_def_bones=True`; der Exporter backt Constraints automatisch. Im GLB landen nur die 30 Deform-Bones. 7. Ergebnis in Godot prüfen (`tests/manual/inspect_rig.gd`, `tests/manual/capture_rig.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, Hashes und – falls synchronisiert – Größe und SHA-256 der Zieldatei. Fehlt das Asset (z. B. in CI), wird der Dateicheck übersprungen, der Schema-Test bleibt aktiv.