Spaces

A space is a logical container for entities, objects and systems. It holds all things for one 'layer' of a scene. For example, there would be a space for the background, one for the level and one for the UI. Spaces should not interact with other spaces.

Systems, entities and objects can be inserted via the << instance method but not removed. To remove entities, one has to call their Entity#suicide method, all dead entities are removed upon the next update. Systems should not be removed.

Spaces have multiple ways to select entites. The [] and []? methods can be used for direct access via entity id. Then there is each_with. It is used to get all entities in a space which hold the specified components. The call signatures are:

each_with(comp_type, &block)
each_with(comp_type, *other_comp_types, &block)

Both methods accept a block and yields the found entity and the component with the type specified in the first parameter.

comp_type and *comp_types are classes (not instances) which inherit from Scar::Component. comp_types are not yielded but filtered for. This allows systems to only process entities with certain components. That way, empty components can also be used as tags.

Example

...
# in app#init
backgroundEntity = Entity.new(...)
playerEntity = Entity.new(...)

self << Scene.new(
    Space.new("level",
        LevelScrollSystem.new,
        backgroundEntity,
        playerEntity z: -1),
    Space.new("ui",
        FpsCounterSystem.new,
        Entity.new(...)
    )
)

To see the each_with methods in action, please refer to the systems section.