Python ECS

This repository contains Entity Component System concept written on the Python language. Can be used for a gamedev purposes.

Disclaimer: This ECS implementation very raw and primitive, since I'm using this repo just to explore Python features and syntax. I needed some gameplay loop to work with games in Python, and made this. It is not suitable for production, and will not be.

Dependencies

This project uses Raylib python bindings, so, in order to work, repo requires to install raylibpy.

Usage

Where to start

Import all from ecscore module by using from ecscore import *.
Make a new Entities class instance.
Make at least one SystemsLoop class instance. Setup its entities field with Entities instance from step 2.
Make your Systems/Components by creating a simple classes with your data. System require to have Init and Run methods.
Instantiate your system classes.
Add them to your SystemsLoop class instance by using systemsLoop.add(yourSystem) method.
Init systems by calling SystemsLoop class instance's Init method.
Run systems in some for loop by calling SystemsLoop.Run() method.

So, full initialization can look like this:

from ecscore import *

world = World() # initializing a new ECS World, where all ECS actions will be proceed
systemsLoop = SystemsLoop(world) # Systems Loop is used to handle a group of systems. World can have any number of Systems Loops

# <...>
systemsLoop.add(SystemA())
systemsLoop.add(SystemB())

systemsLoop.init()

# <...>
while someCondition:
  systemsLoop.run()

For more info, check example files (main.py, systems and components folders).

Components

To make a new component, simple define a new class with some data type defines (since it is python, you can don't define anything at all, but is it a good idea? :))

Systems

Systems proceeds all game logic, handling ingame entities and their components.

from ecscore import *

# defining a new system. Derive it from ECS built-in System class
class SomeSystem(System):
    def Init(self):
        # do some init steps there. It will be runned once at start

    def Run(self):
        # do entity components update logic here, called every frame. Get frame time from your game framework to correctly handle all data.

Filters

Filters is a key concept to work with ECS. Them allows you to get all needed entities and exclude unneeded ones from a query.

How to use:

from ecscore import *
# import your component types here

# example system
class SomeSystem(System):
    def Init(self):
        # making a filter with two components, all entities, which doesn't have both components, will be excluded.
        self.filter = self.world.new_filter().make_inc((Transform2D(), SpriteRenderer()))

    def Run(self):
        for ent in self.filter.entities:
            # do something with each ent there

You need to initialize filter only once, and it will track all entities and components change.

Actually, for filters tuples are used, it is not very fancy syntax, but it made like this to be consistent with make_inc_exc, which has both include and exclude arguments (so *args cannot by used here).

If your filter has only one component, you can use make_inc_one(YourComponent()) or make_exc_one(YourComponent()).

License

MIT

OlegDzhuraev / Python-ECS