magsim - A Magical Athlete Simulator

A fan-made Python simulation engine and analysis toolkit for the board game Magical Athlete.

BoardGameGeek · CMYK Games · Designer Diary · Art Blog

---

What is this?

Magical Athlete is a draft-based racing board game where you roll a die to move, but every racer has a game-breaking, unique ability.

magsim translates the physical game into a high-performance Python engine. Capable of running 60+ full races per second with complete state logging, it allows you to:

• Simulate Races: Run single game simulations in the command line or UI
• Data Generation: Run high-volume batch simulations to generate datasets for analysis
• Visual Analytics: Visualize races and analyze aggregated data in a reactive marimo dashboard
• A/B Experiments: Pit Smart AI against Random AI, compare the impact of racers and measure modifying rules changes the balance via the CLI tool

---

Quickstart

The fastest way to use magsim is via the web-based frontend. The dashboard runs in WASM-mode, expect long loading times.

To run magsim locally, I recommend using uv (Install uv here).

1. Run a single test race:

uvx magsim game

2. Run a game with specific configuration:

uvx magsim game -n 6 -b standard -r Egg Magician

3. Launch the interactive dashboard locally:

uvx magsim gui

---

Command Line Interface

magsim ships with a powerful CLI for running simulations, conducting A/B testing, and generating datasets.

---

magsim game

Run a single game simulation. If no board or racers are specified, the engine will pick defaults and a random seed.

Option	Flag	Description
Racers	-r, --racers	Space-separated list of racer names to include.
Player Count	-n, --number	Target number of racers. Roster is filled with unique randoms if fewer are provided.
Board	-b, --board	The name of the board to race on.
RNG Seed	-s, --seed	Integer seed for reproducible races.
Config File	-c, --config	Path to a TOML configuration file.
Encoding	-e, --encoding	Base64 encoded configuration string.
House Rules	-H, --houserule	Repeatable key-value pairs for custom rules (e.g., start_pos=5).
Max Turns	--max-turns	Safety cutoff for infinite loops. (Default: 200)

Config Precedence: 1. CLI Args ➔ 2. Base64 Encoding ➔ 3. TOML Config ➔ 4. Defaults

Examples:

# Basic quickstart
magsim game -n 6 -b WildWilds

# Specific matchups with a fixed seed
magsim game -r Mouth BabaYaga -n 5 -s 123

---

magsim batch

Run high-volume batch simulations driven by a TOML configuration. Saves results to .parquet files for the frontend dashboard.

Option	Flag	Description
Config	<path>	(Required) Path to the TOML simulation config file.
Runs	--runs	Override the number of runs per combination.
Max Runs	--max	Override the maximum total runs across the batch.
Turn Limit	--turns	Override the max turns per race.
Seed Offset	--seed-offset	Offset for RNG seeds to prevent overlap. (Default: 0)
Force	-f, --force	Delete existing Parquet/DuckDB files in results/ without prompting.

Examples:

magsim batch configs/sim.toml --runs 50 --max 100000 
magsim batch configs/sim.toml --force

---

magsim compare

Run comparative A/B experiments. Appends run histories to Parquet files in results/. All commands accept -n (total games) and -o (save markdown report to path).

Command	Target	Description
ai	<RACER>	Pits a Smart AI against a Baseline Random AI.
rule	<k=v>	Default rules vs a modified setting.
racer	<RACER>	The overall impact of one specific racer on the field.

Examples:

# Test how 'Mouth' performs with Smart AI vs Random AI over 1000 games
magsim compare ai Mouth -n 1000 -o results/ai_mouth.md

# Evaluate the impact of a house rule (e.g., Mastermind steals 1st place)
magsim compare rule hr_mastermind_steal_1st=True -n 2000

# See how 'BabaYaga' warps the win rates of the rest of the field
magsim compare racer BabaYaga -n 3000

---

magsim recompute

Internal data analysis and aggregation tools. Both commands accept -f, --folder to target a specific data directory (Default: results/).

Command	Description	Example
aggregate	Recomputes internal statistical aggregates.	magsim recompute aggregate
stats	Generates a fresh racer_stats.json file.	magsim recompute stats -f custom_results/

---

magsim gui

Instantly launch the interactive simulation analysis dashboard.

magsim gui

---

🖥️ Run GUI Locally

If you want to modify the dashboard or analyze custom datasets, you can run the project locally from a cloned repository.

1. Clone the repository:

git clone https://github.com/pschonev/magical-athlete-simulator.git
cd magical-athlete-simulator

2. Generate your custom dataset:

magsim batch configs/sim.toml

3. Start the dashboard:

uv run marimo run --no-sandbox frontend/magical_athlete_analysis.py

---

Changelog

See the CHANGELOG.md for version history.