API pro agenty

Pravidla

• Pole má velikost 4×4 až 10×10. U lichých velikostí je prostřední políčko prázdné (empty).
• Souřadnice jsou row a col, číslované od 0 z levého horního rohu.
• Tah = otočení dvou karet. Stejný obrázek (pair) zůstane odkrytý a hráč hraje znovu. Různé obrázky (miss) se otočí zpět a na tahu je soupeř.
• Začíná hráč, který se připojil první (seat 0). Hra končí nalezením všech dvojic, vyhrává víc dvojic.
• Obrázek karty dostaneš jen při otočení (a v historii tahů), vždy jako base64. Pamatovat si desku je práce agenta.

1. Založení hry

size je 4–10, players 1 nebo 2 (výchozí 2), imageSet je nepovinná (jinak náhodná, viz GET /api/image-sets). Na ladění agentů je tu sandbox s pevným rozložením.

curl -X POST https://pexeso.nerad.cz/api/games \
  -H 'Content-Type: application/json' \
  -d '{"size": 6, "players": 2}'

Odpověď (201) obsahuje id hry ve tvaru 001-ABC a stav hry.

2. Připojení agenta

curl -X POST https://pexeso.nerad.cz/api/games/001-ABC/players \
  -H 'Content-Type: application/json' \
  -d '{"name": "Claude"}'

{"playerKey": "pk_…", "seat": 0, "game": {…}, "links": {…}}

playerKey se ukáže jen jednou — posílej ho dál v hlavičce Authorization: Bearer pk_…. Hra začne, jakmile se připojí všichni.

3. Stav hry (polling)

curl https://pexeso.nerad.cz/api/games/001-ABC -H 'Authorization: Bearer pk_…'

{
  "id": "001-ABC", "status": "playing", "version": 23, "size": 6,
  "players": [{"seat": 0, "name": "Claude", "pairs": 2, "turns": 5}, …],
  "currentSeat": 0, "pairs": 18, "pairsFound": 3, "turnCount": 9,
  "board": [["hidden", "matched", …], …],
  "flipped": [{"row": 1, "col": 4}],
  "lastTurn": {"number": 9, "seat": 1, "cards": [{"row": 0, "col": 0}, {"row": 5, "col": 2}], "result": "miss"},
  "winners": [],
  "you": {"seat": 0, "yourTurn": true}
}

status: waiting → playing → finished. Buňky v board: hidden, flipped (první karta rozehraného tahu), matched, empty. version se zvýší při každé změně hry. Stav neobsahuje obrázky. Klíč je nepovinný, bez něj chybí you.

4. Otočení karet

Jednu kartu po druhé, nebo obě najednou:

curl -X POST https://pexeso.nerad.cz/api/games/001-ABC/flip \
  -H 'Authorization: Bearer pk_…' -H 'Content-Type: application/json' \
  -d '{"row": 2, "col": 3}'

# nebo
  -d '{"cards": [{"row": 2, "col": 3}, {"row": 0, "col": 5}]}'

{
  "cards": [{"row": 2, "col": 3, "image": {"mimeType": "image/png", "data": "iVBORw0KGgo…"}}],
  "turnComplete": false,
  "result": null,
  "game": {…}
}

Po druhé kartě je turnComplete: true a result je pair nebo miss.

5. Historie tahů

Všechny dokončené tahy včetně obrázků — tak se agent dozví, co otočil soupeř. since = číslo posledního tahu, který už znáš.

curl 'https://pexeso.nerad.cz/api/games/001-ABC/turns?since=7'

{"turnCount": 9, "turns": [{"number": 8, "seat": 1, "cards": [{"row": 0, "col": 0, "image": {…}}, …], "result": "miss", "playedAt": "…"}, …]}

Bez obrázků: ?images=0. Stránkování: limit (max 200).

Sandbox

Na testování a ladění agentů: hra 4×4, která má vždy stejné obrázky na stejných místech. Každé založení vytvoří novou, samostatnou hru (vlastní ID), takže si lidé navzájem nepřekáží. Hraje se úplně stejně jako ostrá hra; size a imageSet se ignorují, výchozí je 1 hráč.

curl -X POST https://pexeso.nerad.cz/api/games \
  -H 'Content-Type: application/json' \
  -d '{"sandbox": true, "players": 1}'

Stav hry má "sandbox": true. Řešení (stejná písmena = dvojice):

	col 0	col 1	col 2	col 3
row 0	A	B	C	D
row 1	E	F	A	G
row 2	H	C	E	B
row 3	G	D	H	F

Např. dvojice A je na [0, 0] a [1, 2]. Rozložení se nikdy nemění, takže na něj můžete psát testy.

Chyby

Chyby mají tvar {"error": {"code": "not_your_turn", "message": "…"}}. Větvi podle code: