# 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](doc/spelbeskrivning.md).

**Status:** M9b klar (2026-10-24) – sex banor på en bankarta i
spelbrädesstil, med sidospår och flera våningar. Japanska skyltar och
ordinlärning, lämmeltåget, minikarta, tågkort, biljetter och minispel,
svårighet med tidsgräns, poäng och debuffar, tåg som rullar in till
avgångsmelodin, progression med XP, skillträd, items och sparfil. Och nu
lever stationen: folk som går i vägen, filer där man ska hålla till vänster,
reklam på väggarna, sorl i bakgrunden, och tåg med flera vagnar där man
väljer vagn, låter folk kliva av först och aktar sig för kvinnovagnen.
Nästa är M9: navigeringslägena lista och skyltläge. Se
[doc/roadmap.md](doc/roadmap.md).

![Bankartan](doc/img/map.png)

![Skylt på japanska med delvis översättning](doc/img/sign.png)

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.

![Tåget på väg in](doc/img/approach.png)

![Perrongen – tåget är inne](doc/img/platform.png)

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.

![Automaten](doc/img/ticket.png)

I kioskens butik (B) köper du hattar, masker, kläder, skor och prylar med
buffar; några är genvägar, som JR Pass som öppnar alla spärrar. Klarade
banor ger XP, nivåer ger skillpoäng till skillträdet (T), och garderoben (I)
visar vad du bär.

![Skillträdet](doc/img/skills.png)

Stationer kan ha flera våningar. Du ser bara den våning du står på; trappor
tar dig upp och ner, och minikartan visar vilket plan du är på.

![Tokyo station, 1F](doc/img/floors-1f.png)

På svåra banor är stationen full av folk, väggarna av reklam och luften av
sorl. Tågen har flera vagnar: låt folk kliva av först, välj en vagn med lite
folk för extra poäng, och undvik den rosa kvinnovagnen om det finns en man i
sällskapet.

![Vagnval](doc/img/cars.png)

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.

![Sittplatsval](doc/img/seats.png)

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.

![Shinjuku station med sällskapet](doc/img/level-002.png)

Fler bilder och en genomgång finns i
[wikin](https://gitea.brasse-pc.eu/brasse/metro-puzzle-jp/wiki).

## 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

```bash
# 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
```

```bash
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.

```powershell
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. Sparfilen
ligger utanför spelmappen, i `~/.config/metro-puzzle-jp/` (Linux) eller
`%AppData%\metro-puzzle-jp\` (Windows).

### 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 -save /sökväg/save.json   # annan sparfil (standard ~/.config/metro-puzzle-jp/save.json)
metro-puzzle-jp -nosave                   # läs sparfilen men skriv aldrig (tester/skärmdumpar)
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, T skillträdet, I garderoben, B butiken vid en kiosk, M
döljer/visar minikartan, P på kartan 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 [ord…]` | tar dokumentationens skärmdumpar till `doc/img/` – **kör efter varje grafik-/UI-ändring och committa bilderna**. Med argument körs bara skott vars bana eller skript innehåller något av orden (t.ex. `go run ./tools/shots 005 ride.png`). På Linux körs spelet på en osynlig skärm (headless Wayfire + Xwayland) så att inget fönster syns eller tar fokus; `METRO_HEADLESS=0` använder skärmen |

## 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](doc/plan.md) – navet: mål, stack, milstolpar, öppna frågor
- [doc/spelbeskrivning.md](doc/spelbeskrivning.md) – hela speldesignen
- [doc/roadmap.md](doc/roadmap.md) – teknikval, katalogstruktur, milstolpar i ordning
- [doc/mal-och-tester.md](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/progress/      XP, skillträd, items, banresultat, upplåsning (ren Go)
internal/save/          sparfil (versionerad JSON)
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](https://gitea.brasse-pc.eu/brasse/metro-puzzle-jp/releases/tag/latest).
En tagg `vX.Y.Z` ger en versionerad release. Packa upp och kör binären;
`resources/` måste ligga bredvid.