Brief
Install the package, run a match, train an agent, validate it against the frozen interface contract, then upload it and climb the ladder. The whole loop is train → validate → upload.
| Arena | 3D box 100 × 100 × 100 m — z is altitude |
| Target | Static at (50, 50, 0), HP = 3 |
| Blue — defenders | 5 drones, scattered in a shell around the target (random per match) |
| Red — attackers | 5 drones, from a random bearing near the perimeter |
| Collisions | Any two drones within 2 m both die — friend or foe |
| Target hit | Any drone within 3 m removes 1 HP — a clumsy defender can wreck its own |
| Tick rate | 10 Hz, up to 600 ticks / 60 s |
| Outcome | Winner |
|---|---|
| Target HP reaches 0 | red — attackers |
| All attackers dead | blue — defenders |
| Time limit, target alive | blue — defenders |
One shared per-drone policy plays both sides (it reads
team_sign from the observation). Full obs/action/replay spec:
docs/CONTRACT.md.
1. Install
Ravens isn't on PyPI yet, so install straight from the repo. The
[student] extra is what you want: it adds the Gym training
env plus ONNX export/validate on top of the tiny numpy core.
# gym env + ONNX export/validate, straight from git
pip install "ravens[student] @ git+https://github.com/Quillstacks/ravens"
# or, to hack on the code, clone first then install editable
git clone https://github.com/Quillstacks/ravens
cd ravens
pip install -e ".[student]"
Bare pip install ravens is numpy-only —
tiny and fast. It runs the deterministic sim and ravens demo
on its own. [student] adds training + ONNX;
[server] is only for hosting the tournament.
2. Quickstart
Run a demo match
Baseline vs. baseline. Writes a replay you can drop into the 3D viewer.
ravens demoPick the fighters
Run any two policies head to head — here the seed champion against itself.
ravens play \
--blue heuristicOne \
--red heuristicOne3. Train your model
Train with any framework. One shared per-drone policy
plays both sides — it reads which side it's on from
team_sign in the observation. Two on-ramps:
Rule-based — quick
No training needed. Copy the reference template and edit the
policy() function — pure numpy.
cp starter-kit/heuristic_one.py \
my_agent.py
python my_agent.py # self-play replayDeep RL — strongest
SAC / TD3 self-play with Stable-Baselines3. GPU recommended for a real competitor.
pip install stable-baselines3 torch
# template lives in:
# starter-kit/rl_sb3/
The obs/action contract is frozen: input obs is a
float32 [N, 890] batch, output action is a
float32 [N, 3] desired-velocity vector. The full spec lives in
docs/CONTRACT.md.
4. Validate
Before you upload, check your exported ONNX against the contract and the
on-drone compute budget. ravens validate prints a clear
PASS/FAIL.
ravens validate model.onnx --side red --n 10
The ladder also requires a model card: a public repo plus a
filled-in MODEL_CARD.md documenting how the model was trained
(template in starter-kit/rl_sb3/).
5. Upload & climb
Submit your validated model on the upload page. Your model then fights the sampled ladder — best-of-3, playing both roles — and you can watch your replay against the champion.
New ELO ratings and replays publish every Monday. Win decisively to move further: the rating margin is graded on the match score, not just the win.