Skip to main content

Physics

These functions relate to the physics engine, which simulates the movement and collision of entities in your game. See Learn > Physics for a more general overview of how physics works in Easel.

info

To make a entity physically simulated, you must first give it a Body, then attach one or more PolygonColliders to that body. You will need to give the PolygonCollider a Category so that you can define rules about which categories can collide with what. When you are starting out, you can simply use the built in Category:Default for your colliders, which will make them all collide with each other.

Category constants​

You define categories using the category keyword, for example:

pub tangible category Category:Projectile
pub category Category:Destructible

This defines a new category called Category:Projectile which can be used to filter collisions. Categories can be combined, for example, you might make a PolygonCollider(category = Category:Projectile | Category:Destructible) which would belong to both categories.

Various combinations of categories have been predefined:

Category:All -> categories

The union of all categories defined using with category keyword.

Category:Tangible -> categories

The union of all categories declared with tangible category. This is useful to make exceptions to the tangible category, for example Category:Tangible ^ Category:Projectile would toggle off the Category:Projectile category from the union of all tangible categories.

Category:None -> categories

An empty set of categories.

Category:Default​

Category:Default -> categories

A default category that you can use for convenience. Category:Default gets automatically declared as pub tangible category Category:Default if used somewhere in your code. If you don't use it, it doesn't get declared and so does not take up any space in your 32 category limit.

AfterCollide​

await this.AfterCollide<Id?> -> entity

Waits until the end of any collision involving a collider belonging to this entity.

  • If no Id is provided, waits for the end of a collision involving any collider that belongs to this entity, except for colliders that were created with isolate=true (see PolygonCollider parameters).
  • If an Id is provided, waits for the end of a collision involving the collider that matches that Id.

A collision ends once the two colliders involved are no longer in contact. If this is nullish, waits forever.

See also: BeforeCollide

ApplyImpulse​

body.ApplyImpulse(impulse)

Applies an impulse (an instantaneous force) to the body, changing its velocity. The change in the velocity will equal the impulse divided by the body's mass. The force will be applied at the center of mass of the body, and so will only change the linear velocity of the body and not its turn rate.

  • body (Entity): The body to apply the impulse to.
  • impulse (Vector): The magnitude and direction of the impulse.

If any parameter is nullish, does nothing.

info

Consider just modifying the Velocity directly instead of using this function. The following two lines are equivalent:

ApplyImpulse(Mass * @(10, 0))
Velocity += @(10, 0)

Here you are multiplying the change in velocity by mass, and then inside the engine it will then divide by the mass again to get the change in velocity. It is more efficient to just modify the Velocity directly.

ApplyImpulseAt​

body.ApplyImpulseAt(impulse, pos)

Applies an impulse (an instantaneous force) to a particular point on a body, changing its velocity and turn rate.

  • body (Entity): The body to apply the impulse to.
  • impulse (Vector): The magnitude and direction of the impulse.
  • pos (Vector): The world-space point where the impulse is applied.

If any parameter is nullish, does nothing.

ApplyTurningImpulse​

body.ApplyTurningImpulse(turningImpulse)

Applies a turning impulse to the body, changing its turn rate. The change in the turn rate will equal the turning impulse divided by the body's moment of inertia.

  • body (Entity): The body to apply the turning impulse to.
  • turningImpulse (Number): The magnitude of the turning impulse.

If any parameter is nullish, does nothing.

BeforeCollide​

await this.BeforeCollide<Id?> -> entity, point

Waits until the start of a collision involving a collider belonging to this entity. A collision starts once the two colliders involved come into contact.

  • If no Id is provided, waits for a collision involving any collider that belongs to this entity, except for colliders that were created with isolate=true (see PolygonCollider parameters).
  • If an Id is provided, waits for a collision involving the collider that matches that Id.

If this is nullish, waits forever.

Returns:

  • that (Entity): The entity that owns the other collider

  • point (Vector): The collision point. More specifically, returns the midpoint of the contact surface in world-space coordinates. If there are multiple contact surfaces, returns the midpoint of one of the contact surfaces, whichever the physics engine finds first.

info

In 2D, there is almost always just one contact surface - a single point-to-edge or edge-to-edge contact - and so this point is simply the midpoint of the only contact surface.

For a shape to be able to have multiple contact surfaces, it must be non-convex (it must fold back on itself). In that case, only the midpoint of the first contact surface will be returned. This guarantees that point is actually on the surface where the two colliders meet, while also reducing expensive computation on complex shapes.

See also: AfterCollide

Body​

this.Body([pos, velocity?=, heading?, turnRate?, immovable?, noRotation?, gravityScale?, bullet?, space?])
delete this.Body

Creates or replaces an entity's body. A body defines the physical position and velocity of an entity. Many things can be attached to a body, for example colliders, sprites, and sounds, to name a few.

  • this (Entity): the entity to add a Body to. If the entity already has a Body, it will be replaced. If this is nullish, this function does nothing.

