API Reference

Quick reference for the Pluton 2D public API: constructor, geometry, and dimensions.

Pluton2D

Constructor

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

Flat params only. Reactivity tracks top-level mutations via Proxy. Nested objects need deep watching (not supported). Keep complex state outside scene.params, sync flat values in draw callback.

ViewBox (Coordinate Space)

Set explicit drawing coordinate system independent of pixel dimensions:

const scene = new Pluton2D(svg, {
  params: { size: 100 },
  viewBox: { width: 200, height: 300 },
});

Priority order:

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

A larger viewBox gives more room for geometry without affecting visual scale. For example, viewBox: { width: 1000, height: 1000 } provides a spacious coordinate space even if the SVG is only 500×500 pixels on screen.

Properties

Create groups once at setup, request builders inside draw callbacks. Avoids recreating elements every frame.

Methods

const unsubscribe = scene.draw((params) => {
  // build geometry and dimensions
});

unsubscribe(); // stop this callback

scene.dispose(); // tear down everything

scene.params.width = 150; // supported
Object.assign(scene.params, { width: 200, height: 100 }); // supported
scene.params = { width: 200, height: 100 }; // throws

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

const tealFill = scene.addHatchFill("#0f766e");
geom.path({ fill: tealFill }).moveToAbs(...).lineTo(...).close();

scene.setFilterIntensity(0.9);

Responsive Scaling

Scale the view programmatically for different screen sizes:

// Mobile - scale down to give geometry breathing room
if (window.innerWidth <= 640) {
  scene.setViewScale(0.7);
}

// Tablet - moderate scaling
else if (window.innerWidth <= 1024) {
  scene.setViewScale(0.85);
}

// Desktop - full scale
else {
  scene.setViewScale(1.0);
}

Key points:

• Scales visual output only. Coordinate system unchanged
• Zoom/pan still work normally
• Camera state preserved (zoom level unaffected)
• Smoothly interpolates like pan/zoom

Geometry

GeometryGroup

Create groups once, outside draw callbacks. Groups persist across frames. Request builders with path() inside draw callbacks. Engine recycles them automatically.

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

path(options) fields

PathBuilder

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

const path = geom.path({ className: "optional-class" });

path.moveTo(dx, dy)          // relative move
path.moveToAbs(x, y)         // absolute move
path.lineTo(dx, dy)          // relative line
path.lineToAbs(x, y)         // absolute line
path.cubicTo(c1dx, c1dy, c2dx, c2dy, dx, dy)         // relative cubic Bezier
path.cubicToAbs(c1x, c1y, c2x, c2y, x, y)            // absolute cubic Bezier
path.smoothCubicTo(c2dx, c2dy, dx, dy)               // relative smooth cubic
path.smoothCubicToAbs(c2x, c2y, x, y)                // absolute smooth cubic
path.quadTo(c1dx, c1dy, dx, dy)                      // relative quadratic Bezier
path.quadToAbs(c1x, c1y, x, y)                       // absolute quadratic Bezier
path.smoothQuadTo(dx, dy)                            // relative smooth quadratic
path.smoothQuadToAbs(x, y)                           // absolute smooth quadratic
path.arcTo(dx, dy, r, clockwise?, largeArc?)    // relative arc
path.arcToAbs(x, y, r, clockwise?, largeArc?)   // absolute arc
path.close()                 // close path
path.reset()                 // clear commands

Curve types

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

Dimensions

DimensionsGroup

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

Methods: translate(x, y), setDrawUsage(mode), clear(), dimension(options?). Clear resets translation to origin.

DimensionsBuilder: Positioning

const dim = dims.dimension({ className: "optional-class" });

dim.moveTo(dx, dy); // relative move
dim.moveToAbs(x, y); // absolute move
dim.lineTo(dx, dy); // relative line
dim.lineToAbs(x, y); // absolute line

Relative moves from current position, absolute moves to world coordinates. Use for dimension lines and leaders.

DimensionsBuilder: Primitives

Angles in radians. 0 points right, π/2 points up.

dim.arc(r, startAngle, endAngle)     // arc centered at current position
dim.arrow(angleRad, size?)           // open arrow (default size: 8)
dim.arrowFilled(angleRad, size?)     // filled arrow (default size: 8)
dim.tick(angleRad, size?)            // architectural tick (default size: 15)
dim.centerMark(size?)                // crosshair with center dot (default size: 10)
dim.close()                          // close path

DimensionsBuilder: Text

dim.textAt(dx, dy, text, align?, className?)
dim.textAtAbs(x, y, text, align?, className?)

align: "start" | "middle" | "end" (default: "middle"). Controls text anchor. className: Optional CSS class for <text>.

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