Files
Dreierpack-Manager/docs/new_ui/desktop/save-load/README.md
T

211 lines
12 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.
<!-- SPDX-License-Identifier: GPL-3.0-only -->
# Speichern, Laden und Desktopansichten
Die native RmlUI-Fassung überträgt den privaten HTML-Goldstand der Dateien
`desktop/save-load-menu.js`, `desktop/save-load-window.css`,
`desktop/modern-dialogs.js` und `desktop/desktop-views.js`. Referenzrevision:
`4b1c3b61ccd7b19351cd0b2dfac1006918103c97`. Die Referenz bleibt privat und
unverändert; diese öffentliche Implementierung enthält keine Originalgrafiken
oder Originalspielstände. Ausgangsstand der nativen Umsetzung ist `db89d88`.
## Sichtbare Ansichten
Spielstände verwenden den gemeinsamen Untermenürahmen mit 2720 × 2040
Entwurfseinheiten. Die Desktopansichten verwenden das eigenständige
Desktopdialogfenster mit 2560 × 1840 Einheiten. Beide haben eine unbegrenzt
scrollbare Liste, eine getrennte Detailansicht und bestätigte Aktionen für
Überschreiben, Umbenennen und Löschen. „Neuer Speicherstand“ beziehungsweise
„Neue Ansicht“ erscheint nur beim Speichern. Fehlende oder beschädigte Dateien
bleiben mit einer Fehlermeldung erkennbar.
Die Karriereübersicht zeigt Saison, Spieltag, Spieldatum, Manager und Vereine
aus dem ausgewählten Dokument. Nur ein neuer Eintrag zeigt die aktuelle
Karriere. Die Demo befindet sich ohne gesonderte gespeicherte
`game_info.matchday`-Angabe in der Vorbereitung; hier wird kein zukünftiger
Engine-Spieltag erfunden. Die Saison folgt dem gespeicherten Spieldatum und
beginnt im Juli. Speicherdatum, Dateigröße und Änderungsdatum stammen aus dem
Dateianbieter. Namen werden vor der Anzeige als RmlUI-Text maskiert.
Die Ansicht „Standard“ ist eine unveränderliche, immer verfügbare Vorlage.
Sie verwendet beim Laden den aktuellen Look. Ihre Vorschau wird unmittelbar
aus der Standardgeometrie gezeichnet; sie ist kein Screenshot einer heimlich
auf die aktive Karriere angewendeten Ansicht. Eigene Ansichten enthalten den
tatsächlichen Desktop-Screenshot zum Speicherzeitpunkt sowie Anordnung,
Widgetgrößen, Sichtbarkeit, Fixierungen und Look. Der Screenshot entsteht ohne
Dateidialog und ohne das darüberliegende Verwaltungsfenster.
## Lokale Dateitransaktionen
`DemoFiles` speichert ausschließlich UI-Demostände; es liest und schreibt keine
OBS-/Engine-Karriere. Die Ablage liegt unter dem weltbezogenen
`userdata/ui-demo/<world-hash>/saves` beziehungsweise `layouts`. Der explizite
Parameter `--ui-userdata` erlaubt eine vollständig isolierte QA-Ablage.
Globale Anzeige-, Sound- und Themenpräferenzen bleiben in ihrer eigenen Datei.
Ein Datensatz ist ein Dokument mit Schema `openbmh-ui-file@1`. Es enthält
Bezeichnung, Art, Zeitstempel, Payload, Welt-ID, Hash der Weltmanifestrevision,
PNG-Vorschau und separate Inhaltsprüfsummen. Die PNG-Bytes werden verlustfrei
hexadezimal eingebettet. Deshalb werden Layout und Screenshot mit **einem**
atomaren Dateiaustausch veröffentlicht. Die Dateinamen sind opake IDs und
werden nicht aus Benutzernamen zusammengesetzt. Eine umbenannte Ansicht
behält Identität, ursprünglichen Speicherzeitpunkt und Vorschau.
Vor der Veröffentlichung werden Karriere und Desktop in isolierten Objekten
validiert. Karriereprüfungen nutzen die bestehenden `DemoSource`-Regeln. Die
aktive Quelle wird erst nach erfolgreicher Validierung ersetzt. Entwürfe
binden sich an Welt, Source-Objekt und Source-Revision. Bestätigungen tragen
zusätzlich den SHA-256-Token der ausgewählten Dateiversion. Ein inzwischen
geänderter, gelöschter oder fremder Datensatz wird zurückgewiesen.
Ein kurzlebiges Transaktionsverzeichnis serialisiert Anbieteroperationen.
Fehlgeschlagene Schreibvorgänge behalten den bisherigen Datensatz. Löschen
verwendet eine atomare Umbenennung; bei einem unterbrochenen Aufräumen bleibt
die Datei als versteckter, wiederherstellbarer Rest erhalten. Ein nach einem
Prozessabsturz verbliebenes Transaktionsverzeichnis wird nicht ungeprüft
entfernt: Nach Beenden aller beteiligten Prozesse muss es geprüft werden.
Symlinks und Pfadwechsel aus der Ablage werden zurückgewiesen. Abgeleitete
PNG-Vorschaudateien unter `.previews` sind nur ein durch Hash identifizierter
Cache; sie sind nie die autoritative gespeicherte Vorschau.
Namen besitzen 1 bis 64 Unicode-Zeichen und keine Steuerzeichen. Der
plattformunabhängige Vergleich berücksichtigt Groß-/Kleinschreibung,
deutsches ß, Ö/ö und komponierte/dekomponierte lateinische Tastaturakzente.
Ansichten berücksichtigen zusätzlich vollbreite ASCII-Kompatibilitätszeichen;
„Standard“ bleibt dabei reserviert. Speichernamen verwenden diesen
Kompatibilitätsschritt nicht. Die kleine portable Hilfe ist kein vollständiger
Unicode-NFC-/NFKC-Normalisierer: Seltene kombinierte Schriftzeichen außerhalb
der dokumentierten lateinischen Akzente bleiben bytegenau unterscheidbar.
Diese Grenze betrifft die Namen, nicht die Dateiinhalte oder Spielvalidierung.
Ältere rohe Demo-JSON-Spielstände und Layoutdateien werden gelesen, aber beim
Navigieren nicht umgeschrieben. Vorhandene PNG-Seitendateien können in ein
neues konsistentes Dokument übernommen werden. Alte Ansichten ohne Vorschau
zeigen einen ausdrücklichen Hinweis; vor der Veröffentlichung einer neuen
Ansichtsdatei ist eine gültige Vorschau erforderlich.
## Aktionen und Zustandsgrenzen
Import und Export sind ausdrückliche Buttonaktionen. Erst dann öffnet NFD
einen Betriebssystemdialog. QA kann mit `--ui-file-import` und
`--ui-file-export` konkrete Pfade bereitstellen; die Parameter lösen allein
keine Dateiaktion aus. Import validiert das Dokument vollständig und legt
einen neuen, bei Namenskonflikten umbenannten Eintrag an. Es wird kein
bestehender lokaler Stand überschrieben und keine Karriere automatisch
geladen. Export enthält Payload und Vorschau gemeinsam; ein vorhandenes
Ziel benötigt eine separate Überschreibbestätigung.
Karriere-Save setzt Source und Karriere-Desktop erst nach erfolgreicher
Veröffentlichung auf „gespeichert“. Karriere-Load setzt den ausgewählten
validierten Stand samt Layout auf „gespeichert“. Ansichts-Save verändert diese
Karrieremarkierungen nicht. Ansichts-Load erzeugt einen Desktop-Undo-Schritt,
speichert die globale Themenpräferenz zuerst und übernimmt anschließend
Layout und Look. Andere Anzeige- oder Soundwerte werden dabei nicht aus dem
Spielstand übernommen.
Die Root-Glue-Hooks `files_saved_success(bool)` und `files_loaded_success()`
verantworten den Rücksprung ins Hauptmenü, die Fortsetzung eines bestätigten
Beenden-Ablaufs und das Zurücksetzen sourceabhängiger Presenter. Abbrechen
und Escape verwerfen nur lokale Dateifensterentwürfe und die ausstehende
Beenden-nach-Speichern-Absicht. Navigation, Auswahl und Vorschau verändern die
aktive Karriere nicht.
## Prüfung und offene Enginefragen
`tests/modern_files_ui_tests.cpp` verwendet nur eine synthetische Welt und
temporäre QA-Dateien. Es prüft Namenskonflikte, atomare Payload-/PNG-Rundläufe,
veraltete Tokens, beschädigte Importe, fehlgeschlagene Überschreibungen,
Transaktionskonflikte, ausgewählte Dateimetadaten, Exportkollisionen, getrennte
UI-Präferenzen und den Rollback fehlgeschlagener Karrierevalidierung.
Ein Build und native Screenshot-/Interaktionsprüfungen müssen separat
ausgeführt werden; die Testquelle allein belegt kein Plattformverhalten.
Die spätere Engineanbindung muss den gemeinsamen Karriere-/Sessionanbieter
verwenden. OBS-Migration, Managerbesitz, Engine-Revisionen, RNG-Zustände,
Autosaves und echte Saisonfortschritte werden hier ausdrücklich nicht als
implementiert behauptet. Sie gehören nicht in diesen UI-Demodateianbieter.
## Bewusste Abgrenzungen zum Browser-POC
Ansichten und Arbeitsanordnung liegen in dieser nativen Demo im weltbezogenen
UI-Verzeichnis; vorhandene ältere native Layouts bleiben so erreichbar. Der
Browser-POC speichert diese Bibliothek browserglobal. Anzeige und Sound bleiben
nativ unabhängig von der Welt gespeichert. Das Laden einer Karriere setzt
diese globalen Präferenzen nicht zurück; eine benannte Ansicht darf dagegen
ihre ausdrücklich gespeicherte Gestaltung wiederherstellen.
Erfolgreiches Speichern und Laden einer Karriere lässt das Dateifenster mit
Auswahl und Rückmeldung offen. Ansichts-Speichern und -Laden kehren zum Desktop
zurück. Arbeitsanordnungen lösen keinen Spielstand-Speicherbedarf aus.
## Gespeicherte Person und Nationalrolle
Savekopf und Mitspieler-Untertext beziehen sich auf den tatsächlich ausgewählten
Slot. `career.role` und `career.active_portrait` stammen aus dessen Payload, nicht
aus dem aktuellen Betrachter und nicht pauschal aus Person0. Ein gespeicherter
Nationalcoach zeigt Deutschland samt GUI-Flagge; die intern kompatible
Vereinsreferenz wird nicht als dessen Mannschaft ausgegeben. Bei kombinierten
Karrieren behalten die anderen gespeicherten Personen ihre Vereinsbeschriftung.
Der gezielte native Test speichert tatsächlich eine Nationalansicht von Robin
und betrachtet sie anschließend mit einer anderen laufenden Vereinsrolle/Person0.
Der rechte Kopf und Robins Zeile zeigen weiter Deutschland; der laufende
Viewer-Source bleibt unverändert. Es werden ausschließlich Metadaten gelesen,
kein Karrierepayload oder Enginezustand umgebaut.
## Echte OBS-Karrieren (Engine-Einstieg, 29.10.2026)
Der normale Modern-Einstieg verwendet dieselbe RmlUI-Liste mit Detailbereich,
liest und schreibt aber echte OBS-Dateien. Der getrennte `--modern-ui-demo`-Weg
behält seine lokalen JSON-Präsentationsstände; sie sind keine Engine-Spielstände.
Die HTML-Goldreferenz und das gemeinsame Layout bleiben unverändert.
Die Ablage liegt unter `userdata/careers/<SHA-256 der Welt-ID>/`. Eine Mod darf
nur Karrieren derselben Welt-ID und Datenrevision öffnen. Die Metadaten stammen
vom geprüften OBS-Inhalt: Datum, Saison, nächster Ligaspieltag, logische Menschen,
aktuelle Rolle und kanonische Namen. In der Nationalrolle steht Deutschland;
wartende Manager behalten ihre Vereinsnamen. Es wird kein fiktives Desktopdatum
oder Porträtvergleich als Rollenbestimmung benutzt.
- Neue Bezeichnung oder gewählter Eintrag; Ersetzen immer mit Rückfrage.
- Umbenennen ändert auch den `.obs`-Dateinamen. Namen sind auf allen drei
Zielsystemen gültig; Groß-/Kleinschreibungs- und Unicode-Konflikte werden erkannt.
- Löschen mit Rückfrage; beschädigte, noch lesbare Dateien bleiben löschbar.
- Import/Export mit nativer Dateiauswahl. Ein Import ändert keine laufende Partie.
- Vor dem Laden ungespeicherter Änderungen: Abbrechen, ohne Speichern laden
oder erst speichern. Abgebrochene/fehlgeschlagene Vorgänge beenden die Partie nicht.
- Strg+S/Strg+O öffnen die Bibliothek. Der ausdrückliche QA-Override
`--ui-file-export` erhält den bisherigen direkten Save-Export über die App-Taste.
Schreibvorgänge werden pro Ablage durch eine vom Betriebssystem freigegebene
Sperre serialisiert. Der Writer erzeugt zunächst eine temporäre OBS-Datei,
liest sie erneut ein und veröffentlicht sie atomar. Ein SHA-256-Auswahltoken
blockiert veraltetes Ersetzen, Umbenennen, Löschen, Laden oder Exportieren,
wenn eine Datei inzwischen extern verändert wurde. Es gibt kein neues OBS-Format.
Laden innerhalb einer Welt baut eine neue Session auf dem vorhandenen Mount auf
und prüft ihren vollständigen Desktop-/Menüsnapshot. Erst dann wird die bisherige
Session ersetzt. Bei einem Fehler bleiben die bisherige Karriere und ihre
Zufallszustände erhalten; die Prozessdimensionen werden wieder auf die aktive
Welt gesetzt. Ansichts- und Archivcaches werden auch beim Laden derselben
Karriere, desselben Datums und derselben Revision verworfen.
Nach erfolgreichem Engine-Speichern/Laden geht es zum Desktop zurück. Die
abweichend oben beschriebene offenbleibende Liste betrifft weiterhin den Demo-Pfad.
Bei Speichern und beenden schließt die Anwendung erst nach erfolgreicher
Veröffentlichung. Spielregeln, Matchablauf und Anstoßfreigabe werden nicht geändert.
### Prüfung dieses Integrationspakets
56 synthetische Regressionstests, 54 native Hauptprüfungen, 20 zusätzliche
Randfallprüfungen und 516 Geometrieprüfungen bestanden. Native Dialoge unter
Linux x64/SDL2/OpenGL in Silver, Midnight und Matchday bei 1080p/720p. Geprüft
wurden auch echter Prozessneustart, vier Menschen, dritter Mensch als
Nationalcoach, Speichern vor Laden und Speichern vor Beenden. Defekte Archive
und ein korrekt gehashtes Archiv mit ungültigem Driver ersetzen die aktive
Session nicht; danach funktioniert ein echter Eintrittspreisbefehl weiterhin.
RNG und Almanachbytes bleiben bei bloßem Speichern/Laden unverändert.
Windows/macOS wurden in diesem Paket nicht nativ ausgeführt. Die private
Galerie enthält Screenshots und zugehörige OBS-Dateien unter
`bmh_4k_ui/docs/qa/engine-files-2026-10-29/`.