A C++17 Baba Is You simulator with Python bindings, GUI, and reinforcement-learning examples

What This Project Does

baba-is-auto simulates a subset of Baba Is You: it loads a text map, parses rules formed by word tiles, applies movement and object interactions, and exposes the resulting state to C++ and Python callers.

The repository provides:

• A reusable C++17 simulator library.
• A pyBaba Python extension built with pybind11.
• A pygame GUI that consumes the Python API.
• Gym-style reinforcement-learning environments with DQN and REINFORCE examples.
• An optional C++ ImGui level editor.

For the simulator design and behavior contract, see ARCHITECTURE.md. Contributors and coding agents should also read AGENTS.md.

What Is Baba Is You?

Baba Is You is an award-winning puzzle game in which the rules are physical blocks. Moving those blocks can change the player, obstacles, and win condition while a level is in progress.

Quick Start

Prerequisites

• CMake 3.31.6 or later
• A C++17 compiler
• Python 3 with development headers
• Git

Platform-specific tools:

• Windows: Visual Studio 2022 with the Desktop development with C++ workload.
• macOS: Xcode Command Line Tools, plus autoconf, autoconf-archive, automake, curl, libtool, pkg-config, tar, unzip, and zip.
• Ubuntu: build-essential, autoconf, autoconf-archive, automake, curl, libtool, pkg-config, python3-dev, python3-setuptools, tar, unzip, and zip.

1. Install vcpkg

Clone and bootstrap vcpkg, then expose its location to CMake.

macOS and Linux:

git clone https://github.com/microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh
export VCPKG_ROOT="$PWD/vcpkg"

Windows PowerShell:

git clone https://github.com/microsoft/vcpkg.git
.\vcpkg\bootstrap-vcpkg.bat
$env:VCPKG_ROOT = (Resolve-Path .\vcpkg)

The environment variable only needs to be set in the shell used to build the project. Alternatively, set CMAKE_TOOLCHAIN_FILE to the absolute path of scripts/buildsystems/vcpkg.cmake inside the vcpkg checkout.

2. Clone

git clone https://github.com/utilForever/baba-is-auto.git
cd baba-is-auto

3. Build

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

vcpkg installs the dependencies declared in vcpkg.json during configuration. The root CMake project then builds the baba-is-auto library, pyBaba extension, and UnitTests executable.

4. Run the C++ Tests

macOS and Linux:

./build/bin/UnitTests

Windows release builds:

.\build\bin\Release\UnitTests.exe

Python API

Build and install pyBaba with:

python -m pip install .

Level Editor

Enable the optional editor feature and build its target:

cmake -S . -B build-editor -DBABA_BUILD_EDITOR=ON
cmake --build build-editor --target BabaEditor --config Release

Reinforcement-Learning Examples

Each bundled environment uses the actions UP, DOWN, LEFT, and RIGHT.

Environment	Level	Algorithms
baba-babaisyou-v0	Environment	DQN, REINFORCE
baba-outofreach-v0	Environment	DQN, REINFORCE
baba-volcano-v0	Environment	DQN, REINFORCE

Architecture at a Glance

Area	Paths
Core C++ API	Includes/baba-is-auto/
Core C++ implementation	Sources/baba-is-auto/
Python binding	Extensions/BabaPython/
GUI simulator	Extensions/BabaGUI/
Level editor	Extensions/BabaEditor/
RL examples	Extensions/BabaRL/
C++ and Python tests	Tests/UnitTests/, Tests/PythonTests/
Map fixtures	Resources/Maps/

The C++ core is the source of simulator behavior, and Extensions/BabaPython/ mirrors its public surface. Changes to games, maps, rules, enums, objects, or agents should keep both layers in sync. The aggregate header Includes/baba-is-auto/baba-is-auto.hpp is generated during the CMake build; edit the individual headers or generator instead.

Development

Run the Python checks used by CI 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/

GitHub Actions builds and tests the project on Ubuntu, macOS, and Windows. See AGENTS.md for the complete validation matrix and repository rules.

Contributing

Issues and pull requests are welcome. Keep changes focused, add the narrowest test that covers behavior changes, and follow AGENTS.md.

Acknowledgement

Thank you to Arvi "Hempuli" Teikari for allowing this project to be developed. Baba Is You and its original game concepts belong to Hempuli.

License

This project is licensed under the MIT License.

Copyright © 2020-2026 Chris Ohk.