mettagrid 0.1.6__tar.gz → 0.2.0.1__tar.gz

mettagrid-0.2.0.1/.bazelrc

@@ -0,0 +1,65 @@
+# Bazel configuration for mettagrid
+
+# Common C++ build flags
+build --cxxopt=-std=c++20
+build --host_cxxopt=-std=c++20
+
+# Use the current Python from environment
+build --action_env=PYTHON_BIN_PATH
+build --action_env=PYTHON_LIB_PATH
+build --python_path=python
+
+# Prod build mode. --compilation_mode=[opt|dbg] is a required Bazel field.
+build:opt --compilation_mode=opt
+build:opt --copt=-O3
+build:opt --copt=-DNDEBUG
+build:opt --strip=always
+
+# Debug build mode. --compilation_mode=[opt|dbg] is a required Bazel field.
+build:dbg --compilation_mode=dbg
+build:dbg --copt=-O0
+build:dbg --copt=-g
+build:dbg --strip=never
+
+# Test configuration
+test --test_output=errors
+test --test_summary=detailed
+
+# Coverage configuration
+coverage --combined_report=lcov
+coverage --instrumentation_filter=//:mettagrid_lib,//:mettagrid_c
+
+# Platform-specific settings for macOS
+build:macos --copt=-fvisibility=hidden
+build:macos --cxxopt=-stdlib=libc++
+build:macos --linkopt=-stdlib=libc++
+
+# Platform-specific settings for Linux
+build:linux --copt=-fvisibility=hidden
+
+# Detect and use platform config automatically
+build --enable_platform_specific_config
+
+# Silence some warnings in external dependencies
+build --per_file_copt=external/.*@-w
+
+# Enable colors in output
+common --color=yes
+
+# Show progress messages
+common --show_progress_rate_limit=0.5
+
+# Local disk cache configuration
+build --disk_cache=~/.cache/bazel
+build --repository_cache=~/.cache/bazel-repo
+
+# Build execution optimization
+build --jobs=auto
+build --local_test_jobs=auto
+
+# CI configuration - use system Python to avoid root user issues
+# Remove BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN to allow toolchain detection
+build:ci --repo_env=PYTHON_BIN_PATH=/usr/bin/python3
+build:ci --python_path=/usr/bin/python3
+# Skip hermetic Python toolchain in CI
+build:ci --@rules_python//python/config_settings:bootstrap_impl=system

mettagrid-0.2.0.1/BUILD.bazel

@@ -0,0 +1,60 @@
+# BUILD.bazel file for mettagrid C++ extension module
+load("@pybind11_bazel//:build_defs.bzl", "pybind_extension", "pybind_library")
+
+# Basic compiler flags
+COPTS = [
+    "-std=c++20",
+    "-fvisibility=hidden",
+    "-DNPY_NO_DEPRECATED_API=NPY_1_7_API_VERSION",
+    "-O3",
+    "-DNDEBUG",
+]
+
+# Library for tests - use pybind_library without hidden visibility
+pybind_library(
+    name = "mettagrid_lib",
+    srcs = glob([
+        "src/metta/mettagrid/*.cpp",
+        "src/metta/mettagrid/**/*.cpp",
+    ]),
+    hdrs = glob([
+        "src/metta/mettagrid/*.hpp",
+        "src/metta/mettagrid/**/*.hpp",
+    ]),
+    copts = [
+        "-std=c++20",
+        "-DNPY_NO_DEPRECATED_API=NPY_1_7_API_VERSION",
+        "-O3",
+        "-DNDEBUG",
+    ],  # Removed -fvisibility=hidden
+    includes = ["src/metta", "src/metta/mettagrid"],
+    visibility = ["//visibility:public"],
+)
+
+# Python extension module
+pybind_extension(
+    name = "mettagrid_c",
+    srcs = glob([
+        "src/metta/mettagrid/*.cpp",
+        "src/metta/mettagrid/**/*.cpp",
+        "src/metta/mettagrid/*.hpp",
+        "src/metta/mettagrid/**/*.hpp",
+    ]),
+    copts = COPTS,
+    includes = ["src/metta/mettagrid"],
+    visibility = ["//visibility:public"],
+)
+
+# Export the .clang-tidy config file for use by the linter
+exports_files([".clang-tidy"])
+
+# Export source files for test_mettagrid
+exports_files(
+    glob([
+        "src/metta/mettagrid/*.cpp",
+        "src/metta/mettagrid/**/*.cpp",
+    ]),
+    visibility = ["//visibility:public"],
+)
+
+

