QWAY language reference

Grammar and values

program   = command* ;
command   = "\" identifier "[" arguments? "]" (";" | "{" command* "}") ;
arguments = identifier "=" value ("," identifier "=" value)* ;
value     = identifier | JSON-string | boolean | number unit?
          | "@" alias ("." feature)* | "(" value ("," value)* ")" ;
comment   = "%" text-to-end-of-line ;

This notation is LaTeX-inspired, not TeX. There are no macros, executable expressions, recursion, file access or imports. Use ASCII identifiers; quoted strings support Unicode and JSON escapes. A command name can contain hyphens. Unknown or duplicate arguments are errors.

Numbers may be signed decimals or scientific notation (for example -0.5, .25, 1e-3); they must be finite. NaN/Infinity are not numeric literals. Length/angle/mass/time require explicit units, including zero. Tuples have typed fixed arity. Object aliases are not identities: declarations need a UUID or an existing host identity binding. References can be forward-declared, but must resolve. Feature paths refer only to pinned manifest candidates or accepted feature labels.

Declarations are resolved before geometric dependency ordering; source order is not an imperative placement script. Formatter preserves comments/literal spelling while canonicalizing whitespace. printSource(CST) reproduces the original draft exactly; diagnostic spans use UTF-16 half-open offsets.

Defaults and phases

Compilation parses, checks signatures/units, resolves identities and pinned features, applies versioned policy, lowers inverse relations, validates graphs/physics, solves layout and independently evaluates relations. A parser-valid program may still be geometrically impossible.

All relations share temporal=initial, strength=hard and weight=1 unless overridden. Recognized maintain syntax does not promise implemented runtime maintenance. Exact policy/default contracts are versioned in the compiled scene. The argument tables below are generated from the current implementation.

\scene

Exactly one root. name is an alias; id or host binding establishes identity. seed makes layout reproducible. profile defaults to conservative static policy. composition=room opts into room composition.

\scene[name=example]{}

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\room

Room dimensions are (width,height,depth). A declaration owns a block. WRIGHT topology is separate typed data, not arbitrary nested QWAY coordinates.

\room[name=example,size=(1m,1m,1m)]{}

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\object

Declare an instance of an existing asset UUID. Pin manifest/archetype revisions. Optional size/height/up/front are explicit user intent. Defaults preserve visible, unlocked objects and conservative role/policy. notes are untrusted semantic context, not geometry.

\object[name=example,asset="00000003-1111-4111-8111-111111111111"];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\material

Reusable semantic surface resource: UUID identity, source alias, label, description and category. Standard metallic/roughness or Unlit shading; colour, emission, alpha, faces and immutable image maps with UV transforms. Assign material=@alias on objects or wall-image declarations; WRIGHT backdrops reference the same materialId. Shared edits affect all users; Make unique creates a copy. The common Material inspector writes this source and participates in undo/save. Existing projects migrate at API startup with backups and unchanged geometry. Material definitions never execute shader code or alter physics.

\material[name=example];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\wall-image

Presentation-only wall bitmap with immutable image pin, wall-local position and dimensions. It never receives physics or collision.

\wall-image[name=example,image="00000009-1111-4111-8111-111111111111",wall=@desk,position=(0m,0m),size=(1m,1m),uri="example",mediaType="example",sha256="example",bytes=1];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\label

Presentation-only child of an existing object. PDF, HTML, audio and video actions pin immutable resources; RIDLEY emits qway.interaction.activate to a typed target. Labels never enter layout or physics.

\label[name=example,object=@desk,text="example",action=none];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\pose

At least one meaningful transform component should be supplied. Positions use metres after unit conversion; scale is dimensionless; quaternion is [x,y,z,w]. yaw is an angle about Y. Do not supply conflicting yaw/quaternion intent. Authored components constrain placement.

\pose[object=@desk];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\presentation

Serialized camera/environment JSON is validated; this is not executable JavaScript. Normally maintained by the visual editor. Omitted fields keep policy defaults.

\presentation[];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\on

Place subject on a target surface. offset is surface-local 2D; gap defaults to contact. A measured feature reference is preferable to an ambiguous whole object. Evaluator checks actual support, not just bounds height.

\on[subject=@desk,target=@table];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\inside

Subject occupies a verified interior/cavity of target. margin reserves clearance. Arbitrary concave interiors may be unsupported; naming something a container is not evidence.

\inside[subject=@desk,target=@table];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\contains

Inverse inside relation. The contained target must fit subject’s independently supported cavity evidence.

\contains[subject=@desk,target=@table];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\supports

Inverse convenience form: subject supports target. Lowered to target on subject. Same independent support verification and offsets apply.

