Creates a new sprite.
Input parameters are optional. A sprite's default position is in the center of the canvas [0,0] and default box collider is 50x50 pixels.
Optionalx: numberhorizontal position
Optionaly: numbervertical position
Optionalw: numberwidth of the collider
Optionalh: numberheight of the collider
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Creates a new sprite.
Optionalx: numberhorizontal position
Optionaly: numbervertical position
Optionalw: numberwidth of the collider
Optionalh: numberheight of the collider
OptionalroundedRadius: numbercorner radius for a rounded box collider
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Creates a new sprite with a circle collider.
horizontal position
vertical position
diameter of the circle collider
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Creates a new sprite with a capsule collider.
array of two [x, y] points defining the capsule's endpoints
the radius of the capsule's rounded ends
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Creates a new sprite with a chain or polygon collider defined by absolute vertex positions. If the first and last vertex are the same and the shape is convex, it becomes a polygon.
array of [x, y] vertex positions
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Creates a new sprite with a chain collider defined by relative vertex offsets from the sprite's position.
horizontal position
vertical position
array of relative [x, y] vertex offsets
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Creates a new sprite with a chain collider defined by alternating segment lengths and angles. Each angle is relative to the previous segment's angle. If the last value is 5, the chain is closed into a loop.
horizontal position
vertical position
alternating segment lengths and relative angles; append 5 to close the chain
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Creates a new sprite with a rounded chain collider defined by alternating segment lengths and angles. Each angle is relative to the previous segment's angle. If the last value is 5, the chain is closed into a loop.
horizontal position
vertical position
alternating segment lengths and relative angles; append 5 to close the chain
the rounded radius of the chain's segments
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Creates a new sprite with a regular polygon collider.
horizontal position
vertical position
the length of each side of the polygon
'triangle', 'square', 'pentagon', 'hexagon', 'septagon', or 'octagon'
OptionalroundedRadius: numbercorner radius for a rounded polygon
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Keys are the animation label, values are Ani objects.
The Box2D body id for the sprite's physics body. Don't change it!
Array of colliders that are part of the sprite's physics body.
Groups the sprite belongs to.
Each sprite has a unique id number. Don't change it! They are useful for debugging.
Joints that the sprite is attached to.
Modification tracking object.
It has sprite property number codes as keys, these correspond to the index of the property in the Sprite.props array, and boolean values, that indicate which properties were changed since the last frame.
Useful for limiting the amount of sprite data sent in netcode to only the sprite properties that have been modified.
The sprite's rotation on the previous frame.
The sprite's x position on the previous frame.
The sprite's y position on the previous frame.
Array of sensors that are part of the sprite's physics body. Sensors are used to detect overlaps without causing physical collisions.
Text displayed at the center of the sprite.
Horizontal velocity of the visual.
Vertical velocity of the visual.
If set to true, q5play will record all changes to the sprite's
properties in its mod array. Intended to be used to enable
online multiplayer.
Stores animations. Keys are the animation label, values are Ani objects
A bearing indicates the direction that needs to be followed to reach a destination.
Setting a sprite's bearing doesn't do anything by itself.
You can apply a force to the sprite at its bearing angle
using the applyForce function.
The sprite's absolute position on the canvas.
The center of mass of the sprite's physics body, the point at which the physics body is balanced and rotates around. By default it's the same as the sprite's position, but it can be changed with this setter.
The diameter of a circular sprite.
The diameter of a circular sprite.
The angle of the sprite's movement.
Can be set with directional strings like "up", "down", "left", "right", "upRight", "upLeft", "downRight", and "downLeft". The setter's input parser ignores capitalization, spaces, underscores, dashes, and cardinal direction word order.
Displays the sprite.
This function is called automatically at the end of each
sketch draw function call but it can also be run
by users to customize the order sprites are drawn in relation
to other stuff drawn on the canvas. Also see the sprite.layer
property.
A sprite's draw function can be overridden with a custom draw function, inside this function (0, 0) is the center of the sprite.
Draws the visual on the canvas.
Whether the sprite can be grabbed by a pointer.
The height of the sprite.
Half the height of the sprite.
Half the width of the sprite.
The height of the sprite.
Half the height of the sprite.
Half the width of the sprite.
Sprites with the highest layer value get drawn first.
By default sprites are drawn in the order they were created in.
The mass of the sprite's physics body.
Gets the sprite's position as a readonly object {x, y} which won't be updated if the sprite moves. Useful for saving the sprite's position at a specific moment in time.
The sprite's position vector.
The sprite's position vector.
The sprite's rotation on the previous frame. Alias for sprite.prevRotation.
The sprite's x position on the previous frame. Alias for sprite.prevX.
The sprite's y position on the previous frame. Alias for sprite.prevY.
The radius of a circular sprite.
The radius of a circular sprite.
Horizontal and vertical scale of the sprite.
Components can be negative to flip/mirror the sprite on an axis.
The valueOf function for sprite.scale returns the scale as a
number. This enables users to do things like sprite.scale *= 2
to double the sprite's scale.
The minimum speed (in m/s) at which the sprite must be moving before it is considered awake.
The sprite's stroke weight, the thickness of its outline.
The sprite's text size, the sketch's current textSize by default.
The tile character that represents the sprite in a tile map.
Runs before each physics update by default.
Set this to a custom function that handles input, directs sprite movement, and performs other tasks that should run before the physics update.
Optionally, users can run this function manually in q5play's update
function.
The width of the sprite.
The width of the sprite.
The horizontal position of the sprite.
Horizontal position of the visual.
The vertical position of the sprite.
Vertical position of the visual.
Adds an animation to the Sprite or Visual.
the URL of the sprite sheet image
the number of frames in the sprite sheet
A promise that fulfills when the animation is loaded
Add multiple animations to the Sprite or Visual.
an object with animation names as keys and an animation or animation atlas as values
A promise that fulfills when the animations are loaded
Add multiple animations to the Sprite or Visual.
the URL of the sprite sheet image
an object with animation names as keys and an animation or animation atlas as values
A promise that fulfills when the animations are loaded
Add multiple animations to the Sprite or Visual.
the URL of the sprite sheet image
the size of each frame in the sprite sheet in the format "WIDTHxHEIGHT" (example: "32x32")
an object with animation names as keys and an animation or animation atlas as values
A promise that fulfills when the animations are loaded
Adds a collider to the sprite's physics body.
It accepts parameters in a similar format to the Sprite constructor except the first two parameters are x and y offsets, the distance new collider should be from the center of the sprite.
This function also recalculates the sprite's mass based on the size of the new collider added to it. However, it does not move the sprite's center of mass, which makes adding multiple colliders to a sprite easier.
distance from the center of the sprite
distance from the center of the sprite
Optionalw: numberwidth of the collider
Optionalh: numberheight of the collider
OptionalroundedRadius: numbercorner radius for a rounded box collider
Creates overlap sensors that are the same size as the sprite's
colliders. If you'd like to add more sensors to a sprite, use the
addSensor function.
Used internally if a sprite overlap detection function is called but the sprite has no overlap sensors.
Adds an overlap sensor to the sprite's physics body.
Sensors can't displace or be displaced by colliders. Sensors don't have any mass or other physical properties. Sensors simply detect overlaps.
This function accepts parameters in a similar format to the Sprite constructor except the first two parameters are x and y offsets, the relative distance the new sensor should be from the center of the sprite.
distance from the center of the sprite
distance from the center of the sprite
Optionalw: numberwidth of the collider
Optionalh: numberheight of the collider
OptionalroundedRadius: numbercorner radius for a rounded box sensor
Finds the minimum angular distance the sprite would need to rotate to face a position, taking into account the sprite's current rotation.
Useful for rotateTowards-style logic where you need the signed delta
rather than an absolute target angle.
x coordinate
y coordinate
Optionalfacing: numberoffset angle, default is 0
the minimum angular distance to face the position
Finds the minimum angular distance the sprite would need to rotate to face a position, taking into account the sprite's current rotation.
object with x and y properties
Optionalfacing: numberoffset angle, default is 0
the minimum angular distance to face the position
Finds the angle from this sprite to the given position.
Equivalent to atan2(y - sprite.y, x - sprite.x) + facing.
Returns the sprite's current rotation if the position is within 0.01 pixels.
Can be used to set the direction of a sprite so it moves toward a position.
x coordinate
y coordinate
Optionalfacing: numberoffset angle added to the result, default is 0
angle to the position
Finds the angle from this sprite to the given position.
object with x and y properties
Optionalfacing: numberoffset angle added to the result, default is 0
angle to the position
Applies a force magnitude at the sprite's current bearing.
force magnitude
Optionalorigin: { x: number; y: number }point (relative to the sprite) where the force is applied. Accepts an object with x and y properties.
Applies a force vector to the sprite.
force vector as an object with x and y properties or array of [x, y]
Optionalorigin: { x: number; y: number }point (relative to the sprite) where the force is applied. Accepts an object with x and y properties.
Applies a force scaled to the sprite's mass using a magnitude.
force magnitude
Optionalorigin: { x: number; y: number }point (relative to the sprite) where the force is applied. Accepts an object with x and y properties.
Applies a force scaled to the sprite's mass using a vector.
force vector as an object with x and y properties
Optionalorigin: { x: number; y: number }point (relative to the sprite) where the force is applied. Accepts an object with x and y properties.
Apply a torque on the sprite's physics body. Torque is the force that causes rotation. A positive torque will rotate the sprite clockwise. A negative torque will rotate the sprite counter-clockwise.
This function is the rotational equivalent of applyForce(). It will not imperatively set the sprite's rotation.
Applies wind force to the sprite.
the strength of the wind
the angle the wind is blowing at
Optionaldrag: numberthe force that opposes the relative velocity
Optionallift: numberthe force that is perpendicular to the relative velocity
Applies a force to the sprite's center of mass attracting it to the given position.
x coordinate
y coordinate
Optionalforce: numberApplies a force to the sprite's center of mass attracting it to the given position.
object with x and y properties
Optionalforce: numberChanges the sprite's animation. Use addAni to define the
animation(s) first.
the name of the animation to switch to
Deletes the Sprite from the sketch and all the groups it belongs to.
When a sprite is deleted it will not be drawn or updated anymore. If it has a physics body, it will be deleted from the physics simulation.
There's no way to undo this operation. If you want to hide a
sprite use sprite.visible = false instead.
Removes colliders from the sprite's physics body.
Removes overlap sensors from the sprite's physics body.
Returns the distance to another sprite, the mouse, a touch pointer,
or any other object with x and y properties. Uses q5's dist function.
distance
Returns the distance to another sprite, the mouse, a touch pointer,
or any other object with x and y properties. Uses q5's dist function.
object with x and y properties
distance
Attempts to move the sprite to a destination at a constant speed and stops the sprite if it reaches the destination.
The destination check is deferred until the sprite is estimated to be
at the target position, based on world.physicsTime.
destination x, or null to only move on the y-axis
destination y, or null to only move on the x-axis
Optionalspeed: numbermovement speed in pixels per frame, defaults to the sprite's current speed or 1
a lazy thenable that resolves true if the sprite reached the
destination, or false if it didn't.
Attempts to move the sprite to a destination at a constant speed and stops the sprite if it reaches the destination.
destination object with x and y properties
Optionalspeed: numbermovement speed in pixels per frame, defaults to the sprite's current speed or 1
a lazy thenable that resolves true if the sprite reached the
destination, or false if it didn't.
Moves the sprite towards a position at a percentage of the distance between itself and the destination.
destination x, or null to only move on the y-axis
destination y, or null to only move on the x-axis
Optionaltracking: numberpercent of the distance to move towards the destination as a 0-1 value, default is 0.1 (10% tracking)
Moves the sprite towards a position at a percentage of the distance between itself and the destination.
destination object with x and y properties
Optionaltracking: numberpercent of the distance to move towards the destination as a 0-1 value, default is 0.1 (10% tracking)
Plays an animation.
You can put special modifier characters before the name:
the name of the animation to play
A promise that fulfills when the animation completes
Plays a sequence of animations.
You can put special modifier characters before each ani name:
You can put sequence modifiers at the end of the sequence:
the names of animations
A promise that fulfills when the sequence completes
Applies a force to the sprite's center of mass repelling it from the given position.
x coordinate
y coordinate
Optionalforce: numberApplies a force to the sprite's center of mass repelling it from the given position.
object with x and y properties
Optionalforce: numberRecalculates the sprite's mass based on its current density and size.
Rotates the sprite by the smallest angular distance to a target angle at a constant speed, stopping when it arrives.
target rotation angle
Optionalspeed: numberabsolute rotation per frame, defaults to the sprite's current rotationSpeed or 1
a lazy thenable that resolves true if the sprite reached the
target angle, or false if it didn't.
Rotates the sprite by the smallest angular distance to face a position at a constant speed, stopping when it arrives.
object with x and y properties
Optionalspeed: numberabsolute rotation per frame, defaults to the sprite's current rotationSpeed or 1
Optionalfacing: numberrotation angle the sprite should be at when "facing" the position, default is 0
a lazy thenable that resolves true if the sprite reached the
target angle, or false if it didn't.
Rotates the sprite to a target angle at a constant speed, stopping if it arrives.
The destination check is deferred until the sprite is estimated to be
at the target angle, based on world.physicsTime.
target rotation angle
Optionalspeed: numberrotation speed in degrees (or radians) per frame, defaults to the sprite's current rotationSpeed or 1
a lazy thenable that resolves true if the sprite reached the
target angle, or false if it didn't.
Rotates the sprite to face a position at a constant speed, stopping if it arrives.
object with x and y properties
Optionalspeed: numberrotation speed in degrees (or radians) per frame, defaults to the sprite's current rotationSpeed or 1
Optionalfacing: numberrotation angle the sprite should be at when "facing" the position, default is 0
a lazy thenable that resolves true if the sprite reached the
target angle, or false if it didn't.
Rotates the sprite towards an angle.
angle in degrees
Optionaltracking: numberpercent of the distance to rotate on each frame towards the target angle, default is 0.1 (10%)
Rotates the sprite towards a position.
object with x and y properties
Optionaltracking: numberpercent of the distance to rotate on each frame towards the target position, default is 0.1 (10%)
Optionalfacing: numberrotation angle the sprite should be at when "facing" the position, default is 0
Scales the the sprite.
Components can be negative to flip/mirror the sprite on an axis.
horizontal scale factor or uniform scale factor for both axes
Optionaly: numbervertical scale factor
Efficiently sets the sprite's speed and direction at the same time.
Returns the sprite's unique identifier sprite.idNum.
the sprite's id
Moves and rotates a sprite's physics body towards a target transform at a percentage of the distance on each frame.
Uses Box2D's b2Body_SetTargetTransform for maximum efficiency
compared to using moveTowards and rotateTowards separately.
destination x
destination y
Optionalrotation: numbertarget rotation angle
Optionaltracking: numberpercent of the distance to move towards the target as a 0-1 value, default is 0.1 (10% tracking)
Moves and rotates a sprite's physics body towards a target transform at a percentage of the distance on each frame.
destination object with x and y properties
Optionalrotation: numbertarget rotation angle
Optionaltracking: numberpercent of the distance to move towards the target as a 0-1 value, default is 0.1 (10% tracking)
StaticwithCreates a new sprite with an overlap sensor instead of a collider.
Optionalx: numberhorizontal position
Optionaly: numbervertical position
Optionalw: numberwidth of the sensor
Optionalh: numberheight of the sensor
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Creates a new sprite with an overlap sensor instead of a collider.
Optionalx: numberhorizontal position
Optionaly: numbervertical position
Optionalw: numberwidth of the sensor
Optionalh: numberheight of the sensor
OptionalroundedRadius: numbercorner radius for a rounded box sensor
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Creates a new sprite with a circle overlap sensor.
horizontal position
vertical position
diameter of the circle sensor
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Creates a new sprite with a capsule overlap sensor.
array of two [x, y] points defining the capsule's endpoints
the radius of the capsule's rounded ends
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Creates a new sprite with a chain overlap sensor defined by absolute vertex positions. If the first and last vertex are the same and the shape is convex, it becomes a polygon sensor.
array of [x, y] vertex positions
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Creates a new sprite with a chain overlap sensor defined by relative vertex offsets from the sprite's position.
horizontal position
vertical position
array of relative [x, y] vertex offsets
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Creates a new sprite with a chain overlap sensor defined by alternating segment lengths and angles. Each angle is relative to the previous segment's angle. If the last value is 5, the chain is closed into a loop.
horizontal position
vertical position
alternating segment lengths and relative angles; append 5 to close the chain
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Creates a new sprite with a rounded chain overlap sensor defined by alternating segment lengths and angles. Each angle is relative to the previous segment's angle. If the last value is 5, the chain is closed into a loop.
horizontal position
vertical position
alternating segment lengths and relative angles; append 5 to close the chain
the rounded radius of the chain's segments
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
Creates a new sprite with a regular polygon overlap sensor.
horizontal position
vertical position
the length of each side of the polygon
'triangle', 'square', 'pentagon', 'hexagon', 'septagon', or 'octagon'
OptionalroundedRadius: numbercorner radius for a rounded polygon
OptionalphysicsType: stringphysics type is DYNAMIC by default, can be STATIC or KINEMATIC
A Sprite has a Box2D physics body with a collider (by default), which can interact with other sprites in the physics simulation.