pyriak 0.2.0

A lightweight implementation of Entity Component System architecture

pyriak

A lightweight implementation of Entity Component System architecture for Python.

(Originally created August 2, 2022.)

Concepts

Usage

Entity creation

Any entity must first be created and populated with components.

A system can directly create and populate an entity. This system may decide itself to create an entity, or handle an event that directly tells it to create one.

player = space.entities.create(
  components.Player(),
  components.CameraFocus(),
  components.Sprite(),
)

A listening system can extend a created entity.

@bind(ComponentAdded, 200, RocketBooster):
def add_rocket_exhaust(space, event):
  event.entity.add(ParticleEmitter(rocket_particles))

Often, multiple systems will need to create a certain set of components that are not related enough to put under a single component, but common enough to necessitate code reuse. A dedicated module can provide functions that produce a "batch", a set of components, sometimes with parameters for customization.

# batches.py
def spaceship(radius=20):
  body = components.Body(radius)
  body.collision_type = 'spaceship'
  return body, components.Engine(), components.Sprite(spaceship_sprite)
...

# systems/player.py
import batches
...
player = space.entities.create(
  *batches.spaceship(),
  components.CameraFocus(),
  components.PlayerController()
)
enemy = space.entities.create(
  *batches.spaceship(),
  components.AIController()
)

It is also easy to customize or initialize the components after the entity and batch have been created as opposed to passing in customization parameters to the batch function.

Small, individual components may be created directly by systems. Batch functions should only be made when necessary, for when it is likely to be reused: repeated at least twice, lots of boilerplate. Batch functions should not be made for a large, unique set of components for a specific entity. It is preferable to have smaller batches to allow for more control in choosing which components to use.

A batch function that calls another batch function mimics inheritance, which can lead to avoidable problems. Batches should be considered large components, not a standalone pseudo-class. (However, a batch function that only calls other batch functions is fine because it does not create any components itself, so its use is not directly required by anything.)

Also note that the components should represent one, indivisible thing. Components can be created large and then later broken down into a batch of multiple components.

TO DO:

• dynamic handlers?
• 3.11 typing features
• fix multibinding typing
• system "new" method instantiation
• __future__.annotations
• type aliases
• 'direct', 'indirect', 'strict', 'immediate' vocab docs
• validate subclasses: hash, mro
• sys mgr expose handlers + bind predicate/filter + _Binding public
• __contains__ TypeError raise?
• picklable __setstate__ __getstate__ __copy__ classes
• 'processor' game pump generator yield event method, 'event loop'
• discard method
• keys method (for dict protocol)
• improve error messages
• raise from None bad
• views, items methods: mappingproxy
• __eq__, remove __hash__: mgrs
• types(*types) method functionality all mgrs+entity ?
• entities from ids: itertools helpers in entitymgr
• 'add', 'remove' methods return value
• entity mgr garbage collection behavior (currently undefined?)
• game __call__ use ?
• more container (set) dunder methods, operations
• copy methods
• more positional only arguments
• more system config
• str and repr methods all
• place documentation in code, along with all rules (style guide first)
• optimization through profiling, scalene (in a game)
• make imported module variables private (consistency)
• python version lower in poetry dependencies ? find min python version
• review and rewrite readme.txt