Table of Contents

Metro Puzzle JP – wiki

Så fungerar spelet (läget efter M10b)

Uppdatera bilderna

Arkitektur i korthet
Designbeslut
Bygg och release
Status

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.

Metro Puzzle JP – wiki

Bygginstruktioner, flaggor, styrning, verktyg och beroenden finns på Bygga och verktyg. Den här sidan beskriver spelet.

Pixel art-pusselspel: led lämmeltåget (ditt sällskap) genom japanska tågstationer byggda som labyrinter, läs skyltarna, hitta rätt tåg och kom fram till rätt resmål.

Den detaljerade dokumentationen ligger i repot och är alltid sanningen:

Fil i repot	Innehåll
`README.md`	Bygga, köra, testa, beroenden per OS
`doc/plan.md`	Navet: mål, stack, milstolpar, öppna frågor
`doc/spelbeskrivning.md`	Hela speldesignen, renskriven
`doc/roadmap.md`	Teknikval, katalogstruktur, milstolpar M0–M12
`doc/mal-och-tester.md`	Projektmål, teststrategi, checklistor

Så fungerar spelet (läget efter M10b)

Titelskärmen beskriver premissen och har Fortsätt/Starta, Tutorial, Inställningar och Avsluta (Enter två gånger). Första gången spelet startar väljer du språk. Tutorialen går igenom målet och stationen, hur man läser en skylt (resmålets tecken markerade, resten nedtonad, 番線 = spår, 方面 = mot, 改札 = spärr), kort/biljetter/spärrar, sällskapet och tåget, lägen och tangenter. I första banan dyker dessutom tips upp när du behöver dem, och resmålets tecken markeras på skyltarna tills banan är klarad. Esc i en bana öppnar pausmenyn (Fortsätt, Lämna banan, Inställningar, Avsluta) så att inget lämnas av misstag.

Bankartan är ett spelbräde: huvudbanorna på en linje från flygplatsen, sidospåren som avstickare ovanför. Låsta banor är grå, klarade visar sina stjärnor. Nästa huvudbana öppnas när föregående är klarad, sidospår när föräldern är det. ⟳ betyder att banan återupptas med samma seed som när du slutade. Pilar väljer, Enter startar; L ordlistan, T skillträdet, I garderoben, P telefonen.

I banan startar du på den gröna dörrmattan. Stationen är en labyrint: mörka väggar, ljust golv, skyltar (blå tavla på stolpe), biljettautomat (låda med cyan skärm) och spärrar (stolpar med grön lampa). Rörelsen är rutbaserad – en ruta i taget, mjukt animerad, och riktning byts vid rutgränser. HUD:en visar bana, resmål, tid och antal steg.

Större stationer scrollar: kameran följer dig och stannar vid kartans kanter. Bana 002 (Shinjuku, 33×21 rutor) finns för att testa just det.

Skyltar visar sin text när du står stilla på skyltrutan – på japanska. Ord du kan lyser gult i originalet och översätts i raden under; okända ord står kvar i grått. På lätta banor finns en engelsk rad (cyan) på alla skyltar, på svårare banor på allt färre, på de svåraste inga alls.

Fråga någon om hjälp med H. En förbipasserande förklarar skylten – det tar några sekunder (kortare ju bättre din japanska är), och går du därifrån avbryts det.

När hjälpen är klar är hela skylten översatt och du har lärt dig ett nytt ord. Lär du dig fyra ord når du nivå 1, och då visar HUD:en resmålet även på japanska (新宿) så att du kan matcha tecknen mot skyltarna. Från nivå 2 visas läsningen efter kända ord. Kunskapen följer med mellan banorna.

Fler sätt att lära sig ord. Varje gång du stannar på en skylt eller perrong har varje okänt ord en chans att ge ett framsteg ("Framsteg: 京成線 1/3"); vid tre framsteg kan du ordet. Klarar du en bana under par får du tre stjärnor, och från två stjärnor lär du dig resmålets namn. Varje stjärna ger en språkpoäng som du lägger på valfria ord i ordlistan (L): hela ordboken sorterad på hur vanliga orden är, med kända ord, framsteg och kostnad.

