metro-puzzle-jp/doc/roadmap.md

Roadmap och teknikval

Ordningen nedan är den ordning saker ska byggas i. Varje milstolpe är ett körbart, testat steg som går att visa upp. Teknikvalen står först eftersom de styr hur milstolparna byggs.

Teknikval

Område	Val	Varför
Språk	Go 1.27	En enda installation ger kompilator, pakethanterare, testramverk och formatterare. Snabba byggen. Björn använder redan Go i andra projekt.
Spelbibliotek	Ebitengine v2.10 (github.com/hajimehoshi/ebiten/v2)	Byggt för 2D-pixelspel: intern upplösning + heltalsskalning, nearest-neighbour-sampling, inbyggt ljud (OGG/WAV/MP3), tangentbord/gamepad/mus, textrendering med TTF. Ren Go på Windows → korsbygge från Linux utan C-verktyg.
Tester	Standardbiblioteket testing	Inget att installera. go test ./... kör allt.
Speldata	JSON i resources/data/	Läsbart, diffbart i git, encoding/json i standardbiblioteket. Byt till TOML bara om kommentarer blir ett verkligt behov.
Bygg	go run ./tools/build	Ett Go-program i stället för make/bash/PowerShell. Samma kommando på alla plattformar. Stämplar version och läge, kopierar resurser.
IDE	VS Code + tillägget golang.go	.vscode/tasks.json (bygg/test) och .vscode/launch.json (F5 med delve). Tillägget installerar delve åt dig.
Font	PixelMplus 10/12 px via ebiten/v2/text/v2	Pixelfont med kana och kanji (JIS 1+2), M+ FONT LICENSE. Valdes framför Misaki (8 px) för läsbarhetens skull – 10 px kanji går att läsa vid 3–4× skala.
Ljud	ebiten/v2/audio med OGG Vorbis (musik, jinglar) och WAV (korta effekter)	Ingår i Ebitengine, inga externa bibliotek.
Slump	math/rand/v2 (PCG) genom internal/rng	Seedbart, deterministiskt, del-seeds per kontext.
Sparfiler	JSON i os.UserConfigDir()/metro-puzzle-jp/	Rätt plats på både Linux (~/.config) och Windows (%AppData%).
Versionshantering	Git, lokalt nu, Gitea senare	Enligt playbooken; CI-release när projektet är redo att delas.

Varför inte …

• Godot: utmärkt för pixel art, men bygger inte "i VS Code" på samma sätt, kräver editor + exportmallar, och C#-spåret drar in .NET. Hade passat om kravet varit "snabbast till prototyp", inte "få byggverktyg".
• Rust + macroquad/Bevy: bra, men Windows-korsbygge kräver MinGW eller MSVC, och Bevy har långa byggtider. Rust-toolchain är en till sak att hålla i gång på två OS.
• C++ + raylib/SDL: CMake + kompilator per plattform, pakethantering för hand. Precis det "många byggverktyg"-problem vi vill undvika.
• Love2D (Lua): inget byggsteg alls, men distribution som en binär kräver att man "fuserar" ihop filer, och det saknas ett naturligt testramverk.

Regler för Windows-portabilitet (gäller från dag 1)

1. Bygg sökvägar med filepath.Join, aldrig med / i strängar.
2. Inga Linux-specifika syscalls eller /proc-läsningar. Behövs OS-specifik kod: lägg den i *_linux.go / *_windows.go.
3. Sparfiler och konfiguration via os.UserConfigDir(), aldrig ~ i strängar.
4. Resurser hittas relativt binären (internal/res), aldrig relativt arbetskatalogen i release.
5. Textfiler skrivs med \n; läsning tål \r\n.
6. Varje milstolpe avslutas med go run ./tools/build -mode release -os windows så att Windows-bygget aldrig hinner gå sönder obemärkt.
7. Inget cgo i vår egen kod.

Katalogstruktur

metro-puzzle-jp/
├── cmd/metro-puzzle-jp/   main.go – flaggor, fönster, startar spelet
├── internal/
│   ├── buildinfo/          version + läge (sätts av byggverktyget)
│   ├── res/                hittar och läser resources/ (ren Go)
│   ├── rng/                seedad slump (ren Go)
│   ├── level/              banformat, validering, BFS (ren Go)
│   ├── sim/                rutbaserad rörelse, kollision, kamera, banomgång (Run), sällskap (Party), dimma (Fog) – ren Go
│   ├── lang/               ordbok, tokenisering, kunskap, delvis översättning, engelska-andel, hjälptid – ren Go
│   ├── minigame/           påfyllning, biljettköp, trängsel, tågresa – seedade, ren Go
│   ├── progress/           XP, skillträd, items, banresultat, upplåsning – ren Go
│   ├── save/               sparfil: versionerad JSON, migrering, atomisk skrivning
│   ├── game/               Ebitengine-loop, scener, input, rendering, skriptläge  ← får använda Ebitengine
│   ├── archtest/           beroenderegler
│   └── …                   kommande: lang/, nav/, score/, save/, minigame/, ui/, audio/
├── tools/build/            byggverktyget
├── tools/genart/           genererar placeholder-grafik (tiles.png, player.png)
├── tools/shots/            tar dokumentationens skärmdumpar till doc/img/
├── resources/              kopieras bredvid binären vid bygge
│   ├── sprites/            bilder, tilesets, UI
│   ├── sound/              OGG/WAV
│   ├── text/               sv.json, en.json, jp-dictionary.json, fonts/PixelMplus*.ttf
│   └── data/               levels/, items.json, skills.json
├── doc/                    denna dokumentation (doc/img/ = skärmdumpar från tools/shots)
├── .gitea/workflows/       CI: test + release-zippar för linux/windows på brasse-linux01-runnern
├── .vscode/                tasks.json, launch.json
└── build/                  (gitignorerad) debug/ och release/<os>-<arch>/

Byggflöde

Vad	Kommando	Resultat
Debug (standard, Ctrl+Shift+B)	go run ./tools/build	build/debug/metro-puzzle-jp + resources/; inga optimeringar, full debuginfo
Debug med debugger (F5)	VS Code "Debug (dlv)"	Kompilerar och startar under delve med cwd = repots rot
Release Linux	go run ./tools/build -mode release -os linux -arch amd64	build/release/linux-amd64/ – strippad, -trimpath
Release Windows	go run ./tools/build -mode release -os windows -arch amd64	build/release/windows-amd64/metro-puzzle-jp.exe – GUI-subsystem, inget konsolfönster
Tester	go test ./...

