gta6/docs/superpowers/specs/2026-09-13-minimap-design.md

Minimap — Entwurf

Datum: 2026-09-13 Zusammenhang: Teil des Boden-Updates, das der Nutzer nach dem Spielen angefordert hat. Reihenfolge vom Nutzer entschieden: Schichten und Minimap parallel, danach Straßenbau (Rissrichtung, Bordstein, Gehweg). Baut auf: docs/superpowers/specs/2026-09-12-leonida-vice-slice-design.md und dem umgesetzten Plan dazu.

Ziel

Eine große Kartenansicht des gesamten Vice-City-Ausschnitts, die sich über dem laufenden Spiel öffnet, wenn man M drückt.

Entscheidungen des Nutzers

Frage	Entscheidung
Darstellung	Große Karte als Überlagerung, bildschirmfüllend. M oder Esc schließt. Keine Eckkarte.
Inhalt	Eigene Position mit Blickrichtung, Fahrzeuge, Zoomen und Verschieben, Klick zum Hinspringen. Keine Wahrzeichen.
Kartenbild	Vorab erzeugt, 1 Pixel je Meter.
Welt während offener Karte	Läuft weiter, keine Pause.
Klick auf Gebäude oder Wasser	Landung in der Mitte des nächsten begehbaren Maskenpixels im Umkreis von 20 m, sonst Hinweis und kein Sprung.
Chunks	Raster auf der Karte sichtbar, jeder Chunk benannt als Planquadrat A1 bis L12. Zweck: der Nutzer spricht Chunks im Chat für die Feinkalibrierung an.

Daten

Drei neue Dateien neben manifest.json in public/data/vice-a/:

Datei	Inhalt
map.png	3.000 × 3.000 px, 1 px/m. Wasser, Land, Sand, Park, Stadtfläche, Straßen und Brücken, Gebäude nach Höhe getönt — dieselben Farben wie die Gesamtansicht. Ohne Palmen: bei 1 px/m wären sie nur Rauschen. Löcher werden wie in der Gesamtansicht über eine Maske korrekt ausgespart.
map-walkable.png	750 × 750 px, 4 m/px, Graustufen. 255 = begehbar: die ganze 4 × 4-m-Fläche ist Kollisionsboden — Landplatte oder Brücke — ohne Gebäude, aus einem 1-m-Raster verdichtet. 0 = sonst. Straßen und Beläge zählen nur über der Landplatte, weil sie selbst reine Auflagen ohne Kollision sind. (Nach dem Abschluss-Review verschärft: die frühere großzügige Maske setzte die Figur bei 4,3 % der Klicks auf Gebäude in eine Wand oder ins Wasser.)
map.json	{ "scale": 1.0, "walkable_scale": 0.25, "slice": { "x0": -1000, "x1": 2000, "y0": -500, "y1": 2500 }, "manifest_sha256": "<SHA-256 von manifest.json>" }

map.json ist die einzige Quelle für Maßstab und Ausschnittsgrenzen der Karte. Der Browser liest sie, statt die Werte ein zweites Mal im JavaScript festzuschreiben.

Erzeugung: am Ende von tools/extract/run.py über render_map aus overview.py, seit der Beschriftungs-Plan gelandet ist. cd tools/extract && uv run python overview.py erzeugt dieselben Dateien weiterhin einzeln, etwa nach einer Änderung nur an den Farben. manifest_sha256 sichert ab, dass Karte und Chunks zusammenpassen (siehe Fehlerfälle).

Aufbau

Einheit	Aufgabe
tools/extract/overview.py	Zusätzlicher Ausgang für map.png, map-walkable.png und map.json. Die bestehende Debug-Gesamtansicht bleibt unverändert erhalten.
src/ui/mapMath.js	Reine Funktionen ohne DOM, vollständig ohne Browser testbar: worldToMap, mapToWorld, Zoom- und Verschiebungsgrenzen, Unterscheidung Klick gegen Ziehen, nearestWalkable(mask, px, py, radiusPx).
src/ui/map.js	Die Kartenkomponente: ein Canvas über dem Spiel, zeichnet jedes Bild Kartenbild, Spielerpfeil und Fahrzeugsymbole. Öffnen, Schließen, Offen-Zustand.
src/main.js	Nur Einhängen: Taste M und Esc, Position, Blickrichtung, Fahrzeuge, Sprung.

