PhysLoom Physics-as-Code
中文
Studio

Docs

Language reference

Statements, attributes, and ports generated from the compiler registry.

This page reads the compiler authoring contract directly. It does not maintain a second keyword list, so a changed or newly registered DSL statement appears here with the next build.

Common structure

A file may contain one or more scene blocks. A scene contains entities, relations, presentation requests, and motion requests:

scene example {
  body A mass=1kg
  support O
  attach A.top to O
  show force
}

Identifiers are case-sensitive. Strings use double quotes. Write a physical quantity as a number followed by a unit, such as 2kg, 30deg, or 9.8m/s^2.

Rope path segments

A rope path supports anchor(id), around(pulley), tie(body), and a plain entity or free-end identifier. Segment order defines rope topology.

Scene and core entities

support Defines a fixed support, wall, ceiling, or other attachment reference.
Syntax
support <id> [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: length
Ports
anchor
surface Defines a renderable contact surface such as a table or incline.
Syntax
surface <id> [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: lengthangle: anglefriction: smooth | rough | static | kineticmu: quantitymu_kinetic: quantitymu_static: quantitytype: horizontal | incline
block Defines a carrier block that can group one or more physical bodies.
Syntax
block <id> carries <body> [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: length
Ports
centertopbottomleftright
body Defines a physical body, mass, load, or object.
Syntax
body <id> [role] [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: lengthaxis: identifiercross_section: areaguide: identifierinertia_factor: quantitymass: massmaterial: identifier | stringmotion: identifieron: identifierradius: lengthrole: identifiershape: point | block | solid_sphere | hollow_sphere | solid_cylinder | hooptie: identifiervelocity: speedvelocity_x: speedvelocity_y: speedvolume: volume
Ports
centertopbottomleftrightcontactopposite_contactdownslopeupslope
load Defines a load body; shorthand for `body ... role=load`.
Syntax
load <id> [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: lengthmass: mass
Ports
centertopbottomleftright
disk Defines a rigid solid disk rotating about its symmetry axis.
Syntax
body <id> [role] [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: lengthaxis: identifiercross_section: areaguide: identifierinertia_factor: quantitymass: massmaterial: identifier | stringmotion: identifieron: identifierradius: lengthrole: identifiershape: point | block | solid_sphere | hollow_sphere | solid_cylinder | hooptie: identifiervelocity: speedvelocity_x: speedvelocity_y: speedvolume: volume
Ports
centertopbottomleftrightcontactopposite_contactdownslopeupslope

Mechanics and constraints

pulley Defines a fixed or movable pulley.
Syntax
pulley <id> [fixed to <support> | attached to <body>] [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: lengthradius: length
Ports
axlerim
pendulum Defines a pendulum suspended from a fixed support.
Syntax
pendulum <id> fixed to <support> [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: lengthangle: anglegravity: accelerationlength: length (required)mass: mass
Ports
pivotbob
spring Defines an elastic connector with start and end ports.
Syntax
spring <id> [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: lengthdisplacement: lengthextension: lengthmodulation_depth: quantitymodulation_frequency: frequencymodulation_phase: anglestiffness: stiffness (required)
Ports
startend
damper Defines a linear viscous damper with start and end ports.
Syntax
damper <id> [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: lengthcoefficient: damping (required)
Ports
startend
attach Attaches an entity port to another entity or port.
Syntax
attach <from> to <to>
Attributes
none
pivot Constrains a rigid body to rotate about a point fixed to a support.
Syntax
pivot <body> on <support> [attributes]
Attributes
position: length
roll Constrains a round rigid body to roll on a surface with an explicit contact mode.
Syntax
roll <body> on <surface> <without_slipping|with_slipping>
Attributes
mode: without_slipping | with_slipping (required)
orbit Constrains one body to an orbital path around another body.
Syntax
orbit <body> around <center> [attributes]
Attributes
direction: clockwise | counterclockwiseeccentricity: quantityobservation_radius: lengthsemi_major_axis: length (required)start: apoapsis | periapsis
circular-motion Constrains a body to uniform circular motion about a fixed center.
Syntax
circular-motion <body> around <center> [attributes]
Attributes
direction: clockwise | counterclockwiseperiod: timeradius: length (required)speed: speedstart: angle
launch Defines ideal projectile initial conditions and a straight horizontal or inclined landing surface.
Syntax
launch <body> from <origin> [attributes]
Attributes
angle: angle (required)gravity: accelerationheight: lengthspeed: speed (required)
impact Defines an ideal smooth impact; the collision axis is either horizontal or derived from contact geometry.
Syntax
impact <bodyA> with <bodyB> [attributes]
Attributes
axis: horizontal | contact (required)restitution: quantity | identifier (required)
rope Defines a rope path through anchors, pulleys, bodies, handles, or tie points.
Syntax
rope <id> path <segment> -> <segment> [...]
Attributes
none
Ports
free
force Defines an external force vector on a target body or an explicit body port such as body.center.
Syntax
force <id> on <entity-or-port> [attributes]
Attributes
angle: angledirection: up | down | left | right | up_left | up_right | down_left | down_rightfrequency: frequencymagnitude: forceposition: length
torque Applies a constant external torque to a rigid body about its fixed pivot.
Syntax
torque <body> [attributes]
Attributes
direction: clockwise | counterclockwise (required)magnitude: torque (required)

Experimental apparatus

rod Defines a rigid experimental rod with attachment points.
Syntax
rod <id> [attributes]
Attributes
length: length (required)mass: mass
Ports
centerleftright
fiber Defines a suspension or torsion fiber.
Syntax
fiber <id> [attributes]
Attributes
stiffness: stiffness
Ports
topbottom
attract Relates two bodies through an attractive interaction.
Syntax
attract <source> to <target> [attributes]
Attributes
law: identifiermagnitude: quantity | identifier
measure Measures an observable from a source with a detector.
Syntax
measure <detector> on <source> [attributes]
Attributes
observable: identifierreading: quantity | identifier

Thermodynamics

reservoir Defines a thermal reservoir or material energy store.
Syntax
reservoir <id> [attributes]
Attributes
energy: quantity | identifiermedium: identifier | stringtemperature: temperature
Ports
inout
heat-engine Defines a cyclic device exchanging heat and work.
Syntax
heat-engine <id> [attributes]
Attributes
efficiency: quantity | identifier
Ports
hotcoldwork
ensemble Defines a statistical ensemble of microscopic constituents.
Syntax
ensemble <id> [attributes]
Attributes
entropy: quantity | identifiermicrostates: quantity | identifierparticles: quantity | identifier
transfer Transfers energy from one physical entity to another.
Syntax
transfer <source> to <target> [attributes]
Attributes
amount: quantity | identifierform: identifierlabel: identifier | string
cycle Connects a heat engine between hot and cold reservoirs.
Syntax
cycle <engine> between <hot> and <cold> [attributes]
Attributes
heat_in: energyheat_out: energyschedule: equal_stageswork: energy

Fields and waves

object Defines the physical object whose image is formed by an optical system.
Syntax
object <id> [attributes]
Attributes
height: length (required)
Ports
basetip
lens Defines an ideal thin converging or diverging lens.
Syntax
lens <id> [attributes]
Attributes
type: converging | diverging (required)focal_length: length (required)
Ports
centersurface
medium Defines a homogeneous optical medium by its refractive index.
Syntax
medium <id> [attributes]
Attributes
refractive_index: quantity (required)
light-source Defines a source of light or radiation.
Syntax
light-source <id> [attributes]
Attributes
color: identifierfrequency: frequency
Ports
emission
prism Defines a refracting prism.
Syntax
prism <id>
Attributes
none
Ports
entryexit
screen Defines an observing screen or photographic plate.
Syntax
screen <id>
Attributes
none
Ports
surface
detector Defines a detector for light, waves, particles, or current.
Syntax
detector <id>
Attributes
none
Ports
input
mirror Defines a reflecting mirror.
Syntax
mirror <id>
Attributes
none
Ports
surface
beam-splitter Defines an optical beam splitter.
Syntax
beam-splitter <id>
Attributes
none
Ports
inputtransmittedreflected
coil Defines a conducting coil.
Syntax
coil <id> [attributes]
Attributes
radius: lengthresistance: resistanceturns: quantity | identifier
Ports
ab
magnet Defines a permanent magnet.
Syntax
magnet <id> [attributes]
Attributes
dipole_moment: magnetic-dipole-moment
Ports
northsouth
field Defines a physical field.
Syntax
field <id> [attributes]
Attributes
direction: identifierkind: identifiermagnitude: quantity | identifier
wave Defines a propagating wave associated with a field.
Syntax
wave <id> [attributes]
Attributes
amplitude: quantity | identifierfield: identifierfrequency: frequencyphase: anglespeed: speedwavelength: length
Ports
startend
ray Routes a light ray from a source through an optical element to a target.
Syntax
ray <source> through <optic> to <target> [attributes]
Attributes
bend: quantity | identifiercolor: identifier
image Forms the image of an optical object through an ideal thin lens.
Syntax
image <object> through <lens> [attributes]
Attributes
object_distance: length (required)
refract Sends a light source from one optical medium into another across a plane interface.
Syntax
refract <source> from <incidentMedium> into <transmittedMedium> [attributes]
Attributes
incidence_angle: angle (required)
reflect Reflects a light source from an ideal plane mirror according to the law of specular reflection.
Syntax
reflect <source> from <mirror> [attributes]
Attributes
incidence_angle: angle (required)
induction Relates a coil to a changing magnetic source.
Syntax
induction <coil> by <magnet> [attributes]
Attributes
axis: axialdistance: lengthmotion: identifier
lorentz Constrains a charged particle to motion under the magnetic Lorentz force.
Syntax
lorentz <particle> in <field> [attributes]
Attributes
velocity: right | left | up | down (required)
velocity-selector Selects the undeflected velocity of a charged particle in perpendicular uniform electric and magnetic fields.
Syntax
velocity-selector <particle> through <electricField> and <magneticField> [attributes]
Attributes
velocity: right | left | up | down (required)length: length (required)
propagate Propagates a wave from a source to a detector.
Syntax
propagate <wave> from <source> to <target> [attributes]
Attributes
distance: length
interfere Superposes two coherent waves at a shared detector or observation point.
Syntax
interfere <waveA> with <waveB> at <target>
Attributes
none

Electric circuits

battery Defines an ideal DC voltage source with explicit positive and negative terminals.
Syntax
battery <id> [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: lengthvoltage: voltage (required)
Ports
positivenegative
ac-source Defines an ideal sinusoidal RMS voltage source with explicit terminals.
Syntax
ac-source <id> [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: lengthrms_voltage: voltage (required)frequency: frequency (required)phase: angle
Ports
positivenegative
resistor Defines a two-terminal linear resistor.
Syntax
resistor <id> [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: lengthresistance: resistance (required)
Ports
ab
capacitor Defines an ideal linear capacitor.
Syntax
capacitor <id> [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: lengthcapacitance: capacitance (required)
Ports
ab
inductor Defines an ideal linear inductor.
Syntax
inductor <id> [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: lengthinductance: inductance (required)
Ports
ab
wire Joins two component terminals with an ideal conductor.
Syntax
wire <from> to <to>
Attributes
none

Electrostatics

charge Defines a point charge used as an electrostatic field source or probe.
Syntax
charge <id> [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: lengthvalue: charge (required)role: source | test
electric-field Adds a point charge contribution to an electric field by superposition.
Syntax
electric-field <field> from <source>
Attributes
none

Fluids

fluid Defines a homogeneous fluid used by hydrostatic and flow relations.
Syntax
fluid <id> [attributes]
Attributes
height: lengthwidth: lengthx: lengthy: lengthdensity: density (required)gravity: acceleration
Ports
surface
float Constrains a body to hydrostatic equilibrium at a fluid free surface.
Syntax
float <body> in <fluid>
Attributes
none

Modern physics

particle Defines a material particle or radiation quantum.
Syntax
particle <id> [attributes]
Attributes
charge: chargeenergy: energyfrequency: frequencymass: massmomentum: quantity | identifierspeed: speedspin: quantity | identifierwavelength: length
Ports
trajectory
atom Defines an atom with an optional structural model.
Syntax
atom <id> [attributes]
Attributes
element: identifier | stringmodel: identifier
Ports
center
nucleus Defines an atomic nucleus or fission fragment.
Syntax
nucleus <id> [attributes]
Attributes
isotope: identifier | stringneutrons: quantity | identifierprotons: quantity | identifier
Ports
center
energy-level Defines a discrete energy level or quantum state.
Syntax
energy-level <id> [attributes]
Attributes
energy: quantity | identifier (required)n: quantity | identifier
Ports
state
wavefunction Defines a quantum state represented by a wavefunction.
Syntax
wavefunction <id> [attributes]
Attributes
energy: quantity | identifiermomentum-spread: quantity | identifierposition-spread: quantity | identifierstate: identifier
Ports
state
aperture Defines a slit, crystal, or aperture used for diffraction.
Syntax
aperture <id> [attributes]
Attributes
kind: identifierspacing: quantity | identifier
Ports
entryexit
sample Defines a physical sample with measurable activity.
Syntax
sample <id> [attributes]
Attributes
activity: quantity | identifiermaterial: identifier | string
Ports
emission
reactor Defines a controlled nuclear chain-reaction assembly.
Syntax
reactor <id> [attributes]
Attributes
multiplication: quantity | identifiermoderator: identifier
Ports
corecontrol
reference-frame Defines an inertial reference frame with a relative velocity.
Syntax
reference-frame <id> [attributes]
Attributes
velocity: quantity | identifier
Ports
origin
event Defines a spacetime event.
Syntax
event <id> [attributes]
Attributes
position: quantity | identifiertime: quantity | identifier
Ports
point
transition Moves a particle between two discrete energy levels.
Syntax
transition <particle> from <from> to <to> [attributes]
Attributes
photon: quantity | identifier
occupy Places a particle in a discrete quantum state.
Syntax
occupy <particle> in <level>
Attributes
none
describe Associates a particle with its quantum-state description.
Syntax
describe <particle> by <state>
Attributes
none
diffract Diffracts a particle or wave through an aperture toward a detector.
Syntax
diffract <particle> through <aperture> to <detector>
Attributes
none
scatter Scatters a projectile from a target toward a detector.
Syntax
scatter <projectile> by <target> to <detector> [attributes]
Attributes
angle: quantity | identifier
photoelectric-effect Transfers a photon quantum to an electron in a material.
Syntax
photoelectric-effect <photon> on <material> releases <electron> [attributes]
Attributes
angle: angleworkfunction: energy (required)
signal Connects two spacetime events by a signal in a reference frame.
Syntax
signal <signal> from <from> to <to> in <frame>
Attributes
none
antiparticle Relates a particle to its antiparticle partner.
Syntax
antiparticle <antiparticle> of <particle>
Attributes
none
decay Transforms a parent sample or nucleus while emitting a particle.
Syntax
decay <parent> to <daughter> emits <emission>
Attributes
none
collision Collides a projectile with a target to produce an outgoing particle.
Syntax
collision <projectile> with <target> produces <product>
Attributes
none
fission Splits a nucleus after impact into two fission fragments.
Syntax
fission <parent> by <projectile> into <fragmentA> and <fragmentB> [attributes]
Attributes
energy: quantity | identifierneutrons: quantity | identifier
chain-reaction Sustains a fission chain in a reactor core.
Syntax
chain-reaction <reactor> from <fuel> [attributes]
Attributes
generations: quantity | identifier

Presentation and motion

place Pins an entity center to a normalized responsive-canvas position without changing the physical model.
Syntax
place <entity-or-port> at x=<0..1> y=<0..1> [variant=compact|standard|wide|print|poster]
Attributes
x: quantityy: quantityvariant: compact | standard | wide | print | poster at least one: x, y
show Requests labels, diagrams, or annotations for rendering.
Syntax
show <feature> [feature ...]
Attributes
none
drive Requests a constrained physical motion; phase selects a solved process while displacement defines its observation window.
Syntax
drive <target> [direction] [attributes]
Attributes
angle: angleamplitude: lengthplayback: timedisplacement: lengthduration: timeincidence_angle: angleobject_distance: lengthphase: current_flow | decay | emission | flight | flyby | heave | impact | parametric | period | release | rotation | steady_state | transit