Diagram DSL reference

The Diagram DSL builds physics and chemistry figures from relations, not coordinates. Declare objects with their physical parameters, then constrain them — the engine solves placement, rotation, and scaling. Open the DSL panel in the editor (toolbar ▸ DSL) to render scenes live and insert them as a single group.

How it works

A constraint a.anchor = b.anchor moves element a so its anchor coincides with the reference — the right-hand element stays put. a.prop = expr assigns scalars (numbers, arithmetic on el.anchor.x/.y); a.anchor.x = b.anchor.x aligns one axis without contact. Line, rope and vector endpoints stretch instead of translate. Constraints run in multiple passes — order doesn't matter — and dependents re-route.

canvas 800x500 grid 8x8

incline ramp1 x=100 y_base=380 angle=30 run=260
block m1 on_incline=ramp1 at=0.55 w=70 h=46
pulley p1
p1.handle.endpoint = ramp1.tip      # strut pivots at the tip
rope r1 from=m1.top to=m2.top through=p1
vector N on=m1 preset=normal len=56

Elements

Rules

• Constraints: a.anchor = b.anchor moves element a so the anchors coincide. a.prop = expr assigns scalars (radius, width, left_side_size…). a.orientation = vertical|horizontal|deg orients anything (line axes, block rotation, ramp angle). Endpoints on line/rope/vector stretch rather than translate. Constraints run in two passes — order does not matter, and dependents re-route.
• Composed objects expose their lines: Every polygon's edges are named lines: ramp1.inclined_line / .horizontal_line / .vertical_line (block: top_edge etc). Line anchors apply: .t:0.3, .t1_10, .t1:10, _middle, _k_n_point, _left/right_point, _size. Circles expose center, rim:deg, clock:N, Noclock, Ndeg, arc:t (fraction of circumference).
• Every element inherits: bbox names (center/top/bottom/left/right/tl…br), edge families (<edge>_middle, <edge>_<k>_<n>_point, <edge>_size, <edge>_left|right_point), polygon family (v:i, seg:i:t) when verts exist, line family (a,b,mid,t:,length) when a,b exist, circle family (rim:deg, clock:N, Noclock, Ndeg) when c,r exist.
• Named parts: X.<part>.<prop>: Any element can compose sub-elements: X.<part>.len / .slope / .endpoint / .color / .sw. Strut-like parts (handle, strut, rod, arm, stem, leg, mount) make a rod from the parent centre — endpoint/pivot names the mounting point and the parent rides the far end. Other parts are plain anchored lines (v1.shaft); arrow.head/tail alias the arrow endpoints.
• Styling: color= / fill= / stroke= on any element: names (red, teal), hex (#eaf, #888, #ff0033), rgb(). color sets both; fill/stroke target each.
• Mirroring: mirror=h|v (or flip=) flips the SHAPE only — relations and outward faces stay consistent (normals, angle, slope sign-flip; text stays readable). h/x/horizontal = left-right, v/y/vertical = up-down.
• Rotation: rot=deg on any element — rotates about its own bbox centre (clockwise-positive). Anchors and slope_dir/normal rotate with it.
• Autoscale under constraints: incline apex/tip pins rescale `run` to keep y_base grounded — pin ramp1.tip = ramp2.tip and the 30° ramp grows/shrinks its run so the base stays on the floor, not translates.
• Anchor offsets: any anchor accepts ±N: m1.right+20 = m2.left leaves a 20px gap. The offset follows the anchor direction word (right→+x, left→−x, top→−y, bottom→+y; default +x).
• Dashed lines: dashed=1 or dash="4 3" on any element — stroke-dasharray for construction lines, hidden edges, ray tails.
• Line size props: len/length sizes the free end; slope=deg pins direction (clockwise-positive); orientation=vertical|horizontal; endpoint/to names the far end — slope keeps direction, endpoint sets extent.
• Point expressions: "x,y" literals, "el.anchor" refs, "canvas.cell:c:r", "canvas.region:name", and "+(dx,dy)" offsets: label L pos=m1.top+(0,-10)

Placement guide

Idioms for positioning — pins, alignment, gaps, rotations, stretching:

Pin direction: lhs moves

a.anchor = b.anchor      # moves a so its anchor lands on b's anchor
# the rhs never moves — pin the element that should TRAVEL
m1.top = s.top            # block m1 lands its top edge on surface s
# to move b instead, swap sides: b.top = a.top

Seat an edge on a line (2 pins)

# two pins on the SAME edge family rigid-seat the element:
m1.bottom_edge_1_10 = ramp1.inclined_line_3_10
m1.bottom_edge_8_10 = ramp1.inclined_line_4_10
# the solver picks rotation <=90deg — body stays outside the ramp
# prefer on_incline= when available; 2 pins = manual seat

Align without touching (axis pins)

m2.center.x = m1.center.x     # same x — stacks vertically
m2.top.y = m1.bottom.y        # level the edges — no contact
p1.center.x = ceiling.bottom.x  # centre under a point

Gaps and offsets

m1.right+20 = m2.left        # 20px gap — offset follows the
# anchor direction: right->+x, left->-x, top->-y, bottom->+y
m1.top+15 = s.top             # 15px below the surface line

Point offsets

label l pos=m1.top+(0,-10) text="m1"   # 10px above the anchor
# works in from/to/pins:  v1.origin = m1.center+(30,-40)

Endpoint stretch (lines)

# line/rope/vector endpoints move instead of translating:
l.left = m1.center           # left end sticks to the block centre
l.right = p1.9oclock         # right end on the pulley rim
frame.slope = 30             # direction pinned; endpoint sets extent
frame.length = 200           # free end sized

Rotation + slope

m1.rot = 15                  # rotate about own centre (deg)
ramp2.orientation = 40       # incline angle via constraint
l.slope = -30                # line direction, clockwise-positive
l.orientation = vertical     # snap to axis

Mirror

incline r2 angle=40 mirror=h     # flips the SHAPE; anchors follow
# mirror changes geometry only — normals/angles/signs stay consistent

Scalar props + expressions

p1.radius = m1.width / 2         # reads assigned value — order matters:
m1.width = 60                # assign plain numbers FIRST
m2.center.x = ramp1.apex.x - m2.width/2 - 10   # coords inside arithmetic
# stable props only: width/height/radius/angle/slope/length

Rope over a pulley

rope r1 from=m1.top to=m2.top through=p1
# routes over the rim — never pin both ends to rim points

Strut / handle parts

p1.handle.endpoint = ramp1.tip   # rod pivots at the tip
p1.handle.slope = 270          # direction (270 = straight up)
p1.handle.len = 25             # rod length; pulley rides the far end
# also strut/rod/arm/stem/leg/mount; X.<part> is a line element

Vectors

vector N  on=m1 preset=normal      len=56   # normal on incline
vector W  on=m1 preset=gravity     len=70   # straight down
vector Fr on=m1 preset=friction_up len=44   # along slope up
vector T  on=m2 along_rope=r1     len=64   # tension from a rope
vector F  on=m1 anchor=m1.left preset=up     # anchor picks the origin

Grid + regions

m1.center = canvas.cell:2:2          # grid cell centre (0-indexed)
label t pos=canvas.region:bottom text="FBD"   # named canvas regions

Canonical recipes

Pulley under a support

surface ceiling x=150 y=50 w=200 h=16
pulley p1 mount=strut of=ceiling anchor=ceiling.bottom angle=90 len=70
# rod from ceiling.bottom straight down 70px, pulley at its end

Atwood: two masses over one pulley

rope r1 from=m1.top to=m2.top through=p1
m1.center.x = p1.9oclock.x      # hang left mass off the left tangent
m2.center.x = p1.3oclock.x      # right mass off the right tangent
# through=p1 routes the rope over the top — no manual endpoint wiring

Block on an incline + forces

block m1 on_incline=ramp1 at=0.55 w=70 h=46
vector N  on=m1 preset=normal      len=56
vector W  on=m1 preset=gravity     len=70
vector Fr on=m1 preset=friction_up len=44

Free pulley at the ramp tip

pulley p1
p1.handle.endpoint = ramp1.tip    # strut pivots at the tip
p1.handle.slope    = 210          # rod direction (deg, clockwise)
p1.handle.len      = 40
# the pulley rides the rod's far end

Back-to-back inclines (Λ Atwood)

incline ramp1 x=100 y_base=380 angle=30 run=240
incline ramp2 x=360 y_base=380 angle=40 run=200 mirror=h
ramp1.tip = ramp2.tip      # shared apex — run AUTOSCALES so the base
# stays grounded; pin the unmirrored ramp's tip, never the reverse
pulley p1
p1.handle.endpoint = ramp1.tip
p1.handle.slope = 270            # straight up
block m1 on_incline=ramp1 at=0.5
block m2 on_incline=ramp2 at=0.5
rope r1 from=m1.top to=m2.top through=p1

Common mistakes

• Prefer `pulley p mount=strut of=el anchor=el.bottom angle=90 len=N` over hand-pinning p.center — the strut keeps the mount live
• For a rope over a pulley use `through=p` — do NOT pin both endpoints to rim anchors (they land on the same point)
• Axis pins (a.x = b.x) align without touching — use full pins `a.b = c.d` only when contact is intended
• Scalar refs read the *assigned* value: put `m1.width = 60` before `p.radius = m1.width/2`
• Self-referencing positions (m.center.x = …m.center.x…) are unstable — reference stable props (width/height/slope) instead
• Prefer round numbers and tenth-fractions: at=0.5 / 0.6, widths like 50/60 — avoid arbitrary decimals (0.37, 0.618); anchor fractions t:0.5 / t5_10 read cleaner than decimals
• Seat blocks with on_incline=ramp (not edge pins) — it follows the slope normal correctly even on mirrored inclines; when edge pins are needed, pin fractions of ONE edge (bottom_edge_1_10 + bottom_edge_8_10) and the solver picks the sub-90° seating automatically
• For back-to-back inclines the MIRRORED ramp keeps its position — pin the unmirrored ramp's apex onto it (ramp1.tip = ramp2.tip), never the reverse