Die Kartenkomponente bekommt ihre Abhängigkeiten übergeben, statt selbst in Controller oder Streamer zu greifen:

createMap({
    getPosition,        // () => { x, z } in three-Koordinaten
    getHeading,         // () => Winkel in Radiant, 0 = Norden, im Uhrzeigersinn
    getVehicles,        // () => [{ x, z, heading, occupied }]
    onTeleport,         // ({ x, z }) => void
    baseUrl,            // Verzeichnis mit map.json, map.png, map-walkable.png und manifest.json
}) // -> { open(), close(), toggle(), isOpen() }

Die Karte lädt map.json, beide Bilder und das Manifest selbst, und zwar erst beim ersten Öffnen. So bricht eine fehlende Kartendatei nicht den Spielstart, sondern zeigt ihren Hinweis erst, wenn jemand M drückt. Das Manifest liest sie als Rohbytes: der Fingerabdruck in map.json ist über die Datei gebildet, ein bereits geparstes und neu serialisiertes Objekt ergäbe einen anderen Wert.

Koordinaten

three.js (x, z) → Welt (x, y = −z) → Kartenpixel:

px = (x − slice.x0) · scale
py = (slice.y1 − y) · scale  =  (slice.y1 + z) · scale

Die Umkehrung dient den Klicks. mapMath.js ist die einzige Stelle, an der die Achsenumkehr zwischen three.js-z und Karten-y steht — genau dort würde sonst eine gespiegelte Karte entstehen.

Chunk-Raster und Namen

Die Namen sind die Schnittstelle zwischen Nutzer und Feinkalibrierung: was im Chat „C10" heißt, muss auf der Karte, in den Dateinamen und in der Pipeline eindeutig dasselbe sein.

Schema: Spalte als Buchstabe A bis L aus i, Zeile als Zahl 1 bis 12 aus j.

name(i, j) = "ABCDEFGHIJKL"[i] + (j + 1)

Richtung, gegen die Daten geprüft: chunkOrigin(i, j) liefert ox = x0 + i · 250 und oy = y1 − j · 250. i wächst also nach Osten, j von der Nordkante nach Süden. Damit gilt:

Name	Datei	Lage
A1	chunk_0_0.json	Nordwest-Ecke, oben links auf der Karte
L1	chunk_11_0.json	Nordost-Ecke
A12	chunk_0_11.json	Südwest-Ecke
L12	chunk_11_11.json	Südost-Ecke
C10	chunk_2_9.json	Beispiel

Eine Umrechnung, zweimal geschrieben, einmal geprüft: chunkName(i, j) und parseChunkName(name) -> { i, j } stehen in src/world/coords.js neben chunkForWorld, und dieselben zwei Funktionen als chunk_name und parse_chunk_name in tools/extract/leonida/coords.py — die Feinkalibrierung wird sie in der Pipeline brauchen. Beide Seiten prüfen denselben festen Satz an Beispielen aus der Tabelle oben, damit JavaScript und Python nicht auseinanderlaufen können. parseChunkName akzeptiert Groß- und Kleinschreibung (c10 = C10) und weist alles außerhalb von A1–L12 ab.

Auf der Karte:

• Rasterlinien an allen Chunk-Grenzen.
• Der Name steht in der Mitte jedes Chunks, sobald der Chunk auf dem Bildschirm mindestens 40 px breit ist; darunter nur die Linien. Beim Öffnen passt der ganze Ausschnitt ins Fenster, dann ist jeder Chunk auf gängigen Bildschirmen breit genug.
• Eine feste Anzeige oben links unter der Standortanzeige nennt Chunk-Name und Weltkoordinate der Stelle unter dem Mauszeiger, etwa F3 · x 412 / y 1830. Die Koordinate erlaubt, eine Stelle innerhalb eines Chunks genau zu benennen.
• Der Chunk, in dem der Spieler gerade steht, ist hervorgehoben und sein Name steht fest in einer Ecke der Karte.

Anbindung an vorhandene Funktionen