Lämmeltåget. Dina polare följer efter dig i en rad. Var och en har mätare för mat, dryck och toa (panelen uppe till höger). Mätarna sjunker med tiden, och med jämna mellanrum händer något: någon måste på toa, blir törstig, hungrig eller distraherad av en butik. Ju fler ni är, desto oftare. Ett behov saktar ned hela sällskapet och visas över huvudet på den det gäller. Toaletten (vit dörr, W) tar några sekunder per person; kiosken (randig markis, K) kostar 150 yen per person från kortet. Händelserna är slumpade från omgångens seed, så en sparad omgång ger samma händelser.

Minikartan i hörnet visar från början bara det man kan orientera sig efter: perrongerna (gula; vita när tåget står inne), starten (grön) och spärrarna (cyan), plus en avgångslista per spår – 2 ●6s betyder att tåget på spår 2 står inne och går om sex sekunder, 1 ○14s att nästa tåg på spår 1 kommer om fjorton. Allt annat fylls i när du går förbi: du ser tre steg längs gångarna, inte genom väggarna. Kartan nollställs för varje bana och omgång, flyttar sig till ett hörn som inte täcker dig eller inforutan, och M döljer den.

Spärrarna (stolpar med grön lampa) släpper bara igenom dig om tågkortet har saldo. Avgiften dras när du går in i spärren; HUD:en visar saldot. Alla perronger ligger innanför spärrar – det är en regel som testerna kontrollerar för varje bana.

Perrongen (gul ledlinje längs kanten) har ett tåg med tidtabell och räls bortom kanten. Fem sekunder innan tåget kommer spelar avgångsmelodin, lamporna vid kanten blinkar för den som står nära och strålkastarna syns i tunneln. Tåget rullar in i tre vagnar, står med öppna dörrar, dörrsignalen ljuder de sista sekunderna och sedan accelererar det ut – med damm som blåser längs perrongen. Avgångstavlan är en skylt som alla andra – japansk, sedd genom din kunskap – och säger om tåget är inne ("Avgår om"), på väg ("Tåget kör in om") eller borta ("Nästa tåg om"). Du kliver på med Enter medan dörrarna är öppna.

På tåget passerar stationerna en i taget med 次は-utrop. Kliv av med Enter vid ditt resmål – namnen är på japanska och renderas genom din kunskap, så HUD-hinten med resmålets tecken (nivå 1) är guld värd. Kliver du av fel eller åker förbi är banan förlorad, och på fel tåg finns resmålet inte ens på linjen.

Pengarna. Du har ett IC-kort och kontanter. Spärren och kiosken drar från kortet. Tar det slut går du till automaten (T) och fyller på: hitta チャージ bland knapparna (fel knapp kostar en straffsekund), välj belopp och håll Enter för att mata in sedlarna.

På svårare banor kräver spärren en pappersbiljett i stället. Automaten visar en taxetavla med resmål på japanska – köp rätt resmål, annars släpper inte tåget på dig. Lägger du kortet i telefonen (P i menyn) går du snabbare, men ibland måste du skanna igen i spärren, och dör batteriet måste du köpa biljett.

Fulla tåg kräver att du tränger dig på: tryck Enter när markören är i det gröna fältet. Två bom och tåget går utan dig.

Svårigheten ställs per bana. Svåra banor har tidsgräns och ett maxantal missade tåg. Med egna kort har alla i sällskapet sitt eget tågkort som måste ha saldo i spärren (automaten frågar vems kort), och alla behöver biljett. Med sittplatsval fortsätter biljettköpet med att placera sällskapet i vagnen efter deras önskemål – fönster eller gång, vänster eller höger sida, bredvid någon särskild. Missnöjda blir sura: mätaravdrag och poängavdrag.

