rinkplanner/docs/assets.md
torsten 8861cbae92 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
2026-10-31 12:30:49 +01:00

5.8 KiB
Raw Blame History

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

./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

{
  "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.