• Position: über playerPosition(player) aus src/player.js. Damit fährt der Pfeil auch im Fahrzeug korrekt mit; dort liefert die Kapselposition nur einen lokalen Sitzplatz-Offset.
• Blickrichtung: aus der Weltrichtung der Kamera, auf die Bodenebene projiziert. Das gilt zu Fuß wie im Fahrzeug gleichermaßen, weil die Kamera der Fahrzeugrichtung folgt (followVehicleDirection: true).
• Fahrzeuge: über player.getAllVehicles(). Das Fahrzeug, in dem der Spieler sitzt, wird nicht zusätzlich als eigenes Symbol gezeichnet. Ob der Spieler gerade fährt, kommt aus player.getControllerMode() === 1, nicht aus getActiveVehicle() — letzteres wird beim Aussteigen nie zurückgesetzt.
• Sprung: über das vorhandene requestTeleport, mit seiner Wartewache, bis der Ziel-Chunk bereit ist.

Bedienung

• Öffnen und Schließen: M öffnet und schließt, Esc schließt. M wird ignoriert, solange ein Textfeld (Text- oder Zahleneingabe, textarea, editierbarer Inhalt) den Fokus hat — sonst öffnete sich die Karte beim Eintippen eines Werts im Panel. Hat eine Auswahlliste, ein Kontrollkästchen oder ein Farbwähler den Fokus, öffnet M die Karte, bricht die Standardaktion ab und löst den Fokus — sonst wählte eine Auswahlliste per Tipp-Suche einen Eintrag, etwa ein Wahrzeichen, und spränge dorthin. Bei offener Karte wandert Tab nicht ins verdeckte Panel.

• Beim Öffnen immer der ganze Ausschnitt, eingepasst ins Fenster.

• Mausfang: beim Öffnen wird der Pointer-Lock gelöst. Beim Schließen wird er nicht automatisch neu angefordert; Browser erlauben das nur nach einer Nutzergeste, ein Klick ins Spiel fängt ihn wie gewohnt.

• Steuerung ruht, Welt läuft. Solange die Karte offen ist, erreichen Tastatur- und Mausereignisse die Figur nicht; Streaming, Fahrzeugphysik und Animation laufen weiter.

  Umsetzung, am Quelltext des Controllers belegt: InputSystem registriert keydown, keyup, mousemove und click auf window in der Bubble-Phase.

  • Die Karte registriert Listener auf window in der Capture-Phase, die nur bei offener Karte wirken. Tastaturereignisse fängt sie dort vollständig ab (und wertet M und Esc selbst aus). Mausereignisse, deren Ziel außerhalb der Karte liegt, fängt sie dort ab; Mausereignisse auf der Karte lässt sie bis zum Canvas durch und stoppt sie an der Kartenwurzel in der Bubble-Phase, bevor sie window erreichen. Ein Stopp schon in der Capture-Phase auf window würde sonst auch den eigenen Canvas-Listenern die Ereignisse nehmen.
  • Die Listener bleiben dauerhaft registriert statt beim Öffnen hinzugefügt und beim Schließen entfernt zu werden: M muss bei geschlossener Karte ohnehin gehört werden, und ein vergessenes Entfernen kann so nicht passieren.
  • Beim Öffnen wird einmal window.dispatchEvent(new Event("blur")) ausgelöst. Das ruft im Controller resetKeys() auf, damit eine beim Drücken von M gehaltene Bewegungstaste nicht hängen bleibt und die Figur weiterlaufen lässt.
  • Nicht unbindEvents() verwenden: es setzt isupdate = false und hält damit die gesamte Figurenaktualisierung an, nicht nur die Eingabe. Das widerspräche der Entscheidung, dass die Welt weiterläuft.

• Zoomen: Mausrad oder Trackpad, um den Mauszeiger herum, von „ganzer Ausschnitt passt ins Fenster" bis vierfach. Der Zoomfaktor wächst mit der Scrollstrecke (ein Rastschritt von etwa 100 px zoomt um rund 1,16×), damit die vielen kleinen Ereignisse einer Trackpad-Geste fließend zoomen; Zeilen, Seiten und die Pinch-Geste werden wie im Controller umgerechnet.

• Verschieben: Ziehen mit gedrückter Maustaste, begrenzt auf den Kartenrand.

