Getting Started

Getting Started#

This guide will help you get started with PyECS, a Python Entity Component System implementation with runtime type safety.

Installation#

Install PyECS using pip:

pip install pyecs

Basic Concepts#

PyECS follows the Entity Component System (ECS) architectural pattern:

  • Entities - Unique identifiers (UUIDs) that represent game objects

  • Components - Plain Python classes that store data (no logic)

  • Systems - Classes that contain the game logic and operate on entities

  • World - The main container that manages everything

  • Archetypes - Groups of entities that share the same component types

See Also: Architecture & Internals for detailed flowcharts of these concepts

Your First PyECS Program#

Here’s a minimal example to get you started:

from dataclasses import dataclass
from pyecs import ECSWorld

@dataclass
class Position:
    x: float = 0
    y: float = 0

@dataclass
class Velocity:
    dx: float = 0
    dy: float = 0

class MovementSystem:
    def update(self, world, dt):
        from pyecs.querying.Query import Query

        query = Query().with_components(Position, Velocity)
        entities = query.execute(world)

        for entity in entities:
            pos = world.get_component(entity, Position)
            vel = world.get_component(entity, Velocity)
            pos.x += vel.dx * dt
            pos.y += vel.dy * dt

world = ECSWorld()
world.add_system(MovementSystem())

player = world.create_entity()
world.add_component(player, Position(x=0, y=0))
world.add_component(player, Velocity(dx=5, dy=0))

for i in range(10):
    world.update(dt=0.1)
    pos = world.get_component(player, Position)
    print(f"Frame {i}: Player at ({pos.x}, {pos.y})")

See Also: Architecture & Internals - World.create_entity, World.add_component, World.add_system, World.update, World.get_component

Key Points to Remember#

  1. Components are just data - Any Python class can be a component

  2. Systems receive the world - The update method gets the world object, not entities

  3. Use archetypes for queries - This is the most efficient way to find entities

  4. Entity IDs are UUIDs - Unique identifiers for each entity

Common Patterns#

Creating multiple entities:

for i in range(10):
    enemy = world.create_entity()
    world.add_component(enemy, Position(x=i*10, y=0))
    world.add_component(enemy, Health(hp=100))

See Also: Architecture & Internals - World.create_entity, World.add_component

Checking if entity has component:

health = world.get_component(entity, Health)
if health != -1:
    print(f"Entity has {health.hp} health")

Removing components:

world.remove_component(entity, PowerUp)

See Also: Architecture & Internals - World.remove_component

Next Steps#

Contents