Curves and Paths

Creating paths from curves, getting points along them, drawing them with Graphics, and making sprites follow paths automatically using PathFollower in Phaser 4.

src/curves/

src/curves/path/

src/gameobjects/pathfollower/

src/gameobjects/components/PathFollower.js

Quick Start

// In a Scene's create() method:

// 1. Create a Path starting at (50, 300)
const path = this.add.path(50, 300);

// 2. Add curves to the path
path.lineTo(200, 100);
path.splineTo([ new Phaser.Math.Vector2(300, 400), new Phaser.Math.Vector2(500, 200) ]);
path.lineTo(700, 300);

// 3. Draw the path using Graphics
const graphics = this.add.graphics();
graphics.lineStyle(2, 0xffffff, 1);
path.draw(graphics, 64);

// 4. Create a PathFollower sprite that moves along the path
const follower = this.add.follower(path, 50, 300, 'ship');
follower.startFollow({
    duration: 5000,
    rotateToPath: true,
    repeat: -1,
    yoyo: true
});

Core Concepts

Path

Phaser.Curves.Path

this.add.path(x, y)

• curves

  -- array of

  Phaser.Curves.Curve

  objects in the Path

• startPoint

  --

  Vector2

  , the defined starting position

• autoClose

  -- boolean, if true

  getPoints()

  appends the first point at the end

• defaultDivisions

  -- number (default: 12), divisions per curve when calling

  getPoints()

• name

  -- string, empty by default, for developer use

Curves

Phaser.Curves.Curve

• getPoint(t, out)

  -- get a point at position t (0-1) based on curve parameterization

• getPointAt(u, out)

  -- get a point at position u (0-1) based on arc length (evenly spaced)

• getPoints(divisions, stepRate, out)

  -- array of points along the curve

• getSpacedPoints(divisions, stepRate, out)

  -- array of equidistant points by arc length

• getDistancePoints(distance)

  -- points spaced by pixel distance

• getLength()

  -- total arc length in pixels

• getBounds(out, accuracy)

  -- bounding Rectangle

• getTangent(t, out)

  /

  getTangentAt(u, out)

  -- unit tangent vector

• getStartPoint(out)

  /

  getEndPoint(out)

  -- first/last points

• getRandomPoint(out)

  -- random point on the curve

• draw(graphics, pointsTotal)

  -- render the curve onto a Graphics object

• active

  -- boolean, when false the parent Path skips this curve

PathFollower

Phaser.GameObjects.PathFollower

Components.PathFollower

this.add.follower(path, x, y, texture, frame)

• path

  -- the

  Phaser.Curves.Path

  being followed

• pathTween

  -- the internal Tween driving movement

• pathOffset

  --

  Vector2

  , offset added to path coordinates

• pathVector

  --

  Vector2

  , current position on the path

• pathDelta

  --

  Vector2

  , distance traveled since last frame

• rotateToPath

  -- boolean, auto-rotate to face path direction

• pathRotationOffset

  -- number (degrees), added to auto-rotation

Common Patterns

Creating Paths with Chained Curves

const path = this.add.path(100, 500);

path.lineTo(300, 100);                          // straight line
path.cubicBezierTo(500, 100, 350, 50, 450, 50); // cubic bezier (endX, endY, cp1X, cp1Y, cp2X, cp2Y)
path.quadraticBezierTo(700, 400, 600, 100);     // quadratic bezier (endX, endY, cpX, cpY)
path.splineTo([                                  // spline through points
    new Phaser.Math.Vector2(750, 300),
    new Phaser.Math.Vector2(600, 500)
]);
path.ellipseTo(50, 80, 0, 270, false, 0);       // ellipse arc (xRadius, yRadius, startAngle, endAngle, clockwise, rotation)
path.circleTo(40);                               // shortcut for ellipseTo with equal radii and 0-360

// Jump to a new position without drawing (creates a gap)
path.moveTo(400, 400);
path.lineTo(500, 400);

// Close the path by connecting end to start
path.closePath();

Adding Standalone Curve Objects

const path = new Phaser.Curves.Path(0, 0);

// Add pre-constructed curve objects
const line = new Phaser.Curves.Line(new Phaser.Math.Vector2(0, 0), new Phaser.Math.Vector2(200, 200));
path.add(line);

