metro-puzzle-jp/README.md

Metro Puzzle JP

Pixel art-pusselspel: leda ett sällskap – lämmeltåget – genom japanska tågstationer byggda som labyrinter, hitta rätt tåg och komma fram till rätt resmål. Nästan alla skyltar är på japanska; ju mer du lär dig, desto mer kan du läsa. Sällskapet behöver mat, dryck och toapauser, tågkortet måste ha saldo, telefonen batteri, och på svåra banor tickar klockan.

Storyn följer några polare på semester i Japan, från landningen på flygplatsen till avresan. Efter storyn låses ett oändligt läge och New Game+ upp. Hela speldesignen finns i doc/spelbeskrivning.md.

Status: M7b klar (2026-10-24) – tre banor med stigande svårighet. Japanska skyltar och ordinlärning, lämmeltåget med sina behov, minikarta med dimma, tågkort, biljetter och minispel, svårighet med tidsgräns, poäng, debuffar, egna kort och sittplatsval. Och nu lever tågen: de rullar in på rälsen till avgångsmelodin, står med öppna dörrar, dörrsignalen ljuder och de accelererar ut igen, med vind längs perrongen och lampor som varnar den som står nära rälsen. Nästa är M8: progression, items och sparfiler. Se doc/roadmap.md.

Så fungerar det: du startar på den gröna dörrmattan och letar dig genom stationen. Skyltarna är på japanska. Ord du kan markeras och översätts i raden under, okända ord står kvar. Trycker du H frågar du en förbipasserande, väntar några sekunder och får hela skylten översatt plus ett nytt ord. Spärrarna släpper bara igenom dig om kortet har saldo. På perrongen (gul ledlinje) är avgångstavlan också japansk. Står tåget inne trycker du Enter för att kliva på. Rätt tåg tar dig till resmålet, fel tåg avslutar banan. På tåget passerar stationerna en i taget; kliv av med Enter vid ditt resmål. Klarar du banan under par får du stjärnor, språkpoäng och resmålets namn.

Spärren drar från tågkortet. Tar saldot slut fyller du på vid automaten, där du först måste hitta rätt knapp bland de japanska. På svårare banor krävs i stället en pappersbiljett till rätt resmål, köpt från en taxetavla på japanska.

På de svåraste banorna har alla i sällskapet egna kort som måste ha saldo, alla behöver biljett, och när biljetten är köpt ska sällskapet placeras i vagnen efter sina önskemål: fönster eller gång, vänster eller höger sida, eller bredvid en viss person. Missnöjda blir sura och drar ned poängen.

Ditt sällskap följer efter i en rad. Mätarna uppe till höger visar mat, dryck och toa för var och en; faller de får någon ett behov som saktar ned er alla tills ni hittar en kiosk eller en toalett. Minikartan i hörnet visar från början bara perrongerna, starten och spärrarna plus en avgångslista; resten fylls i allt eftersom ni går.

Fler bilder och en genomgång finns i wikin.

Bygga

Enda kravet är Go ≥ 1.27. Linux behöver dessutom en C-kompilator och X11/GL-headers för fönsterhanteringen (Ebitengine/GLFW). Windows-bygget är ren Go och kan korsbyggas från Linux.

Linux

# Arch / Garuda
sudo pacman -S --needed go gcc pkgconf mesa libx11 libxrandr libxcursor libxinerama libxi libxxf86vm alsa-lib

# Debian / Ubuntu
sudo apt install golang gcc libc6-dev pkg-config libgl1-mesa-dev libx11-dev libxrandr-dev libxcursor-dev libxinerama-dev libxi-dev libxxf86vm-dev libasound2-dev

git clone <remote>/metro-puzzle-jp.git && cd metro-puzzle-jp
go run ./tools/build                                   # debug  → build/debug/
go run ./tools/build -mode release -os linux            # release → build/release/linux-amd64/
go run ./tools/build -mode release -os windows          # korsbygge → build/release/windows-amd64/
./build/debug/metro-puzzle-jp                          # kör
go test ./...                                          # tester

Windows (bygga på Windows)

Installera Go från https://go.dev/dl/. Ingen C-kompilator behövs.

go run ./tools/build -mode release        # → build\release\windows-amd64\metro-puzzle-jp.exe

VS Code

Öppna mappen med tillägget Go (golang.go, föreslås automatiskt).

Vad	Hur
Bygga debug	Ctrl+Shift+B (tasken build)
Debugga	F5 – "Debug (dlv)". Tillägget erbjuder att installera delve första gången.
Bygga release	Terminal › Run Task › build: release (linux-amd64) / (windows-amd64) / (alla plattformar)
Köra tester	Terminal › Run Task › test, eller testknapparna i editorn

Resultatet av ett bygge

build/
├── debug/                       debug-bygge för den här datorn
│   ├── metro-puzzle-jp
│   └── resources/
└── release/
    ├── linux-amd64/
    │   ├── metro-puzzle-jp     en strippad binär
    │   └── resources/           sprites/  sound/  text/  data/
    └── windows-amd64/
        ├── metro-puzzle-jp.exe
        └── resources/

