Path2D
Lines, polygons and curves in a 2D scene — a road on a map, a trail, a debug line, an area with a
border, a rounded panel: a Node2D drawn in the sprite batch, sorted like any node.
Not the browser's Path2D: to paint into an image use Canvas; a collider
is a Shape2D (a path has no picking and no collider of its own).
- draw a line or a polyline in a 2D scene: a road, a debug line, a laser
- draw a filled polygon, a rectangle, a circle or an ellipse
- draw a rounded rectangle: a panel or a button shape in the world
- draw a smooth curve: Bézier curves and arcs
- keep a line the same width on screen at every scale
- cut a hole in a filled shape
- give a line an outline, round its joins and ends
- keep curves smooth up close
Platforms: wherever a Scene2D runs; headless tests build the geometry
(points) but draw nothing.
At a glance
const scene = new Scene2D({ background: "#1d2430" })
const road = Path2D.line([[-200, -60], [-40, 20], [200, 0]], { width: 3, units: "px", color: "#fc4", join: "round" })
const park = Path2D.polygon([[-80, 40], [60, 40], [60, 120], [-80, 120]], { fill: "#2a8f4a", stroke: { width: 1, units: "px", color: "#9fe0b0" } })
const sun = Path2D.circle(24, { fill: "#f8d34a", position: [150, 120] })
const card = Path2D.roundRect([160, 60], 12, { fill: "#223", stroke: 2, position: [0, -140] })
const bend = Path2D.shape(p => {
p.moveTo(-200, -100)
p.cubicTo(-100, 20, 100, -220, 200, -100) // an S bend
}, { stroke: { width: 4, color: "#7dd3fc", cap: "round" } })
scene.add(road, park, sun, card, bend)
scene.open()Points are in the node's local frame, Y-up, like every 2D position: move the whole path with
position / rotation / scale.
Draw a line, a polygon, a rectangle: line, polygon, rect
Path2D.line(points: Vec2Like[], stroke: Stroke2D | number, options?): Path2D // an open polyline
Path2D.polygon(points: Vec2Like[], options?): Path2D // a closed ring: give it a fill and / or a stroke
Path2D.rect(size: Vec2Like, options?): Path2D // a rectangle centred on the node's origin
new Path2D(options: { points: Vec2Like[], closed?: boolean, ...the options below })The options every path takes:
{
stroke?: Stroke2D | number // a number = { width }; omit = no stroke
fill?: ColorInput // omit = no fill
closed?: boolean // the stroke joins its end to its start; fills always close
holes?: Vec2Like[][] // rings cut out of the fill
tolerance?: number // curves only, below; default 0.25
antialias?: boolean // default true; false for crisp pixel-art lines
position?: Vec2Like
rotation?: number // degrees, CCW
scale?: number | Vec2Like
z?: number // draw order, see Scene2D
renderPriority?: number // 0..7, default 4
material?: Material2D // only its blend matters for a path
}closed defaults to false for line, shape, arc and a plain constructor, true for polygon,
rect, roundRect, ellipse and circle. Fills are triangulated over the outer ring and
its holes; the stroke follows the outer ring only.
Line width, color, joins, ends and outline: Stroke2D
type Stroke2D = {
width: number // in `units`
color?: ColorInput // default white
units?: 'world' | 'px' // default 'world'; 'px' = logical screen px at any zoom
join?: 'miter' | 'round' | 'bevel' // how segments meet; default 'miter'
cap?: 'butt' | 'round' | 'square' // the ends of an open path; default 'butt'
outline?: { width: number, color?: ColorInput } // a band each side of the line, in `units`; default black
}units: 'px' keeps a line the same width on screen at every scale — roads on a map, debug lines;
the default 'world' scales with the rest of the scene. The width is applied per frame, so a
change of scale costs no rebuild. A px-wide line's horizontal and vertical segments land on
the device-pixel grid: a 1 px border is one crisp row.
Draw passes keep roads and areas clean (draw order): a stroke's outline
draws under every body of the same renderPriority and z, so two outlined roads at one z merge
at their junction (a different z keeps them apart); the stroke of a filled path is its border and
draws over the neighbours' fills.
const scene = new Scene2D({ background: "#e8e4da" })
const roadStyle = { width: 6, units: "px" as const, color: "#ffffff", join: "round" as const, cap: "round" as const,
outline: { width: 1.5, color: "#9a9384" } }
const avenue = Path2D.line([[-200, 0], [200, 0]], roadStyle)
const side = Path2D.line([[0, 0], [40, 160]], roadStyle) // same z: the outlines merge at the junction
scene.add(avenue, side)
scene.open()Circles, ellipses, arcs and rounded rectangles: the shape statics
Path2D.circle(radius: number, options?): Path2D
Path2D.ellipse(radii: [rx, ry], options?): Path2D
Path2D.roundRect(size: Vec2Like, radius: number | [topLeft, topRight, bottomRight, bottomLeft], options?): Path2D
Path2D.arc(radius: number, startAngle: number, endAngle: number, options? & { clockwise?: boolean }): Path2DEach is centred on the node's origin. roundRect takes one radius or one per corner as they read
on screen; radii too big for a side shrink together. arc angles are radians, measured
counter-clockwise on screen from +X (Y is up), and it sweeps counter-clockwise unless clockwise;
it is an open stroke unless closed (the chord joins its ends — a fill is then the disc's segment).
const scene = new Scene2D()
const ring = Path2D.circle(40, { stroke: { width: 6, color: "#333" } })
const progress = Path2D.arc(40, Math.PI / 2, Math.PI / 2 - 0.7 * Math.PI * 2, { // 70 %, from the top
clockwise: true, stroke: { width: 6, color: "#4ade80", cap: "round" },
})
progress.z = 1 // over the track
scene.add(ring, progress)
scene.open()Draw a curve with the pen: Path2D.shape
Path2D.shape((p: PathBuilder2D) => void, options?): Path2D
p.moveTo(x, y) // start the outline
p.lineTo(x, y)
p.quadTo(cpx, cpy, x, y) // quadratic Bézier
p.cubicTo(c1x, c1y, c2x, c2y, x, y) // cubic Bézier
p.arcTo(x1, y1, x2, y2, radius) // a rounded corner (Canvas2D arcTo)
p.arc(cx, cy, radius, startAngle, endAngle, clockwise = false) // radians
p.ellipse(cx, cy, rx, ry, rotation, startAngle, endAngle, clockwise = false)
p.roundRect(x, y, w, h, radius | [tl, tr, br, bl]) // a whole closed outline: on an empty pen only
p.close() // join the end to the start; ends the pathCanvas2D's path vocabulary (each call returns the pen), in the node's local frame. Y is up, so
angles turn counter-clockwise on screen and clockwise: true sweeps the other way. arc and
ellipse first draw a line from the current point to their start; a curve with no current point
starts at its first control point. The shape is open unless it calls close() or the path has
closed: true.
const scene = new Scene2D({ background: "#10131a" })
const tab = Path2D.shape(p => {
p.moveTo(-60, 0)
p.arcTo(-60, 40, 0, 40, 12) // round the top-left corner
p.arcTo(60, 40, 60, 0, 12) // and the top-right one
p.lineTo(60, 0)
p.close()
}, { fill: "#2563eb", stroke: { width: 1, units: "px", color: "#93c5fd" } })
scene.add(tab)
scene.open()a path is one outline. A second moveTo after something was drawn, a roundRect
after other segments, or anything after close() is dropped with the rest of the pen — the engine
logs path <id>: … dropped (one subpath per path). Draw a second outline as a second
Path2D; a hole goes through holes.
Smooth curves up close: tolerance
The engine flattens a curve into straight chords once, when the shape is set: no chord strays
more than tolerance local units from the curve (default 0.25 — a quarter of a logical px at
zoom 1 and node scale 1; clamped to 0.01..100). It is never flattened again, so a curve seen up
close shows its chords: choose the tolerance for the largest zoom (and node scale) it will be seen
at — 0.25 / zoom.
const scene = new Scene2D()
const coin = Path2D.circle(8, { fill: "#f8d34a", tolerance: 0.25 / 8 }) // smooth up to zoom 8
scene.add(coin)
scene.open()
scene.camera.zoom = 8A smaller tolerance means more points — and a write of tolerance flattens the shape again.
antialias is separate: a fringe one logical px wide, applied per frame at any zoom.
Change a path while the game runs: live properties
path.points: Vec2[] // the outer ring; of a shape: the ring the engine flattened it to
path.shape // the pen function, or null for a points path
path.tolerance
path.closed
path.stroke // Stroke2D | null — null = no stroke
path.fill // ColorInput | null — null = no fill
path.holes // Vec2[][] — a write replaces them all
path.antialias
path.materialA write of points, shape, closed, holes or tolerance tessellates the path again natively
(writing points turns a shape path into a polyline), and so does turning the stroke or the fill
on or off, a new join / cap or antialias; a new width or color does not. When a shape only
moves, animate the node's position / rotation / scale instead of its points. A line that
does change, like an aim line, is rewritten from a system:
const scene = new Scene2D()
const hero = new Sprite({ size: [16, 16], color: "#4f7cff", position: [-100, 0] })
const target = new Sprite({ size: [16, 16], color: "#f43f5e", position: [100, 60] })
class AimLine extends System<"aim", Scene2D> {
private line!: Path2D
onAttach() {
this.line = Path2D.line([hero.position, target.position], { width: 2, units: "px", color: "#f43f5e" })
this.scene.add(this.line)
}
update() { this.line.points = [hero.position, target.position] } // once per frame
}
scene.add(hero, target)
scene.system(AimLine)
scene.open()
hero.animateTo({ y: -80, duration: 2000, loop: true, loopMode: "ping-pong" })Cut a hole in a filled shape: holes
const scene = new Scene2D({ background: "#e8e4da" })
const yard = Path2D.polygon(
[[-100, -60], [100, -60], [100, 60], [-100, 60]],
{ fill: "#86c06c", holes: [[[-30, -20], [30, -20], [30, 20], [-30, 20]]] }, // a gap for the pond
)
scene.add(yard)
scene.open()Holes are point rings in the node's frame and cut the fill only: the stroke follows the outer ring,
so a hole's own border is a second path (Path2D.polygon(ring, { stroke })). A curved hole is a
ring of points too: a path you never add gives one — Path2D.circle(20).points, centred on the
origin.
Paths in a scene file: the path block
// map.scene2d.ts
export default defineScene2d({
nodes: {
road: { path: { points: [[0, 0], [400, 120]], stroke: { width: 3, units: "px", color: "#fc4" } } },
lake: { path: { shape: p => { p.ellipse(0, 0, 80, 50, 0, 0, Math.PI * 2).close() }, fill: "#5aa0d8" }, position: [200, -80] },
},
})The block takes the constructor's options (points or shape, closed, stroke, fill,
holes, tolerance, antialias); transform and draw order are the node's props. See
scene files.
Pitfalls
// ✗ Canvas names on the pen — the pen has no bezierCurveTo / quadraticCurveTo
p.bezierCurveTo(10, 40, 50, 40, 60, 0)
// ✓
p.cubicTo(10, 40, 50, 40, 60, 0)
// ✗ two outlines in one pen: the second moveTo and everything after it are dropped
Path2D.shape(p => { p.roundRect(-50, -20, 100, 40, 8); p.moveTo(0, -20); p.lineTo(10, -35) })
// ✓ one path per outline (a speech bubble = its box + its tail, the same fill)
const box = Path2D.roundRect([100, 40], 8, { fill: "#fff" })
const tail = Path2D.polygon([[-6, -20], [6, -20], [0, -32]], { fill: "#fff" })
// ✗ degrees: arcs take radians
Path2D.arc(30, 0, 90)
// ✓
Path2D.arc(30, 0, Math.PI / 2)See also
- Scene2D — draw order, adding nodes
- Node2D — transform, hierarchy (inherited)
- Text2D — labels beside the lines
- Canvas — paths painted into an image instead
- 2D physics — a collider for a shape (
Shape2D)