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 type=horizontal friction=rough mu=0.25
body crate mass=8kg on=floor
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 top, bottom, left, right, and center; a pulley has axle and rim. Reference a port with a dot:

attach P.axle to ceiling
attach spring.end to crate.left

You rarely need to author ports by hand. Higher-level forms such as pulley P fixed to ceiling and pendulum P fixed to beam select the proper ports. Use explicit ports only for a custom connection.

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:

attach rod.center to pivot
roll wheel on ramp mode=without_slipping
launch ball from 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.

Write a rope path in order

rope ... path follows a rope from one end to the other:

rope R path anchor(ceiling) -> around(M) -> around(F) -> handle

• anchor(ceiling) fixes an end to a support.
• around(M) makes tangent contact with and wraps around a pulley.
• tie(load) ties an end to a body.
• handle is a 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 at 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.