Versionen i binären kommer från git describe --tags --always --dirty, så en tagg v0.1.0 ger metro-puzzle-jp v0.1.0 i -version.

Skärmdumpar till dokumentationen

README och wikin visar bilder från doc/img/. De tas av spelet självt i skriptläge så att de alltid är pixelexakta och går att återskapa:

go run ./tools/genart   # bara om placeholder-grafiken ska genereras om
go run ./tools/shots [ord…]   # bygger debug, kör spelet med -script, skriver doc/img/*.png (ord filtrerar på bana/skript)

Regel: när sprites, tileset eller UI ändras – kör tools/shots och committa doc/img/ i samma commit, så visar README och wiki alltid aktuell grafik. Nya vyer läggs till i listan i tools/shots/main.go.

Osynlig skärm: på Linux startar tools/shots en egen headless wlroots-kompositor (Wayfire med WLR_BACKENDS=headless och Xwayland) och kör spelet där, så att skärmdumparna varken syns eller tar fokus från det man själv gör på datorn. Bilderna är pixelidentiska med riktiga skärmen (mjukvarurendering, nearest-filter). METRO_HEADLESS=0 stänger av det; saknas wayfire används skärmen. Samma knep för manuella körningar: DISPLAY=:N WAYLAND_DISPLAY=wayland-N ./metro-puzzle-jp … mot en startad headless-instans.

CI

.gitea/workflows/release.yaml kör go vet + go test, bygger linux-amd64 och windows-amd64 och lägger zipparna på den rullande releasen latest (en tagg vX.Y.Z ger en versionerad release). Jobbet körs på brasse-linux01-runnern (label linux-amd64), aldrig på Pi5:n.

Milstolpar

M0 – Skelett och byggkedja ✓ (klar 2026-10-23)

• Repo, Go-modul, Ebitengine-fönster 320×180 med heltalsskalning.
• internal/res, internal/rng, internal/level med tester.
• Byggverktyg, VS Code-tasks och launch-konfigurationer.
• Första banan (001-flygplatsen) renderad som färgade rutor med placeholder-sprite.
• Verifierat: debug-bygge, Linux-release, Windows-korsbygge, smoke-test med fönster, alla tester gröna.

M1 – Rörelse, kollision och kamera ✓ (klar 2026-10-23)

• Mål: gå runt i en labyrint som är större än skärmen.
• Rutbaserad rörelse i 4 riktningar (pilar/WASD + gamepad d-pad/spak), mjukt interpolerad, riktningsbyte vid rutgränser; kollision mot väggar; kamera som följer spelaren och klampas till kartan (centrerar små kartor).
• Scen-system: meny (banlista) → bana → resultat (rätt/fel tåg, R = spela om).
• Tileset (tiles.png) och spelarsprite med gå-animation i fyra riktningar (player.png), genererade av tools/genart tills riktig pixel art finns.
• Större testbana 002-shinjuku (33×21 rutor) som bevisar kamerascrollen.
• Skriptläge (-script) och tools/shots som tar dokumentationens skärmdumpar deterministiskt.
• Teknik: internal/sim (Mover, Camera – ren Go med tester), internal/game (scener, input, assets), Ebitengine inpututil/vector.
• Avsteg: resultatskärmen visar redan rätt/fel tåg eftersom perrongen är det naturliga slutet på en bana; tidtabell, spärrar och väntan på tåg kommer i M2 som planerat.

M2 – Stationen: tåg, spärrar och vinst/förlust ✓ (klar 2026-10-23)

• Mål: bana 001 går att klara och misslyckas.
• Tåg med tidtabell per perrong (schedule: första ankomst, intervall, uppehåll). Tågvagnen ritas bortom perrongkanten när tåget är inne; HUD:en visar spår, linje, resmål och "avgår om / nästa tåg om".
• Ombordstigning är ett aktivt val: stå på perrongen och tryck Enter medan tåget är inne. Rätt tåg = vinst, fel tåg = förlust, resultatskärm med tid, steg, spärrpassager och kortsaldo.
• Spärrar kräver kort med saldo (startsaldo 2000 ¥, avgift per bana, dras när man går in i en spärr från en vanlig ruta). Tomt kort stoppas med meddelande. Riktig ekonomi och påfyllning kommer i M6.
• Skyltar har text (signs i bandatan, sv/en/ja) som visas när man står stilla på skyltrutan. Japanskan ritas först i M3.
• Regel för banor: alla perronger ska ligga innanför spärrar. level.UngatedPlatforms kontrolleras i det datadrivna testet; bana 001 byggdes om när regeln avslöjade två genvägar.
• Teknik: internal/sim.Run (klocka, kort, spärrlogik, ombordstigning – ren Go), level.Schedule, level.Path (BFS), skriptkommandot waittrain.
• Klar när: TestBotWinsLevel001 låter en bot gå kortaste vägen, passera spärren, vänta in tåget och kliva på – headless. ✓

M3 – Japanska och skyltsystemet ✓ (klar 2026-10-23)

