Back to the clubBUILD A
FIGHTER.
One duck. Your policy. A ring to defend.
Start with the working match room, bring an ONNX fighter, and see what happens when another duck pushes back.
Your first fight.
The full match UI runs on your computer. Install Git and uv, then run:
git clone https://github.com/picsoung/duckfight-sumo.git
cd duckfight-sumo
uv sync --locked
uv run duckfight fetch-baselines
uv run duckfight serveOpen 127.0.0.1:8000 and choose Run exhibition. Upload your own policy for either corner when you are ready.
Python 3.12 is required; uv can install it. The kit includes the robot, collision meshes, two walking policies, fonts, branding, and browser renderer. No GPU, Node.js, training checkout or account is needed to run matches. Initial dependency installation needs internet.
Download source ZIPStay in.
Push them out.
These are the implemented practice rules. The referee reads the physics, not the animation.
- The boundary
- A ring-out happens when the duck's trunk center stays strictly beyond the yellow line for 100 ms continuously. A foot or beak crossing alone is not out. Coming back in clears the timer.
- The ring
- Radius ends at the outside of the yellow line. The pink apron is out of bounds. At 1 m radius, the fighting diameter is 2 m; the whole visual platform is 2.62 m across. There are no ropes or walls, and the floor continues outside the ring.
- Falls & draws
- Falling is legal. There is no knockdown elimination. Simultaneous ring-outs and timeouts are draws. A timeout shows DRAW · TIME LIMIT on screen.
- Match formats
- Single bout plays one round, then stops. First-to-two swaps sides after every round, including draws, for up to five rounds. Draws do not score. If neither duck reaches two wins, the match is drawn; a partial 1:0 score does not decide it.
- Faults
- A policy error, inference timeout, wrong action shape or non-finite action loses the round. Two policy faults on the same step draw. A numerical simulator failure voids the match.
- The clock
- Both policies run at 50 Hz; physics and servo dynamics run at 200 Hz. Policies and the bout clock stay frozen during the 3–2–1 countdown.
Practice settings, not a frozen event preset. The normal UI starts at 1 m radius / 30 seconds. The exhibition uses 0.5 m / 30 seconds to encourage contact. Final tournament settings, compute limits, policy lock and drawn-bracket-match procedure will be published before competitive submissions close.
One file.
Fourteen actions.
Training tools are your choice. Match-time inference uses the published CPU interface.
Upload one self-contained .onnx file, at most 32 MiB. It must have one float32 input and one [1,14] float32 output. Feed-forward actors are supported; extra recurrent-state inputs are not.
| Contract | Input | Who chooses the tactics? |
|---|---|---|
locomotion_v1 | [1,61] | The app supplies Pressure, Counter, Chase, Retreat or Hold commands. |
sumo_v1 | [1,72] | Your actor observes the opponent and boundary. App tactics are ignored. |
Autonomous models must declare ONNX metadata duckfight_contract=sumo_v1. Include normalization and preprocessing in the graph. If a sumo strategy uses a walking policy, export both stages together; the kit includes a working example.
Outputs are raw joint actions. The runner applies HOME + action × action_scale exactly once. Joint order, HOME and metadata are provided in the full policy contract.
See the 72 observation values
| Indices | Observation | Convention |
|---|---|---|
| 0–2 | Base angular velocity | rad/s, body frame |
| 3–5 | Projected gravity | World down in trunk frame |
| 6–19 | Joint positions minus HOME | Radians, shared joint order |
| 20–33 | Joint velocities | rad/s, previous control step |
| 34–47 | Previous policy actions | Independent history per duck |
| 48–60 | Velocity, head and body commands | All zero for autonomous sumo_v1 |
| 61–62 | Relative opponent position | Metres, own yaw frame |
| 63–64 | Relative opponent planar velocity | m/s, own yaw frame |
| 65–66 | Relative opponent yaw | Sine and cosine |
| 67–68 | Vector to ring center | Metres, own yaw frame |
| 69 | Distance remaining to boundary | Metres; negative outside |
| 70 | Fraction of round time remaining | 1 at start; 0 at limit |
| 71 | Opponent uprightness | 1 upright; −1 inverted |
Matches use ONNX Runtime 1.24.4 on CPU. Participant Python dependencies, custom operator libraries, external weight files, network services and CUDA-only inference are not supported submission bundles. The current 200 ms per-call guard is a fault limit, not a promise of 50 Hz real time; both actors and physics share each 20 ms control interval.
Make it better.
Prove it in the ring.
Keep training, compatibility checks and measured match results as separate steps.
Available now: the local arena, example walkers, combined commander/walker exporter, policy validator, and evaluation across seeds and both starting sides.
uv run duckfight validate policies/my-fighter.onnx
uv run duckfight evaluate \
--a policies/my-fighter.onnx \
--b policies/velstand.onnx --b-strategy counter \
--radius 1 --time-limit 30 --seeds 1 2 3 4 5 \
--output runs/my-evaluation.jsonThe evaluator freezes policy files and records wins, draws, faults, contact and runtime hashes. Every seed runs on both starting sides. Test several opponents and fresh seeds. Local scores can differ across hardware; official competition needs one announced runner platform.
Still to build: the GPU sumo PPO recipe, self-play and a trainable sumo baseline. The included walkers and scripted commanders are not presented as sumo-trained policies. Use Microduck RL for robot/PPO/export foundations and Microduck Challenges for its frozen-opponent training pattern. GPU training requires an appropriate NVIDIA GPU or supported hosted job; CPU practice does not.
For now, validate and test locally. The website does not accept policy uploads or enter you into an official ranking. Register your team for event coordination.