mettagrid-0.2.0.1/MANIFEST.in

@@ -0,0 +1,7 @@
+include bazel_build.py
+include BUILD.bazel
+include MODULE.bazel
+include MODULE.bazel.lock
+include .bazelrc
+recursive-include src/metta/mettagrid *.cpp *.hpp
+

mettagrid-0.2.0.1/MODULE.bazel

@@ -0,0 +1,34 @@
+# MODULE.bazel for mettagrid - using Bzlmod (modern Bazel module system)
+module(name = "mettagrid", version = "0.1.6")
+
+# Basic Bazel dependencies
+bazel_dep(name = "platforms", version = "1.0.0")
+bazel_dep(name = "bazel_skylib", version = "1.8.1")
+
+# C++ rules and toolchain
+bazel_dep(name = "rules_cc", version = "0.2.0")
+
+# Python toolchain - use latest compatible version
+bazel_dep(name = "rules_python", version = "1.5.3")
+
+python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+python.toolchain(
+    python_version = "3.11",
+    is_default = True,
+)
+
+# pybind11 for Python bindings
+bazel_dep(name = "pybind11_bazel", version = "2.13.6")
+
+# Google Test for testing
+bazel_dep(name = "googletest", version = "1.17.0")
+
+# Google Benchmark for benchmarking
+bazel_dep(name = "google_benchmark", version = "1.9.4")
+
+# Abseil (dependency of some Google libraries)
+bazel_dep(name = "abseil-cpp", version = "20250814.0")
+
+# Linting and formatting with rules_lint
+bazel_dep(name = "aspect_bazel_lib", version = "2.21.1")
+bazel_dep(name = "aspect_rules_lint", version = "1.6.0")

