Grid Engine

Grid Engine is a deterministic ECS gridworld engine for turn-based games, agent environments, and simulation prototypes.

It provides:

• A compact runtime: World, App, resources, messages, intents, commands, and ordered schedules.
• Builder helpers for common worlds and composable plugin bundles.
• Built-in plugins for movement, objectives, scoring, pickup, inventory, doors, portals, pushing, damage, effects, loss conditions, AI, and observations.
• Gymnasium integration with image or symbolic grid observations.
• Procedural examples and image rendering over bundled asset packs.

Install

pip install -e .

For development and docs:

pip install -e ".[dev,doc]"

Minimal Example

from grid_engine.builder import AppBuilder, WorldBuilder, default_bundles
from grid_engine.plugins.agent.api import submit_agent_action
from grid_engine.plugins.agent.components import Agent
from grid_engine.plugins.movement.actions import MoveAction

world = (
    WorldBuilder(5, 5)
    .add_agent((1, 1))
    .add_exit((3, 3))
    .build()
)

app = AppBuilder().use(default_bundles()).build()
app.reset(world)

agent_id = next(iter(world.components(Agent)))
submit_agent_action(world, agent_id, MoveAction("right"))
app.step(world)

API Map

• Core Runtime: ECS state, schedules, plugin registration, and transient buses.
• Builders: ergonomic world and app construction.
• Environment: Gymnasium wrapper and observations.
• Actions: built-in action dataclasses and environment action adapter.
• Plugins: plugin-by-plugin reference for gameplay, mechanics, lifecycle, and utility plugins.
• Observations: grid/info/image observation plugins and image rendering APIs.
• Examples: procedural maze and curated gameplay worlds.