# Spaces

A space is a logical container for [entities](https://vypxl.gitbook.io/scar/application-structure/entities), [objects](https://vypxl.gitbook.io/scar/application-structure/objects) and [systems](https://vypxl.gitbook.io/scar/application-structure/systems). It holds all things for one 'layer' of a [scene](https://vypxl.gitbook.io/scar/application-structure/scenes). 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](https://vypxl.gitbook.io/scar/application-structure/systems),  [entities](https://vypxl.gitbook.io/scar/application-structure/entities) and [objects](https://vypxl.gitbook.io/scar/application-structure/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](https://vypxl.gitbook.io/scar/application-structure/entities). 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](https://vypxl.gitbook.io/scar/application-structure/components). The call signatures are:

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

Both methods accept a block and yields the found [entity](https://vypxl.gitbook.io/scar/application-structure/entities) and the [component](https://vypxl.gitbook.io/scar/application-structure/components) 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](https://vypxl.gitbook.io/scar/application-structure/systems) to only process entities with certain components. That way, empty components can also be used as tags.

### Example

```ruby
...
# 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](https://vypxl.gitbook.io/scar/application-structure/systems) section.