Mazer

Mazer is a simple dungeon-escape game. You are trapped in a 2×2 grid. Find the exit to escape! This project contains example of AI Agent to play the game by itself (currently it support Gemini AI).

    col 0      col 1
   ┌──────────┬──────────┐
r1 │  OPEN    │  EXIT 🚪 │  ← reach EXIT to win
   ├──────────┼──────────┤
r0 │  START ⚑ │  WALL 🧱 │  ← you always begin here (0,0)
   └──────────┴──────────┘

• Coordinates: (x=col, y=row) — y increases going up.
• You start at (0, 0).
• The exit is at (1, 1).
• Winning path: UP → RIGHT (2 moves)

How It Works (the short version)

1. Register — POST /users with a name → you get a user_id.
2. Start a game — POST /start with your user_id → you get a session_id.
3. Move — POST /game/{session_id}/move with a direction (up, down, left, right).
4. Repeat until you win or get blocked by a wall.

Quick Start using docker

1. Run the services with command: ./app.sh run or GOOGLE_API_KEY="xxx" ./app.sh run --with-agent if you want to run the AI-Agent in parallel.

2. Open:

   • http://localhost:8000/ui for the UI
   • http://localhost:8000/docs for the Swagger UI
   • http://localhost:8000/openapi.json for the OpenAPI specification
   • http://localhost:8501 for the Gemini Agent

Run Tests using docker

./app.sh test

Endpoints

Method	Path	Description
GET	/ui	Game UI (HTML interface)
POST	/users	Register a new player (returns id)
GET	/users	List all players
DELETE	/users/{user_id}	Delete a player and all their sessions
POST	/start	Start a new game session (requires user_id, returns session_id)
POST	/game/{session_id}/move	Make a move: up, down, left, right
POST	/game/{session_id}/reset	Reset a finished/abandoned session back to the start
GET	/game/{session_id}	Get current state + full move history
GET	/games	List all sessions
DELETE	/game/{session_id}	Abandon a session

Move result values

result	Meaning
moved	Successfully stepped to a new cell
blocked	Wall or boundary — position unchanged
won	Reached the exit — game complete

Session status values

status	Meaning
active	Game in progress
won	Player reached the exit
abandoned	Player called DELETE

Note

Why separate users and sessions?

A user is your permanent account (just an id + name). A game session is one play-through. You can start many sessions with the same user and compare runs. Deleting a user also removes all their sessions. Two sessions can't use the same session simultaneously — moves are locked at the database row level to prevent race conditions from parallel requests.