Position:

  • pos (Vector): the position of the body.
  • heading (Number): the angle of the body, in radians. Defaults to 0rev.

Speed:

  • velocity (Vector): the velocity of the body. Defaults to @(0, 0).
  • turnRate (Number): the rate at which the body turns in radians per second. Defaults to 0rev.

Locking:

  • immovable (Boolean): if true, the Velocity of the body will never be changed by the physics engine (e.g. in response to a collision or due to gravity). You can still set Velocity manually. Defaults to false.

  • noRotation (Boolean): if true, the TurnRate of the body will never be changed by the physics engine (e.g. in response to a collision). You can still set TurnRate manually. Defaults to the value of immovable, meaning if you set immovable=true then by default noRotation=true unless otherwise specified.

Gravity:

  • gravityScale (Number): a multiplier for the Gravity applied to the body. Defaults to 1. Note that gravity is always ignored for an immovable body. There is no need to set gravityScale=0 when immovable=true.

Space:

  • space (Entity): A body will only ever interact another body that is in the same space. A space can be used to designate different rooms or areas of the map, for example. Any entity can be used as a space. If undefined, defaults to World (the main space). If null, the body is put into the null space which means it cannot collide with anything. See Spaces.

Deprecated parameters:

  • bullet (Boolean): if true, enables continuous collision for every collider on this body. This parameter has been deprecated, use the intercept parameter on PolygonCollider instead. That parameter lets you enable continuous collision on a per-collider basis rather than on every collider on the body, and so is more computationally efficient. See Continuous Collision Detection.

Category​

this.Category -> categories

Gets category of this entity. If this is nullish, returns undefined.

this.Category = categories

Sets the category of this entity. If this is nullish, does nothing.

delete this.Category -> categories

Deletes the category of this entity. Returns the previous category, or undefined if the entity had no category assigned previously. If this is nullish, does nothing and returns undefined.

CountContacts​

body.CountContacts<Id?>(that?=, direction?, filter?, solids?, sensors?, against?, [owner?]) -> number

Of colliders that are in contact with the given collider, counts the number that also match the specified criteria.

Collider:

Use the body and Id parameters to identify the collider to query for contacts with.

  • body (Entity): The Entity that owns the collider. Should match the this parameter given to PolygonCollider when creating the collider.
  • Id: The Id of the collider to use. Should match the Id parameter given to PolygonCollider when creating the collider.

Filtering:

  • that (Entity): Only look for contacts with colliders owned by that. Should match the this parameter given to PolygonCollider when creating the other collider.

  • direction (Vector): Only include contacts in the given direction. For example, @(0, 1) would look for contacts below the collider, whereas @(1, 0) would only look for contacts to the right. More specifically, only include contacts where, at the point of contact, the other collider lies in this direction relative to the given collider.

  • filter (Categories): For a collider to match, both the collider's categories and it's body's Category property must overlap with the filter. Defaults to Category:All.

  • sensors (Boolean): Whether to include or exclude sensor colliders in the results. Defaults to true.

  • solids (Boolean): Whether to include or exclude non-sensor colliders in the results. Defaults to true.

Alliance:

  • against (Flags): Filters entities based on their alliance status with owner. For an entity to match, the alliance status between the owner parameter and the Owner of the Entity must overlap with against. Defaults to Alliance:All. See Alliance flags for all possible values.
  • owner (Entity): The player who is performing the query. Affects how the against filter is interpreted.

Returns: Returns the Number of colliders found that match the given criteria. Returns 0 if no colliders were matched.

Notes:

This function queries the contact graph which is updated once per physics step, making it a relatively fast query, but it also means that any changes since the previous physics step will not be reflected in the results.

If an entity has multiple colliders that match, it will be returned multiple times. If no colliders overlap, returns undefined.

See also: QueryAnyContact, QueryContacts

DecaySpeed​

body.DecaySpeed([speedDecay?], speedLimit?=)
delete body.DecaySpeed

Makes the speed of body decay by a certain proportion after the physics simulation phase of each tick.

  • body (Entity): The entity to modify. If nullish, this function will do nothing.

  • speedDecay (Number): The rate at which the body's speed decays. Should be a value between 0 and 1. Values outside of this range will be clamped. Defaults to the physics.speedDecay configuration setting in easel.toml or 0.05 if not specified.

  • speedLimit (Number): The minimum speed of the body. The speed will only decay if it is above this value. Defaults to 0.

See also: RecoverSpeed, LimitSpeed

DecayTurnRate​

body.DecayTurnRate([turningDecay?])
delete body.DecayTurnRate

Makes the turn rate of body decay by a certain proportion after the physics simulation phase of each tick.

  • body (Entity): The entity to modify. If nullish, this function will do nothing.
  • turningDecay (Number): The rate at which the body's turn rate decays. Should be a value between 0 and 1. Values outside of this range will be clamped. Defaults to the physics.turningDecay configuration setting in easel.toml or 0.5 if not specified.

