Skip to content

AGENTS.md

Latest commit

 

History

History
107 lines (77 loc) · 8.27 KB

AGENTS.md

File metadata and controls

107 lines (77 loc) · 8.27 KB
Raw

AGENTS.md

Guidance for AI coding agents (Codex, Claude Code, etc.) working in this repository. Humans should start with README.md; this file restates the project rules in the operational order an agent needs them.

What this repository is

This is baba-is-auto, a C++17 Baba Is You simulator with reinforcement learning examples, a pygame GUI, and a Python API exposed through pybind11.

It is not just a single C++ library:

  • The core simulator is in Includes/baba-is-auto/ and Sources/baba-is-auto/.
  • The Python extension under Extensions/BabaPython/ mirrors parts of the core API and implementation.
  • Python GUI/RL examples consume the Python-facing behavior from Extensions/BabaGUI/ and Extensions/BabaRL/.
  • Test fixtures and sample levels live in Resources/Maps/.

Upstream lives at https://github.com/utilForever/baba-is-auto.git.

Golden rules (read before any change)

  1. Keep the C++ core and Python binding in sync. If you change game, map, rule, enum, object, or agent behavior in the core library, check whether the mirrored files under Extensions/BabaPython/ need the same update.
  2. Do not hand-edit generated aggregate headers casually. Includes/baba-is-auto.hpp is generated by Scripts/header_gen.py during the CMake build. Change headers or the generator instead of treating the generated file as the primary source.
  3. Use CMake targets as the source of truth. Before adding or moving C++ files, read the relevant CMakeLists.txt so the intended target will build on Ubuntu, macOS, and Windows.
  4. Preserve C++17 portability. Avoid compiler-specific assumptions unless they are guarded by CMake or clearly isolated.
  5. Do not add unpinned Python dependencies. requirements.txt is hash-pinned and CI installs it with --require-hashes.
  6. Run the relevant tests before considering behavior changes complete. Documentation-only changes usually do not need a build, but code or API changes should be verified with the commands below.

The most common task: changing simulator behavior

  1. Find the domain in Sources/baba-is-auto/ and the matching public headers in Includes/baba-is-auto/.
  2. Check for mirrored binding code in Extensions/BabaPython/Includes/ and Extensions/BabaPython/Sources/.
  3. Update or add doctest coverage in Tests/UnitTests/ when the C++ behavior changes.
  4. If Python-visible behavior changes, update Tests/PythonTests/ and build the extension in place before running pytest.
  5. If a map fixture is needed, keep it small and place reusable fixtures in Resources/Maps/.
  6. Rebuild and run the relevant C++ and Python tests.

Repository map

Use this map to jump to the right part of the tree before editing:

Area Paths What to check there
Core C++ API Includes/baba-is-auto/ Public headers, exported types, generated umbrella header inputs
Core C++ implementation Sources/baba-is-auto/ Game, map, object, rule, and agent behavior
Python binding Extensions/BabaPython/Includes/, Extensions/BabaPython/Sources/, Extensions/BabaPython/main.cpp pybind11-facing API and mirrored C++ code that may need core updates
GUI simulator Extensions/BabaGUI/ pygame consumer of the Python API
RL examples Extensions/BabaRL/ gym-style environments, rendering helpers, and training scripts
C++ tests Tests/UnitTests/ doctest coverage for simulator behavior
Python tests Tests/PythonTests/ pytest coverage for Python-visible behavior
Map fixtures Resources/Maps/ Small text levels used by tests and examples
Build configuration CMakeLists.txt, Sources/baba-is-auto/CMakeLists.txt, Tests/UnitTests/CMakeLists.txt, Extensions/BabaPython/CMakeLists.txt Target membership, dependency wiring, generated header behavior
Python packaging setup.py, requirements.txt Extension build settings and hash-pinned Python dependencies
Project tooling Scripts/, CMake/, vcpkg.json Header generation, CMake helpers, and native dependency manifest
CI .github/workflows/ Platform matrix and required build/test sequence
Media assets Medias/, extension sprites/ directories Images and sprites; usually leave these alone unless the task is asset-related

Build and validation

Set VCPKG_ROOT or CMAKE_TOOLCHAIN_FILE before configuring. The root CMakeLists.txt will use either environment variable automatically.

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --config Release

Run C++ unit tests after building:

./build/bin/UnitTests

On Windows release builds, the executable is usually:

build\bin\Release\UnitTests.exe

Run Python tests after building the extension in place:

python -m pip install --require-hashes -r requirements.txt
python setup.py build_ext --inplace
python -m pytest Tests/PythonTests/

For coverage work, CI configures a Debug build with -DBUILD_COVERAGE=ON, runs UnitTests, collects coverage with lcov, and uploads the cleaned report to Codecov.

CI expectations

The main GitHub Actions workflows build on Ubuntu, macOS, and Windows. They configure CMake with vcpkg, build the C++ project, run UnitTests, install the Python requirements with --require-hashes, build the pybind11 extension in place, and run pytest against Tests/PythonTests/.

Treat those workflows as the compatibility contract. A change that only works on the local platform is not complete.

Commit conventions

  • Use focused commits with conventional prefixes where they fit: feat:, fix:, refactor:, test:, docs:, or chore:.
  • Keep generated or mirrored updates in the same commit as the source change that requires them.
  • Do not mix documentation, dependency, and behavior changes unless they are part of the same logical fix.
  • For agent-assisted commits, it is fine to include an Assisted-by: trailer if the maintainer wants that recorded.

Things to leave alone unless explicitly asked

  • Large vendored assets, sprites, and media files under Medias/ and extension sprite directories.
  • Hash pins in requirements.txt, unless the task is specifically a dependency update.
  • Generated aggregate headers, unless the generator output is the actual target of the change.
  • CI matrix entries and platform versions, unless the task is about CI support.