• Mål: spelets identitet – skyltar på japanska som man lär sig läsa.
• Font: PixelMplus 10/12 px (M+ FONT LICENSE, i repot under resources/text/fonts/), ritad med text/v2 på heltalspositioner. All text i spelet går via den; debugfonten är borta.
• Ordbok (resources/text/jp-dictionary.json, 60 ord): japanska → kana, romaji, sv, en, tier. Ett test kräver att all japanska i banorna (skyltar, namn, resmål, linjer) finns i ordboken.
• Kunskapsmodell (lang.Knowledge): kända ord + kana-läsning. Nivå 0–5 = kända ord / 4. Kana låses upp efter tre kända kana-ord.
• Rendering (lang.Render): skylten tokeniseras med längsta matchning; kända ord markeras i gult i originalet och översätts i raden under, okända står kvar på japanska i grått, kana-ord som kan läsas men inte förstås visas som romaji i grönt. Avgångstavlan på perrongen är en skylt som alla andra.
• Engelska efter svårighet (lang.ShowEnglish): andel skyltar med engelsk rad 100/60/30/10/0 % för svårighet 1–5, deterministiskt per bana + position.
• Fråga någon om hjälp (H): tar lang.HelpSeconds(nivå) sekunder (6 s på nivå 0, ned till 2 s), avbryts om man går, avslöjar hela skylten och lär spelaren det första okända ordet på den. Notis "Nytt ord".
• Hintar efter nivå: från nivå 1 visar HUD:en resmålet på japanska (att matcha mot skyltarna), från nivå 2 visas läsningen efter kända ord.
• Kunskapen följer med mellan banor under en session (Game.Know); att spara den på disk är M8. Flaggorna -know ord,ord, -points N och -seed N ger förkunskap och determinism för tester och skärmdumpar.
• Inlärning utöver hjälp (Björns regler, tillägg samma dag):
  • Bra resultat lär ut resmålet. Vinst ger 1–3 stjärnor efter tid mot par (parSec i bandatan, annars kortaste vägen × 0,5 s + 20 s); från två stjärnor lärs resmålets ord in.
  • Läsning ger framsteg. Varje gång spelaren stannar på en skylt eller perrong har varje okänt ord 35 % chans (seedat per bana, skylt och besök) att få +1 framsteg; vid 3 framsteg kan man ordet.
  • Språkpoäng (1 per stjärna) läggs på valfria ord i ordlistan (L i menyn och på resultatskärmen): hela ordboken sorterad på tier, kända ord, framsteg och kostnad (= tier). Blir ett riktigt träd i M8.
• Teknik: internal/lang (ren Go, 11 tester + datatester), sim.Run (hjälp-tillstånd, avslöjade skyltar), internal/game/text.go (pixelbaserad radbrytning av färgade textsegment).
• Klar när: samma skylt visar olika mycket beroende på kunskap, och det är testat (TestRenderPartialTranslation, TestKanaReadingWithoutMeaning, TestAskHelpRevealsSignAndTeachesWord); bana 001 spelas med japanska skyltar. ✓

M4 – Lämmeltåget och mätarna ✓ (klar 2026-10-23)

• Mål: sällskapet följer med och ställer till det.
• Följare som går i rad efter spelaren längs ledarens spår (party i bandatan: 001 har två, 002 tre; max fem). Egna färgtoner tills de får egna sprites.
• Mätare mat/dryck/toa per person (100 → 0 på ~10/7/8 min). Under 25 uppstår ett behov av sig självt.
• Händelser var 45 s / antal i sällskapet (± 30 %), slumpade från omgångens seed: någon måste på toa, blir törstig, hungrig eller distraherad. Fler i lämmeltåget = oftare, testat.
• Behov saktar ned hela sällskapet (×0,8; distraktion ×0,5 i 4 s; tom mätare ×0,5) och syns som markering över huvudet och i HUD:en.
• Toalett (W, Enter: 3 s per person) och kiosk (K, Enter: 150 ¥ per person från kortet) återställer mätarna och tar bort behoven. Mätarpanel uppe till höger.
• Teknik: sim.Party (ren Go, 7 tester), sim.Run (fart, faciliteter), nya rutor W/K i level och tools/genart; banor med sällskap måste ha minst en toalett och en kiosk (testas).
• Klar när: fler i gruppen ger mätbart fler händelser i test (TestMoreMembersMoreEvents), händelser är seedade (TestEventsAreSeeded) och går att lösa i spelet (TestToiletAndKioskInRun). ✓
• Skjutet till M7: mätarnas värde vid målgång påverkar poängen; debuffar vid tomma mätare.

M5 – Minikarta och utforskning ✓ (klar 2026-10-24)

• Mål: orientering utan att avslöja labyrinten.
• Dimma (sim.Fog): när spelaren når en ruta avslöjas allt inom tre steg via passerbara rutor plus de väggar som gränsar till dem – man ser längs gången, inte genom väggen. Nollställs per omgång (ny Run).
• Riktmärken syns alltid: perrongerna (avgångarna), starten och spärrarna. Allt annat (kiosker, toaletter, skyltar, automater, gångar) ritas först när det setts.
• Minikartan ritas i ett hörn som varken täcker inforutan eller spelaren, 1–3 px per ruta beroende på banans storlek. Under kartan står en avgångslista per spår: 2 ●6s = tåget inne, avgår om 6 s; 1 ○14s = kommer om 14 s. Perrong med tåg inne lyser vit. Spelaren blinkar vit, följarna i sina färgtoner. M döljer/visar kartan.
• Resultatskärmen visar utforskad andel av banan (används av poängen i M7) samt antal försörjda i sällskapet.
• Teknik: sim.Fog (ren Go, 3 tester), internal/game/minimap.go.
• Klar när: upptäckta rutor markeras och nollställs per bana, avgångar syns från start – TestFogRevealsAlongCorridorsNotThroughWalls, TestLandmarksAlwaysVisible, TestFogGrowsWithMovementAndResetsPerRun. ✓

M6 – Kort, biljetter, telefon och minispel ✓ (klar 2026-10-24)

• Mål: resurshantering och de seedade minispelen.
• Plånbok (sim.Wallet, följer med mellan banor): IC-kort (2000 ¥), kontanter (5000 ¥), ev. pappersbiljett, kortet i telefonen + batteri, totalt spenderat (poäng i M7). Spärren drar från kortet; kiosken också.
• Påfyllning (automaten T): minispel – hitta チャージ bland japanska knappar i seedad ordning (fel knapp = straffsekund), välj belopp, håll Enter för att mata in sedlar. Kontanter → kort.
• Biljettbanor (ticketRequired, bana 002): spärren kräver pappersbiljett i stället för kort. Automaten visar en taxetavla med resmål på japanska i seedad ordning – köp rätt resmål kontant. Tåget släpper bara på den vars biljett gäller dit; biljetten förbrukas.
• Kortet i telefonen (P i menyn, -phone): fart ×1,1, men 15 % seedad chans per spärr att behöva skanna igen (1,5 s stillastående). Batteriet laddar ur på 15 min; dött = kortet oanvändbart → köp biljett.
• Fullt tåg (crowded, 002:s rätta tåg): tidsminispel – tryck Enter när markören är i den gröna zonen, två försök, annars går tåget (räknas som missat tåg, M7).
• Tågresan (alla banor): stationerna passerar med 次は-utrop; kliv av med Enter vid resmålet. Fel station eller att åka förbi förlorar banan; på fel tåg finns resmålet inte på linjen. Namnen renderas genom kunskapen, med romaji efter svårighetens engelska-andel. rideStops styr längden (3 standard, 002 har 4).
• Teknik: internal/minigame (ren Go, gemensamt Game-gränssnitt, all slump från del-seeds, 5 tester), sim.Run.StepMini (klockan och sällskapet tickar, rörelsen pausar), vyer i internal/game/minigame_view.go, skriptkommandon hold N och waitstop.
• Klar när: varje minispel är deterministiskt för en seed (test) och spelbart; TestTicketLevelFlow spelar hela 002 headless: fel biljett stoppas, rätt biljett, spärr, trängsel, resa, vinst. ✓

