Phaser API Documentation

  Version: 
Filter
This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Curves . Path

This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Curves . Path

A Path combines multiple Curves into one continuous compound curve. It does not matter how many Curves are in the Path or what type they are.

A Curve in a Path does not have to start where the previous Curve ends - that is to say, a Path does not have to be an uninterrupted curve. Only the order of the Curves influences the actual points on the Path.

Constructor:

new Path([x], [y])

Parameters:

name type arguments description
x number <optional>

The X coordinate of the Path's starting point or a {@link Phaser.Types.Curves.JSONPath}.

y number <optional>

The Y coordinate of the Path's starting point.

Since: 3.0.0
Source: src/curves/path/Path.js (Line 21)

Members

<private> _tmpVec2A: Phaser.Math.Vector2
Focus
Focus

Description:

A temporary vector used to avoid object creation when adding a Curve to the Path.

Type:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 100)
Focus
Focus
<private> _tmpVec2B: Phaser.Math.Vector2
Focus
Focus

Description:

A temporary vector used to avoid object creation when adding a Curve to the Path.

Type:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 110)
Focus
Focus
autoClose: boolean
Focus
Focus

Description:

Automatically closes the path.

Type:
boolean
Default: false
Since: 3.0.0
Source: src/curves/path/Path.js (Line 79)
Focus
Focus
cacheLengths: Array.<number>
Focus
Focus

Description:

The cached length of each Curve in the Path.

Used internally by #getCurveLengths.

Type:
Array.<number>
Default: []
Since: 3.0.0
Source: src/curves/path/Path.js (Line 67)
Focus
Focus
curves: Array.<Phaser.Curves.Curve>
Focus
Focus

Description:

The list of Curves which make up this Path.

Type:
Default: []
Since: 3.0.0
Source: src/curves/path/Path.js (Line 57)
Focus
Focus
name: string
Focus
Focus

Description:

The name of this Path. Empty by default and never populated by Phaser, this is left for developers to use.

Type:
string
Default: ''
Since: 3.0.0
Source: src/curves/path/Path.js (Line 46)
Focus
Focus
startPoint: Phaser.Math.Vector2
Focus
Focus

Description:

The starting point of the Path.

This is not necessarily equivalent to the starting point of the first Curve in the Path. In an empty Path, it's also treated as the ending point.

Type:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 89)
Focus
Focus

Methods

add(curve)
Focus
Focus

Description:

Appends a Curve to the end of the Path.

The Curve does not have to start where the Path ends or, for an empty Path, at its defined starting point.

Parameters:

name type description
curve Phaser.Curves.Curve

The Curve to append.

Returns:
Description:

This Path object.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 130)
Focus
Focus
circleTo(radius, [clockwise], [rotation])
Focus
Focus

Description:

Creates a circular Ellipse Curve positioned at the end of the Path.

Parameters:

name type arguments Default description
radius number

The radius of the circle.

clockwise boolean <optional> false

true to create a clockwise circle as opposed to a counter-clockwise circle.

rotation number <optional> 0

The rotation of the circle in degrees.

Returns:
Description:

This Path object.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 149)
Focus
Focus
closePath()
Focus
Focus

Description:

Ensures that the Path is closed.

A closed Path starts and ends at the same point. If the Path is not closed, a straight Line Curve will be created from the ending point directly to the starting point. During the check, the actual starting point of the Path, i.e. the starting point of the first Curve, will be used as opposed to the Path's defined startPoint, which could differ.

Calling this method on an empty Path will result in an error.

Returns:
Description:

This Path object.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 168)
Focus
Focus
cubicBezierTo(x, y, control1X, [control1Y], [control2X], [control2Y])
Focus
Focus

Description:

Creates a cubic bezier curve starting at the previous end point and ending at p3, using p1 and p2 as control points.

Parameters:

name type arguments description
x number | Phaser.Math.Vector2

The x coordinate of the end point. Or, if a Vector2, the p1 value.

y number | Phaser.Math.Vector2

The y coordinate of the end point. Or, if a Vector2, the p2 value.

control1X number | Phaser.Math.Vector2

The x coordinate of the first control point. Or, if a Vector2, the p3 value.

control1Y number <optional>

The y coordinate of the first control point. Not used if Vector2s are provided as the first 3 arguments.

control2X number <optional>

The x coordinate of the second control point. Not used if Vector2s are provided as the first 3 arguments.

