Files
Dreierpack-Manager/docs/new_ui/main-menu/README.md
T

217 lines
13 KiB
Markdown

<!-- SPDX-License-Identifier: GPL-3.0-only -->
# Hauptmenü und lokale Mod-Bibliothek
Dieser Backendvertrag gehört zur nativen Modern-UI-Umsetzung auf Basis
`ab4a962`. Schreibgeschützte Gestaltungsreferenz sind `desktop/mod-library.js`
und `desktop/main-menu.js` im privaten HTML-Goldstand, Revision
`97c19979f10f190a87bbb93a06df397a8d3dae89`. Proprietäre Inhalte werden nicht in
dieses Repository übernommen. Das Hauptmenü wählt eine Mod für das nächste
Spiel aus; die Aktivierung erzeugt keine Karriere und verändert keine Engine.
## Ablage und Schnittstelle
`UiModLibrary(portable_root)` verwendet `portable_root/mods/<name>/content.obw`
und optional `mod.json`. Der Root-Parameter ist ausdrücklich die portable
Basis, nicht das Verzeichnis `mods` selbst. `--ui-mods` kann diese Basis für
isolierte Tests überschreiben. Neu installierte Modern-Mods besitzen ein Profil mit
Schema `openbmh-mod@1.0`. Classic-Mods bleiben für den vorhandenen 0.2-Launcher
streng `content.obw`-only; auch bestehende solche Verzeichnisse bleiben lesbar. `UiModEntry.path` bezeichnet immer den
Mod-Ordner, nicht die Paketdatei.
Die öffentliche API steht in `src/modern/ui/mod_library.hpp`:
- `snapshot()` liefert Einträge, eine optionale aktive Verzeichnis-ID,
Auswahl-Token und Bibliotheksfehler. Beschädigte Einträge bleiben als
Fehlerzeilen erhalten. Eine beschädigte Profilbeschreibung verhindert keine
sichere Entfernung des eigenen Datensatzes. Fremde oder nicht normalisierbare
Namen blockieren nicht pauschal neue Importe.
- `inspect(source,start_year)` liefert einen `ModImportPlan` mit geprüftem
Namensvorschlag und Metadaten. Es wird noch keine Mod installiert, keine
Bibliotheksauswahl geändert und kein echtes Nutzerverzeichnis angelegt.
- `commit(plan,name,progress)` veröffentlicht erst nach erneuter Quellprüfung
ein vollständig vorbereitetes Verzeichnis. Öffentliche Plan-Metadaten dienen
der Anzeige; maßgeblich bleibt der private unveränderliche geprüfte Plan.
- `activate`, `deactivate`, `rename` und `remove` verlangen sowohl die konkrete
Bibliotheksmitgliedschaft als auch aktuelle Datei- und Auswahl-Token.
Inspektion und Commit enthalten keine SDL-/RmlUI-Aufrufe. Die Oberfläche darf
sie in einem Hintergrundauftrag ausführen und währenddessen weitere
Mutationen sperren. Der optionale Fortschrittscallback liefert nur Text und
muss durch den UI-Besitzer sicher an dessen Hauptthread weitergereicht werden.
Ein explizites externes `--mod` ist ein vorübergehender Startoverride und wird
nicht als Bibliotheksmitglied oder persistierte Aktivierung ausgegeben.
## Metadaten und unterstützte Quellen
Die Detaildaten sind `type`, `source`, `version`, `file_count`, `bytes` und
`description`. Art und Herkunft folgen den tatsächlich validierten Inhalten.
Ein importiertes `mod.json` darf Classic und Modern nicht gegeneinander
umdeklarieren. Die Dateianzahl und Bytes zählen die geprüften, entpackten
Paketinhalte; vor einer Originalkonvertierung beschreibt der Plan die
Originalquellensammlung. Interne Bibliotheksprofile gehören nicht zu dieser
Inhaltszahl.
Unterstützt werden OBW-/ZIP-Weltpakete mit einer Manifestdatei an der
Archivwurzel, entpackte Weltverzeichnisse und Mod-Verzeichnisse mit
`content.obw`. Der vorhandene `editor::ArchiveStore` prüft sichere Pfade,
Grenzen und komprimierte Einträge. Alle Payload-Einträge werden gelesen und
gehasht, nicht lediglich die Manifestdatei. Modern-Inhalte müssen durch den
vorhandenen `Catalog` lesbar sein und bekannte UI-Weltanforderungen erfüllen.
Unbekannte Profile oder eine Welt ohne von der UI-Demo unterstützten Verein
werden ausdrücklich zurückgewiesen. Das ist keine Zusage einer vollständigen
Modern-Engine-Ausführung.
Classic wird ausschließlich nach erfolgreichem `content::open` klassifiziert:
Das vorhandene Siegel, die exakten Inhaltshashes, der Classic-Adapter und die
unterstützte Ligastruktur bleiben verbindlich. Herkunft ist bei geprüften
deutschen Inhalten `BMH`, bei Football Limited `FTLD`; letzteres ist das
historische UI-Kürzel, während die echte Originaldatei `FLTD.EXE` heißt.
Originalordner und explizit gewählte `BMH.EXE`/`FLTD.EXE` werden mit
`launch::check_game_directory` geprüft. Nicht unterstützte Disketteneditionen,
unvollständige und mehrdeutige Installationen ergeben konkrete Fehler.
Die eigentliche Konvertierung verwendet unverändert
`launch::ModLibrary::add`/`AddMod` in einer isolierten temporären Bibliothek,
mit `migrate=false`. Nutzerspielstände, Einstellungen und Desktopdateien werden
nicht migriert. Nach vollständiger Prüfung wird nur das resultierende
`content.obw` in die echte Mod-Bibliothek übernommen.
Eine Quelle darf höchstens 512 MiB und 12.000 Dateien umfassen; die bestehenden
strengeren Classic- und ArchiveStore-Grenzen gelten zusätzlich. Quell- und
Mitgliedschaftstoken werden blockweise gebildet, damit ein großes Paket nicht
als zusätzliche vollständige Kopie im RAM gehalten werden muss. Temporäre
ArchiveStore-Snapshots und Konvertierungsordner werden beim Verwerfen des
Plans beziehungsweise nach dem Vorgang entfernt. Eine ungefähr 1,6-GiB große
Season-Sammlung liegt außerhalb dieses Bibliotheksimports und wird nicht
stillschweigend als unterstütztes Ligaset übernommen.
## Auswahl und Transaktionen
Ohne gespeicherte Auswahl ist keine Mod aktiviert. Import aktiviert niemals
automatisch den ersten oder zuletzt importierten Eintrag. Eine explizite
Auswahl steht atomar in `.ui-active-mod.json`; ihr Wert ist entweder genau
eine existierende gültige Verzeichnis-ID oder `null`. Fehlt eine referenzierte
Mod oder ist sie beschädigt, meldet `snapshot()` den Fehler und zeigt keine
falsche aktive Mod. Ein Neustart wählt keinen Ersatz aus.
Neue Namen besitzen höchstens 64 Unicode-Zeichen und 240 UTF-8-Bytes. Die
Vergleichsregeln übernehmen die portable deutsche Casefold-Hilfe der
Dateiverwaltung einschließlich Ö/ö, ß und zerlegter lateinischer Akzente.
Zusätzlich gelten portable Dateinamensregeln: keine Schrägstriche, Doppelpunkte
oder anderen Windows-Sonderzeichen, keine versteckten Namen, kein abschließender
Punkt und keine reservierten Gerätenamen. Bestehende gültige 0.2-Namen bis
100 ASCII-Zeichen bleiben lesbar und können auf einen neuen kürzeren Namen
umbenannt werden. Die dokumentierte Unicode-Normalisierungsgrenze des
Dateianbieters bleibt bestehen.
Installieren veröffentlicht einen fertig geprüften Staging-Ordner mit einer
einzigen abschließenden Umbenennung. Für Rename/Delete werden der Ordnerwechsel
und die aktive Namensreferenz durch ein kleines Journal mit Auswahl-Nonce
verbunden. Ein Fehler vor dem Auswahl-Commit stellt die bisherige Anordnung
wieder her. Nach dem Commit wird ausschließlich aufgeräumt. Auch reine
Groß-/Kleinschreibungsänderungen verwenden einen temporären Zwischennamen,
damit das Verhalten auf Windows nicht vom Umbenennen auf denselben Pfad
abhängt. Ein liegen gebliebenes Journal wird vor dem nächsten Bibliothekszugriff
geprüft und soweit eindeutig wiederhergestellt. Unerwartete externe Änderungen
führen zu einer ausdrücklichen Prüfmeldung; unbekannte Daten werden dabei
nicht gelöscht.
Der eigene temporäre Schreib-Lock verhindert konkurrierende Anbietertransaktionen.
Ein nach einem Prozessabsturz verbliebener Lock wird nicht ungeprüft entfernt.
Symlinks innerhalb der verwalteten Mod-Struktur und verknüpfte Quellen werden
zurückgewiesen. Die vertrauenswürdige portable Basis wird kanonisiert, damit
gewöhnliche Betriebssystem-Basisaliase funktionieren. `userdata` hat einen
unabhängigen Lebenszyklus und bleibt bei Mod-Rename und Mod-Delete erhalten.
## Prüfung
`tests/modern_mods_ui_tests.cpp` verwendet ausschließlich temporäre synthetische
Welten und den bereits öffentlichen künstlichen Classic-Testgenerator. Es
prüft Modern-/versiegelte Classic-Metadaten, 0/1-Auswahl über Neustarts,
Namenskonflikte, Mitgliedschaft, alte 0.2-Ordner, fehlerhafte Profile, geänderte
Quellen, Staging-Abbruch, IO-/Lock-Fehler, Symlinks und erhaltene Nutzerdaten.
Originalkonvertierungen mit tatsächlich proprietären Installationen gehören
ausschließlich in die private QA. Die Testquelle allein belegt weder einen
ausgeführten Build noch natives Plattformverhalten.
## Native Oberfläche und Bedienung
Der native RmlUI-Client übernimmt das Hauptmenü mit sechs großen Textaktionen,
Hover-/Fokuspfeil und zurückhaltender Versionsanzeige. Ohne aktive Mod bleibt
Neues Spiel gesperrt. Das Netzwerk ist ein sichtbarer Platzhalter; Downloads
führt in den zweiten Mod-Tab mit angekündigtem, gesperrtem Datenbankzugang.
Die Bibliothek zeigt die tatsächlich installierten Classic-/Modern-Pakete und
ihre geprüften Metadaten. Auswahl aktiviert noch nichts. Aktivierung bleibt
explizit und wird über Neustarts erhalten. Umbenennen und Löschen verwenden
lokale Bestätigungen; beim Löschen der aktiven Mod gibt es keine automatische
Ersatzwahl. Nutzerdateien bleiben getrennt erhalten.
Der Import bietet Originalordner, Paketdatei und Export-/Modordner. Nach
Dateiauswahl folgt die asynchrone Prüfung, danach ein editierbarer Namensentwurf.
Erst Importieren veröffentlicht das Paket. Auswahlabbruch und verworfene
Namensentwürfe ändern die Bibliothek nicht. Während laufender Prüfung oder
Übernahme sperrt der Client weitere Mutationen, Escape und Schließen; ein
in-flight Abbruch wird nicht angeboten. Der vorhandene Classic-Konverter wird
wiederverwendet und verändert keine Originaldateien. Inspektion, Konvertierung
und Veröffentlichung laufen ohne SDL-/RmlUI-Zugriffe im Worker.
`--ui-mods <portable Basis>` isoliert eine Bibliothek mit ihrem Unterordner
`mods/`; `--ui-mod-import <Quelle>` ersetzt ausschließlich die explizite
OS-Dateiauswahl für QA. Das JSONL-Skript wartet mit `front-wait` auf denselben
normalen Abschlussweg wie die interaktive Anwendung. Es injiziert keine
Bibliothekszustände.
Ein explizites `--mod` ist eine temporäre externe Welt und wird nicht als
installierte oder dauerhaft aktivierte Mod dargestellt. Neues Spiel einer
Classic-Mod startet weiter den vorhandenen Classic-Client; die zugehörige
Spielstandauswahl bleibt ebenfalls dort. Modern verwendet weiterhin den
getrennten UI-Datenanbieter. Die echte Engine wird nicht geändert und Anstoß
bleibt ohne Aktion. Die eigentliche Bildschirm-/Audioanbindung und das größere
Stadionperipherie-Redesign gehören nicht zu diesem Paket.
Private Vorher-/Nachherbilder, UI-Zustände, synthetische Importfixtures und
Eingabeskripte liegen in
`bmh_4k_ui/docs/qa/front-mods-batch-2026-10-26/`. Gold enthält eine fiktive
mitgelieferte Beispielmod; die native frische Liste bleibt wegen der getrennten
Nutzerdaten leer. Gold sammelt Originalbytes nur lokal für den POC, während der
native Client den bestehenden tatsächlichen Converter verwendet. Das ist eine
ausdrückliche Datenstrecken-Abgrenzung, keine Behauptung identischer Engine-
funktionalität.
## Prüfung
Die lokale Meilenstein-Suite umfasst 35 bestandene Tests. Synthetische
Referenzpakete lassen sich reproduzierbar über
`modern_mods_ui_tests --write-fixtures <leeres Verzeichnis>` erzeugen; dabei
wird keine Engine gestartet. Der unabhängige UI-Lauf besteht auf seiner
zugeordneten Runtime 132 Prüfungen in neun Prozessen (darunter zwei Neustarts).
Die neue Kompatibilitäts-/Coverkohorte wird getrennt dokumentiert. Native
Bild- und Bedienungstests laufen unter Linux/OpenGL; die Plattform-CI baut
und prüft synthetisch, ersetzt aber keine Windows-/macOS-Spielabnahme.
## Spieleinstieg
Grundeinstellungen, Managerwahl, Entwürfe und Bestätigungen sind im
[separaten Einstiegsvertrag](entry/README.md) beschrieben.
## Nachtstand 26./27. Oktober 2026: Büro-Hauptmenü
Das HTML-Hauptmenü verwendet die transparente Navigation der Studie4832d248.
Die sechs vorhandenen Funktionen bleiben Neues Spiel, Laden, Netzwerk (gesperrt),
Mod, Einstellungen und Beenden. Die aktive Mod steht dezent unten. Die große
OpenBMH-Überschrift entfällt. Das Vereinsbüro ist Vorgabe; die alternative
Trophäenbüro-Studie bleibt in der privaten HTML-Vorschau erhalten.
Die RmlUI-Fassung übernimmt Anordnung, Menüflächen und Navigation in `front_screens.inc`
und `front.rcss`. Das feste Bild wird als GUI-Ressource `menu.club-office`
geladen, nicht aus dem Weltpaket. Ältere GUI-Ressourcensätze ohne diesen neuen
Schlüssel behalten ihren vorhandenen Hintergrund; es wird kein Bild aus fremden
Weltassets erraten. Die getrennte Vorbereitung kann zusätzlich `menu.trophy-office`
führen. Das Almanach-SVG bleibt mit seinem Ball innerhalb des Buchdeckels.
HTML-Bedienprüfungen und tatsächliche Bilder liegen im privaten Repository unter
`docs/qa/night-ui-2026-10-27/main-menu`. Der native Build-/Sichtnachweis folgt
nach Integration des zeitgleich überarbeiteten Karrierepakets; dieser Eintrag
behauptet noch keine native Abnahme.