curves-and-paths

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.

Key source paths: src/curves/, src/curves/path/, src/gameobjects/pathfollower/, src/gameobjects/components/PathFollower.js Related skills: ../sprites-and-images/SKILL.md, ../graphics-and-shapes/SKILL.md, ../tweens/SKILL.md

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

A Phaser.Curves.Path is a container that combines multiple Curves into one continuous compound curve. Curves in a Path do not need to be connected end-to-end. Only the order of curves affects point calculations along the path.

Created via factory: this.add.path(x, y) where x/y is the starting point.

Key properties:

• 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

All curve types extend Phaser.Curves.Curve (the base class). Every curve supports:

• 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