See also: RecoverTurnRate

ForcefulStep​

body.ForcefulStep(step, restitution?=)

Move the body by the given step during the next physics simulation.

The movement is done using a one-off force. This may cause the body to bounce off other bodies and/or knock them back.

  • step (Vector): The intended distance to move during the next tick. The actual distance moved will depend on the PhysicsTimescale and whether the body collides with other bodies during the simulation.

  • restitution (Number): A proportion between 0 and 1 which determines how much knockback the step has. Defaults to 1, meaning full knockback.

If any body or step is nullish, does nothing.

info

The difference between Move and ForcefulStep is that restitution=1 by default for ForcefulStep, meaning it can generate knockback.

See also: Move, ForcefulTurn

ForcefulTurn​

body.ForcefulTurn(step, restitution?=)

Turns the body by the angle given by step by applying a one-off force during the next physics simulation.

The movement is done using a one-off force. This may cause the body to bounce off other bodies and/or knock them back.

  • step (Number): The intended angular distance to rotate during the next tick. The actual amount rotated will depend on the PhysicsTimescale and whether the body collides with other bodies during the simulation.

  • restitution (Number): A proportion between 0 and 1 which determines how much knockback the step has. Defaults to 1, meaning full knockback.

If any body or step is nullish, does nothing.

info

The difference between Turn and ForcefulTurn is that restitution=1 by default for ForcefulTurn, meaning it can generate knockback.

See also: Turn, ForcefulStep

Gravity​

space.Gravity -> vector

Get the current gravity Vector for the given space. If the space has no gravity assigned, returns @(0, 0).

  • space (Entity): The Space for which to get the gravity Vector. Defaults to World.
space.Gravity = value

Sets the gravity for the given space.

  • If given a Vector, sets the gravity vector to that value.
  • If given a Number, sets the gravity vector to @(0, value), meaning the gravity will pull downwards with the given strength.
  • If given null or undefined, resets the gravity to @(0, 0).

Parameters:

  • space (Entity): The Space for which to set the gravity Vector. Defaults to World.

Example:

Gravity = 10
Gravity = @(0, 10)
inside.Gravity = @(0, 10)
outside.Gravity = @(0, 0)
await space.Gravity -> vector

Waits until the gravity changes, then returns its new value.

GravityScale​

body.GravityScale -> vector
body.GravityScale = value

Gets or sets the current gravity scale of the body. The gravity scale is a multiplier applied to the Gravity vector of the World. A value of 1 means the body is affected by gravity as normal, whereas 0 means the body is not affected by gravity at all.

If body is nullish or refers to an entity with no Body, does nothing.

Heading​

body.Heading -> angle

Gets the current heading of the body, in radians. If body is nullish or refers to an entity with no body, returns undefined.

body.Heading = angle

Sets the current heading of the body, in radians. If body refers to an entity that does not yet have a body, a immovable body is first created, then assigned the new heading. If body is nullish, does nothing.

await body.Heading -> angle

Waits for the heading of body to change, then returns the new value. If body is nullish, waits forever.

LimitSpeed​

body.LimitSpeed([maxSpeed])
delete body.LimitSpeed

Limits the speed of body.

  • body (Entity): The entity to modify. If nullish, this function will do nothing.
  • maxSpeed (Number): The maximum speed of the body. null means no maximum speed.

See also: DecaySpeed, RecoverSpeed

LocatePerimeterPoint​

body.LocatePerimeterPoint(edgeFraction, radiusFraction?=) -> vector

Returns a point within the perimeter of an entity. The perimeter must have been assigned previously using the PolygonPerimeter function, otherwise this will just return the center of the entity's body.

The edgeFraction parameter is a value between 0 and 1 that represents the position along the edge of the perimeter.

The radiusFraction parameter is a value between 0 and 1 that represents the distance from the center of the perimeter to the edge. If the radiusFraction parameter is not provided, it defaults to 1 (the edge).

Mass​

body.Mass -> number

Gets the mass of body.

The mass is equal to the density multiplied by the area of all colliders currently attached to this body. If the body is immovable then returns undefined because the body has infinite mass.

If the body is nullish, or body refers to an entity with no body or colliders, returns 0.

See also: TurningInertia

Move​

body.Move(step)

Move the body by the given step during the next physics simulation.

  • step (Vector): The intended distance to move during the next tick. The actual distance moved will depend on the PhysicsTimescale and whether the body collides with other bodies during the simulation.

If any body or step is nullish, does nothing.

info

Move(step=@(1, 0)) is equivalent to ForcefulStep(step=@(1, 0), restitution=0). See ForcefulStep.

See also: ForcefulStep, Turn

PhysicsSpace​

body.PhysicsSpace -> value

Gets the Entity that represents the current physics Space for the body. If body is nullish or refers to an entity with no body, returns undefined.

body.PhysicsSpace = value

