wecs.core module¶

class wecs.core.World¶

Bases: object

A world contains a set of wecs.core.Entity, a set of wecs.core.System, and runs the systems when update() is called.

update and add_system will cause deferred component updates to entities to be flushed.

create_entity(*components, name=None)¶

components: The entity’s initial component instances.
name: An optional name for debug purposes.

Returns:	`wecs.core.Entity`

get_entity(uid)¶

uid: The wecs.core.UID of entity to return

Returns:	`wecs.core.Entity`

get_entities()¶

Returns:	An iterable of all `wecs.core.Entity` in the world.

destroy_entity(uid_or_entity)¶

Destroys the entity, removing its components, implicitly removing it from all systems during the next flush.

uid_or_entity: A wecs.core.Entity or wecs.core.UID

add_system(system, sort, add_duplicates=False)¶

Add a system to the world. During a ‘world.update()’, systems will be processed in order of ascending ‘sort’.

Adding a system will implicitly cause a flush of deferred component updates to instances of wecs.core.Entity.

system: System to add.
sort: Order the system should run.
add_duplicates: If False (default), a KeyError will be raised when the world already has a system of that type. If True, do not use get_system() to retrieve systems with multiple instances.

has_system(system_type)¶

system_type: The type of wecs.core.System to check for.

Returns:

bool:

get_systems()¶

Returns:	A dictionary of sort: `wecs.core.System`

get_system(system_type)¶

system_type: The type of wecs.core.System to return.

Returns:	`wecs.core.System`

remove_system(system_type)¶

system_type: The type of wecs.core.System to remove.

update()¶: Run all systems in ascending order of sort.

class wecs.core.UID(name=None)¶

Bases: object

Object for referencing a wecs.core.Entity.

exception wecs.core.NoSuchUID¶

Bases: Exception

Raised by wecs.core.World.get_entity() if the entity referenced by the UID has been removed.

class wecs.core.Entity(world, name=None)¶

Bases: object

Everything in a wecs.core.World is an Entity. They are a container for a set of wecs.core.Component.

They are created with wecs.core.World.create_entity()

When components are added to or removed from entities, these changes are deferred until the next flush.

add_component(component)¶

Add a component to an entity. The addition is deferred until the next flush.

component: The component instance to add.

get_components()¶

Returns:	An iterable of the current `wecs.core.Component` instances in the entity.

get_component_types()¶

Returns:	An iterable of the types of the current `wecs.core.Component` instances in the entity.

get_component(component_type)¶

component_type: The type of wecs.core.Component to get.

Returns:	The `wecs.core.Component` instance.

has_component(component_type)¶

component_type: The type of wecs.core.Component to check for.

Returns:

bool:

remove_component(component_type)¶

Remove a component to an entity. The removal is deferred until the next flush.

component_type: The type of component to remove.

class wecs.core.Component(unique=True)¶

Bases: object

New components are declared like dataclasses:

@Component()
class MyComponent:
    my_variable: int = 0

class wecs.core.System(throw_exc=False)¶

Bases: object

A system implements functionality that is executed during a wecs.core.World.update(). It also implements behavior necessary to prepare an entity, or tear it down.

A system has one or more filters that test whether the system should process an entity during an update. It also implements the functionality to set up and tear down the entity when it enters or leaves filters.

For example:

@Component()
class Printer:
    message: str = "I'm being updated!"


class Print(System):
    entity_filters = {
        'printers' : and_filter([Printer])
    }

    def enter_filter_printers(self, entity):
        print("Entity has entered the filter")

    def update(self, entities_by_filter):
        for entity in entities_by_filter['printers']:
            print(entity[Printer].message)

    def exit_filter_printers(self, entity):
        print("Entity has exited the filter")

When a Printer component is added to an entity and a flush happens, enter_filter_printers will be called (with the entity as argument). Conversely, when the component is removed, exit_filter_printers will be called. As long as it has the component during an update, it will be present in the entities_by_filter dictionary in the set under the key printers.

enter_filters(filters, entity)¶

This method is called during a flush when an entity newly matches one or more filters. It can be overridden in implementations of systems. By default it will look up whether the system has an enter_filter_<name> method, and will call that. The order of those calls is the same in which the filters are specified.

filters: A list of filter names
entity: The entity that has entered the filter(s).

exit_filters(filters, entity)¶

This method is called during a flush when an entity no longer satisfies one or more filters. It can be overridden in implementations of systems. By default it will look up whether the system has an enter_filter_<name> method, and will call that. The order of those calls is the reverse of that in which the filters are specified.

filters: A list of filter names
entity: The entity that has exited the filter(s).

update(entities_by_filter)¶

The system’s functionality that is run during an update.

entity_by_filters: A dictionary mapping filter names to sets of wecs.core.entity.

class wecs.core.Filter(*types_and_filters)¶

Bases: object

The base class for filters. Please don’t use it directly. Instead, use wecs.core.and_filter() and wecs.core.or_filter().

class wecs.core.AndFilter(*types_and_filters)¶

Bases: wecs.core.Filter

Class for and-filters. Please use wecs.core.and_filter() instead.

class wecs.core.OrFilter(*types_and_filters)¶

Bases: wecs.core.Filter

Class for or-filters. Please use wecs.core.or_filter() instead.

wecs.core.and_filter(*types_and_filters)¶

Creates a filter that matches entities that contains all of this filter’s wecs.core.Component types and sub-filters.

Examples:

# These filters match entities which have...
and_filter(Foo)  # ...a Foo component
and_filter(Foo, Bar)  # ...a Foo and a Bar components
and_filter(Foo, or_filter(Bar, Qux))  # ...a Foo component, and
    # a Bar and/or Qux component

types_and_filters: The wecs.core.Component types and sub-filters that this (sub-)filter matches against.

Returns:	The filter object

wecs.core.or_filter(*types_and_filters)¶

Creates a filter that matches entities that contains at least one of this filter’s wecs.core.Component types and sub-filters.

Examples:

# These filters match entities which have...
or_filter(Foo)  # ... a Foo component
or_filter(Foo, Bar)  # ... a Foo and/or a Bar component
or_filter(Foo, and_filter(Bar, Qux))  # a Foo component, and/or
    # both a Bar and a Qux component.

types_and_filters: The wecs.core.Component types and sub-filters that this (sub-)filter matches against.

Returns:	The filter object