Poäng och debuffar. En vunnen bana ger poäng för tid mot par, pengar, sällskapets mätare och utforskat, minus avdrag för missade tåg, omskanningar och sura passagerare. Spelandet kan ge debuffar som följer med till nästa banor: onda fötter av många steg, trötthet av långa banor, hunger/irritation av en tom matmätare och matförgiftning med liten otur vid kiosken. De sänker farten, snabbar på mätarna eller gör skyltarna svårare att lära sig, och räknas ned en bana i taget.

Resultatet visar tid mot par, stjärnor, poäng, spenderat och missade tåg – och vad banan gav: XP, nivå upp, nya items och vilka banor som öppnades. R spelar om, L öppnar ordlistan, Enter/Esc går till kartan.

Progression. En klarad bana ger poäng/10 + 25 × stjärnor XP. Nivå n+1 nås vid 150·n(n+1)/2 XP och varje nivå ger en skillpoäng till skillträdet (T): fyra grenar – språk (kana, fokus, hjälp), kropp (fart, törst, toa), resenär (tur) och utforskare (sikt, landmärken på minikartan).

Items köps kontant i kioskernas butik (B): hattar, masker, kläder, skor och prylar med buffar, några med genvägar – JR Pass öppnar alla spärrar, kartor avslöjar en bana, powerbanken håller telefonen vid liv. Ett item per plats bärs (huvud, ansikte, kropp, fötter, väska); skins ändrar din färg. Sidospår belönar unika skins. Det finns fler items än man har råd med på en omgång – det är meningen.

Flera våningar. Stationer kan ha flera plan. Du ser bara våningen du står på; trappor (U/D i bandatan, egen grafik) tar dig upp och ner – du kliver på trappan och står i andra änden en våning upp eller ner. HUD och minikarta visar våningens namn (B1, 1F …), och minikartan ritar bara den våning du är på. Tokyo station (bana 004) börjar under mark.

Stationen lever. På banor med crowd går det folk i gångarna: de vandrar mellan kiosker, toaletter, skyltar och perronger, kliver av tågen när dörrarna öppnas och går mot utgången. De tar plats – du kan inte gå in i någon ("Ursäkta…") utan måste runda dem eller vänta. I breda gångar finns filer med pilar: håll till den sida pilarna visar, annars möter du strömmen och bromsas. clutter sätter affischer på väggarna (en av dem liknar en riktig skylt), noise lägger på sorl som dämpar melodierna.

Vagnarna. När tåget står inne väljer du vagn. Först kliver folk av – tryck inte för tidigt, det kostar. Varje vagn visar hur mycket folk den har och kömarkeringarna var du ställer dig. Lite folk ger bonus; en full vagn gör det svårare att tränga sig på, ger kortare tid per station och passagerare som vill förbi (tryck ← för att kliva åt sidan), och kan göra dig svettig. Kvinnovagnen är rosa och märkt 女性専用, ibland bara under rusningstid som står på skyltarna – har du en man i sällskapet och går på den blir det grova minus.

Linjenätet och navigeringslägena. Tågen bedöms efter var de faktiskt går: resources/data/network.json har Tokyos linjer med stationerna i ordning (Yamanote som ringlinje). Ett tåg är rätt om det når resmålet inom tolv stationer, fel håll om linjen går dit men tåget åt andra hållet, för långt bort om resmålet kommer först efter en lång omväg (fel varv på ringen, Marunouchi via city) och annars kör det bara någon annanstans. Tågresan visar linjens riktiga stationer i färdriktningen, så du lär dig vad som ligger bortom. På bankartan växlar N mellan lägena:

