Entities, ports, and relations

Circles and boxes are only the output. The model itself asks which entities exist, where they connect, and what each connection means.

Entities have identity

An entity begins with a keyword and a unique identifier. Attributes follow it:

support ceiling
surface floor orientation=horizontal friction=rough mu=0.25
load crate 8kg
pulley P radius=8cm

crate, floor, and P are identifiers. Other statements use those names to reference the same objects. Physical quantities such as mass, length, and angle should include units.

Ports name connection points

An entity can expose several meaningful ports. A body has attachment locations and a pulley has an axle and rim, but ordinary models do not name those ports:

pulley M
load crate 8kg

M <-> crate

The compiler reads the entity kinds and selects M.axle and crate.top internally. Explicit endpoint syntax is reserved for a custom path whose topology cannot be inferred.

A relation is not a decorative line

A relation declares a physical constraint. These statements describe a rigid attachment, rolling without slipping, and ideal projectile launch:

pivot pivot_beam body=beam support=O
rolling rolling_wheel body=wheel surface=ramp mode=without_slipping
launch launch_ball body=ball origin=ground speed=12m/s angle=40deg

They enter solving and diagnostics instead of merely asking the renderer for a line. If a radius, speed, or another required condition is absent, the compiler should refuse to solve the incomplete model.

Concise relation values are matched to properties by their physical dimension or allowed value, so 40deg 12m/s is equivalent when the meaning remains unambiguous. Use explicit angle=40deg speed=12m/s when you want the property names visible or need to resolve an ambiguity.

Write a rope path in order

Most common pulley routes are inferred. For a multi-rope or unusual topology, first declare the ropes and then follow each one from one end to the other:

rope R
R: ceiling -> M -> F -> R.free

• ceiling fixes the first end to the support.
• M and F mean that the route wraps around those pulleys in order.
• R.free is the named rope’s free end.

All segments of one ideal rope share tension. The rope-length constraint, tangent points, and motion ratio come from this one path; do not author a second visual connection.

Keep model and layout separate

Entities and relations state physical facts. Use place only when automatic layout cannot preserve the intended composition:

place crate x=0.72 y=0.68 variant=wide

Coordinates are normalized canvas positions from 0 to 1. They do not alter physical coordinates, forces, or equations of motion.