M7 – Svårighet, tid, poäng och debuffar ✓ (klar 2026-10-24)

• Mål: banor som kan misslyckas och poäng att jaga.
• Tidsgräns och maxantal missade tåg på svåra banor; lätta banor obegränsade.
• Poängformel: tid mot par, pengar spenderade, sällskapets mätare vid målgång, utforskat, avdrag för missade tåg och omskanningar; navigeringsläge ger multiplikator i M9.
• Stats (speed, törst, fokus, toalett, tur) som multiplikatorer och debuffar som påverkar dem: onda fötter (många steg), trötthet (lång bana), hunger/irritation (tom matmätare), matförgiftning (seedad chans vid kioskköp, snabbare toamätare). De temporära debuffarna från sidouppdrag (träningsvärk, skoskav, tungt köp, proppmätt, svettig) finns i systemet med varaktighet 1–4 banor; sidouppdragen som ger dem kommer i M10.
• Svårighetsinställningar per bana (Björns tillägg 2026-10-24):
  • Egna kort (individualCards): varje person i sällskapet har sitt eget tågkort; spärren kräver att alla har pengar, biljettbanor att alla har biljett. Påfyllningsautomaten frågar vems kort.
  • Sittplatsval (seatSelection, kräver biljettbana): efter resmålet väljer man platser i vagnen (fönster/gång, vänster/höger, bredvid någon) efter sällskapets seedade önskemål. Missnöjda i sällskapet blir sura: mätaravdrag och poängavdrag.
  • Våningar (floors) är också en svårighetsvariabel men byggs i M9a.
• Teknik: sim/stats.go (Stats, Debuff, Profile – ren Go), Run.Score(), level får maxMissedTrains, individualCards, seatSelection; minigame.TopUp får personval, minigame.Ticket får sittplatssteg.
• Poängformeln som byggdes: tid 500 × min(1, par/tid) + pengar (300 − spenderat/10) + mätare (200 × sällskapets medel) + utforskat (100 × andel) − avdrag (50/missat tåg, 10/omskanning, 30/missnöjd).
• Bana 003 Shibuya (svårighet 3, fyra i sällskapet): biljettbana med egna kort, sittplatsval, fullt tåg, fem stopp, 6 min tidsgräns, max ett missat tåg. Bana 002 fick tidsgräns, maxantal missade tåg och sittplatsval. Generatorn är nu spec-driven (JSON) så fler banor går fort.
• Klar när: poängformeln, tidsgränsen, debuffarna och de två inställningarna är testade (TestScoreBreakdown, TestTimeLimitAndMissedTrainsLose, TestDebuffsAffectRunAndAreEarned, TestIndividualCardsAtGateAndMachine, TestLevel003Flow, TestSeatSelectionPreferences); bana 003 använder dem. ✓

M7b – Tåg som kommer och går ✓ (klar 2026-10-24)

• Mål: tågen ska synas, höras och kännas – man ska förstå när de kommer och går, särskilt när missade tåg kostar (M7).
• Tågfaser ur tidtabellen (level.Schedule.Phase): på väg in (approaching, 5 s före), kör in (arriving, 1,5 s), står inne (dwelling, dörrar öppna), strax avgång (closing, sista 3 s, dörrsignal), kör ut (leaving, 1,5 s), borta. Man kan bara kliva på när dörrarna är öppna.
• Räls ritas längs perrongkanten (egen ruta i tools/genart); tågen rullar in längs rälsen i tre vagnar, står, och accelererar ut – inte "dyker upp/försvinner". Vägrutor för bussar kommer med bussarna (M10).
• Ankomstindikator nära rälsen: står man inom två rutor från perrongen när tåget är på väg in blinkar lampor vid kanten, strålkastare syns från det håll tåget kommer och inforutan säger "tåg på väg in".
• Vind: dammpartiklar längs perrongen när tåget kör in och ut.
• Ljud: ljudsystemet (ebiten/v2/audio) införs här med två placeholder- jinglar genererade av tools/gensound (pentatonisk avgångsmelodi när tåget är på väg in, dörrsignal strax före avgång), med volym efter avstånd till perrongen och -mute. Riktiga inspelningar/kompositioner i M12.
• Teknik: faser i level (ren Go, testade), sim.Run.NearTrack, partiklar/tweening/ljud i internal/game, skriptkommandot waitphase.
• Klar när: faserna beräknas rätt ur tidtabellen (testat: TestSchedulePhases, TestNearTrackAndPhases), indikatorn syns bara nära rälsen, tåget rullar in/ut och melodierna spelas i rätt fas. ✓
• Konsekvens för banorna: uppehållet måste vara minst 5,5 s och tiden borta minst 7,5 s (valideras), så att faserna får plats.

M8 – Progression, items och sparfiler ✓ (klar 2026-10-24)