Listläge – nere till vänster står vilket tåg du ska ta ("Ta: spår 6 Yamanote-sen (+1)" när flera går). Normal poäng.
Skyltläge – du får bara resmålet och läser dig fram med skyltarna och terminalen: biljettautomaten visar linjetavlan för stationen (varje linje med tre grannstationer åt vardera hållet), genom din japanska precis som en skylt. +50 % på grundpoängen. Åker du åt fel håll eller för långt bort är banan förlorad och resultatet förklarar varför.

Bana 006 Ikebukuro är byggd för skyltläget: fyra perronger där Yamanote mot Shinjuku och Saikyo mot Osaki båda är rätt, Saikyo mot Omiya går åt fel håll och Marunouchi mot Ogikubo tar omvägen via city.

Bussar. Vissa banor har bussar i stället för tåg: samma tidtabell och samma regler för rätt och fel, men ett enda fordon på en väg, en hållplatsskylt och "1番" i stället för "1番線" på tavlan. Flygbussterminalen (sidospår från flygplatsen) är en biljettbana med tre bussar: flygbuss mot Shinjuku eller Yokohama och flygplatsbussen mot Tokyo. Harajuku är ett sidospår från Shibuya där Yamanote går åt båda hållen - fel varv tar en halvtimme. På Ueno och Tokyo är stationen dessutom överstimulerande: en reklamticker blinkar under HUD:en och väggarna är fulla av affischer.

Byten. De sista resorna går via en mellanstation. HUD:en visar resmålet "via" bytesstationen och "1/2"; när du klivit av rätt tåg fortsätter samma omgång på nästa station – ny labyrint, ny dimma, nytt folk, men klockan, plånboken, biljetterna och sällskapets mätare följer med, och par-tiden räknas för hela resan. Tar du fel tåg på bytesstationen är resan förlorad. Bana 007 går Akihabara → Ueno → Asakusa, finalen 008 går Tokyo (två våningar) → Nippori → Narita flygplats med Keisei-biljetter och sittplatsval.

Vem betalar, och spärrar utan återvändo. På banor där alla har egna kort frågar kiosken vem som betalar: kontant, ditt kort eller någon i sällskapets – så att alla har kvar pengar till spärrarna; den som inte har råd står i rött. Avgiften dras när du passerar spärren in i det betalda området. På de svåraste stationerna (Ueno, Akihabara, Tokyo, Nippori) släpper spärren inte ut dig igen förrän du åkt: behöver du ut ändå trycker du Enter vid spärren och väntar på personalen (10 s), som låser upp korten. Går du in igen kostar det igen. Tänk på var toaletterna ligger: i Ueno och Nippori finns de bara innanför spärrarna, i Akihabara och Tokyo bara utanför, och på bytesstationen i Ueno på båda sidor.

Hemresan. Klarar du finalen första gången lyfter planet: sällskapet vinkar på marken, resan summeras i siffror (banor, stjärnor, bästa poäng, ord du lärt dig, souvenirer) och eftertexterna rullar. Enter går vidare, Esc hoppar till bankartan. Oändligt läge och New Game+ låses upp i nästa milstolpe.

Oändligt läge och New Game+. När storyn är klar visar bankartan två nya val. O startar oändligt läge: du får ett lottat resmål på en av storyns stationer – samma labyrint och samma tåg, men vilket tåg som är rätt beror på vart du ska – och när du är framme får du poäng och nästa mål. Sällskapet växer med en person var tredje mål och tidsgränsen krymper. Vid första förlusten (eller Esc) är omgången slut och hamnar i poänglistan med de fem bästa. Samma seed ger samma målföljd. G två gånger startar New Game+: storyn börjar om med skills, XP och japanskan kvar, men items, stjärnor, pengar och debuffar nollställs och sällskapet är en person större på alla banor.