\supports[subject=@desk,target=@table];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\beside

side defaults to right, gap to 0.1m and along to 0m. Side is target-local, not screen-left. Evaluator uses resolved transformed geometry.

\beside[subject=@desk,target=@table];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\against

Requests contact/proximity against supported target geometry. It does not deform either mesh.

\against[subject=@desk,target=@table];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\facing

Horizontal facing toward target; yawOffset modifies requested direction. Undefined coincident directions cannot be proved.

\facing[subject=@desk,target=@table];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\attached-to

Initial relative offset, not a Rapier joint or perpetual parenting constraint. Runtime maintain behavior is not implied.

\attached-to[subject=@desk,target=@table];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\keep-clear

Reserve subject-local box size and optional offset. Independent occupancy checks may report conflicts.

\keep-clear[subject=@desk,size=(1m,1m,1m)];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\reachable-from

Requires explicit actor proxy and mode. manipulation, navigation and line-of-sight are different tests. Unsupported geometry stays unsupported.

\reachable-from[subject=@desk,actor=@desk,mode=manipulation];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\physics

Separate motion, collision and controller fields. Inferred defaults follow precedence; override only intended components. Positive mass, bounded friction/restitution and safe collider compatibility are validated. Dynamic triangle mesh is not a universal fallback.

\physics[object=@desk];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\interaction

Capabilities are a tuple drawn from grab, open, close, toggle, walk and animate, not arbitrary code callbacks. enabled defaults true; cooldown is time. Declaring a capability does not implement articulation or other missing runtime support; geometric/runtime support still determines availability.

\interaction[object=@desk,capabilities=(grab)];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\animation

clip is a zero-based existing manifest clip index. Defaults: in-place, speed 1, loop true, offset 0. Root animation and physics cannot compete. Articulated mode needs represented safe structure.

\animation[object=@desk,clip=0];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

\actor

Explicit geometric actor envelope and eye/hand offsets in metres; reach is manipulation range. It does not create a humanoid rig or plan arbitrary routes.

\actor[object=@desk,size=(1m,1m,1m),eye=(1m,1m,1m),hand=(1m,1m,1m),reach=1m];

This signature fragment needs the enclosing scene, existing declarations and pinned resources. It is not a self-contained asset catalog. Full examples below supply those dependencies.

Executable programs

minimal

\scene[name=study,id="00000001-1111-4111-8111-111111111111",seed=12]{
\object[name=desk,id="00000002-1111-4111-8111-111111111111",asset="00000003-1111-4111-8111-111111111111",manifest="00000004-1111-4111-8111-111111111111"];
}

Download source. Uses the generated desk fixture and matching compile input; replace dependencies through the editor for your own assets.

intermediate

\scene[name=study,id="00000001-1111-4111-8111-111111111111",seed=12]{
\object[name=desk,id="00000002-1111-4111-8111-111111111111",asset="00000003-1111-4111-8111-111111111111",manifest="00000004-1111-4111-8111-111111111111"];
\object[name=table,id="00000005-1111-4111-8111-111111111111",asset="00000003-1111-4111-8111-111111111111",manifest="00000004-1111-4111-8111-111111111111"];
\beside[subject=@table,target=@desk,side=right,gap=0.5m];
}

Download source. Uses the generated desk fixture and matching compile input; replace dependencies through the editor for your own assets.

complete

\scene[name=study,id="00000001-1111-4111-8111-111111111111",seed=12]{
\room[name=office,id="00000006-1111-4111-8111-111111111111",size=(6m,3m,5m)]{
\object[name=desk,id="00000002-1111-4111-8111-111111111111",asset="00000003-1111-4111-8111-111111111111",manifest="00000004-1111-4111-8111-111111111111",height=0.75m,heightReference=whole-bounds,role=furniture-desk];
\object[name=table,id="00000005-1111-4111-8111-111111111111",asset="00000003-1111-4111-8111-111111111111",manifest="00000004-1111-4111-8111-111111111111"];
\beside[subject=@table,target=@desk,side=right,gap=0.5m];
\facing[subject=@desk,target=@table,strength=soft];
}
}

Download source. Uses the generated desk fixture and matching compile input; replace dependencies through the editor for your own assets.

Deliberately invalid examples

\scene[name=bad,id="00000001-1111-4111-8111-111111111111"]{
  \pose[object=@missing,position=(1kg,0m,0m)];
  \unknown[];
}

Expect unresolved reference, wrong unit dimension and unknown-command diagnostics. A missing declaration ID/binding produces MISSING_IDENTITY. Duplicate aliases/arguments are errors. The executable documentation check asserts negative examples fail; previous accepted scene remains visible in Studio.