control2Y number <optional>

The y coordinate of the second control point. Not used if Vector2s are provided as the first 3 arguments.

Returns:
Description:

This Path object.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 195)
Focus
Focus
destroy()
Focus
Focus

Description:

Disposes of this Path, clearing its internal references to objects so they can be garbage-collected.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 844)
Focus
Focus
draw(graphics, [pointsTotal])
Focus
Focus

Description:

Draws all Curves in the Path to a Graphics Game Object.

Parameters:

name type arguments Default description
graphics Phaser.GameObjects.Graphics

The Graphics Game Object to draw to.

pointsTotal number <optional> 32

The number of points to draw for each Curve. Higher numbers result in a smoother curve but require more processing.

Returns:
Description:

The Graphics object which was drawn to.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 270)
Focus
Focus
ellipseTo([xRadius], [yRadius], [startAngle], [endAngle], [clockwise], [rotation])
Focus
Focus

Description:

Creates an ellipse curve positioned at the previous end point, using the given parameters.

Parameters:

name type arguments Default description
xRadius number <optional> 0

The horizontal radius of ellipse.

yRadius number <optional> 0

The vertical radius of ellipse.

startAngle number <optional> 0

The start angle of the ellipse, in degrees.

endAngle number <optional> 360

The end angle of the ellipse, in degrees.

clockwise boolean <optional> false

Whether the ellipse angles are given as clockwise (true) or counter-clockwise (false).

rotation number <optional> 0

The rotation of the ellipse, in degrees.

Returns:
Description:

This Path object.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 300)
Focus
Focus
fromJSON(data)
Focus
Focus

Description:

Creates a Path from a Path Configuration object.

The provided object should be a Phaser.Types.Curves.JSONPath, as returned by #toJSON. Providing a malformed object may cause errors.

Parameters:

name type description
data Phaser.Types.Curves.JSONPath

The JSON object containing the Path data.

Returns:
Description:

This Path object.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 332)
Focus
Focus
getBounds([out], [accuracy])
Focus
Focus

Description:

Returns a Rectangle with a position and size matching the bounds of this Path.

Parameters:

name type arguments Default description
out Phaser.Geom.Rectangle <optional>

The Rectangle to store the bounds in.

accuracy number <optional> 16

The accuracy of the bounds calculations. Higher values are more accurate at the cost of calculation speed.

Returns:
Description:

The modified out Rectangle, or a new Rectangle if none was provided.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 386)
Focus
Focus
getCurveLengths()
Focus
Focus

Description:

Returns an array containing the length of the Path at the end of each Curve.

The result of this method will be cached to avoid recalculating it in subsequent calls. The cache is only invalidated when the #curves array changes in length, leading to potential inaccuracies if a Curve in the Path is changed, or if a Curve is removed and another is added in its place.

Returns:
Description:

An array containing the length of the Path at the end of each one of its Curves.

Type:
  • Array.
Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 435)
Focus
Focus
getEndPoint([out])
Focus
Focus

Description:

Returns the ending point of the Path.

A Path's ending point is equivalent to the ending point of the last Curve in the Path. For an empty Path, the ending point is at the Path's defined #startPoint.

Parameters:

name type arguments description
out Phaser.Math.Vector2 <optional>

The object to store the point in.

Returns:
Description:

The modified out object, or a new Vector2 if none was provided.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 472)
Focus
Focus
getLength()
Focus
Focus

Description:

Returns the total length of the Path.

Returns:
Description:

The total length of the Path.

Type:
  • number
Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 502)
Focus
Focus
getPoint(t, [out])
Focus
Focus

Description:

Calculates the coordinates of the point at the given normalized location (between 0 and 1) on the Path.

The location is relative to the entire Path, not to an individual Curve. A location of 0.5 is always in the middle of the Path and is thus an equal distance away from both its starting and ending points. In a Path with one Curve, it would be in the middle of the Curve; in a Path with two Curves, it could be anywhere on either one of them depending on their lengths.

Parameters:

name type arguments description
t number

The location of the point to return, between 0 and 1.

out Phaser.Math.Vector2 <optional>

The object in which to store the calculated point.

Returns:
Description:

The modified out object, or a new Vector2 if none was provided.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 528)
Focus
Focus
getPoints([divisions])
Focus
Focus

Description:

Get a sequence of points on the path.