Ljud och inställningar. Varje station har sin egen avgångsmelodi som spelas innan dörrarna stängs; ett tåg på väg in hörs som en jingel och ett ding-dong när det rullar in, dörrsignalen när det går. Spärren piper eller nekar, kiosken klirrar, toaletten spolar, nya ord pinglar, byten, personal, vinst och förlust har egna ljud, och bankartan har en lugn musikslinga. Allt är syntetiserat och fritt (riktiga JR-melodier är upphovsrättsskyddade). S på bankartan öppnar inställningarna: huvudvolym, effekter, musik och sorl, språk (svenska/engelska, byts direkt), fönsterskala och fullskärm (F11 fungerar överallt). Allt sparas i sparfilen.

Sparfilen ligger i ~/.config/metro-puzzle-jp/save.json (Linux) eller %AppData%\metro-puzzle-jp\ (Windows) och sparas automatiskt vid banstart (med seeden), efter varje bana och vid köp. Den har ett versionsfält så att äldre filer kan migreras.

Japanska tecken (新宿, 山手線 …) visas först i M3 när en pixelfont med kana/kanji är på plats – debugfonten saknar dem, därför romaji tills dess.

Uppdatera bilderna

Bilderna ovan är pixelexakta skärmdumpar som spelet tar om sig självt i skriptläge. När grafik eller UI ändras:

go run ./tools/shots     # skriver doc/img/*.png (bygger debug, kör -script)
git add doc/img && git commit

Wikin länkar till doc/img/ på master, så den uppdateras automatiskt när repot gör det. Nya vyer: lägg till i listan i tools/shots/main.go.

Arkitektur i korthet

cmd/metro-puzzle-jp      programstart, flaggor
internal/game            Ebitengine: scener (meny → bana → resultat), rendering, input
internal/sim             ren spellogik: rörelse, kollision, kamera, banomgång (tåg, spärrar, plånbok, hjälp, stjärnor, minispel), sällskap, dimma/minikarta, folk (NPC)
internal/minigame        påfyllning, biljettköp, trängsel, tågresa – seedade tillståndsmaskiner
internal/progress        XP, skillträd, items, banresultat, upplåsning av bankartan
internal/save            sparfil: versionerad JSON, migrering, atomisk skrivning
internal/lang            japanska: ordbok, tokenisering, kunskap, delvis översättning, engelska-andel
internal/level           banformat (JSON), validering, BFS-lösbarhet
internal/res             hittar resources/ (env → bredvid binären → uppåt från cwd)
internal/rng             seedad slump (PCG), del-seeds per kontext
internal/archtest        beroenderegel: bara game/ui/audio + cmd får röra Ebitengine
tools/build              byggverktyg i Go: debug/release, Linux/Windows, kopierar resources/
tools/genart             genererar placeholder-grafik (tileset, spelare, räls) tills riktig pixel art finns
tools/gensound           genererar placeholder-ljud (avgångsmelodi, dörrsignal)
resources/               sprites/ sound/ text/ data/ – skeppas bredvid binären

Designbeslut