• Mål: något att låsa upp och en anledning att fortsätta.
• XP och nivåer: en klarad bana ger poäng/10 + 25 × stjärnor XP; nivå n+1 nås vid 150·n(n+1)/2 XP (150, 450, 900 …). Varje level-up ger en skillpoäng.
• Skillträd (resources/data/skills.json, 12 noder i fyra grenar: språk, kropp, resenär, utforskare): kana, fokus, hjälp, fart, törst, toa, tur, sikt, landmärken. Krav och kostnad valideras; effekterna är stats-multiplikatorer plus flaggor. Språkpoängen på ord (M3) finns kvar som egen valuta.
• Items (resources/data/items.json, 25 st: hattar, masker, kläder, skor, prylar, skins) med buffar, färgton på spelaren och genvägar: JR Pass (gratis spärrar), kartor (hela minikartan på en bana), powerbank (oändligt batteri). Ett item per plats (huvud, ansikte, kropp, fötter, väska). Köps kontant i kioskens butik (B) – banans sortiment eller ett seedat urval. Designregeln "knappt 33 % per omgång" är ett test: billigaste tredjedelen kostar mer än startkassan.
• Bankartan i spelbrädesstil ersätter menyn: huvudbanorna på en linje, sidospår ovanför, låsta grå, klarade med stjärnor; nästa huvudbana öppnas när föregående är klarad, sidospår när föräldern är. Ny sidobana 002b Kabukicho belönar skinnet Kimono och en skillpoäng.
• Sparfil (internal/save): versionerad JSON med kunskap, plånbok, debuffar, progression och pågående bana + seed, atomisk skrivning, migrering av äldre filer. ~/.config/metro-puzzle-jp/save.json på Linux, %AppData% på Windows. Autospar vid banstart (seeden), efter banan och vid köp/upplåsningar. ⟳ på kartan betyder att banan återupptas med samma slump. Flaggor -save PATH, -nosave.
• Teknik: internal/progress (ren Go, 6 tester), internal/save (3 tester), sim.RunOptions får Extra/FogRadius/Landmarks/FreeGates/ RevealAll/InfiniteBattery, luck påverkar trängselzonen, nya scener karta/skills/garderob och butiken i internal/game.
• Klar när: sparfil round-trip-test grön; "< 33 %" kontrolleras mot itemlistan; skillkrav, upplåsningar och belöningar testade. ✓

M9a – Flera våningar ✓ (klar 2026-10-24)

• Mål: stationer i flera plan – ännu en svårighetsvariabel.
• Banformat: floors: [{name, grid}, …] med lika stora rutnät; gamla banor med grid läses som en våning ("1F"). Rutkoordinaten Point fick Z. Trappor är rutor: U (upp) på en våning kräver D (ner) på samma x,y en våning upp och tvärtom (valideras). Går man in på en trappa hamnar man i andra änden i samma steg. Skyltar har z.
• Logik: Neighbors ger grannarna inkl. trappans andra ände, så Path, lösbarhetstestet, spärregeln och Unreachable fungerar över våningar. Dimman är per våning och avslöjar trappans andra ände. Man ser/hör bara tågen på sin egen våning.
• Spel: bara spelarens våning ritas (följare på andra våningar syns inte förrän de kommer upp), HUD och minikartan visar våningens namn, trappor har egen grafik och färg på minikartan.
• Bana 004 Tokyo (svårighet 3, tre i sällskapet): start under mark på B1 (Marunouchi-linjen), trappan upp till 1F där perronger, spärrar, automat, kiosk och toalett finns. Generatorn gör våningar: labyrint per våning, trappor på gemensamma öppna rutor nära mitten, start på en våning och perronger på en annan.
• Teknik: level (Storey, Point.Z, Neighbors, FloorAt), sim.Run (trappbyte, FloorChanges), sim.Fog 3D, spelet ritar per våning; testbotarna och tools/shots förstår trappor.
• Klar när: en bana med två våningar går att klara av boten headless (TestStairsMoveBetweenFloors, TestFloorsStairsAndPaths), minikartan visar rätt våning, och alla gamla banor fungerar oförändrat (en våning). ✓

M9b – Folk, reklam och ljudröra ✓ (klar 2026-10-24)

• Mål: stationen lever och överstimulerar – tre nya svårighetsvariabler.
• Folk (NPC:er): passagerare som går på och av tågen när dörrarna är öppna, rör sig mellan kiosker, toaletter och utgångar, och in och ut från stationen. De tar plats i rutnätet: man måste runda dem, och att gå in i någon saktar ned (crowd-nivå per bana styr hur många).
• Vänster-/högertrafik: gångar och trappor kan markeras med en sida (pilar i golvet); går man på fel sida möter man strömmen och bromsas.
• Bredare gångar: generatorn kan göra gångar två rutor breda där det ska gå att passera folk; följarna går då i bredd när det får plats.
• Visuell röra (clutter-nivå): dekorationslager med reklam, affischer och blinkande skyltar på väggarna, lockskyltar som liknar riktiga.
• Ljudröra (noise-nivå): japanskt prat, utrop och reklam i bakgrunden som konkurrerar med melodierna; på de svåraste nivåerna överlappar de.
• Vagnar (Björns tillägg 2026-10-24): tåg har cars vagnar; när tåget står inne väljer man vagn på perrongen (kömarkeringar visar var man ställer sig). Folk kliver av först – trycker man för tidigt blir det avdrag. Varje vagn har en seedad trängselnivå (lite/mellan/mycket): lite folk ger poängbonus, mycket folk gör trängselminispelet och resan svårare (kortare tid per station, passagerare som måste släppas förbi vid stationer där man inte ska av) och kan ge debuffen svettig. Kvinnovagn (womenOnlyCar, ev. bara mellan vissa klockslag som står på skyltarna) markeras rosa; har sällskapet en man och går på den blir det grova minus. Sällskapets medlemmar får därför kön.
• Teknik: sim.NPC med enkla mål och BFS-vägar (ren Go, seedade), minigame.CarPick, trängsel i Crowd/Ride, dekorationslager (seedade affischer) och clutter/noise/crowd i banformatet, tools/genart för folk/affischer/vagnmarkeringar, tools/gensound för bakgrundsprat; generatorn får breda gångar med filer.
• Så blev det: sim.NPC (vandrare mellan kiosker/toaletter/skyltar/ perronger med BFS-vägar och seedade pauser; avstigande som kliver av när dörrarna öppnas och går till utgången) tar plats i rutnätet – spelaren stoppas ("Ursäkta…"), folket går igenom varandra så inget låser sig. Filer </> i breda gångar: fel sida ger ×0,7 fart. clutter ger seedade affischer på väggar intill gångar (tre varianter, en liknar en skylt); noise ger loopat bakgrundsprat (chatter.wav) som dämpar melodierna. Vagnval (minigame.CarPick): folk kliver av i 1,5 s (Enter för tidigt = avdrag), vagnarna visas med trängselfigurer och kömarkeringar, kvinnovagn rosa med 女性専用; lugn vagn +50, full vagn ger trängselminispel med smalare zon, kortare tid per station och passagerare som ska släppas förbi (← ), samt 60 % risk för svettig. Man i sällskapet på kvinnovagnen: −200. Sällskapet har kön (Anna/Sara kvinnor, Ville/Omar män, spelaren okänd). Bana 005 Ueno (svårighet 4): breda gångar med filer, folk 2, röra 2, ljud 2, fyra vagnar där vagn 1 är kvinnovagn de första 2,5 minuterna.
• Klar när: NPC:er rör sig på golv, är seedade och blockerar spelaren (TestNPCsWanderStayOnFloorAndBlockPlayer), avstigande kommer och går (TestAlightingNPCsSpawnAndLeave), filer bromsar (TestLanesSlowWrongSide), vagnval/kvinnovagn/trängsel/avdrag (TestCarsWomenOnlyEarlyAndCrowd, TestCarPickAlightingAndChoice, TestRideCrowdLetPass). ✓
• Kvar till senare: NPC:er som väntar på och kliver på tåget, folk som bildar riktiga köer vid markeringarna, utrop/reklam som ljud (M12).