Parameters:

name type arguments Default description
divisions number <optional> 12

The number of divisions per resolution per curve.

Returns:
Description:

An array of Vector2 objects that containing the points along the Path.

Type:
Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 571)
Focus
Focus
getRandomPoint([out])
Focus
Focus

Description:

Returns a randomly chosen point anywhere on the path. This follows the same rules as getPoint in that it may return a point on any Curve inside this path.

When calling this method multiple times, the points are not guaranteed to be equally spaced spatially.

Parameters:

name type arguments description
out Phaser.Math.Vector2 <optional>

Vector2 instance that should be used for storing the result. If undefined a new Vector2 will be created.

Returns:
Description:

The modified out object, or a new Vector2 if none was provided.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 625)
Focus
Focus
getSpacedPoints([divisions])
Focus
Focus

Description:

Divides this Path into a set of equally spaced points,

The resulting points are equally spaced with respect to the points' position on the path, but not necessarily equally spaced spatially.

Parameters:

name type arguments Default description
divisions number <optional> 40

The amount of points to divide this Path into.

Returns:
Description:

A list of the points this path was subdivided into.

Type:
Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 646)
Focus
Focus
getStartPoint([out])
Focus
Focus

Description:

Returns the starting point of the Path.

Parameters:

name type arguments description
out Phaser.Math.Vector2 <optional>

Vector2 instance that should be used for storing the result. If undefined a new Vector2 will be created.

Returns:
Description:

The modified out object, or a new Vector2 if none was provided.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 677)
Focus
Focus
getTangent(t, [out])
Focus
Focus

Description:

Gets a unit vector tangent at a relative position on the path.

Parameters:

name type arguments description
t number

The relative position on the path, [0..1].

out Phaser.Math.Vector2 <optional>

A vector to store the result in.

Returns:
Description:

Vector approximating the tangent line at the point t (delta +/- 0.0001)

Examples:
Since: 3.23.0
Source: src/curves/path/Path.js (Line 696)
Focus
Focus
lineTo(x, [y])
Focus
Focus

Description:

Creates a line curve from the previous end point to x/y.

Parameters:

name type arguments description
x number | Phaser.Math.Vector2

The X coordinate of the line's end point, or a Vector2 containing the entire end point.

y number <optional>

The Y coordinate of the line's end point, if a number was passed as the X parameter.

Returns:
Description:

This Path object.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 736)
Focus
Focus
moveTo(x, [y])
Focus
Focus

Description:

Creates a "gap" in this path from the path's current end point to the given coordinates.

After calling this function, this Path's end point will be equal to the given coordinates

Parameters:

name type arguments description
x number | Phaser.Math.Vector2

The X coordinate of the position to move the path's end point to, or a Vector2 containing the entire new end point.

y number <optional>

The Y coordinate of the position to move the path's end point to, if a number was passed as the X coordinate.

Returns:
Description:

This Path object.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 780)
Focus
Focus
quadraticBezierTo(x, [y], [controlX], [controlY])
Focus
Focus

Description:

Creates a Quadratic Bezier Curve starting at the ending point of the Path.

Parameters:

name type arguments description
x number | Array.<Phaser.Math.Vector2>

The X coordinate of the second control point or, if it's a Vector2, the first control point.

y number <optional>

The Y coordinate of the second control point or, if x is a Vector2, the second control point.

controlX number <optional>

If x is not a Vector2, the X coordinate of the first control point.

controlY number <optional>

If x is not a Vector2, the Y coordinate of the first control point.

Returns:
Description:

This Path object.

Examples:
Since: 3.2.0
Source: src/curves/path/Path.js (Line 236)
Focus
Focus
splineTo(points)
Focus
Focus

Description:

Creates a spline curve starting at the previous end point, using the given points on the curve.

Parameters:

name type description
points Array.<Phaser.Math.Vector2>

The points the newly created spline curve should consist of.

Returns:
Description:

This Path object.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 763)
Focus
Focus
toJSON()
Focus
Focus

Description:

Converts this Path to a JSON object containing the path information and its constituent curves.

Returns:
Description:

The JSON object containing this path's data.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 805)
Focus
Focus
updateArcLengths()
Focus
Focus

Description:

cacheLengths must be recalculated.

Examples:
Since: 3.0.0
Source: src/curves/path/Path.js (Line 831)
Focus
Focus