const spline = new Phaser.Curves.Spline([ 200, 200, 300, 100, 400, 300 ]);
path.add(spline);

const ellipse = new Phaser.Curves.Ellipse(400, 300, 100, 60, 0, 360, false, 0);
path.add(ellipse);

Getting Points Along a Path

// Array of points (uses defaultDivisions per curve)
const points = path.getPoints();

// With explicit divisions per curve
const detailed = path.getPoints(32);

// Equally spaced points along the entire path
const spaced = path.getSpacedPoints(100);

// Single point at normalized position (0-1)
const midpoint = path.getPoint(0.5);

// Tangent vector at a position
const tangent = path.getTangent(0.5);

// Total path length in pixels
const length = path.getLength();

// Bounding rectangle
const bounds = path.getBounds();

Drawing Paths with Graphics

const graphics = this.add.graphics();

// Draw entire path
graphics.lineStyle(2, 0x00ff00, 1);
path.draw(graphics, 64); // 64 = points per curve for smoothness

// Draw individual curves
graphics.lineStyle(1, 0xff0000, 1);
path.curves[0].draw(graphics, 32);

// Draw debug points
const points = path.getSpacedPoints(50);
points.forEach(p => {
    graphics.fillStyle(0xffff00, 1);
    graphics.fillCircle(p.x, p.y, 3);
});

PathFollower Sprite

const path = this.add.path(100, 200);
path.lineTo(400, 400);
path.lineTo(700, 200);

// Create follower
const enemy = this.add.follower(path, 100, 200, 'enemy');

// Start following with config
enemy.startFollow({
    duration: 3000,       // ms to traverse path
    positionOnPath: true, // snap to path start position
    rotateToPath: true,   // auto-rotate to face direction
    rotationOffset: 90,   // offset added to auto-rotation (degrees)
    repeat: -1,           // -1 = infinite repeat
    yoyo: true,           // reverse on each repeat
    from: 0,              // start position on path (0-1)
    to: 1,                // end position on path (0-1)
    startAt: 0,           // initial seek position
    ease: 'Sine.easeInOut' // any valid Phaser ease
});

// Control during playback
enemy.pauseFollow();
enemy.resumeFollow();
enemy.stopFollow();
enemy.isFollowing(); // returns boolean

// Change path at runtime
enemy.setPath(newPath);
enemy.setPath(newPath, { duration: 2000 }); // auto-starts

// Set rotation independently
enemy.setRotateToPath(true, 90); // (value, offsetDegrees)

PathFollower with Simple Duration

// Shorthand: pass just a duration number
enemy.startFollow(5000);

// Equivalent to:
enemy.startFollow({ duration: 5000 });

All Curve Types

Phaser.Curves.Line

(p0, p1)

([x0,y0,x1,y1])

Phaser.Curves.Spline

(points)

Phaser.Curves.CubicBezier

(p0, p1, p2, p3)

([x0,y0,...x3,y3])

Phaser.Curves.QuadraticBezier

(p0, p1, p2)

([x0,y0,...x2,y2])

Phaser.Curves.Ellipse

(x, y, xRadius, yRadius, startAngle, endAngle, clockwise, rotation)

Ellipse Curve Properties

• x

  ,

  y

  -- center position

• xRadius

  ,

  yRadius

  -- radii

• startAngle

  ,

  endAngle

  -- in degrees (get/set convert to/from radians internally)

• clockwise

  -- boolean

• rotation

  -- in radians

• angle

  -- rotation in degrees (alternative to

  rotation

  )

• setWidth(value)

  /

  setHeight(value)

  -- sets radius to value/2

API Quick Reference

Path (

Phaser.Curves.Path

)

add(curve)

lineTo(x, y)

splineTo(points)

cubicBezierTo(x, y, cp1X, cp1Y, cp2X, cp2Y)

quadraticBezierTo(x, y, cpX, cpY)

ellipseTo(xR, yR, start, end, cw, rot)

circleTo(radius, clockwise, rotation)

moveTo(x, y)

closePath()

getPoint(t, out)

getPoints(divisions, stepRate)

getSpacedPoints(divisions)

