feat: externe 3D-Assets, AutoRigPro-Rig und Asset-Sync
- Asset-Manifest mit Hash, Platzierung und Rig-Metadaten - tools/sync_assets.sh prueft Quelle und Ziel und kopiert aus dem Workbench-Archiv nach assets/external (gitignored) - Skater mit AutoRigPro geriggt: 226 Control-, 30 Deform-Bones - glTF-Export inkl. gebackenem Testclip, Godot-Import verifiziert - Manifest-Test mit 48 Assertions (1123 gesamt) - Phase-1-Exporte schliessen assets/external aus - Doku, Roadmap und Findings aktualisiert
This commit is contained in:
parent
05dee8da2b
commit
8861cbae92
16 changed files with 949 additions and 8 deletions
160
docs/assets.md
Normal file
160
docs/assets.md
Normal file
|
|
@ -0,0 +1,160 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue