Co to jest
- Bez kont i instalacji. Wpisujesz nick i czteroznakowy kod pokoju. Stronę można dodać do ekranu głównego jako PWA.
- Do 6 graczy w pokoju, kilka pokoi równolegle; kto nie ma miejsca przy stole, ogląda.
- Tryb cichy. Ciemny motyw, bez dźwięku, wibracje zamiast powiadomień, limit czasu na turę.
- Odporność na słabe Wi-Fi. Stan gry żyje na serwerze, klient łączy się ponownie sam, a po odświeżeniu strony wracasz do partii.
- Także w pojedynkę. Wyzwanie dnia (jedna mini-gra dziennie, ta sama dla wszystkich) i rekordy wszech czasów w każdej mini-grze.
Gry
| Gra | Graczy | W skrócie |
|---|
| Kampus Tour | 2-4 | gra planszowa o kupowaniu pól i czynszach, w realiach Politechniki Rzeszowskiej i Rzeszowa |
| Statki | 2 | cztery tryby, od szybkiego 8×8 po flotę wojenną 12×12 |
| Gomoku | 2 | pięć w rzędzie na planszy 15×15 |
| Chińczyk | 2-4 | tryb klasyczny i szybki |
| Memory | 2-6 | trzy rozmiary planszy |
| Państwa-miasta | 2-6 | 5 rund, wszyscy piszą naraz, odpowiedzi ocenia głosowanie |
| Mini-gry (30) | 1-6 | krótkie wyzwania na refleks, pamięć, oko i liczenie: Refleks, Sekwencja, Narysuj koło, Mapa, Wieża, Rytm, Sudoku i inne |
| Turniej | 1-6 | seria mini-gier w jednym pokoju ze wspólną tabelą punktów |
Dokładne zasady każdej gry: ZASADY-GIER.md.
Jak to działa
Telefon (PWA, React) ⇄ WebSocket ⇄ Serwer Colyseus (Node)
│
├─ logika gier (czyste funkcje TS)
└─ SQLite (ranking, rekordy i zapis pokoi na czas restartu)
Serwer jest jedynym źródłem prawdy. Klient wysyła intencje („rzucam kośćmi”), serwer je waliduje, losuje,
liczy nowy stan i rozsyła każdemu graczowi jego widok, więc ukrytych informacji (ręka, plansza przeciwnika) nie da się podejrzeć.
Każda gra to moduł niezależny od sieci i interfejsu: setup, validateMove, applyMove, playerView, isOver
(kontrakt GameDefinition w packages/games/src/core.ts).
Stack: TypeScript, pnpm workspaces, Colyseus + Express, zod, Vite + React, Tailwind, SQLite (node:sqlite), Vitest, Docker.
Uruchomienie
Wymaga Node 24 i pnpm 12.
pnpm install
pnpm --filter server dev # http://localhost:2567
pnpm --filter web dev # http://localhost:5173
pnpm typecheck && pnpm test
Tryb testowy http://localhost:5173/dev?n=4 pokazuje kilku graczy obok siebie w jednym pokoju.
Struktura
packages/games/src/ zasady gier z testami, kontrakt, rejestr GAMES
apps/server/src/ pokój Colyseus, SQLite, API rankingów
apps/web/src/ frontend: screens/ (platforma), games/ (interfejs każdej gry)
| Dokument | Zawartość |
|---|
| KONCEPT.md | założenia, katalog gier, architektura, reguły platformy |
| ZASADY-GIER.md | dokładne zasady każdej gry |
| ZASADY.md | proces dodawania gry, obowiązkowe testy, spójność wyglądu i animacji |
| DESIGN.md | styl wizualny: tokeny, wzorcowe sekcje, stany |
| AGENTS.md | instrukcje dla agentów AI |
Deploy (Raspberry Pi)
Push na master uruchamia CI, które buduje obraz linux/arm64 i publikuje go jako ghcr.io/figielak/kwadrans:latest.
Jeden kontener serwuje frontend i WebSockety, a Cloudflare Tunnel wystawia go pod games.figielak.dev bez otwierania portów.
Jednorazowo:
-
Cloudflare (bez Zero Trust): domena figielak.dev dodana do konta Cloudflare (darmowy plan, nameservery u rejestratora
wskazują na Cloudflare). Na dowolnej maszynie z cloudflared:
cloudflared tunnel login # w przeglądarce wybierz figielak.dev
cloudflared tunnel create games # tworzy ~/.cloudflared/<UUID>.json
cloudflared tunnel route dns games games.figielak.dev # rekord CNAME na tunel
-
GHCR: ustaw pakiet jako publiczny albo na Pi docker login ghcr.io (PAT z read:packages).
-
Pi: skopiuj docker-compose.yml i katalog cloudflared/, a plik <UUID>.json z kroku 1 wrzuć jako
cloudflared/credentials.json (chmod 644, bo kontener cloudflared działa jako inny użytkownik).
Tunel łączy się z Pi na zewnątrz, więc działa za CGNAT i bez przekierowania portów.
Aktualizacja:
docker compose pull && docker compose up -d
Aktualizacja nie kończy partii: przed zamknięciem serwer zapisuje pokoje do SQLite (ten sam wolumen co ranking), po starcie je odtwarza,
a otwarte strony same wracają na swoje miejsca. Przerwa trwa tyle, ile wymiana kontenera. Tak samo działa restart i awaria (traci najwyżej ostatnie 5 s).
Zapis starszy niż godzina przepada. W dev to samo dzieje się przy każdym restarcie node --watch.