M9 – Navigeringslägen: lista och skyltläge ✓ (klar 2026-10-24)

• Mål: de två sätten att spela story.
• Listläge: nästa tåg visas.
• Skyltläge: 1–4 giltiga vägar, mer poäng, förlust om man åker i fel riktning / för långt bort.
• Teknik: internal/nav (graf över stationer/linjer, giltiga vägar, riktningskontroll – ren Go).
• Så blev det: internal/nav läser resources/data/network.json (76 stationer, 11 linjer: Yamanote som ringlinje, Chuo, Keihin-Tohoku, Saikyo, Marunouchi, Hibiya, Ginza, Toyoko, Tokaido, Narita Express, Keisei). Ett tåg bedöms från lineId + terminus (en station i färdriktningen) mot banans station/to: Direct (resmålet inom 12 stationer), WrongDirection (linjen går dit, men åt andra hållet), TooFar (nås först efter fler än 12 stationer – fel varv på ringen, omvägen via city) eller NoService. correct skrivs inte längre i nätkopplade banfiler utan räknas ut; 1–4 rätta tåg per bana. Tågresan visar linjens riktiga stationer i färdriktningen (resmålet på rätt plats, eller aldrig). Förlustorsakerna Fel håll och För långt bort förklarar vad som hände. Listläge visar "Ta: spår 6 Yamanote-sen (+1)" i HUD:en; skyltläge visar bara att man är i det och ger +50 % på grundpoängen. Läget växlas med N på bankartan och sparas. Terminalen: på nätkopplade banor visar biljettautomaten linjetavlan (varje linje med tre grannstationer åt vardera hållet), läst genom ens kunskap som en skylt. Perrongtecknen generaliserade (P p Q q R r). Bana 006 Ikebukuro (svårighet 4): fyra perronger – Yamanote mot Shinjuku och Saikyo mot Osaki är rätt, Saikyo mot Omiya är fel håll och Marunouchi mot Ogikubo för långt bort. Banorna 001–005 är kopplade till nätet (Keihin-Tohoku mot Omiya i Ueno blev därmed fel håll).
• Klar när: bedömningarna och vägarna är testade (nav.TestJudge, TestTooFarOnLongLoop, TestStopsRoutesAndNames, TestShippedNetwork), banor kopplas rätt (level.TestAnnotateWithNetwork, TestPlatformTilesAndShippedVerdicts), resan använder riktiga stationer och fel håll/för långt förlorar (sim.TestNetworkRideUsesRealStops, TestWrongDirectionLoses, TestTooFarLoses), skyltläget ger bonus (TestSignsModeBonus) och terminalen listar linjer (TestTerminalLines). ✓
• Kvar till senare: flera tåg i rad (byten) kommer med M10; bussar; "terminaler" som egna rutor i stället för biljettautomaten.

M10 – Story-innehåll och flerbytesbanor ✓ (klar 2026-10-24)

• Mål: hela resan från flygplats till flygplats.
• Alla huvudbanor och sidobanor; banor med flera stopp och byten; buss (med vägrutor och hållplatser); stationer i flera våningar (M9a), folk och röra (M9b) och svårighetsinställningarna från M7 i stigande kombinationer.
• Slutanimation (karaktärerna flyger iväg, items och poäng visas) och eftertexter.
• Överstimulerande UI/banor som extra svårighet.
• Teknik: baneditor-stöd behövs troligen här: ett tools/levelcheck som ritar banan som bild och rapporterar onåbara rutor.
• Så blev det: Byten är kedjor av banfiler: en huvudbana har next som pekar på en delbana (kind: "leg", syns inte på bankartan), som i sin tur kan ha next. När man klivit av rätt tåg fortsätter samma omgång på nästa station: klockan, plånboken, sällskapets mätare och räknarna följer med, par-tiden adderas, dimma och folk är nya, och en "Byte!"- banner visas. HUD:en visar resans slutmål "via" delbanans mål och "1/2". Tidsgräns och missade tåg gäller hela resan (första banans värden). level.ValidateChains kräver att delbanor används exakt en gång, att inga cykler finns och att nästa delbana börjar där den förra slutade (nätets stationer). Två nya resor: 007 Akihabara → Ueno (Hibiya eller Yamanote) → Asakusa (Ginza), med fel-håll- och fel-varv-fällor, egna kort och folk; 008 Tokyo (två våningar) → Nippori (Yamanote eller Keihin-Tohoku) → Narita flygplats (Keisei, biljetter med sittplatsval) – storyns final. Slutet: när sista huvudbanan klaras första gången visas hemresan (EndingScene): planet lyfter över skymningshimlen medan sällskapet vinkar, resan summeras (banor, stjärnor, poäng, ord, souvenirer) och eftertexterna rullar; Progress.StoryCleared sparas (M11 låser upp oändligt läge/NG+ på den). -ending öppnar scenen direkt. tools/levelcheck ritar varje våning som PNG (onåbara rutor röda, rätt perrong grönkantad, kortaste vägen prickad) och rapporterar lösbarhet, onåbara rutor, perronger utanför spärrar, tågens bedömning och resornas kedjor; go run ./tools/levelcheck [ord…] → build/levelcheck/. Generatorn fick platforms (fler perronger) utöver floors/wide.
• Klar när: kedjorna valideras och storyn börjar/slutar på flygplatsen (level.TestStoryChains), bytet för med sig tid/plånbok/sällskap och vinner först på sista delbanan (sim.TestJourneyWithTransfer), fel tåg på bytesstationen förlorar (TestJourneyWrongTrainOnSecondLeg), delbanor laddas (TestChainLevelsLoad), alla banor passerar levelcheck. ✓
• Kvar till M10b: bussar och vägrutor, fler sidobanor, överstimulerande UI som eget svårighetsreglage.

