OpenField

Reinforcement learning environment simulating tactical-level medieval battlefields, starting with Roman legionary armies. Individual soldiers are fully simulated (position, HP, fatigue, morale) inside a recursive Legion → Cohort → Century command tree; v1 commands the Legion (General, a free-text VLM stand-in) and Century (Centurion, the precise structured VLC stand-in) echelons with heuristic policies on both sides, standing behind the same interface a future trained Vision-Language(-Code) Model will use. See docs/architecture.md for how it fits together, docs/combat_formulas.md for the combat/morale model, and docs/roadmap.md for what's deliberately not built yet.

Development setup

Requires a C++20 compiler and Python 3.10+.

python3 -m venv .venv
source .venv/bin/activate
pip install cmake ninja pybind11
pip install -e ".[dev,render]"

Build and run the C++ test suite:

cmake -S . -B build -G Ninja -DOPENFIELD_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Debug \
  -Dpybind11_DIR=$(python -c "import pybind11; print(pybind11.get_cmake_dir())")
cmake --build build
ctest --test-dir build --output-on-failure

Run the Python test suite and linter:

pytest
ruff check openfield scripts tests

Watch a heuristic Roman-vs-Warband battle end-to-end (writes an animated GIF plus before/after stills to docs/demo_output/):

python scripts/run_battle.py

Or watch it live in an interactive window (scroll to zoom, drag to pan):

python scripts/run_battle.py --live

Measure vectorized stepping throughput:

python scripts/bench_step_throughput.py