Sets the current physics Space for the body.

  • If entity is null, the body is moved into null space which means it will not collide with anything.

If body is nullish, does nothing.

await body.PhysicsSpace -> entity

Waits for the current physics space of body to change, then returns the new value. If body is nullish, waits forever.

PhysicsTimescale​

space.PhysicsTimescale -> number

Get the timescale of physics for the given space. A value of 1 means physics is running at normal speed.

  • space (Entity): The Space for which to read the physics timescale. Defaults to World.
space.PhysicsTimescale = value

Sets the physics timescale for the given space. This can be used to create a variety of effects:

  • 0 to pause physics entirely
  • 0.5 for half speed (slow motion)
  • 1 for normal speed (the default)
  • 2 for double speed (fast forward)

Parameters:

  • space (Entity): The Space for which to set the physics timescale. Defaults to World.
await space.PhysicsTimescale -> number

Waits until the physics timescale changes, then returns its new value.

PolygonCollider​

this.PolygonCollider<Id?>([shape, body], angleOffset?=, bodyOffset?, scale?, isolate?, [category, bodyScale?, collideWith?, density?, friction?, intercept?, isSensor?, owner?, parent?, passthroughParent?, passthroughSiblings?, restitution?, sense?, tolerance?])
delete this.PolygonCollider<Id?>

Attaches a new collider to body.

  • this (Entity): Determines the lifespan of the collider. When this despawns, the collider is removed.
  • Id: if a collider with the same this and Id already exists, it will be replaced.

Shape:

  • shape (Polygon): The shape of the collider.

  • tolerance (Number): Some shapes may need to be approximated in order to be handled by the physics engine. This value determines the maximum allowed distance between the original shape and the approximated shape. Greater tolerance allows of better performance but less accuracy. Defaults to 0.25.

Position:

  • body (Entity): Determines which Body the collider will be attached to. Must be an Entity that has a Body component.

  • angleOffset (Number): If set, the collider's shape will be rotated by this angle.

  • bodyOffset (Vector): If set, determines the attachment point of the collider to the body.

Scaling:

  • scale (Number): The size of the collider will be multiplied by this factor. Defaults to 1.

  • bodyScale (Number): Both the size of the collider and its bodyOffset will be multiplied by this factor. Defaults to 1.

Interaction Filtering:

  • category (Categories): The categories that the collider belongs to. This determines which other colliders it will collide with. This will automatically set the Category property for this, if it is not set yet. See Categories.

  • collideWith (Categories): This collider will only collide with other colliders belonging to these categories. Defaults to Category:Tangible.

  • sense (Categories or Boolean): The collider will generate collision signals with colliders of these categories, but no collision forces will be generated. If a category is in both sense and collideWith, then sense will take precedence. Defaults to Category:None. The boolean value true will be interpreted as Category:All, and false will be interpreted as Category:None.

  • isSensor (Boolean): If true, the collider is a sensor. That means other collides will not generate collision signals with it, and no collision forces will be generated when it touches other colliders.

Parent:

  • parent (Entity): If set, defines a body that the collider may pass through initially when it has just spawned. This passthrough will continue until the collider stops contact with its parent. This can be used to stop a projectile immediately colliding with its parent and exploding straight away, for example.

  • passthroughParent (Boolean): If true, the collider will always pass through its parent forever, not just initially.

  • passthroughSiblings (Boolean): If true, the collider will also pass through any other colliders that are both still in their "initial passthrough" phase and have the same parent. Defaults to true.

Mass:

  • density (Number): The density of the collider, defaults to 1. Determines the mass of the collider.

Forces:

  • friction (Number): Determines the amount of tangential force that opposes tangential movement in a collision. Should be a value between 0 and 1. Defaults to 0.

  • restitution (Number): Determines the amount of energy conserved in a collision. In other words, the bounciness of the collider. Should be a value between 0 and 1. Defaults to 0.

Continuous Collision Detection:

  • intercept (Boolean or Categories): If true, the collider will use continuous collision detection against other colliders of all categories. If a Categories value is provided, the collider will only use continuous collision detection against colliders belonging to those categories. Defaults to Category:None. See Continuous Collision Detection.

Signals:

  • isolate (Boolean): Determines which forms of BeforeCollide/AfterCollide receive collision signals. When isolate is false (the default), sends collisions to both BeforeCollide/AfterCollide (with no Id) and BeforeCollide<Id>/AfterCollide<Id>. If isolate is true, then only BeforeCollide<Id> and AfterCollide<Id> will receive signals from this collider. It can sometimes be useful to isolate a collider if you are wanting to create a utility collider that must be treated diferently from the other colliders on the same entity, like a proximity sensor.

Ownership:

  • owner (Entity): This will automatically set the Owner property for this, if it is not set yet.

PolygonPerimeter​

this.PolygonPerimeter([shape?], bodyOffset?=, angleOffset?, scale?, [bodyScale?])

