p5play
Version:
A JavaScript game engine that uses p5.js for graphics and Box2D for physics.
1,778 lines (1,775 loc) • 91.5 kB
TypeScript
import 'q5';
declare global {
class P5Play {
/**
* The version of p5play.
* Patch versions are not denoted in this string.
*/
version: string;
/**
* Contains all the sprites in the sketch,
* but users should use the `allSprites` group.
*
* The keys are the sprite's unique ids.
* @type {Object.<number, Sprite>}
*/
sprites: {
[x: number]: Sprite;
};
/**
* Contains all the groups in the sketch,
*
* The keys are the group's unique ids.
* @type {Object.<number, Group>}
*/
groups: {
[x: number]: Group;
};
groupsCreated: number;
spritesCreated: number;
spritesDrawn: number;
/**
* Cache for loaded images.
*/
images: {};
/**
* Used for debugging, set to true to make p5play
* not load any images.
* @type {Boolean}
* @default false
*/
disableImages: boolean;
/**
* The default color palette, at index 0 of this array,
* has all the letters of the English alphabet mapped to colors.
* @type {Array}
*/
palettes: any[];
/**
* Emoji scale factor, used when making emoji images.
* @type {Number}
* @default 1
*/
emojiScale: number;
/**
* Friendly rounding eliminates some floating point errors.
* @type {Boolean}
* @default true
*/
friendlyRounding: boolean;
/**
* Groups that are deleted using `group.delete()` are not
* immediately erased from `p5play.groups` by default, so their data
* is still accessible. Set to false to permanently erase
* deleted groups, which reduces memory usage.
* @type {Boolean}
* @default true
*/
storeDeletedGroupRefs: boolean;
/**
* Snaps sprites to the nearest `p5play.gridSize`
* increment when they are moved.
* @type {Boolean}
* @default false
*/
snapToGrid: boolean;
/**
* The size of the grid cells that sprites are snapped to.
* @type {Number}
* @default 0.5
*/
gridSize: number;
/**
* Information about the operating system being used to run
* p5play, retrieved from the `navigator` object.
*/
os: {};
context: string;
hasMouse: boolean;
standardizeKeyboard: boolean;
/**
* Displays the number of sprites drawn, the current FPS
* as well as the average, minimum, and maximum FPS achieved
* during the previous second.
*
* FPS in this context refers to how many frames per second your
* computer can generate, based on the physics calculations and any
* other processes necessary to generate a frame, but not
* including the delay between when frames are actually shown on
* the screen. The higher the FPS, the better your game is
* performing.
*
* You can use this function for approximate performance testing.
* But for the most accurate results, use your web browser's
* performance testing tools.
*
* Generally having less sprites and using a smaller canvas will
* make your game perform better. Also drawing images is faster
* than drawing shapes.
* @type {Boolean}
* @default false
*/
renderStats: boolean;
/**
* This function is called when an image is loaded. By default it
* does nothing, but it can be overridden.
*/
onImageLoad(): void;
}
var p5play: P5Play;
var DYN: string;
var DYNAMIC: string;
var STA: string;
var STATIC: string;
var KIN: string;
var KINEMATIC: string;
/**
* @class
*/
class Sprite {
/**
* <a href="https://p5play.org/learn/sprite.html">
* Look at the Sprite reference pages before reading these docs.
* </a>
*
* Creates a new sprite.
*
* All parameters are optional. A sprite's default position is in the
* center of the canvas and default box collider is 50x50 pixels.
*
* Depending on the input parameters, the sprite can be created with
* a box, circle, polygon, or chain collider.
*
* Special feature! If the first parameter to this constructor is a
* loaded Image, Ani, or name of a animation,
* then the Sprite will be created with that animation. If the
* dimensions of the sprite are not given, then the Sprite will be
* created using the dimensions of the animation.
*
* Every sprite you create is added to the `allSprites`
* group and put on the top draw order layer, in front of all
* previously created sprites.
*
* @param {Number} [x] - horizontal position of the sprite
* @param {Number} [y] - vertical position of the sprite
* @param {Number} [w] - width of the placeholder rectangle and of
* the collider until an image or new collider are set. *OR* If height is not
* set then this parameter becomes the diameter of the placeholder circle.
* @param {Number} [h] - height of the placeholder rectangle and of the collider
* until an image or new collider are set
* @param {String} [physicsType] - physics type is DYNAMIC by default, can be
* STATIC, KINEMATIC, or NONE
* @example
*
* let spr = new Sprite();
*
* let rectangle = new Sprite(x, y, width, height);
*
* let circle = new Sprite(x, y, diameter);
*
* let spr = new Sprite(aniName, x, y);
*
* let line = new Sprite(x, y, [length, angle]);
*/
constructor(x?: number, y?: number, w?: number, h?: number, physicsType?: string, ...args: any[]);
/**
* Each sprite has a unique id number. Don't change it!
* They are useful for debugging.
* @type {Number}
*/
idNum: number;
/**
* Groups the sprite belongs to, including allSprites.
* @type {Group[]}
* @default [allSprites]
*/
groups: Group[];
/**
* An Anis object, which has animation labels as keys and Ani objects as values.
* @type {Anis}
*/
animations: Anis;
/**
* The joints that the sprite is attached to.
* @type {Joint[]}
* @default []
*/
joints: Joint[];
/**
* If set to true, p5play will record all changes to the sprite's
* properties in its `mod` array. Intended to be used to enable
* online multiplayer.
* @type {Boolean}
* @default undefined
*/
watch: boolean;
/**
* An Object that has sprite property number codes as keys,
* these correspond to the index of the property in the
* Sprite.props array. The booleans values this object stores,
* indicate which properties were changed since the last frame.
* Useful for limiting the amount of sprite data sent in binary
* netcode to only the sprite properties that have been modified.
* @type {Object}
*/
mod: any;
set tileSize(val: number);
/**
* DEPRECATED: Will be removed in version 4.
*
* The tile size is used to change the size of one unit of
* measurement for the sprite.
*
* For example, if the tile size is 16, then a sprite with
* x=1 and y=1 will be drawn at position (16, 16) on the canvas.
* @deprecated
* @type {Number}
* @default 1
*/
get tileSize(): number;
set collider(val: string);
/**
* Deprecated alias for `physicsType`/`physics`.
* @deprecated
* @type {String}
* @default DYNAMIC
*/
get collider(): string;
set x(val: number);
/**
* The horizontal position of the sprite.
* @type {Number}
*/
get x(): number;
set y(val: number);
/**
* The vertical position of the sprite.
* @type {Number}
*/
get y(): number;
set image(img: new (width?: number, height?: number) => HTMLImageElement);
/**
* The sprite's image or current frame of animation.
*
* When `sprite.image` is set, two properties are added:
*
* `sprite.image.offset` determines the x and y position the image
* should be drawn at relative to the sprite's center.
*
* `sprite.image.scale` determines the x and y scale of the image.
* @type {Image}
*/
get image(): new (width?: number, height?: number) => HTMLImageElement;
/**
* Used to detect mouse events with the sprite.
* @type {_SpriteMouse}
*/
mouse: _SpriteMouse;
set shape(val: string);
/**
* The kind of shape: 'box', 'circle', 'chain', or 'polygon'.
*
* If a sprite with a circle shape has its shape type changed to
* chain or polygon, the circle will be turned into a dodecagon.
* @type {String}
* @default box
*/
get shape(): string;
set w(val: number);
/**
* The width of the sprite.
* @type {Number}
*/
get w(): number;
set h(val: number);
/**
* The height of the sprite.
* @type {Number}
*/
get h(): number;
/**
* The sprite's position on the previous frame.
* @type {object}
*/
prevPos: object;
prevRotation: number;
/**
* Text displayed at the center of the sprite.
* @type {String}
* @default undefined
*/
text: string;
/**
* Deprecated alias for `sprite.delete()`.
*
* Will be removed in version 4.
* @deprecated
*/
remove: () => void;
/**
* Adds a collider (fixture) 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.
*
* For better physics simulation results, run the `resetCenterOfMass`
* function after you finish adding colliders to a sprite.
*
* One limitation of the current implementation is that sprites
* with multiple colliders can't have their collider
* type changed without losing every collider added to the
* sprite besides the first.
*
* @param {Number} offsetX - distance from the center of the sprite
* @param {Number} offsetY - distance from the center of the sprite
* @param {Number} w - width of the collider
* @param {Number} h - height of the collider
*/
addCollider(offsetX: number, offsetY: number, w: number, h: number, ...args: any[]): void;
body: any;
/**
* Adds a 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 with other sensors.
*
* 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.
*
* If a sensor is added to a sprite that has no collider (type "none")
* then internally it will be given a dynamic physics body that isn't
* affected by gravity so that the sensor can be added to it.
*
* @param {Number} offsetX - distance from the center of the sprite
* @param {Number} offsetY - distance from the center of the sprite
* @param {Number} w - width of the collider
* @param {Number} h - height of the collider
*/
addSensor(offsetX: number, offsetY: number, w: number, h: number, ...args: any[]): void;
set mass(val: number);
/**
* The mass of the sprite's physics body.
* @type {Number}
*/
get mass(): number;
set rotation(val: number);
/**
* The angle of the sprite's rotation, not the direction it's moving.
*
* If angleMode is set to "degrees", the value will be returned in
* a range of -180 to 180.
* @type {Number}
* @default 0
*/
get rotation(): number;
set vel(val: Vector);
/**
* The sprite's velocity vector {x, y}
* @type {Vector}
* @default {x: 0, y: 0}
*/
get vel(): Vector;
/**
* Removes the physics body colliders from the sprite but not
* overlap sensors.
*/
removeColliders(): void;
/**
* Removes overlap sensors from the sprite.
*/
removeSensors(): void;
set animation(val: Ani);
/**
* Reference to the sprite's current animation.
* @type {Ani}
*/
get animation(): Ani;
set ani(val: Ani);
/**
* Reference to the sprite's current animation.
* @type {Ani}
*/
get ani(): Ani;
/**
* Keys are the animation label, values are Ani objects
* @type {Anis}
*/
get anis(): Anis;
set autoUpdate(val: boolean);
/**
* Controls whether a sprite is updated before each physics update,
* when users let p5play automatically manage the frame cycle.
* @type {Boolean}
* @default true
*/
get autoUpdate(): boolean;
set autoDraw(val: boolean);
/**
* Controls whether a sprite is drawn after each physics update,
* when users let p5play automatically manage the frame cycle.
* @type {Boolean}
* @default true
*/
get autoDraw(): boolean;
set allowSleeping(val: boolean);
/**
* Controls the ability for a sprite to "sleep".
*
* "Sleeping" sprites are not included in the physics simulation, a
* sprite starts "sleeping" when it stops moving and doesn't collide
* with anything that it wasn't already touching.
* @type {Boolean}
* @default true
*/
get allowSleeping(): boolean;
set bounciness(val: number);
/**
* The bounciness of the sprite's physics body.
* @type {Number}
* @default 0.2
*/
get bounciness(): number;
set rotationSpeed(val: number);
/**
* The speed of the sprite's rotation in angles per frame.
* @type {Number}
* @default 0
*/
get rotationSpeed(): number;
set physicsType(val: string);
/**
* Verbose alias for `physics`.
* @type {String}
* @default DYNAMIC
*/
get physicsType(): string;
set physics(val: string);
/**
* The sprite's physics type. Default is DYNAMIC.
*
* The physics type can be one of the following:
* DYNAMIC, STATIC, KINEMATIC, or NONE.
*
* DYN, STA, and KIN can be used as shorthand.
*
* When a sprite's physics type is changed to NONE,
* or from NONE to another type, the sprite will
* maintain its current position, velocity, rotation, and
* rotation speed.
*
* Sprites can't have their physics type
* set to NONE if they have a polygon or chain collider,
* multiple colliders, or multiple sensors.
*
* To achieve the same effect as setting physics type
* to NONE, use `.overlaps(allSprites)` to have your
* sprite overlap with all sprites.
*
* @type {String}
* @default DYNAMIC
*/
get physics(): string;
set color(val: Color);
/**
* Alias for `fill`.
*
* By default sprites get a random color.
* @type {Color}
* @default random color
*/
get color(): Color;
set colour(val: Color);
/**
* Alias for `color` and `fill`. colour is the British English spelling.
* @type {Color}
* @default random color
*/
get colour(): Color;
set fill(val: Color);
/**
* Sets the sprite's fill color.
* @type {Color}
* @default random color
*/
get fill(): Color;
set stroke(val: Color);
/**
* Overrides sprite's stroke color. By default the stroke of a sprite
* is determined by its collider type, which can also be overridden
* by the sketch's stroke color.
* @type {Color}
* @default undefined
*/
get stroke(): Color;
set strokeWeight(val: number);
/**
* The sprite's stroke weight, the thickness of its outline.
* @type {Number}
* @default undefined
*/
get strokeWeight(): number;
set textColor(val: Color);
/**
* Alias for `textFill`.
* @type {Color}
* @default black (#000000)
*/
get textColor(): Color;
set textColour(val: Color);
/**
* Alias for `textFill`.
* @type {Color}
* @default black (#000000)
*/
get textColour(): Color;
set textFill(val: Color);
/**
* The sprite's text fill color. Black by default.
* @type {Color}
* @default black (#000000)
*/
get textFill(): Color;
set textSize(val: number);
/**
* The sprite's text size, the sketch's current textSize by default.
* @type {Number}
*/
get textSize(): number;
set textStroke(val: Color);
/**
* The sprite's text stroke color.
* No stroke by default, does not inherit from the sketch's stroke color.
* @type {Color}
* @default undefined
*/
get textStroke(): Color;
set textStrokeWeight(val: number);
/**
* The sprite's text stroke weight, the thickness of its outline.
* No stroke by default, does not inherit from the sketch's stroke weight.
* @type {Number}
* @default undefined
*/
get textStrokeWeight(): number;
set tile(val: string);
/**
* The tile string represents the sprite in a tile map.
* @type {String}
*/
get tile(): string;
set bearing(val: number);
/**
* 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 at the sprite's
* bearing angle using the `applyForce` function.
* @type {Number}
* @example
* sprite.bearing = angle;
* sprite.applyForce(amount);
*/
get bearing(): number;
set debug(val: boolean);
/**
* If true, an outline of the sprite's collider will be drawn.
* @type {Boolean}
* @default false
*/
get debug(): boolean;
set density(val: number);
/**
* The density of the sprite's physics body.
* @type {Number}
* @default 5
*/
get density(): number;
set direction(val: number);
/**
* The angle of the sprite's movement.
* @type {Number}
* @default 0 ("right")
*/
get direction(): number;
set drag(val: number);
/**
* The amount of resistance a sprite has to being moved.
* @type {Number}
* @default 0
*/
get drag(): number;
set draw(val: Function);
/**
* 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 to 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.
*
* Using this function actually calls the sprite's internal `_display`
* function, which sets up the canvas for drawing the sprite before
* calling the sprite's `_draw` function. See the example below for how to
* run the sprite's default `_draw` function inside your custom `draw` function.
*
* @type {Function}
* @example
* let defaultDraw = sprite._draw;
*
* sprite.draw = function() {
* // add custom code here
* defaultDraw();
* }
*/
get draw(): Function;
set dynamic(val: boolean);
/**
* True if the sprite's physics body is dynamic.
* @type {Boolean}
* @default true
*/
get dynamic(): boolean;
/**
* Returns the first node in a linked list of the planck physics
* body's fixtures.
*/
get fixture(): any;
/**
* Returns the first node in a linked list of the planck physics
* body's fixtures.
*/
get fixtureList(): any;
set friction(val: number);
/**
* The amount the sprite's physics body resists moving
* when rubbing against another physics body.
* @type {Number}
* @default 0.5
*/
get friction(): number;
set heading(val: string);
/**
* The sprite's heading. This is a string that can be set to
* "up", "down", "left", "right", "upRight", "upLeft", "downRight"
*
* It ignores cardinal direction word order, capitalization, spaces,
* underscores, and dashes.
* @type {String}
* @default undefined
*/
get heading(): string;
set img(val: new (width?: number, height?: number) => HTMLImageElement);
/**
* Alias for `sprite.image`.
* @type {Image}
*/
get img(): new (width?: number, height?: number) => HTMLImageElement;
/**
* Read only. True if the sprite is moving.
* @type {Boolean}
*/
get isMoving(): boolean;
set isSuperFast(val: boolean);
/**
* Set this to true if the sprite goes really fast to prevent
* inaccurate physics simulation.
* @type {Boolean}
* @default false
*/
get isSuperFast(): boolean;
set kinematic(val: boolean);
/**
* True if the sprite's physics body is kinematic.
* @type {Boolean}
* @default false
*/
get kinematic(): boolean;
set layer(val: number);
/**
* By default sprites are drawn in the order they were created in.
* You can change the draw order by editing sprite's layer
* property. Sprites with the highest layer value get drawn first.
* @type {Number}
*/
get layer(): number;
set life(val: number);
/**
* When the physics simulation is progressed in `world.physicsUpdate`,
* each sprite's life is decreased by `world.timeScale`.
*
* If life becomes less than or equal to 0, the sprite will
* be removed.
*
* It must be set to a positive integer lower than the max value of
* a 32 bit signed integer, 2147483647, which is the default value
* representing infinite life. This limitation makes sprite netcode
* smaller. But don't worry, at 60 fps this gives users a definable
* sprite life range between 1 frame and ~411 days!
* @type {Number}
* @default 2147483647
*/
get life(): number;
/**
* Recalculates the sprite's mass based on its current
* density and size.
*
* Does not change the sprite's center of mass, to do so
* use the `resetCenterOfMass` function.
*/
resetMass(): void;
/**
* Recalculates the sprite's center of mass based on the masses of
* its fixtures and their positions. Moves the sprite's center to
* the new center of mass, but doesn't actually change the positions
* of its fixtures relative to the world.
*
* In p5play a sprite's center (position) is always the same as its
* center of mass and center of rotation.
*/
resetCenterOfMass(): void;
set mirror(val: any);
/**
* DEPRECATED: Will be removed in version 4.
*
* Use sprite.scale instead.
* @deprecated
* @type {Object}
* @property {Boolean} x - the sprite's horizontal mirror state
* @property {Boolean} y - the sprite's vertical mirror state
* @default {x: false, y: false}
*/
get mirror(): any;
set offset(val: object);
/**
* Offsetting the sprite moves the sprite's physics body relative
* to its center.
*
* The sprite's x and y properties represent its center in world
* coordinates. This point is also the sprite's center of rotation.
* @type {object}
* @property {Number} x - the sprite's horizontal offset
* @property {Number} y - the sprite's vertical offset
* @default {x: 0, y: 0}
*/
get offset(): object;
set opacity(val: number);
/**
* The sprite's opacity. 0 is transparent, 1 is opaque.
* @type {Number}
* @default 1
*/
get opacity(): number;
set previousPosition(val: any);
/**
* Alias for sprite.prevPos
* @type {Object}
*/
get previousPosition(): any;
set previousRotation(val: number);
/**
* Alias for sprite.prevRotation
* @type {Number}
*/
get previousRotation(): number;
set pixelPerfect(val: boolean);
/**
* By default p5play draws sprites with subpixel rendering.
*
* Set pixelPerfect to true to make p5play always display sprites
* at integer pixel precision. This is useful for making retro games.
*
* Also if using a tightly packed sprite sheet,
* consider setting `sprite.anis.cutFrames` to true.
*
* @type {Boolean}
* @default false
*/
get pixelPerfect(): boolean;
set rotationDrag(val: number);
/**
* The amount the sprite resists rotating.
* @type {Number}
* @default 0
*/
get rotationDrag(): number;
set rotationLock(val: boolean);
/**
* If true, the sprite can not rotate.
* @type {Boolean}
* @default false
*/
get rotationLock(): boolean;
set scale(val: number | any);
/**
* Scale of the sprite's physics body. Default is {x: 1, y: 1}
*
* The getter for sprite.scale returns the scale as an object with
* x and y properties.
*
* 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.
* @type {Number|Object}
* @default 1
*/
get scale(): number | any;
set sleeping(val: boolean);
/**
* Wake a sprite up or put it to sleep.
*
* "Sleeping" sprites are not included in the physics simulation, a
* sprite starts "sleeping" when it stops moving and doesn't collide
* with anything that it wasn't already touching.
* @type {Boolean}
* @default true
*/
get sleeping(): boolean;
set speed(val: number);
/**
* The sprite's speed.
*
* Setting speed to a negative value will make the sprite move
* 180 degrees opposite of its current direction angle.
* @type {Number}
* @default 0
*/
get speed(): number;
set static(val: boolean);
/**
* Is the sprite's physics collider static?
* @type {Boolean}
* @default false
*/
get static(): boolean;
set tint(val: Color);
/**
* Tint color applied to the sprite when drawn.
*
* Note that this is not good for performance, you should probably
* pre-render the effect if you want to use it a lot.
* @type {Color}
* @default undefined
*/
get tint(): Color;
set tintColor(val: Color);
/**
* Alias for sprite.tint
* @type {Color}
* @default undefined
*/
get tintColor(): Color;
/**
* The sprite's vertices, in vertex mode format.
* @type {Array}
*/
set vertices(val: any[]);
get vertices(): any[];
set visible(val: boolean);
/**
* If true the sprite is shown, if set to false the sprite is hidden.
*
* Becomes null when the sprite is off screen but will be drawn and
* set to true again if it goes back on screen.
* @type {Boolean}
* @default true
*/
get visible(): boolean;
set pos(val: Vector);
/**
* The position vector {x, y}
* @type {Vector}
*/
get pos(): Vector;
set position(val: Vector);
/**
* The position vector {x, y}
* @type {Vector}
*/
get position(): Vector;
/**
* The sprite's absolute position on the canvas. Read only.
*/
get canvasPos(): any;
set hw(val: number);
/**
* Half the width of the sprite.
* @type {Number}
*/
get hw(): number;
set width(val: number);
/**
* The width of the sprite.
* @type {Number}
*/
get width(): number;
set halfWidth(val: number);
/**
* Half the width of the sprite.
* @type {Number}
*/
get halfWidth(): number;
set hh(val: number);
/**
* Half the height of the sprite.
* @type {Number}
*/
get hh(): number;
set height(val: number);
/**
* The height of the sprite.
* @type {Number}
*/
get height(): number;
set halfHeight(val: number);
/**
* Half the height of the sprite.
* @type {Number}
*/
get halfHeight(): number;
set d(val: number);
/**
* The diameter of a circular sprite.
* @type {Number}
*/
get d(): number;
set diameter(val: number);
/**
* The diameter of a circular sprite.
* @type {Number}
*/
get diameter(): number;
set r(val: number);
/**
* The radius of a circular sprite.
* @type {Number}
*/
get r(): number;
set radius(val: number);
/**
* The radius of a circular sprite.
* @type {Number}
*/
get radius(): number;
set update(val: Function);
/**
* Runs before each physics update by default, when p5play is automatically
* managing the frame cycle.
*
* 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 p5play's `update`
* function.
* @type {Function}
*/
get update(): Function;
set postDraw(val: Function);
/**
* Runs at the end of the p5play frame cycle.
*
* Users should not directly run this function.
* @type {Function}
*/
get postDraw(): Function;
set velocity(val: Vector);
/**
* The sprite's velocity vector {x, y}
* @type {Vector}
* @default {x: 0, y: 0}
*/
get velocity(): Vector;
set gravityScale(val: number);
/**
* A ratio that defines how much the sprite is affected by gravity.
* @type {Number}
* @default 1
*/
get gravityScale(): number;
/**
* If this function is given a force amount, the force is applied
* at the angle of the sprite's current bearing. Force can
* also be given as a vector.
*
* The origin of the force can be given as a vector or as x and y
* coordinates. If no origin is given, the force is applied to the
* center of the sprite.
*
* @param {Number} amount
* @param {Vector} [origin]
* @example
* sprite.applyForce(amount);
* sprite.applyForce(amount, {x: originX, y: originY});
* sprite.applyForce(x, y);
* sprite.applyForce(x, y, {x: originX, y: originY});
* sprite.applyForce({x, y}, {x: originX, y: originY});
*/
applyForce(amount: number, origin?: Vector, ...args: any[]): void;
/**
* Applies a force that's scaled to the sprite's mass.
*
* @param {Number} amount
* @param {Vector} [origin]
*/
applyForceScaled(amount: number, origin?: Vector, ...args: any[]): void;
/**
* Applies a force to the sprite's center of mass attracting it to
* the given position.
*
* Radius and easing not implemented yet!
*
* @param {Number} x
* @param {Number} y
* @param {Number} force
* @param {Number} [radius] - infinite if not given
* @param {Number} [easing] - solid if not given
* @example
* sprite.attractTo(x, y, force);
* sprite.attractTo({x, y}, force);
*/
attractTo(x: number, y: number, force: number, radius?: number, easing?: number): void;
repelFrom(x: any, y: any, force: any, radius: any, easing: any): void;
/**
* 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.
*
* @param {Number} torque - The amount of torque to apply.
*/
applyTorque(val: any): void;
/**
* Moves a sprite towards a position at a percentage of the distance
* between itself and the destination.
*
* @param {Number|Object} x - destination x or an object with x and y properties
* @param {Number} y - destination y
* @param {Number} [tracking] - percent of the distance to move towards the destination as a 0-1 value, default is 0.1 (10% tracking)
*/
moveTowards(x: number | any, y: number, tracking?: number): void;
/**
* Moves the sprite away from a position, the opposite of moveTowards,
* at a percentage of the distance between itself and the position.
* @param {Number|Object} x - destination x or an object with x and y properties
* @param {Number} y - destination y
* @param {Number} [repel] - percent of the distance to the repel position as a 0-1 value, default is 0.1 (10% repel)
*/
moveAway(x: number | any, y: number, repel?: number, ...args: any[]): void;
/**
* Move the sprite a distance from its current position.
*
* You can specify the `direction` and `speed` of movement as
* parameters or set these properties before using this function.
*
* When `tileSize` is not 1, distance is divisible by 0.5,
* and a direction name or cardinal direction angle is given,
* the distance the sprite moves will be rounded up to the
* nearest half tile.
*
* @param {Number} distance
* @param {Number|String} [direction] - direction angle in degrees or a cardinal direction name, if not given the sprite's current direction is used
* @param {Number} [speed] - if not given, the sprite's current `speed` is used, unless it's 0 then it's given a default speed of 1 or 0.1 if the sprite's tileSize is greater than 1
* @returns {Promise} resolves when the movement is complete or cancelled
*
* @example
* sprite.direction = -90;
* sprite.speed = 2;
* sprite.move(1);
* // or
* sprite.move(1, -90, 2);
* // or
* sprite.move('up', 2);
*/
move(distance: number, direction?: number | string, speed?: number, ...args: any[]): Promise<any>;
/**
* Move the sprite to a position.
*
* @param {Number|Object} x - destination x or an object with x and y properties
* @param {Number} y - destination y
* @param {Number} [speed] - if not given, the sprite's current speed is used, unless it is 0 then it is given a default speed of 1 or 0.1 if the sprite's tileSize is greater than 1
* @returns {Promise} resolves to true when the movement is complete
* or to false if the sprite will not reach its destination
*/
moveTo(x: number | any, y: number, speed?: number): Promise<any>;
/**
* Rotates the sprite towards an angle or position
* with x and y properties.
*
* @param {Number|Object} angle - angle in degrees or an object with x and y properties
* @param {Number} [tracking] - percent of the distance to rotate on each frame towards the target angle, default is 0.1 (10%)
* @param {Number} [facing] - (only specify if position is given) rotation angle the sprite should be at when "facing" the position, default is 0
*/
rotateTowards(angle: number | any, tracking?: number, ...args: any[]): void;
/**
* Finds the angle from this sprite to the given position or object
* with x and y properties.
*
* Can be used to change the direction of a sprite so it moves
* to a position or object, as shown in the example.
*
* Used internally by `moveTo` and `moveTowards`.
*
* @param {Number} x
* @param {Number} y
* @returns {Number} angle
* @example
* spriteA.direction = spriteA.angleTo(spriteB);
*/
angleTo(x: number, y: number): number;
/**
* Finds the rotation angle the sprite should be at when "facing"
* a position.
*
* Used internally by `rotateTo`.
*
* @param {Number} x
* @param {Number} y
* @param {Number} [facing] - relative angle the sprite should be at when "facing" the position, default is 0
* @returns {Number} the rotation angle the sprite should be at when "facing" the position
*/
rotationToFace(x: number, y: number, facing?: number): number;
/**
* Finds the minimum angle distance that the sprite would have
* to rotate to "face" a position at a specified facing rotation,
* taking into account the current rotation of the sprite.
*
* Used internally by `rotateMinTo` and `rotateTowards`.
*
* @param {Number} x
* @param {Number} y
* @param {Number} facing - relative angle the sprite should be at when "facing" the position, default is 0
* @returns {Number} the minimum angle distance to face the position
*/
angleToFace(x: number, y: number, facing: number): number;
/**
* Rotates the sprite to an angle or to face a position
* at a given rotation speed.
*
* @param {Number|Object} angle - angle or a position object with x and y properties
* @param {Number} [speed] - amount of rotation per frame, if not given the sprite's current `rotationSpeed` is used, if 0 it defaults to 1
* @param {Number} [facing] - relative angle the sprite should be at when "facing" the given position, default is 0
* @returns {Promise} a promise that resolves when the rotation is complete
* @example
* sprite.rotationSpeed = 2;
* sprite.rotateTo(180);
* // or
* sprite.rotateTo(180, 2);
* // or
* // (x, y, speed)
* sprite.rotateTo(0, 100, 2);
* // or
* sprite.rotateTo({x: 0, y: 100}, 2);
*/
rotateTo(angle: number | any, speed?: number, facing?: number, ...args: any[]): Promise<any>;
/**
* Rotates the sprite by the smallest angular distance
* to an angle or to face a position at a given absolute
* rotation speed.
*
* @param {Number|Object} angle - angle or a position object with x and y properties
* @param {Number} speed - absolute amount of rotation per frame, if not given the sprite's current `rotationSpeed` is used
* @param {Number} facing - relative angle the sprite should be at when "facing" the given position, default is 0
*/
rotateMinTo(angle: number | any, speed: number, facing: number, ...args: any[]): Promise<any>;
/**
* Rotates the sprite by an angle amount at a given rotation speed.
*
* To achieve a clockwise rotation, use a positive angle and speed.
* To achieve a counter-clockwise rotation, use a negative angle
* or speed.
*
* When the rotation is complete, the sprite's rotation speed is
* set to 0 and sprite's rotation is set to the exact destination angle.
*
* If the angle amount is not evenly divisible by the rotation speed,
* the sprite's rotation speed will be decreased as it approaches the
* destination angle.
* @param {Number} angle - the amount to rotate the sprite
* @param {Number} [speed] - the absolute amount of rotation per frame, if not given the sprite's current `rotationSpeed` is used, if 0 it defaults to 1
* @returns {Promise} a promise that resolves when the rotation is complete
*/
rotate(angle: number, speed?: number): Promise<any>;
/**
* Adds an animation to the sprite. Use this function in the `preload`
* function. You don't need to name the animation if the sprite will only
* use one animation. See Ani for more information.
*
* If an animation was already added to a different sprite or group,
* it can not be added to another sprite or group. A clone (copy) of
* the animation will be automatically created and added instead.
*
* @param {String} name - Ani identifier
* @param {Ani} animation - The preloaded animation
* @example
* sprite.addAni(name, animation);
* sprite.addAni(name, frame1, frame2, frame3...);
* sprite.addAni(name, atlas);
*/
addAni(...args: any[]): any;
/**
* Add multiple animations to the sprite.
* @param {Object} atlases - an object with animation names as keys and
* an animation or animation atlas as values
* @example
* sprite.addAnis({
* name0: atlas0,
* name1: atlas1
* });
*/
addAnis(...args: any[]): void;
spriteSheet: any;
/**
* Changes the sprite's animation. Use `addAni` to define the
* animation(s) first.
*
* @param {...String} anis - the names of one or many animations to be played in
* sequence
* @returns A promise that fulfills when the animation or sequence of animations
* completes
*/
changeAni(...args: string[]): Promise<void>;
/**
* Changes the sprite's animation. Use `addAni` to define the
* animation(s) first. Alt for `changeAni`.
*
* @param {...String} anis - the names of one or many animations to be played in
* sequence
* @returns A promise that fulfills when the animation or sequence of animations
* completes
*/
changeAnimation(...args: string[]): Promise<void>;
/**
* Deletes the sprite and removes it from all groups.
*
* If it has physics colliders or sensors, they will be
* destroyed in the physics world simulation.
*
* When a sprite is deleted it will not be drawn or updated anymore.
*
* There's no way to undo this operation. If you want to merely
* hide a sprite use `sprite.visible = false` instead.
*/
delete(): void;
/**
* True if the sprite has been deleted.
* @type {Boolean}
* @default false
* @readonly
*/
readonly get deleted(): boolean;
/**
* Deprecate alias for `sprite.deleted`.
* @deprecated
* @type {Boolean}
* @default false
* @readonly
*/
readonly get removed(): boolean;
/**
* Warning: This function might be changed in a future release.
*
* Returns the sprite's unique identifier `sprite.idNum`.
*
* @returns the sprite's id
*/
toString(): string;
collide(target: any, callback: any): boolean;
/**
* Returns true on the first frame that the sprite collides with the
* target sprite or group.
*
* Custom collision event handling can be done by using this function
* in an if statement or adding a callback as the second parameter.
*
* @param {Sprite|Group} target
* @param {Function} [callback]
*/
collides(target: Sprite | Group, callback?: Function): boolean;
/**
* Returns a truthy value while the sprite is colliding with the
* target sprite or group. The value is the number of frames that
* the sprite has been colliding with the target.
*
* @param {Sprite|Group} target
* @param {Function} [callback]
* @return {Number} frames
*/
colliding(target: Sprite | Group, callback?: Function): number;
/**
* Returns true on the first frame that the sprite no longer overlaps
* with the target sprite or group.
*
* @param {Sprite|Group} target
* @param {Function} [callback]
* @return {Boolean}
*/
collided(target: Sprite | Group, callback?: Function): boolean;
overlap(target: any, callback: any): boolean;
/**
* Returns true on the first frame that the sprite overlaps with the
* target sprite or group.
*
* Custom overlap event handling can be done by using this function
* in an if statement or adding a callback as the second parameter.
*
* @param {Sprite|Group} target
* @param {Function} [callback]
*/
overlaps(target: Sprite | Group, callback?: Function): boolean;
/**
* Returns a truthy value while the sprite is overlapping with the
* target sprite or group. The value returned is the number of
* frames the sprite has been overlapping with the target.
*
* @param {Sprite|Group} target
* @param {Function} [callback]
* @return {Number} frames
*/
overlapping(target: Sprite | Group, callback?: Function): number;
/**
* Returns true on the first frame that the sprite no longer overlaps
* with the target sprite or group.
*
* @param {Sprite|Group} target
* @param {Function} [callback]
* @return {Boolean}
*/
overlapped(target: Sprite | Group, callback?: Function): boolean;
/**
* This function is used internally if a sprite overlap detection
* function is called but the sprite has no overlap sensors.
*
* It creates sensor fixtures 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.
*/
addDefaultSensors(): void;
/**
* Returns the distance to another sprite, the mouse, a touch,
* or any other object with x and y properties. Uses p5's `dist`
* function.
* @param {Sprite} o object with x and y properties
* @returns {Number} distance
*/
distanceTo(o: Sprite): number;
}
/**
* @class
* @extends Array<Image>
*/
class Ani extends Array<new (width?: number, height?: number) => HTMLImageElement> {
/**
* <a href="https://p5play.org/learn/animation.html">
* Look at the Animation reference pages before reading these docs.
* </a>
*
* An `Ani` object contains an array of images (Q5.Image objects)
* that can be displayed with the `animation` function or by
* being a sprite's animation.
*
* An animation can be created multiple ways, including from:
* - a list of image file paths as multiple input parameters
* - a sequence of numbered images by providing the file path to
* the first image frame and last frame index
* - a sprite sheet image path and atlas object, subtexture locator, or
* frame locators array
*
* `Ani` is not a shorthand for `Animation`, since that class name
* is already used by the JS Web Animations API.
*
* @param {...Image} ...images - Image objects to be used as frames
* @example
* let shapeShifter = new Ani("dog.png", "cat.png", "snake.png");
*/
constructor(...args: (new (width?: number, height?: number) => HTMLImageElement)[]);
/**
* The name of the animation
* @type {String}
*/
name: string;
targetFrame: number;
/**
* The offset is how far the animation should be placed from
* the location it is played at.
* @type {Object}
* @example
* ani.offset.x = 16;
*/
offset: any;
demoMode: any;
/**
* True if the animation is currently playing.
* @type {Boolean}
* @default true
*/
playing: boolean;
/**
* Animation visibility.
* @type {Boolean}
* @default true
*/
visible: boolean;
/**
* If set to false the animation will stop after reaching the last frame
* @type {Boolean}
* @default true
*/
looping: boolean;
/**
* Ends the loop on frame 0 instead of the last frame.
* This is useful for animations that are symmetric.
* For example a walking cycle where the first frame is the
* same as the last frame.
* @type {Boolean}
* @default false
*/
endOnFirstFrame: boolean;
/**
* True if frame changed during the last draw cycle
* @type {Boolean}
*/
frameChanged: boolean;
onComplete: any;
onChange: any;
rotation: any;
spriteSheet: any;
set frame(val: number);
/**
* The index of the current frame that the animation is on.
* @type {Number}
*/
get frame(): number;
set frameDelay(val: number);
/**
* Delay between frames in number of draw cycles.
* If set to 4 the framerate of the animation would be the
* sketch framerate divided by 4 (60fps = 15fps)
* @type {Number}
* @default 4
*/
get frameDelay(): number;
set scale(val: number | any);
/**
* The animation's scale.
*
* Can be set to a number to scale both x and y
* or an object with x and/or y properties.
* @type {Number|Object}
* @default 1
*/
get scale(): number | any;
/**
* Make a copy of the animation.
*
* @return {Ani} A copy of the animation.
*/
clone(): Ani;
/**
* Draws the animation. Similar to the q5.js `image` function.
*
* If the animation is playing, it will advance to the next frame
* automatically.
*
* `imageMode` affects the position of the animation.
*
* @param {Number} dx - x coordinate to draw the animation
* @param {Number} dy - y coordinate to draw the animation
* @param {Number} [dw] - width to draw the animation
* @param {Number} [dh] - height to draw the animation
*/
draw(dx: number, dy: number, dw?: number, dh?: number): void;
/**
* Plays the animation, starting from the specified frame.
*
* @returns [Promise] a promise that resolves when the animation completes
*/
play(frame: any): Promise<any>;
/**
* Pauses the animation.
*/
pause(frame: any): void;
/**
* Stops the animation. Alt for pause.
*/
stop(frame: any): void;
/**
* Plays the animation backwards.
* Equivalent to ani.goToFrame(0)
*
* @returns [Promise] a promise that resolves when the animation completes
* rewinding
*/
rewind(): Promise<any>;
/**
* Plays the animation forwards and loops it.
*/
loop(): void;
/**
* Prevents the animation from looping
*/
noLoop(): void;
/**
* Goes to the next frame and stops.
*/
nextFrame(): void;
/**
* Goes to the previous frame and stops.
*/
previousFrame(): void;
/**
* Plays the animation forward or backward toward a target frame.
*
* @param {Number} toFrame - Frame number destination (starts from 0)
* @returns [Promise] a promise that resolves when the animation completes
*/
goToFrame(toFrame: number): Promise<any>;
/**
* The index of the last frame. Read only.
* @type {Number}
*/
get lastFrame(): number;
/**
* The current frame as an Image object. Read only.
* @type {Image}
*/
get frameImage(): new (width?: number, height?: number) => HTMLImageElement;
/**
* Width of the animation's current frame.
* @type {Number}
*/
get w(): number;
/**
* Width of the animation's current frame.
* @type {Number}
*/
get width(): number;
get defaultWidth(): any;
/**
* Height of the animation's current frame.
* @type {Number}
*/
get h(): number;
/**
* Height of the animation's current frame.
* @type {Number}
*/
get height(): number;
get defaultHeight(): any;
}
/**
* <a href="https://p5play.org/learn/animation.html">
* Look at the Animation reference pages before reading these docs.
* </a>
*
* This Anis class serves the same role that Group does for Sprites.
* This class is used internally to create `sprite.anis`
* and `group.anis`.
*
* In instances of this class, the keys are animation names,
* values are Ani objects.
*
* Because users only expect instances of this class to contain
* animation names as keys, it uses an internal private object
* `#_` to store animation properties. Getters and setters are used to
* access the private properties, enabling dynamic inheritance.
*
* @class
*/
class Anis {
set width(val: any);
get width(): any;
w: any;
set height(val: any);
get height(): any;
h: any;
#private;
}
/**
* @class
* @extends Array<Sprite>
*/
class Group extends Array<Sprite> {
/**
* <a href="https://p5play.org/learn/group.html">
* Look at the Group reference pages before reading these docs.
* </a>
*
* A Group is an array of sprites with similar traits and behaviors.
*
* Group extends Array, so you can use them in for of loops. They
* inherit all the functions and properties of standard arrays
* such as `group.length` and functions like `group.includes()`.
*
* Changing a group setting changes it for all the sprites in the
* group, similar to class inheritance. Groups can have subgroups,
* creating a hierarchy of inheritance.
*
* The top level group is a q5 instance level variable named
* `allSprites` that contains all the sprites added to the sketch.
*/
constructor(...args: any[]);
/**
* @type {Number}
*/
x: number;
/**
* @type {Number}
*/
y: number;
/**
* @type {Number}
*/
vel: number;
/**
* @type {Number}
*/
rotation: number;
/**
* @type {Number}
*/
rotationSpeed: number;
/**
* @type {Boolean}
*/
autoDraw: boolean;
/**
* @type {Boolean}
*/
allowSleeping: boolean;
/**
* @type {Number}
*/
autoUpdate: number;
/**
* @type {Number}
*/
bounciness: number;
/**
* @type {Number}
*/
collider: number;
/**
* @type {Number}
*/
color: number;
/**
* @type {Boolean}
*/
debug: boolean;
/**
* @type {Number}
*/
density: number;
/**
* @type {Number}
*/
direction: number;
/**
* @type {Number}
*/
drag: number;
/**
* @type {Number}
*/
friction: number;
/**
* @type {Number}
*/
h: number;
/**
* @type {Boolean}
*/
isSuperFast: boolean;
/**
* @type {Number}
*/
layer: number;
/**
* @type {Number}
*/
life: number;
/**
* @type {Number}
*/
mass: number;
/**
* @type {Object}
*/
mirror: any;
/**
* @type {Vector}
*/
offset: Vector;
/**
* @type {Boolean}
*/
pixelPerfect: boolean;
/**
* @type {Boolean}
*/
deleted: boolean;
/**
* @type {Number}
*/
rotationDrag: number;
/**
* @type {Boolean}
*/
rotationLock: boolean;
/**
* @type {Vector}
*/
scale: Vector;
/**
* @type {Number}
*/
shape: number;
/**
* @type {Boolean}
*/
sleeping: boolean;
/**
* @type {Color}
*/
stroke: Color;
/**
* @type {Number}
*/
strokeWeight: number;
/**
* @type {Number}
*/
text: number;
/**
* @type {Color}
*/
textColor: Color;
/**
* @type {String}
*/
tile: string;
/**
* @type {Number}
*/
tileSize: number;
/**
* @type {Boolean}
*/
visible: boolean;
/**
* @type {Number}