Spelet letar efter resources/ bredvid binären, annars uppåt från arbetskatalogen (så go run och F5 fungerar), och JP_RESOURCES=/sökväg överstyr allt. Att distribuera spelet = zippa en plattformsmapp.

Flaggor

metro-puzzle-jp                          # meny
metro-puzzle-jp -level 001-flygplatsen   # hoppa direkt in i en bana
metro-puzzle-jp -scale 3                 # fönsterstorlek (320x180 × skala)
metro-puzzle-jp -smoke 90                # öppna fönster, avsluta efter 90 bildrutor (smoke-test)
metro-puzzle-jp -know 改札,番線 -points 3   # förkunskap och språkpoäng (tester/skärmdumpar)
metro-puzzle-jp -seed 7                   # fast seed för händelser, läsning och minispel (tester/skärmdumpar)
metro-puzzle-jp -phone -card 0            # kortet i telefonen; kortets startsaldo (tester/skärmdumpar)
metro-puzzle-jp -debuffs sore_feet,tired  # debuffar från start (tester/skärmdumpar)
metro-puzzle-jp -mute                     # inget ljud
metro-puzzle-jp -script "move right 4; shot bild.png; quit"   # skriptläge, se internal/game/script.go
metro-puzzle-jp -version

Styrning

Pilar eller WASD går. Enter väljer, kliver på tåget, använder toaletten, handlar i kiosken eller startar automaten; i minispelen väljer pilarna och Enter bekräftar (håll Enter för att mata in sedlar). H frågar om hjälp vid en skylt, L öppnar ordlistan, M döljer/visar minikartan, P i menyn lägger kortet i telefonen, Esc går tillbaka, R spelar om. Gamepad med standardlayout fungerar: d-pad/vänster spak, A = välj, B = tillbaka, Y = hjälp, X = ordlista, Back/Select = karta.

Verktyg

Kommando	Gör
go run ./tools/build …	bygger (se ovan)
go run ./tools/genart	genererar placeholder-grafiken resources/sprites/tiles.png och player.png
go run ./tools/gensound	genererar placeholder-ljuden resources/sound/*.wav (avgångsmelodi, dörrsignal)
go run ./tools/shots	tar dokumentationens skärmdumpar till doc/img/ – kör efter varje grafik-/UI-ändring och committa bilderna

Beroenden

	Linux	Windows
Bygga	Go ≥ 1.27, gcc, pkgconf, mesa (GL-headers), libx11/libxrandr/libxcursor/libxinerama/libxi/libxxf86vm, alsa-lib	Go ≥ 1.27
Köra	libc, samt ett skrivbord med OpenGL (mesa) och X11 eller Wayland (XWayland), ALSA/PipeWire för ljud – laddas dynamiskt vid start (-mute stänger av ljudet)	Windows 10+ med DirectX 11 eller OpenGL
Go-moduler	github.com/hajimehoshi/ebiten/v2 (spelbibliotek, inkl. text/v2 för TTF-rendering) + indirekta beroenden (purego, gomobile, go-text/typesetting, x/image, x/sys, x/sync)	samma
Font	PixelMplus 10/12 px (M+ FONT LICENSE), ligger i resources/text/fonts/	samma

Release-binären för Linux är dynamiskt länkad bara mot libc; GL/X11 laddas vid körning, så den fungerar på alla vanliga distributioner.

Dokumentation

• doc/plan.md – navet: mål, stack, milstolpar, öppna frågor
• doc/spelbeskrivning.md – hela speldesignen
• doc/roadmap.md – teknikval, katalogstruktur, milstolpar i ordning
• doc/mal-och-tester.md – projektmål, teststrategi, checklistor
• resources/*/README.md – vad som ska ligga i respektive resursmapp

Struktur i korthet

cmd/metro-puzzle-jp/    programstart
internal/game/          Ebitengine: scener, input, rendering, skriptläge (enda paketet som får känna till Ebitengine)
internal/sim/           rutbaserad rörelse, kollision, kamera, banomgång med tåg/spärrar/hjälp (ren Go)
internal/lang/          japanska: ordbok, kunskap, delvis översättning (ren Go)
internal/minigame/      påfyllning, biljettköp, trängsel, tågresa – seedade minispel (ren Go)
internal/level/         banformat, validering, framkomlighet
internal/res/           hittar och läser resources/
internal/rng/           seedad slump
tools/                  build/ genart/ shots/
resources/              sprites/ sound/ text/ data/ – kopieras bredvid binären
doc/                    dokumentation, doc/img/ = skärmdumpar
.gitea/workflows/       CI: test + release-zippar (linux/windows)

Release

Varje push till master bygger zippar för Linux och Windows på Gitea och lägger dem på releasen latest. En tagg vX.Y.Z ger en versionerad release. Packa upp och kör binären; resources/ måste ligga bredvid.