Go + Ebitengine för att Go är enda byggverktyget och Windows-binären korsbyggs från Linux utan C-kompilator (CGO_ENABLED=0). Alternativen (Godot, Rust, C++/raylib, Love2D) och skälen står i roadmapen.
Rutbaserad rörelse (en ruta i taget, mjukt interpolerad). Gör labyrintkollision trivial och gör att sällskapet senare kan följa ledarens spår exakt.
Banomgången är ren logik (sim.Run: klocka, kort, spärrar, tåg, utfall). Scenen bara ritar den. Därför kan en bot spela igenom bana 001 i ett vanligt go test, utan fönster.
Ombordstigning är ett val (Enter på perrongen medan tåget är inne), så att spelaren hinner läsa skylten innan hen bestämmer sig.
Språket är data + ren logik. jp-dictionary.json är enda källan till japanska ord; internal/lang tokeniserar skyltar med längsta matchning och renderar dem genom spelarens kunskap. Ett test kräver att all japanska i banorna finns i ordboken – annars kan spelet inte översätta den.
PixelMplus 10 px som enda font (kana + kanji, fri licens), ritad på heltalspositioner för skarpa pixlar.
Engelska på skyltar hashas från bana + position, inte från seeden: banorna är statiska och ska se likadana ut varje gång.
Följarna går på ledarens spår (klassisk orm): ledarens senaste rutor sparas och följare i står i rutor bakåt, interpolerade med ledarens framsteg. Enkelt, deterministiskt och kolliderar aldrig.
Händelserna skalar med sällskapet genom intervallet 45 s / antal, så att "fler i lämmeltåget = svårare" är en enda tydlig formel som testas.
Minispelen är rena tillståndsmaskiner (internal/minigame) med ett gemensamt gränssnitt (Update/Done/Success) och all slump från del-seeds. Därför kan hela bana 002 – fel biljett, rätt biljett, spärr, trängsel, resa – spelas igenom i ett vanligt go test.
Folk går igenom varandra men inte spelaren. NPC:er blockerar spelarens rutor men ignorerar varandra och spelaren när de själva går – då kan ingen deadlocka någon, och spelaren känner trängseln som det enda hindret.
Vagnvalet är ett minispel före trängsel och resa, så att vagnens trängsel kan styra båda. Kvinnovagnens tidsfönster är bantid i sekunder, vilket skyltarna beskriver i klartext.
Våningar är en koordinat, inte en ny värld. Point fick Z, varje våning är ett eget rutnät av samma storlek och trappor är rutor som pekar på samma x,y en våning upp/ner. Grannfunktionen inkluderar trappans andra ände, så vägsökning, lösbarhetstest, spärregel och dimma fungerar över våningar utan specialfall – och alla gamla banor är bara "en våning".
Progressionen är data. Skills och items är JSON-rader med en effect som antingen multiplicerar en stat eller sätter en flagga; samma tabell gäller debuffar åt andra hållet. Nya items/skills = nya rader, inga kodändringar. Designregeln "knappt 33 % per omgång" är ett test mot itemlistan.
Sparfilen skrivs atomiskt (tempfil + byte av namn) och har version + migrering från dag ett, så att vi kan ändra formatet utan att förstöra någons spel.
Tågets liv är sex faser ur tidtabellen (away, approaching, arriving, dwelling, closing, leaving), beräknade i level utan tillstånd. Animation, ljud, vind och indikator i spelet läser bara av fasen – och boten i testerna kliver på först när dörrarna är öppna.
Ljuden är placeholders från tools/gensound (syntetiserade) så att spelet har rätt beteende nu; riktiga inspelningar byter bara ut filerna.
Stats är fem multiplikatorer (fart, törst, fokus, toalett, tur) och debuffar är bara tabellrader som multiplicerar dem. Items och skills i M8 använder samma tabell åt andra hållet.
Biljetten kontrolleras vid tåget, inte i spärren. Spärren släpper igenom alla med biljett (som i verkligheten); först vid tåget avslöjas om resmålet var rätt. Pusslet sitter alltså i taxetavlan på japanska.
Dimman mäts i steg, inte i avstånd. Att avslöja tre gångsteg runt spelaren (plus gränsande väggar) gör att labyrinten förblir en labyrint på minikartan; en cirkel skulle avslöja parallella gångar genom väggen.
Intern upplösning 320×180, 16 px-rutor, heltalsskalning till fönstret.
All slump via seed. Minispel och oändligt läge ska gå att återskapa från sparfilen.
Data i JSON under resources/, validerad av tester: en bana som inte går att klara stoppar go test.
En binär + resources/ per plattform i build/release/<os>-<arch>/. Att distribuera = zippa mappen.

Bygg och release

Lokalt: go run ./tools/build [-mode release] [-os windows], se README.
CI: .gitea/workflows/release.yaml kör tester och bygger Linux- och Windows-zippar på brasse-linux01-runnern (label linux-amd64, aldrig Pi5:n) och lägger dem på den rullande releasen latest; en tagg vX.Y.Z ger en versionerad release.

Status

Se "Status" i README och milstolparna i doc/roadmap.md.