Assigns a polygon to be the perimeter of an entity with a Body. Perimeters are an efficient way of find a point within the area considered to be within the boundary of an entity. Perimeters are used with the LocatePerimeterPoint function to find points on or within the perimeter. They are also used with the glaze parameter of Spark to create visual effects that spread within the perimeter.

  • this (Entity): The entity to assign the perimeter to.
  • shape (Polygon): The shape of the perimeter.
  • angleOffset (Number): Offset the shape by this angle, specified in radians. Defaults to 0.
  • bodyOffset (Vector): The offset of the perimeter from the body. Defaults to @(0,0).
  • scale (Number or Vector): Changes the size of the shape by this factor. Provide a Vector to scale the width and height of the shape separately.
  • bodyScale (Number or Vector): Scales the body by this factor. Provide a Vector to scale the width and height of the body separately.
delete this.PolygonPerimeter

Removes the perimeter from an entity. The entity will no longer have a perimeter.

  • this (Entity): The entity to remove the perimeter from.

Pos​

body.Pos -> vector

Gets the current position of the body. If body is nullish or refers to an entity with no body, returns undefined.

body.Pos = value

Sets the current position of the body. If body refers to an entity that does not yet have a body, a immovable body is first created, then assigned the new position. If body is nullish, does nothing.

await body.Pos -> vector

Waits for the position of body to move, then returns the new value. If body is nullish, waits forever.

QueryAlongRay​

body.QueryAlongRay(direction, maxDistance?=, filter?, solids?, sensors?, against?, [owner?, space?]) -> entityArray

Searches along a ray for all colliders that match the specified criteria. Returns an Array of the Entities that own the matching colliders.

  • body (Vector or Entity): If body is a Vector, will search from that position. If body is an Entity, will search from the position of the Entity's body. If this is nullish, returns undefined.
  • direction (Vector): The direction to search in.
  • maxDistance (Number): The maximum distance to search.

Filter by Category:

  • filter (Categories): For a collider to match, both the collider's categories and it's body's Category property must overlap with the filter.

Filter by Solid/Sensor:

  • sensors (Boolean): Whether to include or exclude sensor colliders in the results. Defaults to true.
  • solids (Boolean): Whether to include or exclude non-sensor colliders in the results. Defaults to true. Defaults to Category:All.

Filter by Alliance:

  • against (Flags): Filters entities based on their alliance status with owner. For an entity to match, the alliance status between the owner parameter and the Owner of the Entity must overlap with against. Defaults to Alliance:All. See Alliance flags for all possible values.
  • owner (Entity): The player who is performing the query. Affects how the against filter is interpreted.

Filter by Space:

  • space (Entity): Only colliders that are in the given space will match. Defaults to World (the main space).

Note:

If an Entity has multiple colliders that match, it will be returned multiple times.

This function uses a cached spatial index for performance reasons. See ResetSpatialQueryIndex for more details.

QueryAnyContact​

body.QueryAnyContact<Id?>(that?=, direction?, filter?, solids?, sensors?, against?, [owner?]) -> entity, point

Returns one of the colliders that is in contact with the given collider while also matching the specified criteria.

Collider:

Use the body and Id parameters to identify the collider to query for contacts with. We call this the "given collider".

  • body (Entity): The Entity that owns the collider. Should match the this parameter given to PolygonCollider when creating the collider.
  • Id: The Id of the collider to use. Should match the Id parameter given to PolygonCollider when creating the collider.

Filtering:

  • that (Entity): Only look for contacts with colliders owned by that. Should match the this parameter given to PolygonCollider when creating the other collider.

  • direction (Vector): Only include contacts in the given direction. For example, @(0, 1) would look for contacts below the collider, whereas @(1, 0) would only look for contacts to the right. More specifically, only include contacts where, at the point of contact, the other collider lies in this direction relative to the given collider.

  • filter (Categories): For a collider to match, both the collider's categories and it's body's Category property must overlap with the filter. Defaults to Category:All.

  • sensors (Boolean): Whether to include or exclude sensor colliders in the results. Defaults to true.

  • solids (Boolean): Whether to include or exclude non-sensor colliders in the results. Defaults to true.

Alliance:

  • against (Flags): Filters entities based on their alliance status with owner. For an entity to match, the alliance status between the owner parameter and the Owner of the Entity must overlap with against. Defaults to Alliance:All. See Alliance flags for all possible values.
  • owner (Entity): The player who is performing the query. Affects how the against filter is interpreted.

Returns:

  • entity (Entity): The entity that owns the other collider. Matches the this parameter used with PolygonCollider when the other collider was created.
  • point (Vector): The contact point between the given collider and other collider. More specifically, this is the midpoint of the contact surface between the two colliders. If there are multiple contact surfaces, picks one arbitrarily and returns the midpoint of that.

Notes:

This function queries the contact graph which is updated once per physics step, making it a relatively fast query, but it also means that any changes since the previous physics step will not be reflected in the results.