• Hinspringen: Ein Klick — Maustaste gedrückt und losgelassen, und der Zeiger war zu keinem Zeitpunkt dazwischen 4 px oder weiter vom Startpunkt entfernt — springt an die Stelle und schließt die Karte. Sonst ist es ein Ziehen, auch wenn der Zeiger zum Startpunkt zurückkehrt, und es wird nicht gesprungen.

• Landeplatz: Der Klickpunkt wird in map-walkable.png nachgeschlagen. Gelandet wird immer in der Mitte eines begehbaren Pixels, nie am Klickpunkt selbst: weil die Maske einen Pixel nur freigibt, wenn seine ganze Fläche Kollisionsboden ist, sind es von der Mitte aus mindestens 2 m bis zu Wand oder Wasser. Die Abweichung vom Klickpunkt beträgt höchstens 2,8 m.

  • Begehbar: Sprung in die Mitte dieses Pixels.
  • Nicht begehbar (Gebäude, Wasser oder nur teilweise freier Rand): Sprung in die Mitte des nächsten begehbaren Pixels im Umkreis von 20 m, gemessen als euklidischer Abstand. In Maskenpixeln sind das 20 · walkable_scale = 5 px — nearestWalkable erhält den Radius in Pixeln, die Umrechnung aus Metern geschieht an genau einer Stelle über map.json.
  • Kein begehbarer Pixel im Umkreis: kein Sprung, die Karte bleibt offen, und für etwa zwei Sekunden erscheint „Kein Landeplatz".

Fehlerfälle

Fall	Verhalten
map.png lässt sich nicht laden oder passt nicht zu map.json	M öffnet die Überlagerung mit dem Hinweis „Kartenbild fehlt — uv run python overview.py ausführen". Kein Absturz, das Spiel läuft weiter. Erneutes Öffnen lädt neu, ohne die Seite neu zu laden. Ein unerwarteter Fehler beim Zeichnen führt zum selben Hinweis statt zu einer stehenden Karte.
map-walkable.png lässt sich nicht laden oder hat nicht die Größe aus map.json	Anschauen, Zoomen und Verschieben funktionieren. Klick zum Hinspringen ist abgeschaltet, ein Hinweis nennt den Grund. Erneutes Öffnen lädt neu.
map.json fehlt oder ist ungültig	Wie fehlendes Kartenbild: ohne Maßstab und Grenzen lässt sich nichts korrekt platzieren.
manifest_sha256 passt nicht zum geladenen Manifest	Die Karte funktioniert vollständig, zeigt aber sichtbar „Karte veraltet — overview.py erneut ausführen und Seite neu laden".
Kein sicherer Kontext (Aufruf über eine LAN-Adresse statt localhost)	crypto.subtle fehlt dort. Die Veraltungsprüfung entfällt still, alles andere funktioniert.

Grenze der Veraltungsprüfung: Der Fingerabdruck erkennt jede Änderung am Manifest — Klassenanteile, Chunk-Liste, Namensnennung. Eine Änderung, die nur Chunk-Inhalte betrifft, ohne das Manifest zu berühren, bleibt unerkannt; genau so eine war die Mindestbreite für Gebäude. Seit dem Abschluss-Review fängt ein pytest diese Lücke beim Testlauf: er erzeugt Kartenbild, Maske und map.json frisch aus den ausgelieferten Chunks und vergleicht sie mit den ausgelieferten Dateien. Ganz schließt sie sich, wenn die Kartenerzeugung in run.py hängt und damit gar nicht mehr veralten kann.

Namensnennung

Die Namensnennung bleibt auch bei offener Karte sichtbar. Das ist Lizenzpflicht, und die Karte ist selbst aus den CC-BY-4.0-Kacheln abgeleitet. Stapelordnung von oben nach unten:

Ebene	z-index
Namensnennung .attribution	2000 (heute 10, wird angehoben)
Kartenüberlagerung	1500
lil-gui-Panel	1001 (Vorgabe von lil-gui)
Spiel-Canvas	Grundebene

Die Namensnennung steht unten links und reicht auf schmalen Fenstern bis in die rechte Ecke; die Koordinatenanzeige der Karte steht deshalb oben links unter der Standortanzeige, damit sich beide nie überdecken.

