smart-bomberman
Visual Computing Team Project 2023
Released under MIT.
Table of contents
Installation
The project uses uv (install it first).
uv installs the right Python (3.11 by default, 3.10+ supported) and the exact dependency versions from uv.lock:
uv sync
Run the game
uv run smart-bomberman play
Game controls
- Arrow keys to move
- 'X' to place bomb
Battle mode: you vs Two-Fuse
Two-Fuse is the Battle-mode agent. Like the coin-flipping villain it's named after, it flips a coin
before every round, and the coin decides which corner you start in. The last one standing wins.
The map's wandering enemies kill either of you, and once sudden death starts the arena closes in
one cell at a time from the edges until someone is crushed.
uv run smart-bomberman versus # best of 3 on the arena, difficulty normal
uv run smart-bomberman versus --difficulty hard # Two-Fuse plays its best move every time
uv run smart-bomberman versus --arena map_2 --enemies false --rounds 5
- Arrow keys to move,
X or Space to bomb, Esc to quit
--difficulty: easy (a scripted bot), normal (the trained model, sampled) or hard (the trained model, greedy)--tps sets the game speed in ticks per second (default 7). You and Two-Fuse both act once per tick.- Red tiles close soon. Crimson tiles have closed.
Two-Fuse is trained by league self-play. It starts from the single-player agent below: that agent's
weights are copied into the larger Battle-mode network, so it already knows how to bomb a target and
dodge blasts. It then plays against snapshots of itself and against three scripted bots: an
attacker (heuristic) and two that never attack (camper, wanderer), so it has to learn to go
and hunt an opponent who won't come to it. Win rates against all three are checked during training,
and the strongest snapshot is installed as models/two_fuse.zip.
| Two-Fuse win rate (200 games each, arena_1 / map_2 / map_3) | vs heuristic | vs camper | vs wanderer |
|---|
| single-player agent copied in, before versus training | ~13% | ~20% | ~17% |
| v1 (5M steps, only attacking sparring bots) | 52% | 42% | 43% |
| hard (v2: 4.5M more steps with all three bots, greedy) | 76% | 77% | 69% |
| normal (same model, sampled) | 72% | 73% | 71% |
uv run smart-bomberman train-versus --timesteps 5000000 # v1: about 75 minutes on a 12-core laptop CPU
uv run smart-bomberman train-versus --init_from models/two_fuse.zip --timesteps 6000000 # continue training (v2)
uv run smart-bomberman duel models/two_fuse.zip camper # head-to-head record
uv run smart-bomberman versus --player heuristic --save-gif match.gif # record a bot vs Two-Fuse match
Play in the browser
web/ is an Astro + Svelte site for Vercel: play the agents up a ladder, get rated on their Elo scale, and read how
Two-Fuse was trained with the real networks running live. The engine and agents are ported to TypeScript and checked
against the Python reference move for move; ranked results are verified by replaying the match on the server. See
web/README.md.
AI agent
This version picks up the feature/juhyun work and makes the agent actually train.
The original setup could not learn: the game only advanced inside render(),
bomb fuses ran on wall-clock time, and one tile of movement took 16-32 actions.
src/game/ai/ now holds a headless, tile-based engine with the same rules
and a Gymnasium env. A PPO agent trained on it wins:
| Map | Win rate (deterministic, 200 episodes) | Random policy |
|---|
| map_1 (maze, 3 enemies) | 91% | 0% |
| map_2 (open grid, 3 enemies) | 79.5% | 0% |
uv run smart-bomberman watch models/ppo_map1_map2.zip --maps map_1 --deterministic # watch the trained agent
uv run smart-bomberman evaluate models/ppo_map1_map2.zip --maps map_2 --episodes 200 --deterministic
uv run smart-bomberman train --maps map_2 --timesteps 1000000 # about 7 minutes on a laptop CPU
See docs/EXPERIMENTS.md for what was wrong, what changed, and the
results of each round of trials. Tests and checks: uv run pytest, uv run ruff check, uv run mypy src.
AI agents from the 2023 project
Each team member's original approach lives on its own branch. They predate the agent above and
need their own setup (pinned gymnasium and stable-baselines3 versions), so follow the
instructions on each branch.
- feature/divyendu: PPO and NEAT models with multiple observation spaces
- feature/ken: PPO with multiple observation spaces and a curriculum-learning path
- feature/juhyun: Dict observation space, the starting point for the current agent
- feature/sandeep: Box observation space (superseded)
- training/sandeep: Multiplayer mode for visual benchmarking and visualizing training
Notes
- PyTorch builds: on Linux and Windows,
pyproject.toml installs the CPU-only PyTorch wheels
(PyPI's default ones bundle several GB of CUDA). The agents here train fine on a CPU. To train on an
NVIDIA GPU, change the pytorch-cpu index URL in pyproject.toml to a CUDA one from
pytorch.org (e.g. https://download.pytorch.org/whl/cu126)
and run uv lock && uv sync. On macOS the default wheels are used.
Documentation
Please check out the official documentation
pertaining all the key aspects of research and development of the smart-bomberman.
The unofficial documentation covers the later AI work: why the 2023 training
setup could not learn, how it was rebuilt, and the results of each round of trials.
