rinkplanner/docs/findings-2026-10-31-asset-ftp.md
torsten 697274ce1b feat: FTP-Spiegel fuer externe 3D-Assets
- --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
2026-10-31 12:39:30 +01:00

3.4 KiB
Raw Blame History

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

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

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.