See also: CountContacts, QueryContacts

QueryAnyOverlapping​

body.QueryAnyOverlapping<Id?>(filter?, solids?=, sensors?, against?, [owner?, space?]) -> entity

Returns one of the colliders that overlaps the given collider or position and matches the specified criteria.

  • body (Vector or Entity): A Vector position or an Entity that owns a collider to check for overlaps. Checking for a Collider rather than just a Vector position is more powerful as it checks whether the collider's entire shape overlaps, not just its center point.
  • Id: If body refers to a collider, the Id of the collider, if it has one.

Filter by Category:

  • filter (Categories): For a collider to match, both the collider's categories and it's body's Category property must overlap with the filter. Defaults to Category:All.

Filter by Solid/Sensor:

  • sensors (Boolean): Whether to include or exclude sensor colliders in the results. Defaults to true.
  • solids (Boolean): Whether to include or exclude non-sensor colliders in the results. Defaults to true.

Filter by Alliance:

  • against (Flags): Filters entities based on their alliance status with owner. For an entity to match, the alliance status between the owner parameter and the Owner of the Entity must overlap with against. Defaults to Alliance:All. See Alliance flags for all possible values.
  • owner (Entity): The player who is performing the query. Affects how the against filter is interpreted.

Filter by Space:

  • space (Entity): Only colliders that are in the given space will match. Defaults to World (the main space).

Note:

Only entities that have both a Collider (e.g. PolygonCollider) and a Category will be considered by this function. If an entity has multiple colliders that match, it will be returned multiple times. If no colliders overlap, returns undefined.

This function uses a cached spatial index for performance reasons. See ResetSpatialQueryIndex for more details.

QueryAnyWithinRadius​

body.QueryAnyWithinRadius(radius, filter?=, solids?, sensors?, against?, [owner?, space?]) -> entity

