Spaces

Games often consist of multiple rooms, levels or areas. In Easel, these are called Spaces. Each collider belongs to one and only one space, and it can only ever interact with other colliders in the same space.

Defining Spaces

Any entity can be used as a space. You can either reuse an existing entity, or Spawn a new one. In many cases, you already have an entity that represents the level or area, so you can just use that as the space.

Fixed Spaces

If your game has a fixed set of spaces, you could define them upfront somewhere and assign them to constants:

// This game has two spaces
const Space:Inside = Spawn
const Space:Outside = Spawn

// Trees are always outside
pub fn tree.Tree(pos) {
    use body=this
    Body(pos=)
    PolygonCollider(shape=Circle(radius=1), category=Category:Tree, space=Space:Outside)
    // ...
}

Dynamic Spaces

If your spaces are dynamic and not known at compile time, you can put space into your context so it gets automatically passed to everywhere that needs it.

This is an example of using the level entity as a space by assigning it to space in the context. The Tree automatically gets put into space:

pub game fn World.Main() {
    Spawn level {
        use space=this // the level is the space
        Spawn tree {
            Tree(@(10, 10)) // Tree takes `space` from context
        }
    }
}

// Automatically receives `space` from context
pub fn tree.Tree(pos, [space]) {
    use body=this
    Body(pos=)
    // PolygonCollider receives `space` from context automatically
    PolygonCollider(shape=Circle(radius=1), category=Category:Tree)
    // ...
}

Default Space

The World entity is the default space for all colliders. If you do not specify a space for a collider, it will belong to the World space by default.

Querying Spaces

All the querying functions, like QueryNearest take a space parameter. They will only ever search one space at a time, whether that be one you specify, or the default World space.

One Body, Multiple Spaces

There is nothing stopping you from putting multiple colliders on the same body, and putting those colliders into different spaces. That means you could have a character that can exist in multiple dimensions or planes of existence, which could lead to interesting game mechanics.

Be careful, if you do not intend for the colliders to be in different spaces, you must pass the same space parameter to all colliders! The best way to do this is to use space=... so that it is automatically passed everywhere that needs it from context.