MARL-BattleGrounds

The JAX-native Benchmark for Heterogeneous and Competitive Multi-agent Reinforcement Learning.

Two teams of up to five agents fight Team Deathmatch on 52 maps. Each agent is a Mage, Warrior, Hunter, Rogue or Priest, so a team wins by combining movement, attacks, healing and support. The whole game is written in JAX, so thousands of games run at once on one GPU. You bring the method; MARL-BGs gives you the game, training helpers, evaluation, tournaments and replays.

Install

On Linux, an Apple Silicon Mac or Windows with WSL2, one command installs everything and opens the BattleClient. It picks the right JAX build for your GPU:

curl -L https://github.com/oceansystemslab/MARL-BattleGrounds/archive/refs/tags/v1.0.0.tar.gz | tar xz
cd MARL-BattleGrounds-1.0.0 && sh start.sh

In your own Python project (Python 3.12 to 3.14; 3.14 recommended):

pip install "marl-battlegrounds[all]"           # CPU
pip install "marl-battlegrounds[all,cuda13]"    # NVIDIA GPU, driver 580 or newer

With Docker, on any system (add --gpus all and the 1.0.0-cuda12 tag for an NVIDIA GPU):

docker run --rm -it -p 127.0.0.1:8765:8766 -p 127.0.0.1:8767:8768 -v "${PWD}:/work" ghcr.io/oceansystemslab/marl-battlegrounds:1.0.0

Docker runs everything: play, replays, training, evaluation, tournaments, analysis and notebooks. Its limits:

Every route, the GPU builds, Windows, clusters and offline use: the install guide.

Quick Start

import jax
import marl_battlegrounds as marl_bgs

env = marl_bgs.make("tdm", map_id=0, num_envs=4)  # four games at once
key = jax.random.key(0)
observation, state = env.reset(key)
for _ in range(50):
    key, act_key, step_key, reset_key = jax.random.split(key, 4)
    actions = env.sample_actions(act_key, state)  # legal random actions
    observation, state, reward, done, info = env.step(step_key, state, actions)
    observation, state = env.reset_done(reset_key, state)  # restart finished games

On one RTX 5090 with 1,024 parallel 5v5 games, the simulator alone runs 50,416 game steps per second (random legal actions, compilation excluded), and recurrent MAPPO trains at 29,878 game steps per second in pure self-play.

Train

One command trains recurrent IPPO with the Season 0 learner settings (250 million game steps, a few hours on one RTX 5090) against scripted opponents, and keeps its best checkpoint on the validation maps:

python -m marl_battlegrounds.experiments.train method=ippo pool=scripted \
  'validation_opponents=[tdm-alpha,tdm-beta,tdm-gamma]' output_dir=runs/my-ippo

Evaluate

import marl_battlegrounds as marl_bgs

results = marl_bgs.evaluate("random", "tdm-alpha", num_episodes=32, num_envs=32)
print(results.head_to_head())  # games, wins, draws, losses, point margin

Your method is always Team A, and paired games swap the spawn ends, so a map's layout cannot favor either side.

Watch And Play

python -m marl_battlegrounds replay path/to/game.marlbg-replay.json

import marl_battlegrounds as marl_bgs

marl_bgs.battle_client(team_b="tdm-alpha")  # play in your browser against a scripted team

The Six Built-In Learners

The six trained Season 0 models, with every save from 0 to 250M steps, load by name, for example marl_bgs.load_method("MARL-BattleGrounds/tdm-season-0-qmix@final") (Training).

Your own method can be anything that turns permitted observations into legal actions: a network, a planner, a language model or a mix.

Guides

Reproduce The Paper

The paper's commands, frozen settings and result tables are in scripts/paper_experiments/.

Cite

Use the "Cite this repository" button on GitHub, or:

@software{marl_battlegrounds,
  author = {Hawili, Ulixes Tariq},
  title = {{MARL-BattleGrounds}: The JAX-native Benchmark for Heterogeneous and Competitive Multi-agent Reinforcement Learning},
  version = {1.0.0},
  year = {2026},
  url = {https://github.com/oceansystemslab/MARL-BattleGrounds}
}

Contribute

Pull requests are welcome. Start with CONTRIBUTING.md, and open an issue for bugs, ideas, questions and leaderboard submissions.

Author

MARL-BattleGrounds is developed by Ulixes Tariq Hawili as part of the SPADS CDT, University of Edinburgh School of Engineering, and the Ocean Systems Lab at HWU.

License

Licensed under the Apache License, Version 2.0.