Returns one of the colliders that is within the given radius of the given position and matches the specified criteria.

  • body (Vector or Entity): The origin point from which to search. If given an Entity, will use the position (Pos of its body. If this is nullish, returns undefined.
  • radius (Number): The radius to search within.

Filter by Category:

  • filter (Categories): For a collider to match, both the collider's categories and it's body's Category property must overlap with the filter. Defaults to Category:All.

Filter by Solid/Sensor:

  • sensors (Boolean): Whether to include or exclude sensor colliders in the results. Defaults to true.
  • solids (Boolean): Whether to include or exclude non-sensor colliders in the results. Defaults to true.

Filter by Alliance:

  • against (Flags): Filters entities based on their alliance status with owner. For an entity to match, the alliance status between the owner parameter and the Owner of the Entity must overlap with against. Defaults to Alliance:All. See Alliance flags for all possible values.
  • owner (Entity): The player who is performing the query. Affects how the against filter is interpreted.

Filter by Space:

  • space (Entity): Only colliders that are in the given space will match. Defaults to World (the main space).

Notes:

Only entities that have both a Collider (e.g. PolygonCollider) and a Category will be considered by this function. If an entity has multiple colliders that match, it will be returned multiple times. If no colliders overlap, returns undefined.

This function uses a cached spatial index for performance reasons. See ResetSpatialQueryIndex for more details.

QueryContacts​

body.QueryContacts<Id?>(that?=, direction?, filter?, solids?, sensors?, against?, [owner?]) -> array

Returns all the colliders that are in contact with the given collider, and that also match the specified criteria.

Collider:

Use the body and Id parameters to identify the collider to query for contacts with.

  • body (Entity): The Entity that owns the collider. Should match the this parameter given to PolygonCollider when creating the collider.
  • Id: The Id of the collider to use. Should match the Id parameter given to PolygonCollider when creating the collider.

Filtering:

  • that (Entity): Only look for contacts with colliders owned by that. Should match the this parameter given to PolygonCollider when creating the other collider.

  • direction (Vector): Only include contacts in the given direction. For example, @(0, 1) would look for contacts below the collider, whereas @(1, 0) would only look for contacts to the right. More specifically, only include contacts where, at the point of contact, the other collider lies in this direction relative to the given collider.

  • filter (Categories): For a collider to match, both the collider's categories and it's body's Category property must overlap with the filter. Defaults to Category:All.

  • sensors (Boolean): Whether to include or exclude sensor colliders in the results. Defaults to true.

  • solids (Boolean): Whether to include or exclude non-sensor colliders in the results. Defaults to true.

Alliance:

  • against (Flags): Filters entities based on their alliance status with owner. For an entity to match, the alliance status between the owner parameter and the Owner of the Entity must overlap with against. Defaults to Alliance:All. See Alliance flags for all possible values.
  • owner (Entity): The player who is performing the query. Affects how the against filter is interpreted.

Returns: Returns an Array of Entities, one for each matched collider. The Entity is the one that owns the collider - the this parameter given to PolygonCollider when creating that collider.

Notes:

This function queries the contact graph which is updated once per physics step, making it a relatively fast query, but it also means that any changes since the previous physics step will not be reflected in the results.

If an entity has multiple colliders that match, it will be returned multiple times. If no colliders overlap, returns undefined.

See also: CountContacts, QueryAnyContact

QueryNearest​

body.QueryNearest(filter?, maxDistance?=, solids?, sensors?, against?, [owner?, space?]) -> entity

Returns the nearest collider to the given position that matches the specified criteria.

  • body (Vector or Entity): The origin point from which to search. If given an Entity, will use the position (Pos of its body. If this is nullish, returns undefined.

  • maxDistance (Number): The maximum distance to search. Defaults to infinity.

Filter by Category:

  • filter (Categories): For a collider to match, both the collider's categories and it's body's Category property must overlap with the filter. Defaults to Category:All.

Filter by Solid/Sensor:

  • sensors (Boolean): Whether to include or exclude sensor colliders in the results. Defaults to true.
  • solids (Boolean): Whether to include or exclude non-sensor colliders in the results. Defaults to true.

Filter by Alliance:

  • against (Flags): Filters entities based on their alliance status with owner. For an entity to match, the alliance status between the owner parameter and the Owner of the Entity must overlap with against. Defaults to Alliance:All. See Alliance flags for all possible values.
  • owner (Entity): The player who is performing the query. Affects how the against filter is interpreted.

Filter by Space:

  • space (Entity): Only colliders that are in the given space will match. Defaults to World (the main space).

Note:

Only entities that have both a Collider (e.g. PolygonCollider) and a Category will be considered by this function. If an entity has multiple colliders that match, it will be returned multiple times. If no colliders overlap, returns undefined.

This function uses a cached spatial index for performance reasons. See ResetSpatialQueryIndex for more details.

QueryNearestAlongRay​

body.QueryNearestAlongRay<Id?>(direction, maxDistance?=, filter?, solids?, sensors?, against?, [owner?, space?]) -> entity, distance

Searches along a ray for the nearest collider that matches the specified criteria, returning the Entity that owns the collider, and a Number representing the distance to contact.

  • body (Vector or Entity) and Id: If body is a Vector, will search from that position. If body is an Entity, will search from the position of the collider identified by body and Id. Searching using a collider can be more powerful than just a Vector position as it checks whether the collider's entire shape overlaps, not just its center point. If this is nullish, returns undefined.
  • direction (Vector): The direction to search in.
  • maxDistance (Number): The maximum distance to search.

Filter by Category:

  • filter (Categories): For a collider to match, both the collider's categories and it's body's Category property must overlap with the filter.

Filter by Solid/Sensor:

  • sensors (Boolean): Whether to include or exclude sensor colliders in the results. Defaults to true.
  • solids (Boolean): Whether to include or exclude non-sensor colliders in the results. Defaults to true. Defaults to Category:All.

Filter by Alliance:

  • against (Flags): Filters entities based on their alliance status with owner. For an entity to match, the alliance status between the owner parameter and the Owner of the Entity must overlap with against. Defaults to Alliance:All. See Alliance flags for all possible values.
  • owner (Entity): The player who is performing the query. Affects how the against filter is interpreted.

Filter by Space:

  • space (Entity): Only colliders that are in the given space will match. Defaults to World (the main space).

Note:

This function returns the distance to contact. This means if searching for a collider-to-collider contact along the ray, this is the minimum distance the first collider must move along the ray in order for their edges (not centroids) to touch.

This function uses a cached spatial index for performance reasons. See ResetSpatialQueryIndex for more details.

QueryOverlapping​

body.QueryOverlapping<Id?>(filter?, solids?=, sensors?, against?, [owner?, space?]) -> entityArray

Returns an array of all colliders that overlap the given collider or position and match the specified criteria.

  • body (Vector or Entity): A Vector position or an Entity that owns a collider to check for overlaps. Checking for a Collider rather than just a Vector position is more powerful as it checks whether the collider's entire shape overlaps, not just its center point.
  • Id: If body refers to a collider, the Id of the collider, if it has one.

Filter by Category:

  • filter (Categories): For a collider to match, both the collider's categories and it's body's Category property must overlap with the filter. Defaults to Category:All.

Filter by Solid/Sensor:

  • sensors (Boolean): Whether to include or exclude sensor colliders in the results. Defaults to true.
  • solids (Boolean): Whether to include or exclude non-sensor colliders in the results. Defaults to true.

Filter by Alliance:

  • against (Flags): Filters entities based on their alliance status with owner. For an entity to match, the alliance status between the owner parameter and the Owner of the Entity must overlap with against. Defaults to Alliance:All. See Alliance flags for all possible values.
  • owner (Entity): The player who is performing the query. Affects how the against filter is interpreted.

Filter by Space:

  • space (Entity): Only colliders that are in the given space will match. Defaults to World (the main space).

Note:

Only entities that have both a Collider (e.g. PolygonCollider) and a Category will be considered by this function. If an entity has multiple colliders that match, it will be returned multiple times. If no colliders overlap, returns an empty array.

This function uses a cached spatial index for performance reasons. See ResetSpatialQueryIndex for more details.

QueryWithinRadius​

body.QueryWithinRadius(radius, filter?=, solids?, sensors?, against?, [owner?, space?]) -> entityArray

Returns an array of all colliders that are within the given radius of the given position and match the specified criteria.

  • body (Vector or Entity): The origin point from which to search. If given an Entity, will use the position (Pos of its body. If this is nullish, returns undefined.
  • radius (Number): The radius to search within.

Filter by Category:

  • filter (Categories): For a collider to match, both the collider's categories and it's body's Category property must overlap with the filter. Defaults to Category:All.

Filter by Solid/Sensor:

  • sensors (Boolean): Whether to include or exclude sensor colliders in the results. Defaults to true.
  • solids (Boolean): Whether to include or exclude non-sensor colliders in the results. Defaults to true.

Filter by Alliance:

  • against (Flags): Filters entities based on their alliance status with owner. For an entity to match, the alliance status between the owner parameter and the Owner of the Entity must overlap with against. Defaults to Alliance:All. See Alliance flags for all possible values.
  • owner (Entity): The player who is performing the query. Affects how the against filter is interpreted.

Filter by Space:

  • space (Entity): Only colliders that are in the given space will match. Defaults to World (the main space).

Notes:

Only entities that have both a Collider (e.g. PolygonCollider) and a Category will be considered by this function. If an entity has multiple colliders that match, it will be returned multiple times. If no colliders overlap, returns an empty array.

This function uses a cached spatial index for performance reasons. See ResetSpatialQueryIndex for more details.

RecoverSpeed​

body.RecoverSpeed([speed=, speedDecay?])
delete body.RecoverSpeed

Makes the speed of body recover towards speed by a certain proportion after the physics simulation phase of each tick.

  • body (Entity): The entity to modify. If nullish, this function will do nothing.
  • speed (Number): The target speed of the body.
  • speedDecay (Number): The rate at which the body's speed recovers. Should be a value between 0 and 1. Values outside of this range will be clamped. Defaults to the physics.speedDecay configuration setting in easel.toml or 0.05 if not specified.

See also: DecaySpeed

RecoverTurnRate​

body.RecoverTurnRate([turnRate=, turningDecay?])
delete body.RecoverTurnRate

Makes the turn rate of body recover by a certain proportion towards turnRate after the physics simulation phase of each tick.

  • body (Entity): The entity to modify. If nullish, this function will do nothing.
  • turnRate (Number): The target turn rate of the body.
  • turningDecay (Number): The rate at which the body's turn rate recovers. Should be a value between 0 and 1. Values outside of this range will be clamped. Defaults to the physics.turningDecay configuration setting in easel.toml or 0.5 if not specified.

See also: DecayTurnRate

ResetSpatialQueryIndex​

ResetSpatialQueryIndex

Resets the spatial query index used by functions like QueryNearest. The spatial query index is updated automatically once per tick during the physics simulation. Unless you call this function, any changes to bodies or colliders will not be reflected in the spatial query index until the next physics tick. Calculating the spatial query index is computationally expensive so it is recommended to only call this function only when necessary.

Speed​

body.Speed -> number
body.Speed = value

Gets or sets the current speed of the body, measured in distance per second. If body is nullish or refers to an entity with no body, does nothing.

Turn​

body.Turn(step)

Turns the body by the angle given by step during the next physics simulation.

  • step (Number): The intended angular distance to rotate during the next tick. The actual amount rotated will depend on the PhysicsTimescale and whether the body collides with other bodies during the simulation.

If any body or step is nullish, does nothing.

info

Turn(0.1rev) is equivalent to ForcefulTurn(0.1rev, restitution=0)

See also: ForcefulTurn, Move

TurnRate​

body.TurnRate -> number
body.TurnRate = value

Gets or sets the current turn rate of the body, measured in revolutions per second. If body is nullish or refers to an entity with no body, does nothing.

See also: Velocity, Speed

TurningInertia​

body.TurningInertia -> number

Gets the turning inertia of body. When a turning impulse is applied to the body, the resulting turn rate is inversely proportional to the turning inertia. This concept is sometimes called the moment of inertia or the angular inertia, and is analog of mass for rotational motion. The turning inertia is automatically calculated from the shape, density and offsets of the colliders on the body. If the body has noRotation=true, returns undefined as the body has infinite turning inertia. If the body is nullish, or body refers to an entity with no body or colliders, returns 0.

See also: Mass

Velocity​

body.Velocity -> vector
body.Velocity = value

Gets or sets the current velocity of the body, measured in distance per second. If body is nullish or refers to an entity with no body, does nothing.

See also: Speed, TurnRate