mettagrid-0.2.0.1/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: mettagrid
+Version: 0.2.0.1
+Summary: A fast grid-based open-ended MARL environment
+Author-email: David Bloomin <daveey@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://daveey.github.io
+Project-URL: Repository, https://github.com/Metta-AI/mettagrid
+Keywords: gridworld,minigrid,rl,reinforcement-learning,environment,gym
+Requires-Python: ==3.11.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3>=1.38.32
+Requires-Dist: botocore>=1.38.29
+Requires-Dist: google-api-python-client>=2.0.0
+Requires-Dist: google-auth>=2.0.0
+Requires-Dist: google-auth-oauthlib>=1.0.0
+Requires-Dist: gymnasium==0.29.1
+Requires-Dist: matplotlib>=3.10.3
+Requires-Dist: numpy<2,>=1.26.4
+Requires-Dist: omegaconf>=2.3.0
+Requires-Dist: duckdb>=1.3.0
+Requires-Dist: pettingzoo<1.25,>=1.24.1
+Requires-Dist: pufferlib<3.1.0,>=3.0.0
+Requires-Dist: pydantic>=2.11.5
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: scipy>=1.15.3
+Requires-Dist: wandb>=0.19.11
+Dynamic: license-file
+
+# MettaGrid Environment
+
+MettaGrid is a multi-agent gridworld environment for studying the emergence of cooperation and social behaviors in
+reinforcement learning agents. The environment features a variety of objects and actions that agents can interact with
+to manage resources, engage in combat, share with others, and optimize their rewards.
+
+## Overview
+
+In MettaGrid, agents navigate a gridworld and interact with various objects to manage their energy, harvest resources,
+engage in combat, and cooperate with other agents. The key dynamics include:
+
+- **Energy Management**: Agents must efficiently manage their energy, which is required for all actions. They can
+  harvest resources and convert them to energy at charger stations.
+- **Resource Gathering**: Agents can gather resources from generator objects scattered throughout the environment.
+- **Cooperation and Sharing**: Agents have the ability to share resources with other agents and use energy to power the
+  heart altar, which provides rewards.
+- **Combat**: Agents can attack other agents to temporarily freeze them and steal their resources. They can also use
+  shields to defend against attacks.
+
+The environment is highly configurable, allowing for experimentation with different world layouts, object placements,
+and agent capabilities.
+
+## Objects
+
+### Agent
+
+<img src="https://github.com/daveey/Griddly/blob/develop/resources/images/oryx/oryx_tiny_galaxy/tg_sliced/tg_monsters/tg_monsters_astronaut_u1.png?raw=true" width="32"/>
+
+The `Agent` object represents an individual agent in the environment. Agents can move, rotate, attack, and interact with
+other objects. Each agent has energy, resources, and shield properties that govern its abilities and interactions.
+
+### Altar
+
+<img src="https://github.com/daveey/Griddly/blob/develop/resources/images/oryx/oryx_tiny_galaxy/tg_sliced/tg_items/tg_items_heart_full.png?raw=true" width="32"/>
+
+The `Altar` object allows agents to spend energy to gain rewards. Agents can power the altar by using the `use` action
+when near it. The altar has a cooldown period between uses.
+
+- Using the heart altar costs `altar.use_cost energy`. So, no matter how much energy you have, you are always dumping
+  the same amount of energy in it and getting the same amount of reward.
+- After the heart altar is used, it is unable to be used for altar.cooldown timesteps.
+- A single use of the heart altar gives you a single unit of reward: if
+  `target._type_id == ObjectType.AltarT: self.env._rewards[actor_id] += 1`
+
+### Converter
+
+<img src="https://github.com/daveey/Griddly/blob/develop/resources/images/oryx/oryx_tiny_galaxy/tg_sliced/tg_items/tg_items_pda_A.png?raw=true" width="32"/>
+
+The `Converter` object allows agents to convert their harvested resources into energy. Agents can use converters by
+moving to them and taking the `use` action. Each use of a converter provides a specified amount of energy and has a
+cooldown period.
+
+- Using the converter does not cost any energy.
+- Using the converter outputs `converter.energy_output.r1` energy
+  - see `this.output_energy = cfg[b"energy_output.r1"]` in the Converter cppclass
+- Using the converter increments resource 2 by one and decrements resource 1 by 1
+- There is currently no use for `converter.energy_output.r2` and `converter.energy_output.r3`
+- After the converter is used, it is unable to be used for `converter.cooldown` timesteps
+
+### Generator
+
+<img src="https://github.com/daveey/Griddly/blob/develop/resources/images/oryx/oryx_fantasy/ore-0.png?raw=true" width="32"/>
+
+The `Generator` object produces resources that agents can harvest. Agents can gather resources from generators by moving
+to them and taking the `use` action. Generators have a specified capacity and replenish resources over time.
+
+- Using the generator once gives one resource 1
+- After the generator is used, it is unable to be used for `generator.cooldown` timesteps
+
+### Wall
+
+<img src="https://github.com/daveey/Griddly/blob/develop/resources/images/oryx/oryx_fantasy/wall2-0.png?raw=true" width="32"/>
+
+The `Wall` object acts as an impassable barrier in the environment, restricting agent movement.
+
+### Cooldown
+
+The `cooldown` property determines how long before objects can be used again.
+
+## Actions
+
+### Move / Rotate
+
+The `move` action allows agents to move to an adjacent cell in the gridworld. The action has two modes: moving forward
+and moving backward relative to the agent's current orientation.
+
+The `rotate` action enables agents to change their orientation within the gridworld. Agents can rotate to face in four
+directions: down, left, right, and up.
+
+### Attack
+
+The `attack` action allows agents to attack other agents or objects within their attack range. Successful attacks freeze
+the target for `freeze_duration` timesteps and allow the attacker to steal resources. Further, the attacked agent's
+energy is set to `0`. Attacks have a cost and inflict a damage value. The agent selects from one of nine coordinates
+within its attack range.
+
+### Shield (Toggle)
+
+The `shield` action turns on a shield. When the shield is active, the agent is protected from attacks by other agents.
+The shield consumes energy defined by `upkeep.shield` while active. Attack damage is subtracted from the agent's energy,
+rather than freezing the agent.
+
+### Transfer
+
+The `transfer` action enables agents to share resources with other agents. Agents can choose to transfer specific
+resources to another agent in an adjacent cell. It is currently not implemented.
+
+### Use
+
+The `use` action allows agents to interact with objects such as altars, converters, and generators. The specific effects
+of the `use` action depend on the target object and can include converting resources to energy, powering the altar for
+rewards, or harvesting resources from generators.
+
+### Swap
+
+The `swap` action allows agents to swap positions with other agents. It is currently not implemented.
+
+## Configuration
+
+The MettaGrid environment is highly configurable through the use of YAML configuration files. These files specify the
+layout of the gridworld, the placement of objects, and various properties of the objects and agents.
+
+**Current settings:**
+
+1. Ore   - Base resource obtained from mines. Mines produce one ore when used. No resource requirements for use.   -
+   Reward value: 0.005 per unit (max 2)   - Used to create batteries and lasers
+2. Battery   - Intermediate resource created from ore at a generator. Generator turns one ore into one battery.   -
+   Reward value: 0.01 per unit (max 2)   - Used to create hearts and lasers
+3. Heart / heart altar   - High value reward, requires 3 batteries to be converted into a heart at a heart altar.
+4. Laser   - Weapon resource created from ore and batteries. Requires 1 ore and 2 batteries. Created at the lasery.
+
+- Consumed on use. When hitting an unarmored agent: freezes them and steals their whole inventory. When hitting an
+  armoured agent, destroys their armor. **Inventory System**
+- Agents have limited inventory space (default max: 50 items)
+- Resources provide rewards just by being in inventory (up to their max reward value)
+- Resources can be stolen through attacks Objects Various buildings: Mine, Generator, Armory, Lasery, Altar, Lab,
+  Factory, Temple.
+- HP — hitpoints, the number of times something can be hit before destruction.
+- Cooldown between uses (varies by building)
+- Can be damaged and destroyed by attacks
+
+## Environment Architecture
+
+MettaGrid uses a modular architecture designed primarily for the Softmax Studio ML project, with lightweight adapters to
+maintain compatibility with external RL frameworks:
+
+### Primary Training Environment
+
+**`MettaGridEnv`** - The main environment actively developed for Softmax Studio training systems
+
+- Full-featured environment with comprehensive stats collection, replay recording, and curriculum support
+- Inherits from `MettaGridCore` for C++ environment implementation
+- **Exclusively used** by `metta.rl.trainer` and `metta.sim.simulation`
+- Continuously developed and optimized for Softmax Studio use cases
+- Backward compatible with existing training code
+
+### Core Infrastructure
+
+**`MettaGridCore`** - Low-level C++ environment wrapper
+
+- Foundation that provides the core game mechanics and performance
+- **Not used directly** for training - serves as implementation detail for `MettaGridEnv`
+- Provides the base functionality that external adapters wrap
+
+### External Framework Compatibility Adapters
+
+Lightweight wrappers around `MettaGridCore` to maintain compatibility with other training systems:
+
+- **`MettaGridGymEnv`** - Gymnasium compatibility for research workflows
+- **`MettaGridPettingZooEnv`** - PettingZoo compatibility for multi-agent research
+- **`MettaGridPufferEnv`** - PufferLib compatibility for high-performance external training
+
+**Important**: These adapters are **only used with their respective training systems**, not with the Metta trainer.
+
+### Design Philosophy
+
+- **Primary Focus**: `MettaGridEnv` receives active development and new features for Softmax Studio
+- **Compatibility Maintenance**: External adapters ensure other frameworks continue working as the core evolves
+- **Testing for Compatibility**: Demos verify external frameworks remain functional during core development
+- **Clear Separation**: Each environment type serves its specific training system - no mixing between systems
+
+### Compatibility Testing Demos
+
+These demos ensure external framework adapters remain functional as the core environment evolves:
+
+```bash
+# Verify PettingZoo compatibility
+python -m mettagrid.demos.demo_train_pettingzoo
+
+# Verify PufferLib compatibility
+python -m mettagrid.demos.demo_train_puffer
+
+# Verify Gymnasium compatibility
+python -m mettagrid.demos.demo_train_gym
+```
+
+The demos serve as regression tests to catch compatibility issues during core development, ensuring external users can
+continue using their preferred frameworks.
+
+## Building and testing
+
+For local development, refer to the top-level [README.md](../README.md) in this repository.
+
+### Bazel
+
+By default, `uv sync` will run the Bazel build automatically via the custom build backend. If you need to run C++ tests
+and benchmarks directly, you'll need to invoke `bazel` directly.
+
+Build C++ tests and benchmarks in debug mode:
+
+```sh
+# Build with debug flags
+bazel build --config=dbg //:mettagrid_c
+# Run all tests
+bazel test //...
+```
+
+For benchmarks you might prefer to use the optimized build:
+
+```sh
+# Build with optimizations
+bazel build --config=opt //:mettagrid_c
+
+# Run benchmarks
+./build-release/benchmarks/grid_object_benchmark
+```

