# 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:** M1 klar (2026-10-23) – man kan gå runt i labyrinterna med kamera
som följer, välja bana i menyn och nå perrongen. Nästa är M2: tåg med
tidtabell, spärrar och första riktigt spelbara banan. Se
[doc/roadmap.md](doc/roadmap.md).

![Bana 001 – Flygplatsen](doc/img/level-001.png)

Så fungerar det: du startar på den gröna dörrmattan, letar dig genom
stationen förbi skyltar, automater och spärrar, och ställer dig på en
perrong (gul ledlinje). Rätt perrong tar dig till resmålet, fel perrong ger
fel tåg.

![Resultat – rätt tåg](doc/img/result.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.

### 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 -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, Esc går tillbaka, R spelar om. Gamepad
med standardlayout fungerar: d-pad/vänster spak, A = välj, B = tillbaka.

### 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/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 | Windows 10+ med DirectX 11 eller OpenGL |
| **Go-moduler** | `github.com/hajimehoshi/ebiten/v2` (spelbibliotek) + dess indirekta beroenden (`purego`, `gomobile`, `x/sys`, `x/sync`, `x/image`) | 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 (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](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.