Skip to main content

Physics

Category​

Category:All -> categories

The set of all categories defined using with category keyword.

Category:None -> categories

An empty set of categories.

Category:Tangible -> categories

The set of all categories declared with tangible category. This is useful to make exceptions to the tangible category.

Examples:

To collide with any tangible colliders or grabbable item:

    PolygonCollider(..., collideWith = Category:Tangible | Category:Grabbable)

To collide with any tangible collider except for shields:

    PolygonCollider(..., collideWith = Category:Tangible ^ Category:Shield)

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.

ApplyImpulse​

body.ApplyImpulse(impulse)

Applies an impulse to the body, changing its velocity. The change in the velocity will equal the impulse divided by the body's mass. impulse must be a vector. 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 velocity will equal the turning impulse divided by the body's mass. turningImpulse must be a Number. If any parameter is nullish, does nothing.

BeforeCollide​

await this.BeforeCollide<Id?> -> entity

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

  • 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.

A collision starts once the two colliders involved come into contact. If this is nullish, waits forever.

Body​

this.Body([pos, velocity?=, heading?, turnRate?, immovable?, noRotation?, 
  gravityScale?, bullet?])
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.
  • pos (Vector): the position of the body.
  • heading (Number): the angle of the body, in radians.
  • velocity (Vector): the velocity of the body.
  • turnRate (Number): the rate at which the body turns in radians per second.
  • immovable (Boolean): if true, the body will not change its velocity after colliding with other bodies.
  • noRotation (Boolean): if true, the body will not change its heading after collding with other bodies.
  • gravityScale (Number): a multiplier for the Gravity applied to the body. Defaults to 1.
  • bullet (Boolean): if true, the body will use continuous collision detection. This more computationally expensive, but ensures that a fast-moving body (like a bullet or projectile) does not tunnel through other bodies.

Category​

this.Category -> categories
this.Category = categories
delete this.Category -> categories

Gets, sets or deletes the categories of this entity. delete Category will return the previous category, or undefined if the entity had no category assigned previously.

If entity is nullish, will do nothing and/or return undefined.

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 setting in physics.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.

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 setting in physics.toml or 0.5 if not specified.

ForcefulStep​

body.ForcefulStep(step)

Applies a once-off force to move the body's position by the given step during the next physics simulation. The force will be added at the start of the physics simulation and then the opposite force will be applied at the end, so it will cancel out. The body will collide like normal during the physics simulation, and so this force may be transferred to other bodies. This allows for realistic simulation of charging into objects and sending them crashing backward, for example.

step must be a Vector. If any parameter is nullish, does nothing.

ForcefulTurn​

body.ForcefulTurn(step)

Applies a once-off force to rotate the body's heading by the given step during the next physics simulation. The force will be added at the start of the physics simulation and then the opposite force will be applied at the end, so it will cancel out. The body will collide like normal during the physics simulation, and so this force may be transferred to other bodies. This allows for realistic simulation of swinging a sword and hitting objects, for example.

step must be a Number. If any parameter is nullish, does nothing.

Gravity​

Gravity -> vector

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

Gravity = value

Sets the gravity for the World.

  • 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).

Example:

Gravity = 10
Gravity = @(0, 10)

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.

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.

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 nullish, or body refers to an entity with no body or colliders, returns 0.

PolygonCollider​

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

  • body (Entity or Vector): The position of the collider, whether it be attached to an Entity's body or a fixed Vector position in the world. If a collider is a Vector, the collider will be placed at a fixed position and will not move in response to collision forces and will not generate collision events.

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

  • 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.

  • 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.

  • isolate (Boolean): When isolate is false (the default), you can listen for collision events using BeforeCollide/AfterCollide with or without an <Id> parameter. If isolate is truthy, then you must use BeforeCollide<Id> and AfterCollide<Id> to detect collisions with this collider. No collision events will be generated for BeforeCollide/AfterCollide with no <Id>. 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.

  • 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.

  • 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.

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

  • 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.

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

  • sense (Categories): The collider will generate collision events with these categories, but no forces will be applied. If a category is in both sense and collideWith, then sense will take precedence.

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

  • 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.

  • 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): 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.

QueryAnyOverlapping​

body.QueryAnyOverlapping<Id?>(filter?, against?=, [owner?]) -> 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 (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.
  • against (Flags) and owner (Entity): The alliance status between the entity and owner must overlap at least one of these alliance flags. Defaults to Alliance:All.

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?=, against?, [owner?]) -> 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 (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.
  • against (Flags) and owner (Entity): The alliance status between the entity and owner must overlap at least one of these alliance flags. Defaults to Alliance:All.

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.

QueryNearest​

body.QueryNearest(filter?, against?=, [owner?]) -> 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.
  • 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.
  • against (Flags) and owner (Entity): The alliance status between the entity and owner must overlap at least one of these alliance flags. Defaults to Alliance:All.

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?, against?, [owner?]) -> 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 (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.
  • against (Flags) and owner (Entity): The alliance status between the entity and owner must overlap at least one of these alliance flags. Defaults to Alliance:All.

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.

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.

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

QueryOverlapping​

body.QueryOverlapping<Id?>(filter?, against?=, [owner?]) -> 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 (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.
  • against (Flags) and owner (Entity): The alliance status between the entity and owner must overlap at least one of these alliance flags. Defaults to Alliance:All.

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?=, against?, [owner?]) -> 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 (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.
  • against (Flags) and owner (Entity): The alliance status between the entity and owner must overlap at least one of these alliance flags. Defaults to Alliance:All.

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 setting in physics.toml or 0.05 if not specified.

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 setting in physics.toml or 0.5 if not specified.

ResetSpatialQueryIndex​

ResetSpatialQueryIndex

Resets the cached spatial query index used by functions like QueryNearest. The spatial query index is cleared by itself at the end of each tick and after each physics simulation. Any changes to bodies or colliders after these times will not be reflected in the cached index without calling this function. 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. If body is nullish or refers to an entity with no body, does nothing.

TurnRate​

body.TurnRate -> number
body.TurnRate = value

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

Velocity​

body.Velocity -> vector
body.Velocity = value

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