- --publish laedt Workbench-Dateien per FTPS hoch und verifiziert sie durch Rueckdownload und SHA-256 - --sync laedt fehlende Assets vom Server, wenn die Workbench fehlt - Manifest um remote-Pfad ergaenzt, Manifest-Test auf 53 Assertions - Doku, Architektur (D13) und Roadmap aktualisiert
107 lines
3.4 KiB
Markdown
107 lines
3.4 KiB
Markdown
# Findings 2026-10-31 – FTP-Spiegel für externe Assets
|
||
|
||
## Problem
|
||
|
||
Ein frischer Checkout auf einem anderen Rechner hat kein
|
||
Workbench-Archiv und damit keine 3D-Modelle. `assets/external/` ist
|
||
gitignored, der Rig und die GLB fehlen.
|
||
|
||
## Lösung
|
||
|
||
Der vorhandene FTP-Server der Kür-Synchronisation dient zusätzlich als
|
||
Verteilungskopie für die 3D-Assets. Das Repo bleibt die Quelle der Wahrheit
|
||
für IDs und Hashes; der Workbench bleibt die Quelle für die Bearbeitung.
|
||
|
||
```
|
||
FTP-Server
|
||
└── rinkplanner/ # FTP_DIRECTORY aus credentials.txt
|
||
├── ... # Kür-Dateien
|
||
└── assets/
|
||
└── characters/
|
||
└── skater_figure_rigged_deform_v002.glb
|
||
```
|
||
|
||
`FTP_ASSET_DIRECTORY` ist standardmäßig `<FTP_DIRECTORY>/assets` und kann
|
||
überschrieben werden. Beim ersten Upload legt curl die Ordner an.
|
||
|
||
## Ablauf
|
||
|
||
### Veröffentlichen
|
||
|
||
```bash
|
||
./tools/sync_assets.sh --publish
|
||
```
|
||
|
||
1. Quelle gegen den Manifest-Hash prüfen.
|
||
2. Datei per explizitem FTPS hochladen (`AUTH TLS`, Port 21).
|
||
3. Datei zurückladen, Größe und SHA-256 prüfen.
|
||
4. Erst dann „OK".
|
||
|
||
`--publish` ist ein eigener Befehl; ein normaler `--sync` lädt nichts hoch.
|
||
|
||
### Auf einem Rechner ohne Workbench
|
||
|
||
```bash
|
||
cp /pfad/zu/credentials.txt docs/credentials.txt
|
||
./tools/sync_assets.sh --sync
|
||
```
|
||
|
||
`--sync` prüft in dieser Reihenfolge:
|
||
|
||
1. Ziel in `assets/external/` vorhanden und Hash korrekt → OK.
|
||
2. Workbench-Quelle vorhanden → kopieren.
|
||
3. Sonst FTP-Download nach temporärer Datei, Hash prüfen, verschieben,
|
||
Godot-Import anstoßen.
|
||
|
||
## Zugangsdaten
|
||
|
||
`docs/credentials.txt` (gitignored) mit den bestehenden Schlüsseln:
|
||
|
||
```
|
||
FTP_URL=<host>
|
||
FTP_USER=<benutzer>
|
||
FTP_PASSWORD=<passwort>
|
||
FTP_DIRECTORY=rinkplanner
|
||
```
|
||
|
||
Optional `FTP_ASSET_DIRECTORY` und `FTP_VERIFY=1`. Alternativ
|
||
`RINKPLANNER_FTP_*`-Umgebungsvariablen.
|
||
|
||
## Sicherheit und Integrität
|
||
|
||
- Der Server nutzt explizites FTPS. Sein Zertifikat hat keinen passenden
|
||
Hostnamen; die Prüfung ist deshalb standardmäßig aus (`FTP_VERIFY=0`).
|
||
- Der Vertrauensanker ist nicht das Zertifikat, sondern der SHA-256 aus
|
||
`asset_manifest.json`. Jeder Upload wird zurückgelesen und gehasht, jeder
|
||
Download vor dem Verschieben geprüft.
|
||
- Zugangsdaten liegen ausschließlich in der gitignorierten Datei bzw. in
|
||
Umgebungsvariablen. Das Manifest enthält keine Secrets.
|
||
- Der FTP-Spiegel ist eine Verteilungskopie. Ohne Workbench kann man Assets
|
||
laden, aber keine neuen Versionen erzeugen.
|
||
|
||
## Test
|
||
|
||
1. `--publish` lud `skater_figure_rigged_deform_v002.glb` (8.345.424 Bytes)
|
||
nach `rinkplanner/assets/characters/` und verifizierte den Rückdownload.
|
||
2. Ziel aus `assets/external/` entfernt, `RINKPLANNER_WORKBENCH` auf ein
|
||
nicht existierendes Verzeichnis gesetzt.
|
||
3. `--sync` lud die Datei per FTP, Hash
|
||
`1c1f06461b58b02d9b8332a756fdc88f533ff2d25f65a59d21ca0209b65128cb`,
|
||
Godot-Import erfolgreich.
|
||
4. `--check` danach grün.
|
||
|
||
## Tests und Doku
|
||
|
||
- `tests/run_asset_manifest_tests.gd`: jetzt 53 Assertions (zusätzlich
|
||
FTP-Pfad, Relativität, Eindeutigkeit).
|
||
- Gesamtsuite: **1128 Assertions**.
|
||
- `docs/assets.md` beschreibt Spiegel, Befehle und den Rechner ohne
|
||
Workbench.
|
||
|
||
## Offen
|
||
|
||
- Aufräumregel für alte Versionen auf dem Server (aktuell sammeln sich
|
||
versionierte Dateien).
|
||
- Android: 1K-Texturen oder separater Asset-Pack, damit die 8,35 MB nicht
|
||
ungeprüft ins APK wandern.
|
||
- Optional: `--check --remote`, um die Serverdatei ohne Download zu prüfen.
|