Home

Lightweight ECS game engine for Python

Arepy focuses on a small API, fast iteration, and practical game development with ECS, Raylib integration, and built-in gameplay primitives.

Why use Arepy

Arepy is designed for small-to-medium Python games that need an ECS architecture without giving up iteration speed.

1. Small public API — the core workflow stays centered on ArepyEngine, World, EntityBuilder, and Query.
2. ECS-first design — entities, components, and systems are the default way to structure gameplay logic.
3. Typed query model — filters such as With[...] and Without[...] are part of the public API and fit naturally into editor hints and readable system signatures.
4. Built-in gameplay primitives — bundles already include types like Transform, RigidBody2D, and Sprite.
5. Focused documentation — the guides stay concise and centered on the public engine workflow.

Hello World Example

This is the smallest representative example of the current engine workflow.

from arepy import ArepyEngine, Renderer2D, SystemPipeline
from arepy.bundle.components import RigidBody2D, Transform
from arepy.ecs import Entities, Query, With
from arepy.math import Vec2


def movement_system(
    query: Query[Entities, With[Transform, RigidBody2D]],
    renderer: Renderer2D,
) -> None:
    delta_time = renderer.get_delta_time()

    for transform, rigidbody in query.iter_components(Transform, RigidBody2D):
        transform.position.x += rigidbody.velocity.x * delta_time
        transform.position.y += rigidbody.velocity.y * delta_time


engine = ArepyEngine(title="Quickstart")
world = engine.create_world("main")

(
    world.create_entity()
    .with_component(Transform(position=Vec2(32, 32)))
    .with_component(RigidBody2D(velocity=Vec2(60, 20)))
    .build()
)

world.add_system(SystemPipeline.UPDATE, movement_system)
engine.set_current_world("main")
engine.run()

This example is complete as written and matches the public API documented in the guides.

What this gives you

• Engine loop — manage worlds, resources, and frame execution.
• ECS core — create entities, attach components, and register systems.
• Query iteration — iterate matching components directly in gameplay systems.
• Bundle integration — start from reusable gameplay components instead of rebuilding basics.
• Math helpers — use Vec2, Vec3, and companion utilities across systems.

Start here

If you are new to the project, start with installation and the ECS model before jumping into the API reference.

• Getting started

  ---

  Install Arepy, create a world, add components, and run your first systems.

  Open the guide

• Core concepts

  ---

  Learn how World, EntityBuilder, Query, With, and Without fit together.

  Read the guide

• API reference

  ---

  Jump straight to the engine, ECS, bundle, and math reference pages.

  Browse the reference

Next steps

1. Installation — set up the package and dependencies
2. Quickstart — build a minimal world and first systems
3. Engine Lifecycle — understand frame flow and orchestration
4. ECS Basics — learn entities, components, and builders
5. Queries — compose filters and iterate efficiently
6. Built-in Bundle — explore reusable gameplay primitives

Reference map

• Getting Started explains installation and first-run workflow.
• Guide covers lifecycle, ECS, queries, resources, bundle systems, and math.
• API Reference documents the public engine, ECS, bundle, and math surfaces.

Note

The docs stay intentionally concise and technical, with an emphasis on the public engine workflow.