M10b – Bussar, vägar och fler sidospår

• Mål: resten av M10-listan som inte rymdes: buss med vägrutor och hållplatser (egen fordonssprite, hållplatsskylt, tidtabell som tågen), fler sidobanor längs storyn (minst en per stad), och ett "överstimulerande UI"-reglage (fler lockskyltar, blinkande reklam, falska avgångstavlor) som kan slås på per bana.
• Teknik: vägrutor i banformatet, Vehicle-abstraktion i sim som tåg och buss delar, återanvänd nav för busslinjer.

M10c – Vem betalar, och spärrar utan återvändo ✓ (klar 2026-10-24)

• Mål: två av Björns tillägg (2026-10-24) som gör kort- och spärrhanteringen mer strategisk.
• Vem betalar: med fler än en i följet och egna kort väljer man vid kiosken/automaten vem som betalar – kontant, spelarens kort eller någon följares kort – så att alla har kvar pengar till spärrarna. Ett litet väljarminispel (minigame.Payer) framför köpet; de som inte har råd markeras.
• Spärrar utan återvändo: banflaggan oneWayGates. När man har checkat in i spärren släpper den inte ut en igen förrän man åkt. Måste man ut (toalett, kiosk, automat utanför) kallar man på personal med Enter vid spärren (knappen sitter vid spärren – ett kontor kan komma senare); det tar tid, sedan är korten upplåsta och man kan gå ut. Går man in igen dras avgiften igen.
• Teknik: level.InsideGates (rutorna innanför spärrarna, BFS från perrongerna), Run.checkedIn/StaffUnlocked/Staff-tillstånd i sim, prompt och förlopp i inforutan, skriptkommandot urge för skärmdumpar.
• Så blev det: minigame.Payer (kontant / spelarens kort / varje följares kort med saldo; de som inte har råd i rött och nekas; Esc avbryter köpet) öppnas av kiosken när banan har egna kort och fler i sällskapet. Spärrregeln ändrades samtidigt: avgiften dras när man passerar spärren in i det betalda området (level.InsideGates, rutorna som nås från perrongerna utan att korsa en spärr), inte när man står på spärrrutan – så spärrar som ligger i en gång kostar inget att passera utifrån. Med oneWayGates blir man incheckad vid betalningen; en spärr man nått inifrån släpper inte ut en (meddelande i inforutan), Enter på spärren kallar på personal (10 s, förloppsstapel, avbryts om man går), sedan är korten upplåsta tills man gått ut; ny inpassering kostar igen. Flaggan är på i 005 Ueno, 007/007b och 008/008b. Skriptkommandona urge NAMN och push RIKTNING N för skärmdumparna.
• Klar när: väljaren betalar från rätt källa och nekar den som inte har råd (minigame.TestPayerPicksSourceAndRefusesPoor, sim.TestKioskAsksWhoPays); spärren släpper inte ut en, personalen låser upp efter väntetiden och ny inpassering kostar igen (sim.TestOneWayGatesNeedStaff, level.TestOneWayGatesAndInside). ✓
• Kvar till senare: ett kontor (egen ruta) som alternativ till knappen vid spärren; personal som också kan hjälpa med tomt kort.

M10d – Toaletter innanför och utanför spärrarna ✓ (klar 2026-10-24)

• Mål: Björns tillägg 2026-10-24: toaletter finns ibland bara innanför spärrarna, ibland bara utanför, ibland på båda sidor – så att man måste tänka på när sällskapet går på toa, särskilt där spärren inte släpper ut en (M10c).
• Teknik: generatorn får ett betalt område (paidDepth: hur många steg från perrongen spärrarna sätts) och toilets: inside|outside|both som fäster en toalettnisch i en vägg innanför spärrarna och/eller lägger en i en återvändsgränd utanför. tools/levelcheck rapporterar var toaletterna ligger. Banorna 005 Ueno (bara innanför), 007b Ueno (båda) och 008b Nippori (bara innanför) görs om; 007 och 008 har bara utanför.
• Så blev det: generatorn räknar ett betalt område med BFS från perrongerna (paidDepth steg) och sätter spärrar på alla öppna rutor precis utanför; toilets: inside fäster en toalettnisch i en vägg intill en betald ruta (där rutan bortom också är vägg, så inget nytt öppnas), both lägger dessutom en i en återvändsgränd utanför, automat och kiosk ligger alltid utanför. 005 Ueno (betalt område 12 rutor, toalett bara innanför), 007b Ueno (22 rutor, båda) och 008b Nippori (16 rutor, bara innanför) är omgjorda; 007 och 008 har bara utanför. tools/levelcheck rapporterar betalt område och toaletter per sida. Perrongerna är nu återvändsgränder: generatorn behåller bara passagen mot starten in till perrongens cell (rum i den breda labyrinten), murar igen de andra och reparerar labyrinten med nya passager där den annars delas; det betalda området krymper automatiskt om det skulle bli en genomfart. Regeln "varje perrong nås utan att gå genom en annan perrongs betalda område" testas (level.PathOutside, i TestAllShippedLevels och levelcheck) – annars skulle spärrar utan återvändo göra fällperrongerna onåbara. Alla genererade banor utom 003 (som redan klarade regeln) gjordes om.
• Klar när: banorna har toaletter på rätt sida (level.TestToiletSides), spärrtestet fungerar med ett större betalt område (sim.TestOneWayGatesNeedStaff går vägen till första spärren i stället för ett fast steg), och levelcheck är grön. ✓

M13 – Titelskärm, tutorial och trygghet ✓ (klar 2026-10-25)

