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

TypeScript
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

TypeScript
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:

TypeScript
{
  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

TypeScript
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.

TypeScript
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

TypeScript
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 }): Path2D

Each 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).

TypeScript
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

TypeScript
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 path

Canvas2D'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.

TypeScript
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()
Note

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.

TypeScript
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 = 8

A 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

TypeScript
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.material

A 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:

TypeScript
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

TypeScript
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

TypeScript
// 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

TypeScript
// ✗ 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)