🐾 Predator–Prey Gridworld Environment¶

A discrete, grid-based multi-agent predator–prey environment built as a controlled, interpretable, and reproducible testbed for studying coordination, pursuit–evasion, and emergent behavior in Multi-Agent Reinforcement Learning (MARL).

A trained DQN predator running down a prey around obstacles on a 10x10 grid until capture

A trained DQN predator (speed 2) running down a speed-1 prey around obstacles until capture (plug-and-play/configs/dqn_1v1).

Start here: the learning path¶

This documentation is written to take an undergraduate from first principles all the way to running and extending real experiments. Read it in this order:

flowchart LR
    T["1 · Theory<br/>RL & MARL foundations"] --> C["2 · Concepts<br/>the environment"]
    C --> A["3 · Architecture<br/>how it fits together"]
    A --> I["4 · Implementation<br/>algorithms & code"]
    I --> E["5 · Examples<br/>tutorials & guides"]

Step	You will learn	Start with
1. Theory	MDPs, the Bellman equation, Q-learning, then what changes with many agents	RL Foundations → MARL Theory
2. Concepts	The gridworld, agents, observations, rewards, actions, wrappers	GridWorld
3. Architecture	The layered design and how a step flows through it	Architecture
4. Implementation	How each learning algorithm works, with code pointers	Algorithms
5. Examples	Train, watch, interpret, and extend an experiment	First Experiment

New to the project? The Student Reading Guide gives a week-by-week path.

What this project optimizes for¶

Interpretability — state and action spaces are small and fully enumerable, so every transition, reward, and capture can be traced by hand.
Modularity — observations, rewards, action spaces, and algorithms are independent plugins wired through registries; swap one without touching the rest.
Reproducibility — an experiment is fully determined by a YAML config plus a seed: identical configuration yields identical trajectories.

These fold into one governing balance — accessible by default, versatile by design: plug-and-play/ scripts and YAML configs get you running in minutes (accessibility), while every axis of the experiment — what agents see, what they optimize, how they act, and how they learn — is an open plugin surface awaiting your own observation builders, reward terms, action spaces, and algorithms (versatility). The registry pattern bridges the two: a plugin registered once is a one-line YAML option forever. See Design Philosophy for the full extension menu with difficulty ratings, plus a four-scenario showcase ranging from a 1v1 chase to 5 predators and 20 prey on a 100×100 grid.

It is a controlled laboratory for understanding MARL, not a high-performance training platform. See the Mission for the full rationale.

Quick start¶

git clone https://github.com/UHUMALAB/PPAGE.git
cd PPAGE

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\Activate.ps1

pip install -e ".[baselines]"

# Train the default experiment (3 predators vs 3 prey, IQL)
python plug-and-play/scripts/run_from_config.py

Minimal example¶

from ppage.core.gridworld import GridWorldEnv
from ppage.core.agent import Agent

# Agent(agent_type, agent_team, agent_name)
predator = Agent("predator", "predator_1", "Hunter")
prey = Agent("prey", "prey_1", "Runner")

env = GridWorldEnv(agents=[predator, prey], size=8, seed=42)

obs, info = env.reset()
done = False
while not done:
    actions = {"Hunter": 4, "Runner": 4}          # 4 = NOOP for every action space
    out = env.step(actions)                        # returns a dict, not a tuple
    done = out["terminated"] or out["truncated"]

env.close()

See the Quickstart for a full install → train → evaluate walkthrough, and the First Experiment tutorial to watch agents learn.

Citation¶

If you use this environment in your research, teaching, or projects, please cite it. The repository ships a machine-readable CITATION.cff; BibTeX equivalent:

@software{ppage,
  author       = {Muhammad Ahmed Atif and Nehal Naeem Haji and Muhammad Affan and Areesha Kashif and Musab Kasbati and Afshad Yazdi Sidhwa},
  title        = {Predator-Prey Archetype Gridworld Environment},
  year         = {2026},
  version      = {0.9.2},
  doi          = {10.5281/zenodo.21833286},
  url          = {https://github.com/UHUMALAB/PPAGE},
  note         = {A deterministic modular testbed for Multi-Agent Reinforcement Learning}
}

License¶

Licensed under the Apache-2.0 License.