• Mål: Björns feedback efter v0.1.0 (2026-10-25): spelet ska gå att förstå och använda utan att läsa dokumentationen.
• Titelskärm som beskriver premissen i text, med Fortsätt/Starta, Tutorial, Inställningar och Avsluta (ett sätt att stänga spelet inifrån). Första gången spelet startar får man välja språk.
• Tutorial om grundmekaniken: målet, skyltarna, kort/biljetter/spärrar, sällskapet, tåget, lägena och tangenterna. Tips och trix: hur man läser en skylt och vad man ska memorera (resmålets tecken i HUD:en) för att köpa rätt biljett – med resmålet markerat och all annan text nedtonad. Dessutom kontextuella tips i spelet tills första banan är klarad, och samma markering på riktiga skyltar under tiden.
• Esc-skydd: Esc i en bana öppnar en pausmeny (Fortsätt, Lämna banan, Inställningar, Avsluta spelet) i stället för att lämna banan direkt; många Esc i rad växlar bara menyn. Esc på bankartan går till titelskärmen; Avsluta kräver Enter två gånger.
• Karttexten får plats på bredden på svenska (kortare lägestexter).
• Teknik: TitleScene, LangScene, PauseScene, TutorialScene, tips.go, highlightLine i text.go.
• Så blev det: TitleScene (premiss, rullande tåg på räls, meny Fortsätt/Starta – Tutorial – Inställningar – Avsluta med Enter två gånger, version), LangScene första gången sparfilen saknas (svenska/ engelska), PauseScene på Esc i banan (Fortsätt, Lämna banan, Inställningar, Avsluta spelet; Esc igen fortsätter – många Esc i rad växlar bara menyn), Esc på bankartan går till titeln. TutorialScene i fem sidor med riktiga sprites och en exempelskylt där resmålet är markerat och resten nedtonad (highlightLine), plus 番線/方面/ 改札-nyckeln och biljettipset. I spelet visas fem kontextuella tips (start, första skylten, sällskapets behov, spärren, perrongen) tills bana 001 är klarad, och under tiden markeras resmålets tecken på skyltar och avgångstavlor. Lägestexterna på bankartan kortades så att raderna ryms.
• Klar när: titel, språkval, pausmeny och tutorial finns med skärmdumpar; markeringen är testad (game.TestHighlightDestination); karttexterna ryms (skärmdump). ✓
• Kvar till senare: en spelbar tutorialbana med styrda steg, tips som kan slås av i inställningarna.

M11 – Oändligt läge och New Game+ ✓ (klar 2026-10-24)

• Slumpade mål från seed, poäng per mål, egen poänglista. NG+ behåller skills.
• Låses upp när storyn är klar.
• Så blev det: internal/endless lottar mål ur en seed: stationen är en av storyns nätkopplade banor (alla huvud-, sido- och delbanor, aldrig samma två gånger i rad) och resmålet lottas bland stationer som minst ett av banans tåg går rakt till men inte alla – samma labyrint och samma tåg, men vilket tåg som är rätt beror på resmålet. Banan kopieras, får nytt to/destination, inga byten, sällskap som växer med en person var tredje mål (max 5) och en tidsgräns som krymper 5 % per mål (golv 180 s), och bedöms om mot nätet. Samma seed ger samma följd. Omgången: O på bankartan (efter storyn) eller -endless; HUD:en visar "#3 Ueno station"; klarat mål ger poäng (summeras) och XP, Enter ger nästa mål; förlust (eller Esc) avslutar omgången som hamnar i poänglistan (fem bästa i sparfilen, "Ny bästa!" när toppen slås). New Game+: G två gånger på bankartan: banresultat, items, utrustning, pengar och debuffar nollställs, skills, XP och språkkunskap behålls, och sällskapet är en person större på alla banor per NG+-varv (RunOptions.ExtraParty).
• Klar när: målföljden är deterministisk per seed och giltig (endless.TestPlanIsDeterministicAndValid, TestDestinationsNeedTrapAndRoute), NG+ behåller skills men nollställer items (progress.TestNewGamePlusKeepsSkillsResetsItems), poänglistan sorterar och kapar (save.TestEndlessRecords). ✓
• Kvar till senare: oändligt läge med byten (resor över två stationer), stationer som genereras vid körning (generatorn in i repot).

M12 – Ljud, polish och release ✓ (klar 2026-10-25)

• Riktiga avgångsmelodier/ankomstjinglar (ersätter placeholders från M7b), utrop, effekter, musik; mixning och volyminställningar.
• Inställningar (ljudnivåer, språk sv/en, skala, tangenter).
• Windows-test på riktig maskin, ikon i exe:n, eventuell Gitea-CI med releaser enligt playbooken.
• Så blev det: tools/gensound syntetiserar 21 ljud (egna kompositioner, deterministiska): fyra stationsmelodier i klockklang (melody-a–d, banans melody-fält eller vald efter id), ankomstjingel, ding-dong vid inrullning, dörrsignal vid avgång, spärrens pip/nekande, kiosk, toalett, lärt ord, bekräfta/varning, byte, personal, vinst, förlust, flygplan, sorl och en menymusikslinga. internal/game/sfx.go spelar effekterna utifrån vad som hänt i sim.Run sedan förra bildrutan (räknare och tidsstämplar), tågfaserna i trains.go. Ljudlagret har tre volymer (huvud × effekter resp. musik/sorl) och byter inte slinga i onödan (menymusiken fortsätter mellan karta, inställningar och listor). Inställningar (S på bankartan, sparas i sparfilen): volymer, språk sv/en (texterna laddas om direkt), fönsterskala 1–6 (0 = flaggan -scale), fullskärm (även F11 överallt), plus en tangentöversikt. Fönsterikon (icon.png från genart) sätts vid start. Release: CHANGELOG.md och taggen v0.1.0 → versionerad release på Gitea (CI:n bygger redan Linux och Windows). Windows-testet på riktig maskin och ikon inbakad i exe:n (.syso) är kvar att göra manuellt.
• Klar när: alla ljud finns och avkodas (game.TestAllSoundsDecode), stationsmelodin är stabil per bana (TestMelodyForIsStableAndKnown), inställningar får standardvärden och normaliseras (save.TestSettingsDefaultsAndNormalize), melody-fältet valideras. ✓
• Kvar till senare: ikon i exe:n (.syso), omdefinierbara tangenter, riktiga inspelningar, Windows-test på riktig maskin (Björn).

Prioritering

• Måste för ett spelbart spel: M1–M3, M6 (åtminstone kort/spärr), M7.
• Gör spelet till det här spelet: M3, M4, M9.
• Kan skjutas utan att något går sönder: M5, M11, delar av M8 (skill tree), överstimulerande UI i M10.
• Windows-bygget körs vid varje milstolpe men testas på riktig Windows först i M12.