Prüfung

Chunk-Namen, in beiden Sprachen mit demselben Beispielsatz (vitest und pytest):

• A1 ↔ (0, 0), L1 ↔ (11, 0), A12 ↔ (0, 11), L12 ↔ (11, 11), C10 ↔ (2, 9) in beide Richtungen.
• Kleinschreibung wird akzeptiert; M1, A0, A13, A, 10 und die leere Eingabe werden abgewiesen.
• Für jeden der 144 Chunks ergibt parseChunkName(chunkName(i, j)) wieder (i, j).
• Ein Test, der die Namen mit der tatsächlichen Lage verbindet statt nur mit den Indizes: der Downtown-Bezugspunkt aus tools/extract/data/districts.json bei Welt (−511, 254) ergibt über chunkForWorld (i = 1, j = 8) und damit B9; der höchste Turm, das Southeast Financial Center bei (−461, −460), ergibt C12. An der bestehenden Funktion nachgerechnet. (Korrigiert nach Task 4: (−511, 254) ist der Mittelpunkt der westlichen Hochhäuser, nicht der Hochhauskern selbst.)

Ohne Browser (vitest), für mapMath.js:

• worldToMap und mapToWorld an bekannten Punkten: dem früheren Spawn (1699, 3, −743) und allen vier Ecken des Ausschnitts; dazu Hin- und Rückweg ergibt wieder den Ausgangspunkt. Ein Test, der eine gespiegelte Achse sicher fängt.
• Zoomgrenzen: nie kleiner als „ganzer Ausschnitt", nie größer als vierfach; Verschiebung bleibt innerhalb des Kartenrands.
• Klick gegen Ziehen an der 4-px-Schwelle, knapp darunter und knapp darüber, und ein Ziehen, das zum Startpunkt zurückkehrt.
• nearestWalkable an einer künstlichen Maske: begehbarer Treffer landet in der Mitte seines Pixels; ein Gebäudepixel neben einer Straße findet die Straße; nur Wasser im Umkreis ergibt kein Ergebnis; ein Treffer knapp außerhalb von 20 m zählt nicht.

Pipeline (pytest), für overview.py:

• map.png hat 3.000 × 3.000 px; ein bekannter Wasserpunkt in der Bucht ist wasserfarben, ein bekannter Landpunkt nicht.
• map-walkable.png hat 750 × 750 px; die Fläche eines Gebäudegrundrisses ist 0, eine Straße daneben 255; Straße und Belag ohne Landplatte sind 0, eine Brücke 255; ein Pixel, den Wasser oder ein Gebäude nur anschneidet, ist 0.
• Die ausgelieferten Kartendateien entsprechen einer frischen Erzeugung aus den ausgelieferten Chunks.
• map.json enthält den korrekten SHA-256 des aktuellen Manifests.

Im Browser, mit Bildern im Bericht:

• M öffnet, M und Esc schließen; bei fokussiertem Textfeld öffnet M nicht; bei fokussierter Auswahlliste öffnet M die Karte, ohne einen Eintrag zu wählen.
• Beim Öffnen mit gehaltener W-Taste bleibt die Figur stehen, statt weiterzulaufen.
• Zoomen, Verschieben, Kartenrand.
• Klick auf eine Straße, auf ein Gebäude (Landung daneben) und mitten in die Bucht („Kein Landeplatz").
• Im Auto fahren und prüfen, dass Pfeil und Richtung mitfahren und das eigene Fahrzeug nicht doppelt erscheint.
• Mit absichtlich verändertem Manifest erscheint „Karte veraltet".

Nicht Teil dieses Entwurfs

• Die Feinkalibrierung selbst — wie Korrekturen je Chunk gespeichert und angewendet werden. Eigenes Teilsystem mit eigenem Entwurf; diese Spec liefert dafür nur die Namen, das Raster und die Koordinatenanzeige.
• Wahrzeichen auf der Karte (vom Nutzer abgewählt).
• Eine kleine Eckkarte.
• Pausieren des Spiels.
• Wegmarken und Routen.
• Bordstein, Gehweg und Rissrichtung — der anschließende Straßenbau. Kommen dort neue Flächen hinzu, zeichnet overview.py sie in einem eigenen Schritt nach.