mettagrid-0.2.0.1/README.md

@@ -0,0 +1,226 @@
+# MettaGrid Environment
+
+MettaGrid is a multi-agent gridworld environment for studying the emergence of cooperation and social behaviors in
+reinforcement learning agents. The environment features a variety of objects and actions that agents can interact with
+to manage resources, engage in combat, share with others, and optimize their rewards.
+
+## Overview
+
+In MettaGrid, agents navigate a gridworld and interact with various objects to manage their energy, harvest resources,
+engage in combat, and cooperate with other agents. The key dynamics include:
+
+- **Energy Management**: Agents must efficiently manage their energy, which is required for all actions. They can
+  harvest resources and convert them to energy at charger stations.
+- **Resource Gathering**: Agents can gather resources from generator objects scattered throughout the environment.
+- **Cooperation and Sharing**: Agents have the ability to share resources with other agents and use energy to power the
+  heart altar, which provides rewards.
+- **Combat**: Agents can attack other agents to temporarily freeze them and steal their resources. They can also use
+  shields to defend against attacks.
+
+The environment is highly configurable, allowing for experimentation with different world layouts, object placements,
+and agent capabilities.
+
+## Objects
+
+### Agent
+
+<img src="https://github.com/daveey/Griddly/blob/develop/resources/images/oryx/oryx_tiny_galaxy/tg_sliced/tg_monsters/tg_monsters_astronaut_u1.png?raw=true" width="32"/>
+
+The `Agent` object represents an individual agent in the environment. Agents can move, rotate, attack, and interact with
+other objects. Each agent has energy, resources, and shield properties that govern its abilities and interactions.
+
+### Altar
+
+<img src="https://github.com/daveey/Griddly/blob/develop/resources/images/oryx/oryx_tiny_galaxy/tg_sliced/tg_items/tg_items_heart_full.png?raw=true" width="32"/>
+
+The `Altar` object allows agents to spend energy to gain rewards. Agents can power the altar by using the `use` action
+when near it. The altar has a cooldown period between uses.
+
+- Using the heart altar costs `altar.use_cost energy`. So, no matter how much energy you have, you are always dumping
+  the same amount of energy in it and getting the same amount of reward.
+- After the heart altar is used, it is unable to be used for altar.cooldown timesteps.
+- A single use of the heart altar gives you a single unit of reward: if
+  `target._type_id == ObjectType.AltarT: self.env._rewards[actor_id] += 1`
+
+### Converter
+
+<img src="https://github.com/daveey/Griddly/blob/develop/resources/images/oryx/oryx_tiny_galaxy/tg_sliced/tg_items/tg_items_pda_A.png?raw=true" width="32"/>
+
+The `Converter` object allows agents to convert their harvested resources into energy. Agents can use converters by
+moving to them and taking the `use` action. Each use of a converter provides a specified amount of energy and has a
+cooldown period.
+
+- Using the converter does not cost any energy.
+- Using the converter outputs `converter.energy_output.r1` energy
+  - see `this.output_energy = cfg[b"energy_output.r1"]` in the Converter cppclass
+- Using the converter increments resource 2 by one and decrements resource 1 by 1
+- There is currently no use for `converter.energy_output.r2` and `converter.energy_output.r3`
+- After the converter is used, it is unable to be used for `converter.cooldown` timesteps
+
+### Generator
+
+<img src="https://github.com/daveey/Griddly/blob/develop/resources/images/oryx/oryx_fantasy/ore-0.png?raw=true" width="32"/>
+
+The `Generator` object produces resources that agents can harvest. Agents can gather resources from generators by moving
+to them and taking the `use` action. Generators have a specified capacity and replenish resources over time.
+
+- Using the generator once gives one resource 1
+- After the generator is used, it is unable to be used for `generator.cooldown` timesteps
+
+### Wall
+
+<img src="https://github.com/daveey/Griddly/blob/develop/resources/images/oryx/oryx_fantasy/wall2-0.png?raw=true" width="32"/>
+
+The `Wall` object acts as an impassable barrier in the environment, restricting agent movement.
+
+### Cooldown
+
+The `cooldown` property determines how long before objects can be used again.
+
+## Actions
+
+### Move / Rotate
+
+The `move` action allows agents to move to an adjacent cell in the gridworld. The action has two modes: moving forward
+and moving backward relative to the agent's current orientation.
+
+The `rotate` action enables agents to change their orientation within the gridworld. Agents can rotate to face in four
+directions: down, left, right, and up.
+
+### Attack
+
+The `attack` action allows agents to attack other agents or objects within their attack range. Successful attacks freeze
+the target for `freeze_duration` timesteps and allow the attacker to steal resources. Further, the attacked agent's
+energy is set to `0`. Attacks have a cost and inflict a damage value. The agent selects from one of nine coordinates
+within its attack range.
+
+### Shield (Toggle)
+
+The `shield` action turns on a shield. When the shield is active, the agent is protected from attacks by other agents.
+The shield consumes energy defined by `upkeep.shield` while active. Attack damage is subtracted from the agent's energy,
+rather than freezing the agent.
+
+### Transfer
+
+The `transfer` action enables agents to share resources with other agents. Agents can choose to transfer specific
+resources to another agent in an adjacent cell. It is currently not implemented.
+
+### Use
+
+The `use` action allows agents to interact with objects such as altars, converters, and generators. The specific effects
+of the `use` action depend on the target object and can include converting resources to energy, powering the altar for
+rewards, or harvesting resources from generators.
+
+### Swap
+
+The `swap` action allows agents to swap positions with other agents. It is currently not implemented.
+
+## Configuration
+
+The MettaGrid environment is highly configurable through the use of YAML configuration files. These files specify the
+layout of the gridworld, the placement of objects, and various properties of the objects and agents.
+
+**Current settings:**
+
+1. Ore   - Base resource obtained from mines. Mines produce one ore when used. No resource requirements for use.   -
+   Reward value: 0.005 per unit (max 2)   - Used to create batteries and lasers
+2. Battery   - Intermediate resource created from ore at a generator. Generator turns one ore into one battery.   -
+   Reward value: 0.01 per unit (max 2)   - Used to create hearts and lasers
+3. Heart / heart altar   - High value reward, requires 3 batteries to be converted into a heart at a heart altar.
+4. Laser   - Weapon resource created from ore and batteries. Requires 1 ore and 2 batteries. Created at the lasery.
+
+- Consumed on use. When hitting an unarmored agent: freezes them and steals their whole inventory. When hitting an
+  armoured agent, destroys their armor. **Inventory System**
+- Agents have limited inventory space (default max: 50 items)
+- Resources provide rewards just by being in inventory (up to their max reward value)
+- Resources can be stolen through attacks Objects Various buildings: Mine, Generator, Armory, Lasery, Altar, Lab,
+  Factory, Temple.
+- HP — hitpoints, the number of times something can be hit before destruction.
+- Cooldown between uses (varies by building)
+- Can be damaged and destroyed by attacks
+
+## Environment Architecture
+
+MettaGrid uses a modular architecture designed primarily for the Softmax Studio ML project, with lightweight adapters to
+maintain compatibility with external RL frameworks:
+
+### Primary Training Environment
+
+**`MettaGridEnv`** - The main environment actively developed for Softmax Studio training systems
+
+- Full-featured environment with comprehensive stats collection, replay recording, and curriculum support
+- Inherits from `MettaGridCore` for C++ environment implementation
+- **Exclusively used** by `metta.rl.trainer` and `metta.sim.simulation`
+- Continuously developed and optimized for Softmax Studio use cases
+- Backward compatible with existing training code
+
+### Core Infrastructure
+
+**`MettaGridCore`** - Low-level C++ environment wrapper
+
+- Foundation that provides the core game mechanics and performance
+- **Not used directly** for training - serves as implementation detail for `MettaGridEnv`
+- Provides the base functionality that external adapters wrap
+
+### External Framework Compatibility Adapters
+
+Lightweight wrappers around `MettaGridCore` to maintain compatibility with other training systems:
+
+- **`MettaGridGymEnv`** - Gymnasium compatibility for research workflows
+- **`MettaGridPettingZooEnv`** - PettingZoo compatibility for multi-agent research
+- **`MettaGridPufferEnv`** - PufferLib compatibility for high-performance external training
+
+**Important**: These adapters are **only used with their respective training systems**, not with the Metta trainer.
+
+### Design Philosophy
+
+- **Primary Focus**: `MettaGridEnv` receives active development and new features for Softmax Studio
+- **Compatibility Maintenance**: External adapters ensure other frameworks continue working as the core evolves
+- **Testing for Compatibility**: Demos verify external frameworks remain functional during core development
+- **Clear Separation**: Each environment type serves its specific training system - no mixing between systems
+
+### Compatibility Testing Demos
+
+These demos ensure external framework adapters remain functional as the core environment evolves:
+
+```bash
+# Verify PettingZoo compatibility
+python -m mettagrid.demos.demo_train_pettingzoo
+
+# Verify PufferLib compatibility
+python -m mettagrid.demos.demo_train_puffer
+
+# Verify Gymnasium compatibility
+python -m mettagrid.demos.demo_train_gym
+```
+
+The demos serve as regression tests to catch compatibility issues during core development, ensuring external users can
+continue using their preferred frameworks.
+
+## Building and testing
+
+For local development, refer to the top-level [README.md](../README.md) in this repository.
+
+### Bazel
+
+By default, `uv sync` will run the Bazel build automatically via the custom build backend. If you need to run C++ tests
+and benchmarks directly, you'll need to invoke `bazel` directly.
+
+Build C++ tests and benchmarks in debug mode:
+
+```sh
+# Build with debug flags
+bazel build --config=dbg //:mettagrid_c
+# Run all tests
+bazel test //...
+```
+
+For benchmarks you might prefer to use the optimized build:
+
+```sh
+# Build with optimizations
+bazel build --config=opt //:mettagrid_c
+
+# Run benchmarks
+./build-release/benchmarks/grid_object_benchmark
+```