Sumobox — PettingZoo environment

A PettingZoo-compatible Paralell API two-agent 2D enviroment that simulates athletes in a ring. Two circular boxers fight in a sumo ring: move, turn, and throw accelerating punches; win by knocking the opponent out, exhausting them, or shoving them out of the ring.

See docs/PHYSICS.md for the authoritative spec and docs/MAPPING.md for the reference→Python audit.

Install

pip install -e .          # or: pip install numpy gymnasium pettingzoo pygame

Requires Python ≥ 3.9.

Quickstart

import numpy as np
from sumobox_env import parallel_env

env = parallel_env(render_mode="human")     # or render_mode="rgb_array" / None
observations, infos = env.reset(seed=0)

while env.agents:
    actions = {a: env.action_space(a).sample() for a in env.agents}
    observations, rewards, terminations, truncations, infos = env.step(actions)

env.close()

API surface

• possible_agents = ["boxer_red", "boxer_blue"] (homogeneous; ideal for self-play).
• Action (per agent): MultiDiscrete([9, 3, 3]) = (move, turn, hit).
  • move 0=none, 1=ahead, 2=back, 3=right, 4=left, 5=ahead-right, 6=ahead-left, 7=back-right, 8=back-left (relative to facing).
  • turn 0=none, 1=right, 2=left. hit 0=none, 1=left fist, 2=right fist.
• Observation (per agent): Box(33,) float32, egocentric (own 14 + relative 7 enemy 12); angles as (sin, cos). Index map: sumobox_env.observations.OBS_LABELS.
• Reward: dense +/− damage dealt/received per hit, − head-butts, and a terminal win bonus / loss penalty.
• infos: last_hit_strength, cause_of_death (ko/exhaustion/ringout), and live vitals per agent.
• raw_env(**kwargs) returns the AEC-wrapped variant.

Configuration

All kwargs default to the reference setup — parallel_env() is bit-for-bit the original. Pass any to parallel_env(...) / SumoboxParallelEnv(...):

kwarg	default	effect
arena_radius	350.0	ring play radius; smaller ⇒ tighter ring-outs (ring also rescales)
damage_multiplier	1.0	scales vitals damage + knockdown from landed strikes
knockback_multiplier	1.0	scales head/body knockback impulse
energy_regen_multiplier	1.0	scales stamina recovery rate
clearity_regen_multiplier	1.0	scales consciousness recovery rate
hand_hit_cooldown	0	min ticks a hand waits after returning home before re-firing
movement_speed	8.0	translational velocity cap
move_accel_multiplier	1.0	scales move acceleration
steering_speed	0.16	angular-velocity cap
turn_accel	0.04	angular acceleration per turn command
max_episode_steps	1500	truncation horizon
dense_reward	True	master switch for per-step damage shaping (off ⇒ sparse)
terminal_reward	True	master switch for terminal win/loss reward
k_hit,k_recv,k_headbutt	1.0	dense reward coefficients
win_bonus,loss_penalty	100.0	terminal rewards
ringout_extra_penalty	0.0	extra penalty when the loss is a ring-out

The reward is fully configurable: tune the coefficients individually, or flip dense_reward / terminal_reward to switch between dense, sparse-terminal-only, or fully custom regimes. Example — sparse win/loss only:

env = parallel_env(dense_reward=False)

env = parallel_env(arena_radius=250.0, damage_multiplier=1.5, hand_hit_cooldown=4)

Examples

python examples/random_rollout.py --episodes 3 --seed 0          # headless stats
python examples/random_rollout.py --render --seed 0              # watch a bout

Tests

pytest -q

Covers math helpers, physics invariants & lifecycle, hand-derived golden traces, the active-hand block mechanic, configurable parameters, rewards, rendering, and PettingZoo API conformance (parallel_api_test) + determinism.

Acknowlegements

This project is based off an experimental work with identical name conducted by a Youtube creator foo52ru/Simulife Hub. This project reimplements the enviroment used in it as a PettingZoo enviroment so that the agents can be driven by Reinforcement Learning or Neuroevolution techniques. The default physics (movement, hand/punch mechanics, collisions, consciousness/energy, knockdown, damage, knockback, knockout) alongside the arena graphics are faithfully reproduced from it.