rinkplanner/docs/assets.md
torsten 7bbd8c9c1d fix: Release-Härtung, JSON-Dateiformat und Quality-Meilenstein
- Export: Runtime-Bridge-Autoload und Skater-GLB samt Texturen einschließen, Editor-Addons ausschließen
- tools/check_export.sh als headless Smoke-Test; ./tools/test.sh --export
- RoutineFile: JSON-Format, atomare Saves, Whitelist für Legacy-.tres
- Überschreibschutz für Speichern unter/Export, Session- und Autosave-Restore
- Globaler Delete-Shortcut blockiert bei offenen Dialogen
- Sync akzeptiert .json und Legacy-.tres, Konfliktnamen behalten die Endung
- Tests für Dateiformat, Überschreiben, Session und Legacy-Schutz
- Quality-Meilenstein mit 'Als Nächstes' und 'Danach' in der Roadmap
2026-11-03 23:48:01 +01:00

261 lines
9.6 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-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/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",
"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*`) sowie `assets/models/*` aus, nehmen aber die
Skater-GLB samt ihren Quelltexturen
(`assets/external/characters/skater_figure_glide_v006*`) mit. 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` | `skater_figure_glide_v006.glb` | 8,59 MB | 222 Control / 30 Deform, 8 Einflüsse | `Glide` (2-s-Loop) |
Die 3D-Vorschau lädt die Datei über die Manifest-ID
`character.skater.figure`. Fehlt sie, erscheint ein Platzhalter aus
Kapsel und Kopf, damit ein frischer Checkout und die Tests laufen.
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.