https://github.com/budtmo/mazer
a simple dungeon-escape game featuring an AI agent
https://github.com/budtmo/mazer
ai-agent maze-game
Last synced: 2 months ago
JSON representation
a simple dungeon-escape game featuring an AI agent
- Host: GitHub
- URL: https://github.com/budtmo/mazer
- Owner: budtmo
- License: other
- Created: 2026-04-12T20:28:18.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-12T20:33:19.000Z (3 months ago)
- Last Synced: 2026-05-24T03:34:05.788Z (2 months ago)
- Topics: ai-agent, maze-game
- Language: Python
- Homepage:
- Size: 171 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Maintainers: MAINTAINERS
Awesome Lists containing this project
README
# 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.