API Reference

For explanations and usage patterns, see the guide.

Method signatures, parameters, and behavior.

Pluton2D

Constructor

const scene = new Pluton2D(svg, {
  params: { width: 240, height: 120 },
  viewBox: { width: 500, height: 500 },
});

Params must be flat. Reactivity tracks top-level mutations via Proxy. Keep complex state outside scene.params and sync flat values in your draw callback.

ViewBox priority order:

1. Constructor viewBox parameter
2. SVG viewBox attribute
3. SVG pixel dimensions (getBoundingClientRect)

A larger viewBox gives more coordinate space without affecting visual scale. viewBox: { width: 1000, height: 1000 } on a 500x500px SVG means 1 unit = 0.5 pixels.

Properties

Create groups once at setup, grab builders inside draw callbacks. Groups persist across frames.

Methods

Drawing

Engine idles when all draw callbacks unsubscribe (unless camera/input is active).

Scene Controls

Camera

Fills

Lifecycle

Utilities

snapshotSvg

import { snapshotSvg } from "pluton-2d";

const svgText = snapshotSvg(svgElement);

Returns a standalone SVG XML string with inlined computed styles and normalized local paint references (url(#id)).

Use the returned string to create a Blob and download/upload as needed.

GeometryGroup

Creating a group

const geometryGroup = scene.geometry.group();

Create groups once at setup, outside draw callbacks. Groups persist across frames. Grab builders with path() inside draw callbacks.

Methods

In static mode, still call path() every frame. The engine detects unchanged geometry and skips DOM writes after the first commit.

PathOptions

PathBuilder

All methods return this for chaining unless noted otherwise. Relative commands move from the current position, absolute commands move to world coordinates.

Movement

Lines

Arcs

Cubic Bezier

Quadratic Bezier

Smooth commands (S/s, T/t) depend on the previous curve segment. If there’s no compatible previous segment (like after a line or move), SVG treats the inferred control point as the current point, giving a sharp corner instead.

Utility

DimensionsGroup

Creating a group

const dimensionsGroup = scene.dimensions.group();

Same pattern as geometry groups. Create once, outside draw callbacks.

Methods

DimensionOptions

DimensionsBuilder

All methods return this for chaining unless noted otherwise. Angles in radians. 0 points right, π/2 points up.

Positioning

Markers

Arc

Text

align: "start" | "middle" (default) | "end". Controls text anchor.

Text is rendered in world space (Y-up). The engine transforms it to appear upright on screen.

Utility

CSS Variables

Override these on .pluton-root to customize appearance.