Physics

Physics simulation can make games much more engaging and realistic. Easel makes this easy with its built-in physics engine.

Simply give the entity a body and one or more colliders, and the physics engine will handle the rest.

pub also body = projectile
pub tangible category Category:Projectile

pub fn hero.LaunchProjectile() {
    Spawn projectile {
        use categories = Category:Projectile
        use speed=48, radius=0.24, density=30, restitution=1, bullet=true
        
        Body(
            parent=hero,
            pos=hero.Pos,
            heading=hero.Heading,
            speed=Direction(heading) * speed,
        )
        
        PolygonCollider(Circle)
        
        once AfterCollide {
            Expire
        }
        
        // ...
    }
}

Detecting collisions

The BeforeCollide hook is triggered when a collider is about to touch another collider, and the AfterCollide hook is triggered when a collider stops touching another collider. It is guaranteed that an AfterCollide hook will be triggered for every BeforeCollide hook. If an entity despawns, it will first trigger AfterCollide on every other collide it is touching.

pub also body = projectile
pub fn projectile.DetectCollisions() {
    once BeforeCollide {
        Transmission { "Collision started" }
    }
    once AfterCollide {
        Transmission { "Collision ended" }
    }
}

Stepping

Call the ForcefulStep to move the body to another position by applying a one-off force during the next physics simulation. Similarly, call ForcefulTurn to change the body's heading by applying a one-off torque during the next physics simulation.

This differs from just modifying Pos or Heading directly because that would simply teleport the body to its new position, whereas this applies a one-off force which can be transferred to other bodies if a collision occurs.

This technique makes a body realistically push other bodies when it is walking into them, for example a hero pushing into a boulder or into another hero.

Querying

Querying searches all colliders in the physics engine for the ones that meet certain conditions:

• QueryNearest finds the nearest collider to a point.
• QueryWithinRadius finds all colliders within a certain radius of a point.
• QueryOverlapping finds all colliders that overlap with a given collider.
• QueryNearestAlongRay finds the nearest collider along a ray.

Note that the querying is performed on colliders not bodies. That means if a body has multiple colliders, it will be returned multiple times in the results.

Querying is done using a spatial index which is only calculated on demand and cached. The cached spatial index is deleted when the physics simulation is performed, and at the end of every tick. That means if a query is performed, and then body positions are changed manually, the next query will run on a stale spatial index and so results might not be accurate. You can force the spatial index to be recalculated by calling ResetSpatialQueryIndex.