RIDLEY language reference

Syntax and timing

RIDLEY uses the same bounded lexer/CST notation and comments as QWAY but different command signatures and scope. Object references resolve against the accepted world; cinematic/cue/state names are not new scene objects. The source hash and alias bindings pin meaning. Rebinding an existing alias to a different UUID is rejected.

Leaf cinematic cues require id; at is optional absolute time in the sequence. Sequential blocks advance the cursor; sync starts siblings together. duration defaults to 3s for visible nontext cues, max(1,text length/15)s for text, and 0 for emit/return/music/sfx. Visible cues require positive duration; audio commands are instantaneous. Overlapping camera cues or actions for the same actor are rejected.

Command signatures

Command / scope	Arguments	Semantics / defaults
cinematic / root	id; block	Named sequence
voice / root	actor; voice,language,instructions,speed	Actor voice compiled at WorldPack export. Defaults fable, it-IT, speed=1. Cached across exports.
scene / cinematic	no arguments; block	Sequential grouping
sync / cinematic	no arguments; block	Parallel grouping
shot / cinematic	id; at,duration; type; subject OR subjects; shoulder,movement,amount,transition	movement=static; amount=.2 in [-1,1]; transition=cut\|smooth. two-shot needs 2 subjects; OTS needs a distinct shoulder; establishing can omit subject.
dialogue / cinematic	id; at,duration; actor,text; voice,language,instructions,speed	Existing actor; nonempty text ≤4000 characters
subtitle, narration / cinematic	id; at,duration; text	Subtitles display text; narration can opt into generated speech with voice/language/instructions/speed.
action / cinematic	id; at,duration; actor,action; target,clip,persistence	look-at / move-to require distinct target; animate requires actual clip; persistence=temporary\|runtime, default temporary
wait / cinematic	id; at,duration	Advances time
emit / cinematic	id; at,duration; event,target	Instantaneous named event; optional target
return / cinematic	id; at,duration	Return from sequence; instantaneous
trigger / root	id,event,subject,cinematic; target,distance,once	near needs target; once defaults true; supported event enum is checked
audio / root	name,asset,sha256	Pins existing audio resource
music / cinematic or state	track; action,from,volume,fade,loop; cue timing/id only in cinematic	play\|stop\|crossfade; default play, volume1, fade0, looptrue; crossfade needs from
sfx / cinematic	id; at,duration; track,spatial,volume	One-shot sound, optional spatial object
persona / root	name,profile,sha256	Pins existing persona revision
npc / root	actor,persona	Binds actor to persona
experience / root	initial; block	At most one experience
state / experience	id; mode,cinematic; block	mode=interactive by default; cinematic requires sequence
control / state	actor; owner	owner=user\|ridley, default user
camera / state	mode,owner	third-person default; first-person/overhead/overview; owner=user\|ridley
follow / state	actor,target; distance,delay,speed	1.2m distance,1.5s delay,1.2 speed scalar m/s; cycles rejected
conversation / state	actor,persona	Requires bound persona and conversation state
on / experience	id,from,to,event; subject,target,once	Filters shared events; once defaults false. Not the QWAY support relation.
cut, transition / cinematic	recognized but rejected	EXPLICIT_TRANSITION_REQUIRED: use transition on destination shot

Shot and movement enums

Shot types: extreme-closeup, closeup, medium-closeup, medium, american, full, long, extreme-long, two-shot, over-the-shoulder, pov, establishing, insert. Movements: static, pan, tilt, dolly, truck, pedestal, orbit, zoom, follow, crane. These are templates evaluated against actual scene geometry, not promises of collision-free camera travel.

Tested programs

minimal

QWAY / RIDLEY

\cinematic[id=intro]{\shot[id=wide,type=establishing,duration=2s];}

Download. Compile against the matching QWAY example with desk/table aliases. The minimal establishing shot needs no actor alias.

intermediate

QWAY / RIDLEY

\cinematic[id=intro]{
  \sync[]{
    \shot[id=desk_view,type=medium,subject=@desk,duration=3s];
    \subtitle[id=welcome,text="Welcome to the workshop.",duration=3s];
  }
  \shot[id=detail,type=insert,subject=@desk,duration=2s,transition=smooth];
}

Download. Compile against the matching QWAY example with desk/table aliases. The minimal establishing shot needs no actor alias.

complete

QWAY / RIDLEY

\cinematic[id=intro]{
  \scene[]{
    \shot[id=wide,type=establishing,duration=2s];
    \sync[]{
      \shot[id=pair,type=two-shot,subjects=(@desk,@table),duration=3s];
      \narration[id=line,text="Two work surfaces, one shared project.",duration=3s];
    }
    \emit[id=ready,event="workshop.ready"];
    \return[id=done];
  }
}
\experience[initial=explore]{
  \state[id=explore]{\camera[mode=overview];}
  \state[id=tour,mode=cinematic,cinematic=intro]{}
  \on[id=start,from=explore,to=tour,event="workshop.start"];
  \on[id=end,from=tour,to=explore,event="ridley.complete"];
}

Download. Compile against the matching QWAY example with desk/table aliases. The minimal establishing shot needs no actor alias.

Errors and unsupported behavior

Unknown commands/arguments, invalid units, missing actors/clips/resources, alias rebound, conflicting cues, unsupported actions and invalid state graphs reject compilation. Example below is deliberately invalid:

QWAY / RIDLEY

\cinematic[id=bad]{\shot[id=oops,type=closeup,subject=@not_in_world];}

Expected UNKNOWN_ALIAS. Use transition=cut|smooth on a destination shot; standalone cut/transition commands are deliberately diagnosed. No arbitrary scripting, generated animation, TTS or automatic persistent world mutation is available.