getRandomPoint(out)

getStartPoint(out)

getEndPoint(out)

getTangent(t, out)

getCurveAt(t)

getLength()

getCurveLengths()

getBounds(out, accuracy)

draw(graphics, pointsTotal)

toJSON()

fromJSON(data)

updateArcLengths()

destroy()

Base Curve (

Phaser.Curves.Curve

)

getPoint(t, out)

getPointAt(u, out)

getPoints(divisions, stepRate, out)

getSpacedPoints(divisions, stepRate, out)

getDistancePoints(distance)

getLength()

getTangent(t, out)

getTangentAt(u, out)

getTFromDistance(distance)

draw(graphics, pointsTotal)

getBounds(out, accuracy)

active

boolean

defaultDivisions

number

arcLengthDivisions

number

PathFollower Component

setPath(path, config)

startFollow(config, startAt)

pauseFollow()

resumeFollow()

stopFollow()

isFollowing()

setRotateToPath(value, offset)

path

Path

pathTween

Tween

pathOffset

Vector2

pathVector

Vector2

pathDelta

Vector2

rotateToPath

boolean

pathRotationOffset

number

PathConfig (

Phaser.Types.GameObjects.PathFollower.PathConfig

)

duration

number

from

number

to

number

positionOnPath

boolean

rotateToPath

boolean

rotationOffset

number

startAt

number

ease

repeat

yoyo

delay

hold

onComplete

Gotchas

1. getPoint(t)

   vs

   getPointAt(u)

   on curves.

   getPoint

   uses the raw curve parameter t, which does not produce evenly spaced points on most curve types.

   getPointAt

   maps through arc length for even spacing. On a Path,

   getPoint

   already accounts for arc length across the whole path.
2. Path

   moveTo

   creates an inactive curve. The

   MoveTo

   pseudo-curve has

   active: false

   and zero length. It only repositions the end point for the next curve. It does not draw anything and is skipped by

   getPoints()

   and

   draw()

   .
3. PathFollower uses a Tween internally. The

   startFollow

   config is passed to

   scene.tweens.addCounter()

   . All tween properties (ease, delay, repeat, yoyo, callbacks) work. The tween is set to

   persist: true

   automatically.
4. PathFollower offset behavior. When

   positionOnPath: false

   (default), the follower's current position becomes the offset from the path start. When

   positionOnPath: true

   , the follower snaps to the path's start point and the offset is zeroed.
5. Ellipse angles are in degrees. The constructor and

   startAngle

   /

   endAngle

   properties accept degrees. Internally they are stored as radians. The

   rotation

   property is in radians, but

   angle

   is in degrees.

6. closePath

   vs

   autoClose

   .

   closePath()

   adds an explicit Line curve from end to start.

   autoClose = true

   only affects

   getPoints()

   and

   getSpacedPoints()

   output by appending the first point, without adding a curve.
7. Cached lengths can go stale.

   getCurveLengths()

   caches results based on array length only. If you modify a curve's control points, call

   path.updateArcLengths()

   to force recalculation.

8. cubicBezierTo

   parameter order with numbers. When passing numbers:

   cubicBezierTo(endX, endY, cp1X, cp1Y, cp2X, cp2Y)

   . The end point comes first, not the control points. When passing Vector2 objects:

   cubicBezierTo(cp1, cp2, endPoint)

   .
9. Spline needs at least 4 points. The Catmull-Rom interpolation used by Spline works best with 4+ points. With fewer points, the curve may not behave as expected.
10. Line curve

    arcLengthDivisions

    is 1. Unlike other curves (default 100), Line overrides this to 1 since a line is inherently uniform. No need to adjust it.

Source File Map

src/curves/path/Path.js

this.add.path

src/curves/path/MoveTo.js

src/curves/Curve.js

src/curves/LineCurve.js

src/curves/SplineCurve.js

src/curves/CubicBezierCurve.js

src/curves/QuadraticBezierCurve.js

src/curves/EllipseCurve.js

src/gameobjects/pathfollower/PathFollower.js

src/gameobjects/pathfollower/PathFollowerFactory.js

this.add.follower

src/gameobjects/components/PathFollower.js

src/gameobjects/pathfollower/typedefs/PathConfig.js