The Jabbertoon block language
Every move, scene and cartoon on Jabbertoon is a program in this language: JSON that people see as blocks, as text or as a timeline. This is the public edition of the specification. The JavaScript engine in the browser is the reference implementation, and a Python port follows it to within 1e-9 on every recorded case.
Which hats fire today
A script starts with a hat, the block that says when it runs. These hats run today: start (when the move starts), talk-start and talk-end (when the character starts and stops speaking a line), and scene (when a scene of a cartoon starts). In a game, key and click hats also fire: a key the player presses, a click on the character. Four more hats, touch, beat, loud and every, are part of the language: programs that use them load, validate and save without losing anything, but nothing makes them fire yet, so a script under one of them never runs. They are named future features.
What game engines call this
The language's ideas have names in game engines' animation tools, which this reference does not use. Programs that run together and add up (the pose model, below) are what an additive layer in Unity's Animator and Godot's AnimationNodeAdd2 do with clips, a kind of blend. A block that names one part, leaving the others free, works like a mask (Unity's Avatar Mask, a filter on a Godot AnimationTree node). The skeleton's reach is two-bone IK (Unity's IK Manager 2D, Godot's SkeletonModification2DTwoBoneIK). A move written by the roles of parts plays on every body, which engines call retargeting. And there is no state machine (Unity's Animator Controller, Godot's AnimationNodeStateMachine): hats start scripts on events, and the hats that do not fire yet are named above.
The specification
0. Non-negotiables
- Exact time. A timed block that starts at t and lasts d ends at exactly t+d, never at "the next frame". The runtime is a discrete-event scheduler:
stepTo(T)processes every block event with time ≤ T in time order, then the pose is read at T. So a pose depends only on T, not on how the clock was stepped (24 fps, sample jumps, one big jump all agree bit-for-bit; tested). - The only step-dependent things are polls:
while/untilconditions are checked once per step, and a loop iteration that took zero time waits for the next step (no infinite loops). Behaviours meant to be exact use timed blocks (for,wait until), not polls. - Deterministic. No wall clock.
randomis a seeded PRNG per runtime (mulberry32). - Two clocks.
timeline(video: the renderer callsstepTo(frame/fps)) andlive(play: the page steps by the real time elapsed,step(dt), and sends input events). Every block works under both; no block can read the step size (§5: there is nodtname). - Units. Positions in 1080p pixels (renderers scale by min(W,H)/1080). Angles in degrees, positive = counter-clockwise as the viewer sees it (the original studio's PIL convention; canvas renderers draw −angle). Scales are factors. Time in seconds. A scene's placement of a character is in stage fractions (x of the width, y and h of the height; §7.2); behaviour offsets add to it.
1. Program JSON
program := { "v": 1, "kind": "behaviour"|"scene"|"cartoon", "name"?, "params"?: {name: value},
"vars"?: {name: number}, "scripts": [script] } // scene/cartoon add "cast", "places" (§7.1)
script := { "hat"?: hat, "body": [block] } // no hat = { "on": "start" }
hat := {"on":"start"} | {"on":"talk-start"} | {"on":"talk-end"} | {"on":"key","key"?} | {"on":"click"}
| {"on":"scene","name"?,"place"?,"mood"?,"at"?} | {"on":"beat"} | {"on":"loud"} | {"on":"every"} | {"on":"touch"}
block := { "op": string, ...args } // "note" and "id" are allowed on any block
value := number | "=expression" // see §5params are defaults; the caller's params override them. Defaults are evaluated at start, in declaration order, and may use dur and earlier params (e.g. "t_in": "=min(max(dur*0.6, 0.5), 3.0)"). A variable starts at a finite number: a formula, text, true, null, a list or an object is a validation error (vars.x: a variable starts at a number, not "=1"); setVar gives a variable any value as the script runs. vars that is not an object adds no variables (null, 5, []); a list or a string adds its entries by index, which are checked the same way (a string's entries are its UTF-16 code units, as Object.entries gives them: an emoji is two, vars.0 and vars.1).
2. The pose model
A character runs behaviour instances (startBehaviour(char, program, {dur, params})). Each instance owns a layer with two kinds of state:
- Base channels — absolute values written by
setandramp. One value per channel per instance; the last writer wins; a ramp starts from the channel's current value and then holds the target. - Motions —
wave,hop,gait,drive. Continuous functions of time. A motion block does not wait: it starts the motion and the script continues. A motion lives until its scope ends.
Scopes. The script's top level is the instance's root scope: motions started there live until the instance is stopped (even after the script's last block). for and while open a scope; when the for's time is up or the while exits, the motions started inside stop. together branches start motions in the enclosing scope. if, repeat and forever bodies do not open scopes.
Start-or-keep. Running a motion block whose motion is already running in the same scope does nothing (it does not restart or stack). forever { bob; wait 1 } bobs once, continuously.
Combining. The character's pose = rest ⊕ every instance's base ⊕ every motion, where dx dy rot and part channels add, sx sy multiply, mouth blink take the max, mood takes the latest write. Rest is 0 (1 for sx sy). The skeleton adds two pose keys that are not channels (§8): reach (per hand or foot, the latest reach/release wins) and view (the latest view wins, like mood).
Channels. dx dy rot sx sy mouth blink mood, and part channels part:<role>[:<side>][#<index>] (angle, deg) / lift:<role>[:<side>][#<index>] (px, +up). side is −1 left / 1 right; the index's meaning depends on the role: on legs (leg shin foot) it numbers the legs back to front (quadruped: #0 back-left, #1 back-right, #2 front-left, #3 front-right); on a chain (a tail, the spine, ears, hair; §8.2) it numbers the segments from the root (tail#0 is next to the body; the skeleton's blocks write segment 0 on the plain channel, part:tail, §8.2). A drawn node with role R, side S, index I reads the sum of R, R:S, R#I, R:S#I, so "both arms" and "left arm" combine — except a chain follower (segment i ≥ 1 of a chain the template draws), which reads only R#i and R:S#i (§8.1; docs/SHAPES.md §3.2). Roles: head neck torso hips arm forearm hand leg shin foot tail ear wing fin claw snout nose hair hat eye brow (engine/parts.js ROLES, the same list as the roles ui/shapes.js draws; no template draws a neck yet, so a block that moves the neck is a warning, v0.4.1, §8.6). Validation: a channel that does not have this form (part:Arm, lift:arm:2, part:__proto__) is an error; a well-formed part channel of any other lower-case role (part:elbow) is a channel like the others (it sums, rt.pose reports it), but nothing draws it, so it is a warning.
Renderer conventions (part synonyms). The engine computes channels; it does not know which body a character has. So that every character answers the same moves, the shape renderer (ui/shapes.js applyPose) also lets some drawn parts read other roles' channels, added to their own:
- a wing reads
armplus half offorearmat its root, so "lift arms" flaps the wings and "wave" waves a wing; - a hand reads
claw(the original crab moves wiggle a person's hands); - on a four-legged body the front legs (
leg#2, #3) read 40 % ofarmand their shins (shin#2, #3) 40 % offorearm; in profile the left side's angle is negated (a profile body has no outward side, so "lift arms" raises both front legs forward: a dog "waves" a front paw); seen head on it is used as it is (outward, like a person's arm); - (v0.4.1) the part channels name the limb ends a reach names (§8.4):
part:hand(hand:S) moves a four-legged body's front paws (which read the foot channels only by their leg number,part:foot#2), a bird's wing tip (the outer half of its wing) and a monster's claw;part:footmoves a four-legged body's back paws; - (v0.4.1) a part a template draws with fewer segments than a chain block bends (a one-piece torso, tail or ear) shows the whole bend: its last drawn segment also reads the index channels of the segments it does not draw. These are drawing rules, not engine semantics: the pose (
rt.pose) never contains them, and another renderer may choose its own (the Python studio adapter does not apply them).
3. Primitive blocks (the runtime executes only these)
Timing args: over (seconds; 0 = instant), ease ∈ linear | smooth (smoothstep, default) | in (u²) | out (sin(uπ/2)) | inout (=smooth) | snappy (overshoot).
| op | args | waits? | meaning |
|---|---|---|---|
set | to: {ch: value} | no | base channels jump to values |
ramp | to and/or by: {ch: value}, over, ease | over s | glide base channels; a glide cut off by a scope end or a stop freezes where it is |
wait | s or until (behaviour time) | yes | |
for | s or until, body | until the time is up | runs body; aborts it at the end; ends its scope |
while | cond, body | polls | scope; condition checked each iteration/step |
until | cond | polls | wait until cond |
repeat | n, body | — | |
forever | body | — | |
together | branches: [[block]] | until all end | branches run as parallel threads |
if | cond, body, else | — | |
stop / stopAll | — | — | end this script / every script of this instance |
wave | ch (or list), shape, one of w/hz/every, phase, amp, offset, pow, decay, clip, sync | no | value = offset + amp·shape(w·t + phase) |
hop | amp, hz or every, sync | no | the studio hop curve on dy, sx, sy |
gait | every, stride, give, bend, thighScale, shinScale, armSwing, bob: [base, amp] | null, roll, view, sync | no | walk cycle on every leg of the body plan; with view, drawn in that view while it runs (§8.5) |
drive | ch (or list), value | no | channel follows a live expression |
mood | mood | no | |
setVar / changeVar | var, value / by | no | instance variables (score, lives…) |
chain | ch, shape, amp, one of w/hz/every, phase, decay, lag, falloff, segments, sync | no | a wave travelling down ch, ch#1 … ch#(n−1) (§8.2) |
follow | ch (or list), source, gain, hz, damping | no | ch lags source like a damped spring (§8.3) |
reach / release | part, to: {x, y} or at (reach), over, ease | over s | a hand's or foot's reach weight glides to 1 / 0 (§8.4) |
view | to | no | the drawing to show: front, side, back (§8.5) |
wave. shape ∈ sin cos abssin possin dampsin square saw tri. w is rad/s; hz gives w = 2π·hz; every gives w = 2π/every. offset defaults to the channel's rest (0, or 1 for sx/sy), so on a scale channel the wave value is the factor. pow raises the shaped value; dampsin multiplies by e^(−decay·t); clip: "pos"|"neg" clamps after shaping. amp and offset are live (evaluated every frame — e.g. "amp": "=-20*loud" makes the bob follow the voice); w, phase, pow, decay are fixed when the motion starts.
sync. A motion's clock t is local (time since the motion started; default; no pop at start) or start (time since the behaviour started; keeps phase across phases of a behaviour).
gait. ph = (t mod every)/every. Each leg gets walkleg(ph + offset) → (thigh, shin) where stance (p < ½) is thigh = stride − 2·stride·s, shin = give·sin(sπ), and swing is thigh = −stride + 2·stride·s, shin = bend·sin(sπ). Two legs: offsets 0, ½ on part:leg:∓1/part:shin:∓1, arms counter-swing part:arm:S = −thigh_S·armSwing. Four legs: offsets [0, ½, ½, 0] on part:leg#i. Six: tripod. bob adds dy = base − amp·|sin(2π·ph)|; roll adds rot = sin(2π·ph)·roll. view (v0.4.2; front side back, none by default) is the view the body walks in while the gait runs (§8.5); the channels are the same with or without it.
hop. cyc = (t·hz) mod 1. cyc < 0.12: crouch (dy = 6k, sx = 1+0.08k, sy = 1−0.08k, k = cyc/0.12). Else c = (cyc−0.12)/0.88, h = sin(cπ): dy = −amp·h, sx = 1−0.10h, sy = 1+0.12h; landing (c > 0.86): sx = 1+0.11k, sy = 1−0.11k with k = (c−0.86)/0.14. hopair(cyc) in expressions gives h (0 on the ground).
4. Friendly blocks (desugared before running)
move {dx, dy, over} → ramp by · moveTo {x, y, over} → ramp to dx/dy · turn/turnTo {deg} → rot · scaleTo {s | sx, sy} (each a number or =formula) · squash {k} → sx 1+k, sy 1−k · setPart/turnPart {part, deg} · liftPart {part, px} · bob {amp} → wave dy abssin −amp · sway {deg} → wave rot · wobble {px} → wave dx · shake {px, deg} → wave dx (and rot), 6 times a second unless it gives w, hz or every (the wiggles default to every 1 s) · swingPart {part, deg} · window {from, to, body} → wait until from + for until to (negative times count back from dur) · the skeleton's swish flop bend bow letFollow turnView and reach {hold} (§8). Part names accept channels (part:arm:-1), legacy names (arm_l, thigh_r) and words ("left arm", "arms", "tail", "front right leg"; v0.4.1: "front paws" / "front left paw" / "front feet" are part:hand(:S), the front paws being a four-legged body's hands, "back paws" / "hind paws" part:foot; a paw named without front or back is a front paw: "paws" is part:hand, "left paw" part:hand:-1, on two legs the hands). "front legs" / "back legs" without a side is the pair's left leg's channel (part:leg#2, part:leg#0); a friendly block moves both legs of the pair (part:leg:-1#2 and part:leg:1#3, outward as for any pair; a lift lift:leg#2 and lift:leg#3; v0.4.1, before which "swing front legs" moved the front-left leg alone). A friendly block names a part, so a raw channel there must be well-formed and of a role in the vocabulary (§2): part:elbow or part:constructor is an unknown part (an error), not the warning a primitive block gets. Friendly part angles mean "lift outward" on either side: a left-side part's raw angle is negated, and a side-less paired part ("arms", "ears", "legs") becomes both sides mirrored, so setPart arms 80 raises both arms and swingPart arms 30 flaps them together. Unpaired parts (head, tail, neck) pass through raw. Primitive blocks always use raw channel angles (the skeleton's reach/release name a hand or foot like a friendly block, and a reach point's x is outward, §8.4).
5. Expressions
A value is a number or a string starting with =. Grammar, low → high precedence: || · && · == != < <= > >= · + - · * / % · unary - + ! · ^ (right-assoc) · atom (number | name | name(args) | (expr)). % is floored modulo (Python semantics). Comparisons give 1/0. Names: tau (behaviour time), local (motion time), t (runtime time), dur, loud (0..1 voice level), talking (0/1), random, pi, e, then params, then vars, then the page's globals (rt.vars). Functions: sin cos tan abs exp sqrt floor ceil round(=floor(x+½)) sign pow min max mod clamp smoothstep hopair lerp step. Validation knows exactly these built-in names (validate.js BUILTIN_NAMES); any other name must be a param, a var or a page global. Validation cannot see page globals (the page sets rt.vars at run time), so it warns about any name that is not a built-in, a param or a var; when the expression runs, a name that none of them holds (page globals included) is an error.
- There is no
dt. Under exact time (§0) a value never depends on how the clock was stepped, and a step size is exactly that, so the runtime does not provide it (v0.3 validation listed it, and such a program failed when it ran). Usetau/localand timed blocks; a param or var may be calleddt. - Names are data. Function names, ops, params, vars, page globals, part words, channel keys, place names, cast ids and hat names are looked up as own properties (
hasOwnProperty, null-prototype objects for params and vars), soconstructor,toString,__proto__are ordinary names where a name is free (a param, a var, a place, a cast id) and unknown where the vocabulary is fixed (no function, op or part has those names). This is also how the Python port behaves.
6. Interpreter contract (JS engine/runtime.js; Python py/c4c_runtime/)
The Python port (py/c4c_runtime/, docs/PYTHON_PORT.md) is the same contract in snake_case, behaviours, scenes and cartoons (§7) alike (create_runtime, add_character, start_behaviour, step_to, pose, start_cartoon, frame, validate, …), held to the JS engine by fixtures/parity_js.json (poses, frames, timelines, warnings and errors within 1e-9).
rt = createRuntime({ clock: "timeline"|"live", seed,
speech?: (text, {who, voice, mood, speed, pitch}) => seconds, // §7.4
packs?: (id, version) => program | pack, // §7.5, synchronous
fps = 24, aspect = 16/9, maxDuration = 3600 }) // §7.2, §7.7
rt.addCharacter(id, { legs: 2 })
inst = rt.startBehaviour(id, program, { dur, params }) // runs start-hat scripts at rt.t
rt.stopBehaviour(inst)
rt.setInputs(id, { loud, talking })
rt.emit(event, { charId, key, name }) // talk-start/-end set talking; hats restart
rt.stepTo(T) rt.step(dt) // time only moves forward
rt.pose(id) → { dx, dy, sx, sy, rot, parts: {"arm:-1": deg, …}, lift: {…}, mouth, blink, mood,
reach: {"hand:1": {x, y, w} | {spot, w} | {spot, dx, dy, w}, …}, view: "front" | "side" | "back" | null } // §8
rt.startCartoon(program | {cast, places, program}, { params }) → { duration, timeline } // §7; one at a time
rt.frame() → { t, scene, place, background, grade, caption,
characters: { id: { x, y, h, facing, visible, pose, talking } }, order: [id] } // §7.8
rt.timeline rt.duration rt.warnings // §7.7
validate(program) → { ok, errors[], warnings[] } // unknown ops/channels/parts = errors; unknown names, roles nothing draws = warningsThese are all the options: anything else passed to createRuntime is ignored (the plan's twin runtime, §7.7, is marked internally, not by an option). startCartoon either returns with the cartoon running or throws (an invalid program, a scene expression the plan cannot evaluate, a behaviour the cartoon starts failing at once); after a throw no cartoon is running: the runtime has the cartoon it had before (none, or the last one that ended), whatever the failed cartoon had started is stopped, and the next startCartoon is accepted. When the plan failed nothing else changed either: no cast was added, nothing was scheduled, and the speech answers and warnings the plan collected (it asks this runtime's speech provider, §7.4) are dropped with it. When the run failed once begun, the cast it added stays, and so do the plan's warnings and speech answers. engine/index.js poseAt(program, {dur, params, legs, inputs}, tau): one behaviour's pose at tau, the same bits as a fresh runtime started at 0 and stepped once to tau (so a renderer can scrub). It keeps the runtimes of recent calls warm (per program object and settings, a few per program) and steps one on when the next call asks for the same or a later time, so playing forward costs the new stretch of time, not the whole history (a follow-through ticks 240 times a second from its start, §8.3). It reuses a runtime only while that gives the same bits as from scratch: no thread has yielded to a step (a poll, §0; rt.polled), no pose has drawn random, and the inputs are this call's or no block or tick has read them yet (rt.inputsRead; a pose reading them does not count). Otherwise, for an earlier time, or for settings that cannot be compared by value, it starts from scratch. A program object must not change once it has run (the engine prepares each one once). The Python port's pose_at keeps runtimes warm in the same way (the same answers; docs/PYTHON_PORT.md). engine/parts.js: partChannel(name), partAngle(pose, role, side, index), legacyPose(pose). engine/director.js: cartoonProgram(content), scenesOf(program), estimateSpeech(text, {speed}).
7. Scenes and cartoons (built in v0.3: engine/director.js, tests/scene.test.mjs)
A scene or a cartoon is a program like a behaviour, run by the same scheduler (§0 holds: exact time, deterministic, poll-only step dependence). Its scripts are threads of a director instance that is never drawn. The director owns the stage (place, grade, caption), each character's placement, the lines being spoken, and the behaviour instances a scene starts with does.
7.1 Programs and the one design: scene hats
scene := { "v":1, "kind":"scene", "name"?, "cast"?: {id: entry}, "places"?: {name: place}, "params"?, "vars"?, "scripts" }
cartoon := { "v":1, "kind":"cartoon", "name"?, "cast": {id: entry}, "places"?: {name: place}, "params"?, "vars"?, "scripts" }
entry := "role description" | { "name"?, "legs"?: 2, "at"?: {x, y, h, facing}, "voice"?, "pack"?, "look"?, "note"? }
pack := "c4c:char:sunny" | { "id": "c4c:char:sunny", "version"?: "1.0.0" } // a character pack reference
place := "background name" | { "background"?, "grade"? }A cast entry is an inline descriptor (name legs at voice look, what the example cartoon uses) or, once character packs exist, a pack reference (pack, optionally with name/at/voice to override the pack's own); both forms are validated by validate.js (unknown fields are warnings, a pack must be a pack id or {id, version}). docs/PACK_FORMAT.md describes the same two forms.
- A cartoon is an ordered list of scenes, written as scene hats. Every cartoon script starts with
{"on":"scene","name":…}; scripts with the same name are one scene and run in parallel (like two actors' parts); scenes run in the order their names first appear. A hat may carryplace(the scene's place, as if it began withcut {place}),mood(its grade) andat(§7.6). Two scripts of one scene must not disagree about these (validation error). - A scene program (kind
scene, a scene template pack) is exactly one scene: its scripts have no hat or a scene hat; the scene's name is the first hat name, else the program'sname. Itscastusually lists roles ({"A": "any", "B": "any"}) that the page fills withaddCharacterfirst. castids become characters onstartCartoon(addCharacter(id, {legs}), existing characters are kept).name,voice(the default voice of the character's lines),pack(a character pack reference) andlook(the character's design, for the renderer:{template, style, shape, colors: {body, skin, acc}, stretch, options, facing},docs/PACK_FORMAT.md, whatui/shapes.jsmakeCharactertakes as it is) are data the runtime passes through; validation checks the look's form (not an object is an error, anything inside it a renderer cannot use is a warning). A cartoon pack's content is{cast?, places?, program}(docs/PACK_FORMAT.md:programrequired, nothing else allowed);startCartoonaccepts it directly and merges the outer cast and places into the program (cartoonProgram).- A scene's scripts may use the control blocks —
wait for while until repeat forever together if stop stopAll setVar changeVar window— and the scene blocks below. Blocks that move a character (set ramp wave hop gait driveand the friendly moves) are errors in a scene: a scene saysdoes {who, behaviour}. Scene blocks are errors in a behaviour. stopends the script (or thetogetherbranch) it is in.stopAllends every script of the scene, wherever it runs (also inside a branch), so the scene ends then — or holds its stage until a pinned next scene (§7.6). What they cut off ends as in §7.2 and §7.4, and is reported (§7.6).- In scene expressions:
tauis time since the scene started (sowait {until: 2}means 2 s into the scene),tis runtime time,duris the scene's length when the next scene is pinned withat(sowindow {from: -1}works) and Infinity otherwise,randomis the director's own seeded stream (separate from the behaviours', so the plan in §7.7 matches the run), params and vars as usual.loud/talkingbelong to characters; a scene reads 0 (warning). - Held scripts. A scene script that can only wake when its scene ends — a
windowwithoutto,wait {until: "=dur"}, any wait orforuntil Infinity — is held: it does not keep the scene going, and it ends with the scene (itsforscope too, so what it started stops then). Sowindow {from: 1, body}means "from 1 s to the end of the scene" whether or not the end is pinned; alone in its scene, the scene ends when the window's body has run. Counting back from an end that is not pinned (window {from: -1},"=dur - 1") never arrives: validation warns, and the blocks never reached are reported inrt.warnings(§7.6).window {from, to}takes times in seconds (totoo). - Screenplay conversion. The structure is a screenplay already: a scene hat is a scene heading,
sayis a line with a parenthetical,does/enter/exitare action lines,cutis a transition, parallel scripts are simultaneous action.toTextprints it (§7.9).
7.2 Placement (owned by the scene)
Each character has a placement {x, y, h, facing, visible}, separate from its behaviours; behaviours only offset it (pose dx dy etc. are added on top by the renderer).
- Units:
xis a fraction of the stage width (0 = left edge, 1 = right edge) at the character's root;yis the feet line as a fraction of the stage height (0 = top, 1 = bottom; the ground is 0.92);his the character's height as a fraction of the stage height (default 0.5);facingis the way the character faces on screen: +1 right, −1 left (a glide through 0 turns it round). Pose offsets stay in 1080p pixels, scaled by min(W,H)/1080. These are the studio page's own units (its scene table'sax,ah, baseline 0.92·H). - Facing, defined as a product. A character's art has its own facing
A: the way the art faces as designed. The shape templates are drawn facing right (dog, cat) or facing the front (person, kid, bird, monster),A= +1; the studio's "face the other way" switch makesA= −1, and so does a bitmap drawn facing left. The renderer mirrors the designed art byfacing × A(itssx, and the pose'sdxandrotwith it:ui/shapes.jsdrawCharactermirrors "the whole performance"), so on screen the character facesfacingwhichever way its art was designed: a design turned to face left still enters from the left facing right, never walking backwards. Inui/shapes.jsterms, whosedrawCharacter({facing})mirrors the template itself, a cartoon renderer passes the placement'sfacingfor a shape character (the design's own switch is overridden by the scene), and a page without a cartoon passes the design's own facing, as the studio does today.Ais the renderer's to know (from the character design or a cast entry'slook); the engine only carries the placement'sfacing. - Validation of placement values (numbers in
place,enter,exitand a cast entry'sat; a"=formula"is known only when it runs):facingmust be 1 or −1 (error),hmust be more than 0 (error), ayoutside 0..1 (the feet out of frame) is a warning. - Defaults: characters are spread in cast order, x = (i+1)/(n+1), y = 0.92, h = 0.5, facing +1. Nobody is visible until placed: by the cast entry's
at(visible from the start),place, orenter. Afterexitfinishes, the character is not visible. - Persistence: placement persists across behaviours,
doesreplacements and scenes, until a scene block changes it. - The spot on stage survives an exit.
exitremembers where the character stood when it began (on the axis it leaves by: x for left/right, y for top/bottom).enterwithoutx/ycomes back to that spot, per axis, else to its current placement; so exit right → enter from the left lands where it stood, and exit through the bottom → enter from a side lands with its feet on the ground.placewithx/yandenter {x, y}set a new spot. - Glides (
place … over,enter,exit) use the same segments and eases asramp: the script waits exactlyoverseconds; a glide cut off by a scope end (for), astop, or its scene ending freezes where it is (and an interruptedexitleaves the character visible); cut off at the very instant it lands (aforor a pinned scene ending then), it has landed (anexithides). Two glides of one value: the last writer wins (anexitwhose value was taken over by a laterplace/enterdoes not hide the character when it ends). - Off stage for
enter/exitwithaspect = W/H(createRuntime option, default 16/9): left x = −(0.02 + h/aspect), right x = 1 + 0.02 + h/aspect, top y = −0.02, bottom y = 1 + h + 0.02 — far enough for a character as wide as it is tall.
7.3 Scene blocks
| op | args | waits? | meaning |
|---|---|---|---|
say | who, text, voice?, mood?, speed?, pitch? | the line's length | §7.4 |
does | who, behaviour, for?, params?, also? | no | §7.5 |
caption | text, for? | no | shows text for for s (or until its scope/scene ends) |
cut | place?, mood? (at least one) | no | changes the place and/or the grade (§7.6) |
place | who, x?, y?, h?, facing?, over=0, ease=smooth | over | sets or glides the placement; makes the character visible |
enter | who, from=left|right|top|bottom, over=1, ease=linear, x?, y?, h?, facing? | over | jumps off stage on that side, glides to the x/y given, else its spot from before its last exit, else its placement (§7.2; a given h is set at once); facing defaults to the way it moves (from left: +1, from right: −1) |
exit | who, to=right|left|top|bottom, over=1, ease=linear, facing? | over | glides off stage on that side (facing the way it moves), then is not visible |
mood | who, mood | no | the character's face mood (in a behaviour, mood {mood} is the instance's own) |
7.4 say
- Its length comes from
createRuntime({ speech: (text, opts) => seconds }),opts = {who, voice, mood, speed, pitch}(only the given ones;voicedefaults to the cast entry'svoice). Without a provider, or when it throws or returns something that is not a finite number ≥ 0 (a Promise included; warning): 0.06 s per character + 0.25 s, at least 0.6 s, divided byspeed. The provider must be synchronous and pure (the same answer for the same line; measure the audio beforestartCartoon); the runtime asks once per distinct line and reuses the answer. - The block waits exactly that long. From its start to its end the speaker's
talkinginput is 1;talk-starthats fire at the start andtalk-endhats at the end, at the exact times (overlapping lines by one speaker: one talk-start at the first start, one talk-end at the last end). The mouth is the renderer's (from the audio's loudness viasetInputs(id, {loud}), or a flap whiletalking) or a behaviour's (drive mouth); the director does not settalkingby any other means, so pages should not set it themselves while a cartoon runs. - The line is the caption while it lasts.
moodapplies to the speaker from the line's start and holds until another mood is written (a later line's mood,mood {who}, or a behaviour'smood; the latest write wins; at equal times the scene's beats the behaviour's). - Cut off (scope end,
stop, the scene ending), the line ends then: talk-end fires, the caption ends, and the record'sdurbecomes what was spoken. - Record:
{t, dur, kind: "say", who, text, voice, mood}(+speed,pitchwhen given) — exactly what an audio stage needs to synthesise and place the line.
7.5 does
- Starts a behaviour instance on
whoat the current time:behaviouris a pack id ("c4c:beh:bounce"),{id, version}, or an inline program (kindbehaviour). Ids resolve throughcreateRuntime({ packs }), which may return the program or the whole pack (itscontentis used); the engine does no I/O (a page passes its catalog:const cat = await loadPacks(); createRuntime({ packs: cat.get })). A missing or invalid pack never stops the cartoon: it falls back toc4c:beh:idle(or nothing if that is missing too) and is reported inrt.warnings. - The instance's
durisforwhen given, else the time until the earliest known end of its scope: an enclosingforblock, else the scene's end (from the plan, §7.7), else Infinity. paramsare scene expressions, like every other value in a scene block: they are evaluated when thedoesruns, with the scene's names (its params, vars,tau,random, …), in the plan as in the run, and the behaviour receives the numbers (its own defaults fill the rest, evaluated in the behaviour). A name the scene does not know is a validation warning and an error atstartCartoon(the plan evaluates it), never part-way through a render. A param the behaviour does not declare is a warning (validation for an inline behaviour,rt.warningsfor a pack) and is passed anyway. A behaviour that cannot start (e.g. a default naming something unknown) is skipped with a warning.- It ends at
for(exact time), when its scope ends (afor/whileblock in the scene, or the scene), or when replaced: adoeson the same character stops every behaviour the scene started on that character, unless it hasalso: true, which adds it alongside. Behaviours started by the page withstartBehaviourare never replaced by a scene. A stopped behaviour's offsets disappear at once (a new shot). - It does not wait:
does A bouncethensay A "…"bounces while talking. Usewaitto hold.
7.6 Scenes, cuts, captions, the stage
- A scene starts when the previous one ends, or at its pinned
at(seconds from the cartoon's start, normally a song time). It ends when all its scripts have ended (held ones aside, §7.1) — unless the next scene is pinned, in which case it holds its stage until that time, and anything still running is cut off then (glides freeze, lines end). The pin wins: a pin that has already passed when the scene before it starts (an earlier line ran longer than planned, e.g. TTS) cuts that scene off at once — it runs 0 s, its lines are recorded withdur0 — and the pinned scene starts then, late. Validation warns when a pinned scene is pinned before an earlier pinned one. - Nothing a scene loses goes unreported. When a scene ends,
rt.warningsgets one message for it (with the scene, the time and the pin) if it lost anything: squeezed to 0 s by a pin that had passed (and how late the pinned scene starts); a line cut off part-way by a pin (how much was spoken); a caption whoseforran past the scene's end (how much was shown — a caption does not wait); adoes … forwhose time ran past the scene's end (how much of it ran — adoesdoes not wait either); a glide (place … over,enter,exit) cut off part-way by a pin (how much of it ran; a cut-offexitleaves the character on stage, and every cut-off glide leaves it where it froze for the next scene); blocks a script had not reached (cut off by a pin, or after a wait for an end that never comes). Aforever/whileloop cut off by a pin and a hold at the end (awaitwith nothing after it) are expected and not reported — but a line or a glide cut off part-way inside a loop is. Something that ends exactly when the scene ends (a glide landing, aforrunning out) lost nothing, and "exactly" allows for rounding: what was due to end at most a microsecond after the scene (0.1 + 0.2 is 0.30000000000000004, not 0.3) is not a loss. The one exception is anexit, which either has landed or has not: one that rounding put a hair after the scene's end has not landed, so its character stays on stage, just out of frame, and the message says so ("lands 5.6e-17 s after the scene ends (rounding)"). Amounts are printed to 3 decimals, more when 3 would print two different amounts alike ("0.3 of 0.3001 s done"). Adoeswithoutfor(or withforInfinity) and a caption withoutforend with their scene by definition. A scene ended bystopAllsays so ("ended at 1 s by "stop all"") instead of advising await, and lists what thestopAllcut off in the other scene scripts as well: a line or a glide cut off part-way (anexitfrozen on stage), blocks they had not reached. The script that runs thestopAllmeans to stop there, so the blocks after it (in it, or in the other branches of its own script) are not losses, but a line or a glide cut off in its other branches is. Ending a script also ends its inner scopes (afor, awhile) and what was started in them, so a caption or adoes … forstarted there whoseforhad not run out is cut off by thestopAllitself, in any script (the stopping one too, as the same caption at scene scope is cut off by the scene's end), and reported with the amount as of thestopAll; what the scene itself started stays until the scene ends and is reported then. When the next scene is pinned, the stage holds after thestopAlluntil the pin: thestopAll's cut-offs get a message of their own ("was stopped at 1 s by "stop all" and held its stage until the pinned start of "b" at 3 s: …"), and the scene's end reports what the pin cut off, as usual. The plan (§7.7) finds all of these, so they are inrt.warningsas soon asstartCartoonreturns, and a run that follows the plan repeats exactly the same messages, which are not added a second time. A run follows the plan unless the scene scripts poll or loop without waiting and the renderer steps off the plan's frames (§7.7); such a run can cut things off at other times than the plan did and then adds its own messages beside the plan's. - When a scene starts: its place/mood apply, behaviours already running hear
{"on":"scene","name"}hats (a behaviour started by the scene itself starts with its start hats), and its scripts start. - When a scene ends, everything it started ends with it: its
doesbehaviours, its captions, its lines. Placement, place and grade persist into the next scene. cut {place, mood}: the place changes; the grade becomesmood, else the place entry'sgrade, else "normal".cut {mood}changes only the grade. The scene's hatplace/moodwork the same way.- Captions: the frame's caption is the latest-started caption still showing (a
captionblock or a line). When it ends, an earlier one still showing returns. A newer caption block of the same scope that ends no earlier hides an older one for good (only their scope's end cuts caption blocks short, and it cuts both at once), so the director forgets the older one (§7.7).
7.7 The plan: rt.timeline, rt.duration
startCartoon first runs the director alone on a twin runtime (no behaviours: the director cannot read characters, so its timing does not depend on them), stepping on the cartoon's own frames t0 + k/fps (t0 = the time startCartoon was called, k = 1, 2, …) up to maxDuration. So before the first frame:
rt.timelineis the complete record list in time order:scene {name, place, grade},say,does {who, behaviour, also?},caption {text},cut {place, grade}(dur = until the next cut or the scene end),place {who, x?, y?, h?, facing?},enter {who, from},exit {who, to},mood {who, mood}— each witht(runtime seconds) anddur(seconds actually run).rt.durationis the cartoon's length (null if it does not end withinmaxDuration).doeswithoutforlearns the rest of its scene from the plan. The plan equals the run exactly when the scene scripts do not poll (while,until) or loop without waiting; when they do, it matches a renderer stepping on the same frames,stepTo(t0 + k/fps)(§0), whatever t0 is. Tested: plan = run, also from an off-grid t0. Page globals (rt.vars) are copied into the plan as they are atstartCartoon; a page that changes them later gets a run that may differ from the plan.
Cost. Planning and playing take time proportional to the number of blocks the scene scripts run (plus one step per frame for the plan's grid). The director keeps only what is still running: does behaviours and captions whose for has not run out, indexed by the scope they belong to and by character. A caption without for (or with a for of Infinity) is not one of them: it lasts until its scope ends and nothing can cut it shorter, so all it needs is its timeline record's dur set then; its scope keeps a list of such open records (one reference per record, i.e. part of the timeline's own growth), and a caption whose end is not a number (for: "=0/0") keeps nothing at all. Replacing a does, a for running out, a scope ending all remove what they end at once. For display it keeps only the captions that may still show: the lines being spoken, and per scope a stack of caption blocks that no newer one hides for good (§7.6), newest on top with ends decreasing towards it — a new caption pops every one it hides and every one that has ended, and a frame pops the ones that ended by its time, so a frame looks at one caption per scope and line. A caption that ends no earlier than the ones before it in its scope clears them, so a loop of captions holds one or two, whatever its mix of for; the stack grows only while each caption ends earlier than every one before it, and then each one on it will show again when the newer ones end (unless the scope ends first). So a scene that loops for an hour does not slow down as it goes, in the plan or at 24 fps (tested: a 10-minute loop of does, does … for, say, caption … for and together — 150,000 timeline records, 60,000 lines — plans in about 0.2 s on a laptop, where it took 10 s before v0.3.1 and grew quadratically, and the director's working state stays under a hundred entries from 30 s to 10 minutes; a 10-minute loop of captions without for between captions with for, in the scene's scope and in a for's, with lines, holds at most 8 captions for display and plays all 14,400 frames in about 0.25 s, each with the expected caption; before, the display set grew by one caption per loop, and an hour of such a loop took 94 s to play in an earlier version, 0.24 s now). What does grow, by design, is the timeline (one record per block run) and what the program itself keeps running: does … also without for adds a behaviour that lives until its scope ends, and a caption without for holds its timeline record open until then (its dur is known only when the scope ends), even once a newer caption hides it: its scope's list of open records grows with the timeline, never the live items (tested: a 5-minute loop of 100 captions a second without for, with for Infinity and with for NaN, in the scene's scope and in a for's, keeps at most 4 live items, scopes and displayed captions, where an earlier version held one live item per caption, 540,001 after 9 minutes; the 10-minute caption loop above now holds 23 live items at its end, 10,959 before). The runtime's event queue holds one entry per waiting thread and per pending timer (a scene pin, a does … for's stop): a thread that is rescheduled leaves its old entry behind, and a while/until polling inside a for reschedules every step, so the queue is compacted whenever it doubles, and the stop timer of a does … for that was replaced early is cancelled. So a script that polls inside a 10-minute for, in a cartoon or in a behaviour on the live clock, keeps a queue of a few dozen entries (tested; it grew by one entry per step before). Compaction never changes the order events run in.
A runtime runs one cartoon at a time. Once it has ended (frame().scene === null after rt.duration), another may start on the same runtime, at the current time, on a fresh stage (nobody placed, no moods; characters and the page's behaviours are kept). Starting one while another is still running is an error. A startCartoon that throws never leaves a cartoon running (§6).
7.8 rt.frame()
{ t, scene: name | null, place: name | null, background, grade: "normal" | …, caption: text | null,
characters: { id: { x, y, h, facing, visible, pose: rt.pose(id), talking: 0 | 1 } },
order: [id, …] }background is the place entry's background (or the place name). Without a cartoon, every character is visible at its default placement.
orderlists every character id once, in the order the characters were added: first the ones the page added withaddCharacter, in the order it added them; then the cast members that were not there yet, in the cast's key order (a cast is a JSON object, so this is JavaScript'sObject.keysorder: ids that are array indices, such as"7", come first in ascending order, then the others as written; the Python port reads the cast the same way). It is the order to draw them in, first drawn first (behind), the same in every frame, and the same in both engines. Each frame gets its own array.charactershas exactly one own key per character id, each defined rather than assigned, so an id such as__proto__orconstructoris a key like any other and never the object's prototype; look a character up by its id with an own-property test, never withinor a bare lookup of an id that may not exist. Its key order is not meaningful: JavaScript lists array-index ids first whatever order they were added in, the Python port lists them in the order added. Iterateorder.- The default placement (§7.2: spread in cast order, then the other characters) is not this order: a cartoon spreads its cast first, whatever the page added before.
7.9 Text view (engine/text.js)
toText prints scenes as a screenplay-like outline: cast: A = Sunny, B = Grump · scene "Morning" at park · A says "Good morning, Grump!" (happy) · B does annoyed for 2 s · B also does wag · caption "One bite later..." for 1.6 s · cut to park (bloom) · A enters from the left in 2 s · A exits to the left in 2.4 s · place A at x 0.3, facing left in 1 s · B looks happy. An inline behaviour is printed indented under its does. It reads back now: the Screenplay text section below reads these lines as well as writing them. The shorter screenplay view once planned here (A: Hello! (happy), Phase 3) is not built and does not read; a line is written as above, with says and the text in quotes.
7.10 Not built yet
sing {who, text, at} (lines timed to a song), camera blocks (zoom, pan), clip on say (a recorded audio clip instead of TTS), interactive scene hats (key/click in a cartoon).
8. The skeleton (v0.4: engine/runtime.js, engine/desugar.js, tests/skeleton_engine.test.mjs)
Every character is a tree of bones (plan §1d): hips → torso → head, upper arm → forearm → hand, thigh → shin → foot, tails, ears, hair. v0.4 adds what makes the tree act like a skeleton: chains (a tail whips, a back bends), follow-through (ears flop after a hop), reach (a hand on the hip), views (front, side, back drawings) and joint limits (in profile an elbow or a knee bends one way only; seen head on it bends either way on screen, docs/SHAPES.md §3.4). The engine computes channels and two new pose keys; the renderer (ui/shapes.js, docs/SHAPES.md) draws them, and the Python port (py/c4c_runtime) runs the engine's half with the same bits (§8.9). Exact time, determinism and step independence (§0) hold for all of it.
8.1 The shared interface (the engine and the renderer both build to exactly this)
- Chains. A chain is a run of nodes with the same role whose segments are numbered from the root of the chain:
part:<role>#<i>(i = 0 nearest the body). Tails (roletail, 4 segments), spines (roletorso:torso#0= the belly / waist bend,torso#1= the chest), ears and hair where they look good. Every segment is a child of the previous one, so the general channelpart:<role>(no index) rotates segment 0 and the rest follow: exactly today's look for every existing move (backward compatible). Index channels add per-segment bends. Quadruped legs keep#i= leg number: the meaning of#idepends on the role (§2). The engine writes segment 0 on the general channel (part:tail,part:ear:1) and segment i ≥ 1 on#i(thechainmotion and the friendly blocks never write#0; a raw channel block still can). So a part a template draws in one piece moves with the chain's first segment, and on a chain the root (which reads the general channels and its#0) turns by exactly its share. How the renderer reads them (ui/shapes.jsapplyPose,docs/SHAPES.md§3.2): a node that is no chain follower reads the general channels and its index ones (engine/parts.jspartAngle); a chain follower (segment i ≥ 1 of a chain the template draws) reads only its index channelspart:<role>#iandpart:<role>:<side>#i(pluscurl× the general channel where a template says so), never the general channel again (swingPart tail 25turns a four-segment tail at its root, as a one-piece tail turned, not 100° at its tip); and the last segment a template draws (a one-piece part: its only one) also reads the index channels of every segment beyond it (v0.4.1), so a part drawn in fewer pieces shows the whole bend. - Reach.
pose.reach = { "<role>:<side>": { x, y, w } }for hands and feet (rolehandorfoot, side −1 / 1). x, y are character-local 1080p pixels with the origin at the feet centre, x toward the character's own front / right as drawn, y up; w is the 0..1 blend weight (ramped by the block; the pose holds it to 0..1). Character-local means in the character's own frame: the renderer draws the back view as the front mirrored and mirrors a point with it (docs/SHAPES.md§3.5), so a point stays where it is relative to the character. A named spot is{ spot, w }instead (spot∈hip head chest mouth; the block's own field isat): the renderer resolves the spot on the limb's own side (ui/shapes.jsreadsr.spot, else finiter.xandr.y). v0.4.1: a spot moved by an offset is{ spot, dx, dy, w }, dx and dy fractions of the character's height (dx toward the character's front in profile and outward seen head on, so the left limb's dx goes left as its spot is on the left; dy up); the renderer resolves the spot, then adds dx × and dy × the character's drawn height. An offset of 0, 0 is the spot itself,{ spot, w }. (The renderer places a spot for the character's own body shape, and follows an offset beyond the limb's reach only as far as the limb reaches:docs/SHAPES.md§3.5.) The renderer solves 2-bone IK (upper limb + lower limb) toward the target, blending with the FK pose by w; a template may declare a spot one of its limbs cannot reach (a dog's front paws and its hips), and then the reach leaves that limb as the rest of the pose has it (ui/shapes.jscanReach). The renderer also draws a reaching limb at the depth its target implies (in front of the body seen from the front; behind it from behind for the chest and the mouth). - View.
pose.viewis"front" | "side" | "back", ornull= the template's default (front for people, side for animals drawn in profile). The latest writer wins, like mood. The renderer draws the template's tree for that view; the switch is instant in the renderer, and the friendlyturnViewmakes it look like a turn by squashing sx to 0 and back around the switch. - Joint limits are a renderer rule: each template node may declare
limits: {min, max}in degrees (counter-clockwise positive, relative to rest); the renderer clamps the summed angle (every channel the node reads, §2); the pose data is unchanged (rt.posereports the unclamped sum). - Follow-through is engine-side and deterministic: it produces ordinary part channels (§8.3).
8.2 Chains
chain {ch, shape = sin, amp = 1, w | hz | every (default every 1 s), phase = 0, decay = 0, lag = 0.08, falloff = 1, segments = 4, sync = local} is a motion (it does not wait; it lives until its scope ends; start-or-keep; §2). ch is one part channel without an index (part:tail, part:ear:1); segment 0 is ch itself, segment i ≥ 1 is the channel ch#i (§8.1):
t_0 = tl, t_i = tl − i·lag (tl: the motion's clock, as for wave: local or since the behaviour started)
segment i = 0 when t_i < 0 (the wave has not reached it yet)
segment i = amp · f_i · shape(w·t_i + phase) otherwise, f_0 = 1, f_i = f_(i−1) · falloffwith the wave shapes of §3 (dampsin fades by e^(−decay·t_i), the segment's own clock). amp is live; w, phase, decay, lag, falloff are fixed when the motion starts. f_i is a running product (not pow), so both engines get the same bits. Every segment channel is written from the start (0 until the wave arrives).
Friendly chain blocks (desugared; part words and the "lift outward" rule of §4; a side-less pair moves both sides mirrored). A chain role is spread over its segments — tail 4, torso ("body") 2, ear 2, hair 2 (engine/parts.js CHAIN_SEGMENTS; segments overrides, a whole number 1–16). Any other part is not a chain: it moves whole (the plain channel, no index), and a segments there is ignored (a warning). (v0.4 also listed the neck, with 2 segments; v0.4.1 does not, since no template draws a neck: a block that names it is a warning, §8.6.)
| block | defaults | becomes |
|---|---|---|
swish {part, deg, every / hz / w, phase, lag, falloff, segments, sync} ("swish tail 40° every 0.8 s") | tail, 40°, every 0.8 s, lag 0.08 s, falloff 1 | chain {ch, shape: sin, amp: ±deg/n, …speed, lag, falloff, segments: n} per side — deg is the whole part's swing, shared by its n segments, so the tip swings about deg (the segments add up); a part that is no chain: wave {ch, amp: ±deg} (= swingPart) |
flop {…the same} ("flop ears 25° every 1.2 s") | ears, 25°, every 1.2 s, lag 0.15 s, falloff 1.3 (the tips move more) | the same |
bend {part, deg, over, ease, segments} ("bend body 20° in 0.5 s") | body, 20° | ramp {to: {ch: ±deg/n, ch#1: ±deg/n, … ch#(n−1)}} — the angle shared by the segments (the tip turns deg in all); no chain: ramp {to: {ch: ±deg}} |
bow {deg, over, ease} ("bow 30° in 0.5 s") | 30° | bend body −deg: forward, toward the front as drawn (clockwise); bow 0 stands up straight |
A formula is divided as text: deg: "=x" over 3 segments is "=(x) / 3"; numbers are divided as numbers. segments: 1 writes the part's own channel only. A template that draws the part in one piece (a cat's ears, a person's hair, a bird's tail, a dog's body) shows the whole bend (v0.4.1: its piece reads every segment's channel; in v0.4 it showed only segment 0's share, deg / n); one with more segments than the block writes leaves the rest straight (the monster's third antenna segment). A body standing on legs that hang from it turns only as far as its planted legs follow (the renderer eases it into that limit, docs/SHAPES.md §3.7): through the bow pack (40°) a dog's body tips about 22°, a cat's 24°, a monster's 30°; the person and the kid, standing on their hips, bow 40°.
8.3 Follow-through
follow {ch (or a list), source, gain = 1, hz = 2, damping = 0.3} is a motion: its channels lag the source channel like a damped spring, y'' = w²·(u − y) − 2·damping·w·y' with w = 2π·hz, following the source's value u; each channel gets rest + gain·(y − u) (rest: 0, or 1 for sx sy). gain is live; hz (held to 0..60) and damping (below 0 is 0) are fixed at the start, a value that is not a number counting as 0. A spring of 0 Hz (a formula giving 0, a negative number or NaN) has no pull: the motion adds nothing (its channels stay at rest) and never ticks.
- The source is the value the character's pose has on that exact channel key (
dy,rot,part:head,part:torso#1…), from every instance's base channels and motions, combined as in a pose (§2) — leaving out every follow motion's output (a follower never follows a follower, so the order followers run in never matters).moodis not a number (an error). - The grid. A follow motion that starts at t0 ticks at
t0 + k/240for k = 0, 1, 2, … (FOLLOW_RATE= 240;h = 1/240). The scheduler runs the ticks in time order with the block events, after the events at the same time (a block at a tick's time is seen by that tick), so the state at T depends only on what happened up to T: stepping at 24 fps, 30 fps, odd steps or one jump gives the same bits (tested). At tick k: readu= the source att0 + k/240, then k = 0, or y or v not finite: y = u, v = 0 otherwise: v = (v + h·(w2·(u − y))) / den; y = y + h·v (w2 = w·w, den = 1 + h·(2·damping·w)) — semi-implicit Euler with the damping implicit (stable for every hz ≤ 60 and every damping ≥ 0), only+ − × /on doubles in exactly this order, so the Python port gets the same bits from the same source values. A NaN or an Infinity in the source makes that tick's output NaN, as in any motion, and the next tick starts settled again (the spring recovers as soon as the source does). The output at T isrest + gain·(y − u)of the last tick at or before T (y and u of that tick): a step of 1/240 s. Because the tick integrates with the source read at its end, the grid answers the continuous spring one tick early (tested within 1 px of a 40 px step against the exact solution, under-, critically and over-damped). That holds for springs up to 6 per second: a faster one swings further than the continuous spring (at 30 per second and no damping its first swing is 43.5 px for a 40 px step, at 60 per second 64.6 px), so validation warns about a springhzabove 6 (v0.4.1, §8.6). - A follower stops when its scope ends (the motion is removed) or its instance stops; its next start begins settled again (y = u). It costs one source read per tick (the motions that may write that channel).
rt.stepTo(Infinity)returns once nothing is left to run; a follower that is still running ticks for ever then, as aforeverwith awaitin it runs for ever. - Inputs: a source that reads
loud/talkingat tick times sees the inputs as set before the step, so such a follower is as step-dependent as a poll (§0); likewise a source motion whose live value drawsrandomdraws at every tick. Programs without live inputs orrandomin their sources are exact.
Friendly: letFollow {part, after = body, amount = 1, hz, damping, segments} — "let the [ears] follow [the body]". after is body or a part word. It becomes one follow per source, gain = amount × f with the factor f worked out first as a double, then multiplied (a formula amount becomes the text "=(amount) * <f>", f written as JavaScript's String(f)):
body: the bouncedyper side withf = (sign × 0.4) / n(degrees per pixel; sign the friendly side, so a hop flops both ears outward together), then the tiltrotand the spine's segments (part:torso,part:torso#1) each withf = 1 / non every target channel, both sides alike (the part keeps its angle for a moment while the body turns, then catches up).- a part word: its own channels, the plain one and, for a chain role, its segments
#1 … #(m−1)(m: the role's own count), each withf = 1 / non every target channel. A pair named without a side (ears,arms) is both sides' channels: a target on one side follows the same side (f = 1 / n); a target with no side (the hair, the tail) follows the pair's friendly angle,f = (side × 0.5) / n(half the right side, minus half the left: both sides swinging outward together are one swing). The targets are the part's channels (sided): the plain channel and, for a chain role,#1 … #(n−1)(the gain shared over n segments, so the tip lags by the whole amount and the chain curves).
8.4 Reach
reach {part, to: {x, y} | at: spot (+ dx, dy), over = 0.4, ease = smooth, hold?} and release {part, over = 0.4, ease}:
partis a hand or a foot:right hand,left foot,hands/feet(both),paws(the front paws: hands) …; anything else is an error. Withoutpart: the right hand. A four-legged body's front paws are its hands (v0.4.1):front pawsandfront left pawarehand:-1/hand:1(the renderer moves the front legs for them),back pawsthe feet; a paw named without front or back is a front paw (paws,left paw: hands; a later fix in v0.4.1, before whichreach paws for the mouthmoved a dog's back paws, which reach no spot). (In v0.4 "front" was dropped:front pawsnamed the back paws.)- The limb's weight glides to 1 (reach) or 0 (release) over
overwithease, exactly like arampof a base channel: the script waitsover; cut off by a scope end or a stop it freezes; one value per limb per instance, the last writer wins. It starts from the limb as the pose has it when the block runs (whichever move reached or released it last), so a move can take over a hand another move put somewhere: areleasekeeps that target (the spot, or the point frozen where it is) and glides the weight down from there. The pose holds the weight to 0..1 (asnappyglide overshoots; the weight does not). atnames a spot (hip head chest mouth): the pose carries{spot, w}.to: {x, y}is a point (numbers or formulas, evaluated when the block runs) in the interface's character-local coordinates (§8.1): x toward the character's own front / right as drawn, the same for either side (a point is a place, not an angle:reach hands to x 80, y 300puts both hands at that one point, and a left hand reaching forward in a side view has a positive x like the right), y up from the feet; the pose carries{x, y, w}exactly as given. A limb already reaching for a point (w > 0, in this move or another) glides its point to the new one over the sameoverandease; from a spot to a point or to another spot (or from nothing) the target changes at once.- (v0.4.1)
atwithdx,dy(numbers or formulas, evaluated when the block runs; either may be left out, 0): the spot moved by fractions of the character's height, dx toward the character's front in profile and outward seen head on, dy up. A spot is anatomy; the offset makes a place near it that fits every character, whatever its size ("hand up beside the head":reach right hand at head dx 0.1 dy -0.03). The pose carries{spot, dx, dy, w}; with no offset (or 0, 0) exactly{spot, w}. A limb already reaching the same spot (w > 0) glides its offset from the one it has (none is 0, 0) to the new one over the sameoverandease, as a point glides; another spot or a point is set at once. A release keeps the spot and its offset.dx,dywith a point (to) or withoutatare an error. hold: s(friendly):reach …,wait s,release {part, over, ease}— reach, hold, let go the same way.- In the pose, per limb, the instance whose
reach/releaseran last wins (ties: the later instance), with its own weight and target; a limb never reached by it is left out. A stopped instance's reach is gone at once (like its offsets).pose.reachis{}when nothing reaches.
8.5 Views
view {to} sets the view (front side back; to is required) at once; it is per instance, the latest write wins across instances (ties: the later instance), and pose.view is null until a move sets one. A stopped instance's view is gone. Friendly turnView {to = side, over = 0.24} ("turn to the side in 0.24 s") becomes together { for over: drive sx "=abs(cos(pi*local/over))" } { wait over/2; view {to} }: the width squashes to 0 and back (multiplying whatever sx the move has), the view switches at exactly the narrowest point, and the script waits over. A turn of 0 s (or less) switches at once (a warning). A gait {view} (v0.4.2) writes its view while it runs: in the pose it counts as a view written at the time the gait started, so a view written later (or at the same moment) wins, and so does a later move's; when the gait stops (its scope ends, or its move is stopped) its view is gone and the one before it shows again. The switch is at once (a walk starts and ends where a pop does not show: walk comes in from off stage). Why: in the front view a knee bend turns the lower leg sideways on screen, which reads as a knee bending forward; in profile the person's and the kid's knees bend back (docs/SHAPES.md §3.3).
8.6 Validation
Errors: a chain ch that is not one part channel without an index; segments that is not a whole number 1–16 (a formula included); a follow without ch or source, or with an empty list of channels, a source that is not one channel, mood as ch or source; a view without to; a spring hz ≤ 0 or > 60, damping < 0 (numbers as written); a reach / release part that is not a hand or foot; reach without to or at, or with both; a point that is not {x, y} (both numbers or formulas, nothing else); dx / dy without at (v0.4.1); dx / dy that are not numbers or formulas; an unknown spot or view; a friendly chain block's part that is a raise (lift:) or a chain role with an index (part:tail#2); an unknown after. Warnings (odd values): a chain down a leg (its #i is the leg number), down a part nothing draws as a chain, or a role nothing draws; segments on a part that is not a chain; a part no character draws (v0.4.1: the neck, engine/parts.js UNDRAWN_ROLES: swish neck, bend neck, letFollow neck, letFollow ears after neck, a raw part:neck in any block: "no character draws a neck, so … moves nothing"); a lag below 0 or above 1 s; a falloff ≤ 0 or above 2; a spring hz above 6 (v0.4.1, §8.3); a turnView of 0 s or less; a negative hold. A raw channel in a primitive skeleton block (chain {ch: "part:elbow"}, follow {ch, source}) of a well-formed role nothing draws is a warning, as for every primitive block (§2); the friendly blocks name parts, so there an unknown part is an error (§4). Every skeleton block moves a character, so in a scene it is an error (use does).
8.7 Text view
sin wave down the tail chain · every 1 s · amp 20 · 0.1 s later each segment · each × 0.8 · 4 segments · tail 0.5 × behind dy, springing 2 per second, damping 0.3 · reach hands for the hip in 0.4 s · reach right hand to x 80, y 300, hold 1 s, let go · reach right hand for the head + 0.1 out and -0.03 up (× its height) in 0.4 s · let go with right hand in 0.3 s · show the side view · swish tail 30° · every 0.7 s · flop ears 25° · every 1.2 s · bend body 20° in 0.5 s · bow 35° in 0.6 s · let the ears follow the head × 2 · turn to the back in 0.24 s.
8.8 Packs
Written with the friendly blocks, in packs/skeleton/, their permanent home (manifests like every behaviour pack, type: "behaviour", ids c4c:beh:<slug>; tools/packs.mjs checks and hashes them and lists them in packs/index.json with file: "skeleton/<slug>.json", so the site's pages load them like the others; the parity fixture records them in its skeleton_runs, skeleton_packs, pose_at and pose_at_seq sections and the Python port runs them from there): whip_tail (swish tail, flop ears, a bob, the hair follows), bow (1.2.0: turn to the side, bow 40° easing in and out (1.1.0 started fast, ease: out, and a dog's knees snapped into the fold) and back, the head, hair and ears follow, turn to the front; a dog or a cat bows as in play, its feet planted; the bird, which has no side view, bows toward the viewer with a nod, its wings sweeping out at its sides), hands_on_hips (reach both hands for the hips, a sway, the head tilting; a dog or a cat cannot reach its hips and stands on four legs), wave_and_look (1.3.0: the head tilts toward the right hand, which goes up beside the head with the offset form, at: head plus dx, dy (0.09, −0.065), and waves out and in three times between (0.13, −0.11) and (0.07, −0.02), lets go, the head comes back; every character in its own view: the elbow out and the forearm up, a dog's or a cat's front paw raised in front of its chest; 1.1.0 aimed so near the head spot that the elbow went up beside the face, 1.2.0's inner end (0.045, −0.03) put the hand on the temple), floppy_hop (a hop; the ears, tail, hair and hands follow), look_around (side, the other way and back, front, back, front, over and over). They run on 0, 2 and 4 legs with finite poses, the same whatever the stepping (tested), and tests/skeleton_drawing.test.mjs draws every one on every template. packs/behaviours/ holds the 34 packs shipped before v0.4 (tests/skeleton_engine.test.mjs fails if a pack there uses a v0.4 block: the older Python studio's PackPoser reads that folder and its old rigs cannot draw reach or view).
8.9 Not built yet, and the Python port
The renderer side (chained templates, IK toward pose.reach, view trees, joint limits, depth, planted feet) is ui/shapes.js (docs/SHAPES.md). Scene-level views (view {who} in a scene) and a reach toward another character ("point at the dog") are not built. The Python port (py/c4c_runtime) runs §8: chain, follow (the tick grid in its scheduler, exactly as above), reach / release with offsets, view, the friendly blocks' desugaring (the same output keys and formula text), validation's messages, the pose keys reach / view, and warm pose_at; the parity fixture holds it to the JS engine on the six packs of §8.8 (run from packs/skeleton/, which stays their home) and on the skeleton scenarios, within 1e-9 (docs/PYTHON_PORT.md).
10. Screenplay text (engine/text.js: toText, parse, withDefaults)
A program has a text form: the program, line for line, that a person or an AI can read and write. toText(program) prints it; parse(text) reads it back and returns {ok, program, errors, lines}. The two are inverses: for t = toText(p), toText(parse(t).program) === t, and parse(t).program equals withDefaults(p), the program with the defaults its text prints filled in (§10.4), without what unsaid(p) lists (the little a text does not carry, §10.5). Hand-written text may differ from what toText prints in the ways §10.1 allows; toText then prints it in the one form. This section is the grammar; every example in it is read and validated by the test suite (tests/text_roundtrip.test.mjs).
10.1 Lines
- One block, hat or heading per line. A block belongs to the line above it that is less indented: the blocks of a script are indented under its hat, a body under its block (for, until, repeat, forever, while, if, between), a branch's blocks under its branch line (
— 1:, under at the same time), and a move written into a cartoon under its does line. A line indented under any other line (a say, a wait, a move…) is the errortext_child_not_allowed, never a body that does not run;else:follows an if at its indent.toTextindents two spaces a level; a reader takes any deeper indent, as long as the lines of one body share theirs (a line indented between two levels is the errortext_bad_indent). A tab is two spaces (and one character, as a column counts them, §10.8). - A text in a fence, as a chat writes it (a first line
` or `jabbertoon, and a last line``), is the text inside it. Anything else above a cartoon'scartoon "Name"line (a sentence, "Here is your cartoon:") is not part of the text: the cartoon line is the first line (elsetext_heading_not_first`). - Blank lines are skipped, and so is a comment: a line whose first characters are
#or//, and the end of a line from a#or a//that follows a space, outside quotes and brackets (A says "Hi" # a greeting). A#with a letter or a digit after it is part of a word (#d9cbbd,left leg #3). - Words are separated by one space or more; marks (
,;:·°×brackets) may have spaces around them or not (30 °reads as30°,x 0.3,y 0.9asx 0.3, y 0.9). Inside quotes and brackets nothing is changed. A word ends where a word does:sis not the start ofseconds(seconds are writtens). - The marks can be typed on any keyboard: the list dot
·as|or;(template dog | 4 legs),×asxor*with spaces round it (thigh x 1.2),°asdeg,degreesor nothing (turn 30 in 0.5 s), and a branch's—as-or--(- 1:).toTextwrites·,×,°and—. - The words are the ones below, in their order, in lower case as written.
10.2 Values and units
- A number:
0.3,-40,1e-7.toTextwrites up to 6 decimals; a number with more is written in its shortest exact form (0.30000000000000004), so it reads back exactly.InfinityandNaNare numbers too. - A formula is in brackets:
(t * 2)is the JSON value"=t * 2"(§5); what is inside is kept as written. - Text is in double quotes, with JSON's escapes (
"He said \"hi\"","a\nb"); any other JSON value (true,null, a list, an object) is written as JSON, where a number JSON has no word for is writtenInfinity,-InfinityorNaN.?is a value that is missing, wheretoTextprints one for a block that lacks it (a reach's point,reach right hand to x ?, y ?; a chain's or a follow's channel; a view,show the ? view), so an invalid program still reads; it is read in the degrees ofturn,turn to,liftandturn … byand the pixels ofraisetoo. Anywhere else a value must be there:wait ? sis the errortext_expected("expected a value, not ?"). - Units, as everywhere in the language: x is a share of the stage's width (0 the left edge, 1 the right edge); y the feet line as a share of its height (0 the top, 1 the bottom; the ground is 0.92); size (h) a character's height as a share of the stage's height; times in seconds (
s); angles in degrees (°, positive counter-clockwise as the viewer sees it);pxand a move's dx, dy in pixels of a 1080-pixel-high picture;win radians a second,… per secondtimes a second,every … sseconds each time.
10.3 Headings (cartoons and scenes)
A cartoon or a scene program starts with heading lines, in this order, each given once:
cartoon "Happy now?" a cartoon and its name (a scene program: scene program "Name")
cast: A = Sunny, B = Grump, C (any) the cast: id = name, or id (a role description), or the id alone
B: template dog · 4 legs · at x 0.68, y 0.92, size 0.34, facing left · colors body #d9cbbd, skin #9e8a78
places: park = meadow, lab = space (soft), yard = "meadow"
settings: speed = 1.5, t_in = (dur * 0.5)
variables: score = 0cartoonorscene program, then the program's name as a value (usually text). Without it, a text with a cast, places or a scene hat is a cartoon, and any other text is a move.- The cast line names each member; a member with more to say than its name has a line of its own under it,
<id>:and its details separated by·:pack <id>orpack <id> version <v>;template,style,shape,look,proportionsand a name;<n> legs(1 leg);at x …, y …, size …, facing left|right(any of them, in that order; facing is 1 or -1);voice <id>;colors body …, skin …, acc …;stretch head …, body …, legs …;art faces left|right(the look's facing);options {JSON};look note "…";note "…". A member the words cannot say (a field outside them, a value of another type) is its JSON:B: {"name": 5}. An id or a name with a comma, a bracket, a quote or a space at its end is written in quotes. - places:
name = background(the place{background}),name = background (grade),name (grade)(a grade only),name = "background"(a place given as just a background's name), orname = {JSON}. - settings (the program's
params) and variables (vars):name = value, separated by commas. - Any of these headings may instead be
cast is <JSON>,places is <JSON>,settings is <JSON>,variables is <JSON>, which is howtoTextwrites one the words cannot say. A move (a behaviour) has nocartoonline and no cast or places; itssettings:andvariables:lines come first. A program whose top the words cannot say (vnot 1, a kind that is not behaviour, scene or cartoon,scriptsthat are not a list, or a value that is not an object at all) is written as one line,program <JSON>(program {"v":2,"kind":"behaviour","scripts":[]}), which reads back as it is, so it validates as it did; it is the whole text (another line istext_program_not_alone).
10.4 Hats and scripts
Each script is its hat line with its blocks indented under it.
- In a move:
when it starts(no hat, or{"on": "start"}),when I start talking,when I stop talking,when a key is pressed,when the "space" key is pressed({"on": "key", "key": "space"}),when I am clicked,when the scene starts,when scene "Name" starts,on every beat, andwhen <hat>for any other hat (when loud,when every,when touch). - In a cartoon or a scene program:
scene "Name" at <place> (<grade>), starts at <seconds> s(the name, the place, the grade and the pinned start each only when given);when it startsfor a script with no hat (in a scene program it starts with the scene);when <hat>for any other. - A hat the words cannot say is
when {JSON}; a script that is not{hat, body}isscript {JSON}. - Defaults it prints (
withDefaultsfills them, and they change nothing a block does or how it validates): a script with no hat iswhen it starts({"on": "start"}); a script with no body has none; and in the blocks, each default the table below shows in brackets.
10.5 Blocks
The words of each block, its JSON fields in angle brackets; a part in square brackets is written only when the block has that field, and (default) is what the line says when the block leaves the field out. <ch> is a channel label (§10.6); <part> is a part's words as the block has them (right arm, tail, ears, part:arm:1).
| block | text |
|---|---|
set | set <ch> <value>, <ch> <value> |
ramp | glide <ch> <value>, …; by <ch> <value>, … [over <over> s] [(<ease>)] (glide by … when there is no to) |
wait | wait <s> s (s 0) · wait until <until> s |
until | wait until <cond> |
for | for <s> s: · until <until> s: |
while, repeat, forever, if | while <cond>: · repeat <n>: (n 1) · forever: · if <cond>:, then else: at its indent |
together | at the same time:, then a line — 1:, — 2: … under it for each branch, the branch's blocks under that |
stop, stopAll | stop · stop all |
wave | <shape> wave on <ch> + <ch> · <freq> · amp <amp> [· offset …] [· phase …] [· power <pow>] [· decay …] [· clip pos|neg] [· on the behaviour clock|on its own clock] (shape sin, amp 1) |
hop | hop <amp> · <freq> (amp 60), then the clock as for a wave |
gait | walk cycle every <every> s [· thigh × …] [· shin × …] [· arm swing …] [· no bob | · bob <base>/<amp>] [· roll …] [· stride …] [· give …] [· bend …] [· seen from the <view>] (every 0.62) |
drive | <ch> follows <value> |
mood | look <mood> · in a scene <who> looks <mood> |
setVar, changeVar | set <var> to <value> · change <var> by <value> |
move, moveTo | move [right|left <dx>] [down|up <dy>] [in <over> s] (left and up for a negative number) · move to [x <x>] [y <y>] [in <over> s] |
turn, turnTo, turnPart | turn <deg>° [in <over> s] · turn to <deg>° [in …] · turn <part> by <deg>° [in …] |
scaleTo, squash | size [to <s>] [width <sx>] [height <sy>] [in …] · squash <k> [in …] (k 0.1) |
setPart, liftPart | lift <part> to <deg>° [in …] · raise <part> <px> px [in …] |
bob, sway, wobble, shake, swingPart | bob <amp> · <freq> (10, every 1 s) · sway <deg>° · <freq> (5) · wobble <px> · <freq> (10) · shake <px> [· tilt <deg>°] [· <freq>] (8) · swing <part> <deg>° · <freq> (20); then [· phase …] and the clock |
window | between <from> s and <to> s: (from 0; in a move to (dur)); in a scene between <from> s and the end: when it has no to |
chain | <shape> wave down the <ch> chain · <freq> · amp <amp> [· phase …] [· decay …] · <lag> s later each segment [· each × <falloff>] · <segments> segments (sin, every 1 s, 1, 0.08, 4) |
follow | <ch> <gain> × behind <ch>, springing <hz> per second, damping <damping> (1, 2, 0.3) |
reach | reach <part> for the <spot> [+ <dx> out and <dy> up (× its height)] [in …] [, hold <hold> s, let go] · reach <part> to x <x>, y <y> [in …] (part right hand) |
release, view, turnView | let go with <part> [in …] (right hand) · show the <view> view · turn to the <to> in <over> s (side, 0.24) |
swish, flop | swish <part> <deg>° · <freq> [· lag …] [· each × <falloff>] [· <n> segments] (tail, 40, every 0.8 s; flop: ears, 25, every 1.2 s), then phase and the clock |
bend, bow, letFollow | bend <part> <deg>° [in …] [over <n> segments] (body, 20) · bow <deg>° [in …] (30) · let the <part> follow the <after> [× <amount>] [· springing per second <hz>] [· damping …] [· <n> segments] (ears, body) |
say | <who> says "<text>" [(<mood>, voice <voice>, speed <speed>, pitch <pitch>)] |
does | <who> [also] does <move> [for <for> s] [(<name> <value>, …)]: the move is its id without c4c:beh: (walk), walk 1.0.0 for {id, version}, another id as written; a move's name may be in quotes (A does "wave_hello" is A does wave_hello); a move written into the cartoon is a move "name", its text indented under the line |
caption, cut | caption "<text>" [for <for> s] · cut [to <place>] [(<mood>)] |
enter, exit, place | <who> enters from the left|right|top|bottom [to x …, y …, size …, facing …] in <over> s [(<ease>)] (left, 1) · <who> exits to the right [, facing …] in <over> s [(<ease>)] (right, 1) · place <who> at x …, y …, size …, facing … [in …] [(<ease>)] |
A block's id and note (any block may have them, §1) follow its words in brackets: wait 1 s [id "w1", note "a pause"]. <freq> is w <w>, <hz> per second or every <every> s; where the table gives its default (bob, sway, wobble, swing, swish, flop), · <freq> may be left out (bob 10 is bob 10 · every 1 s). The commas between x …, y …, size … and facing … may be left out (place A at x 0.5 facing left). In a move written into a cartoon or a scene, a move, turn, size, squash, lift, raise, reach, let go, bend or bow line says its ease after its time, (<ease>): move right 300 in 1 s (out), reach right hand for the head in 0.3 s (out), hold 0.5 s, let go. in <over> s is written whenever the block gives over (also in 0 s); a block without it takes no time, except enter, exit and turnView, whose line always says their time (1 s, 1 s and 0.24 s when they leave it out; hand-written, a line without in takes the default). A block whose words cannot say all of it (an odd value, a field the words have no place for, a body or an else on a block that holds none) is written as its op and its JSON, wave {"op":"wave","ch":"dx","w":1,"hz":2} (or block {…}), with its body, else and branches still as lines under it; it reads back exactly as it is.
Not carried by the text. unsaid(program) lists it, [{path, value}], and withDefaults keeps it (it only fills in): a move's own name (its pack's, shown beside it; a move written into a cartoon keeps its name, a move "name"); keys of a program's top the language has no place for (nothing reads them); and in a move printed alone (a move's own page, a pack), the ease of move, moveTo, turn, turnTo, scaleTo, squash, setPart, turnPart, liftPart, reach, release, bend and bow (their lines have never said it there, and the move pages print them as they always have; the ease of ramp, enter, exit and place is written as (<ease>), and in a move written into a cartoon or a scene every ease is). Five shipped moves have such an ease, so their text plays a little differently from the move itself: hands_on_hips, jump_for_joy, patrol, wave_and_look and wave_hello (tests/fixtures/lang/text_loss.json records each). To keep an ease, use the move by its name (A does jump_for_joy), or write the move into the cartoon. A hand-written (<ease>) on any of those lines is read.
toText also takes a cartoon file, {cast, program}: it prints the cartoon with the file's cast and places, as the studio and inspect read it.
10.6 Channel labels
dx, dy, rot, sx, sy, mouth, blink and mood as written. A part channel is its part in words: left arm (part:arm:-1), right ear (part:ear:1), arms (part:arm, both), tail, head, hips (a part that comes alone takes no s); a leg's number says which leg, back left leg … front right leg (part:leg#0 … part:leg#3, and the same for shin and foot); a side and a number that name different legs, or a number over 3, left leg #3 (part:leg:-1#3); a chain's segment, tail segment 2 (part:tail#2; part:tail is the root, segment 0); a lift channel ends in lift (head lift, lift:head). A channel of a part nothing draws, or not a channel at all, is written as it is (part:elbow). Several channels are joined by +.
10.7 Examples
A move:
when it starts
repeat 3:
move up 40 in 0.25 s
move down 40 in 0.25 s
wait 0.2 s
lift arms to 150° in 0.3 sSettings, variables and a loop:
settings: height = 30, speed = 1.5
variables: hops = 0
when it starts
forever:
hop (height) · (speed) per second
change hops by 1
wait 0.5 sTwo things at once, and a choice:
variables: hops = 3
when it starts
sin wave on left arm + right arm · every 0.8 s · amp 25
at the same time:
— 1:
sway 6° · every 1.2 s
— 2:
for 2 s:
squash 0.15 in 0.2 s
if (hops > 2):
look happy
else:
look sadA cartoon:
cartoon "The new kid"
cast: kid = Mia, dog = Biscuit
kid: template kid · style outlined · voice af_sky
dog: template dog · 4 legs · at x 0.75, facing left · colors skin #8d6e63
places: yard = meadow, inside = classroom (soft)
scene "Hello" at yard
kid enters from the left to x 0.3 in 1.5 s
kid says "Hi! Is that your dog?" (happy)
dog does wag for 2 s
caption "Biscuit wags hello." for 2 s
wait 2 s
scene "Inside" at inside
place kid at x 0.4, facing right
kid says "Let's draw a picture."
dog also does bounce
wait 1 sA scene program, with a window to the scene's end:
scene program "Rain"
cast: cat
cat: template cat · at x 0.5
places: street = city (sad)
when it starts
cut to street
cat looks sad
cat says "Rain again..." (sad, speed 0.9)
between 1 s and the end:
cat does sadidleA move written into the cartoon:
cartoon "A move of its own"
cast: A = Bo
A: template monster · at x 0.5
scene "Jump"
A does a move "tilt" for 2 s
when it starts
turn 30° in 0.5 s
A says "Ta-da!" (surprised)
wait 1.5 sHand-written, with comments, a blank line and extra spaces (it reads as the one form toText prints):
# a comment line
cartoon "Spaces"
cast: A = Sunny
A: template person · at x 0.4
// another comment
scene "One"
A says "Hello!" (happy)
wait 1 sTyped on a plain keyboard, with comments at the ends of lines (the same as ·, °, × and —):
cartoon "Plain keys"
cast: rex = Rex
rex: template dog | 4 legs | at x 0.4 facing right # Rex starts left of centre
scene "Park"
rex does a move "happy" // a move written into the cartoon
when it starts
turn 15 deg in 0.3 s (out)
bob 6
at the same time:
- 1:
swish tail 30 | every 0.8 s | each x 1.2
- 2:
move right 40 in 0.5 s (inout)
rex says "Woof!" (happy)
wait 1 s10.8 Errors
parse gives every problem it finds (up to 50; the rest of the text is then not read), each {code, where: {line, col}, says, fix, url}; the line and the column are where reading stopped (from 1; a column counts characters, so an emoji is one), at the word that is there instead, and program is null. says names what was expected there, every word the line could take there (up to five), and what was found (expected "s" (seconds are written s); found "seconds"; expected "(", ", starts at" or the end of the line; found "starts"). The error also has did_you_mean when the slip is one it knows: the cast detail meant, when the word there is near one the text knows (a Damerau-Levenshtein distance of 1 for a word of up to 5 letters, 2 for a longer one, 0 for one that differs only in capitals, else a word it starts or that starts it: tempate dog gives ["template"]); or the whole line put right, each way that reads where the line stands (at the left edge a heading, a hat, or on the first line the cartoon line; under a hat a block) and keeps the writer's words (every text in quotes and every number of the line is in it); when no such line reads, there is no did_you_mean. The slips: a unit run on (wait 1s gives ["wait 1 s"]), a word run into what follows it (wait3 s, B says"Back." gives ["B says \"Back.\""]), seconds written out (wait 2 seconds), a colon left out (forever, repeat 3, places park = meadow, cast A = Ann), a heading in capitals (Cast: A = Ann), a colon after scene (scene: "One"), a scene's comma left out (scene "s" starts at 0 s), a bracket or a quote left open (A says "Hi" (happy; a quote left open before the line's list of a face's mood, voice, speed or pitch closes before it: A says "Hi (happy) gives ["A says \"Hi\" (happy)"], never the mood said as words), a block's word near one the text knows (rex say "Hi" gives ["rex says \"Hi\""], trun 30° gives ["turn 30°"]), a capital (Wait 1 s), a screenplay's A: Hello! (happy) (A one of the cast, by its id or its name), scene motion said another way (A walks to x 0.5 in 1 s gives ["place A at x 0.5 in 1 s"], A exits right gives ["A exits to the right"]), and a space that is not one (a no-break space between two words: says names it). For example
cartoon "Oops"
scene "One"
A trun 30°gives {code: "text_unknown_line", where: {line: 3, col: 3}, says: "Line 3, column 3: that line is not a block, a hat or a heading the screenplay text knows ("A trun 30°").", …}. The codes: text_unknown_line (nothing of the line reads), text_expected (it reads up to the column, then not: says names what was expected there), text_bad_value (a value there cannot be read), text_unclosed_quote, text_unclosed_bracket (a formula's, or the list in brackets at the end of a line), text_bad_json (a block's JSON does not read, or is not that block), text_block_outside_script (a block line not under a hat), text_bad_indent, text_heading_twice, text_heading_late (a heading after a scene), text_heading_not_first (a cartoon or scene program line after another line), text_child_not_allowed (a line indented under one that holds no lines), text_cast_unknown_id, text_cast_field_unknown, text_else_alone (an else that is not right after an if), text_branch_alone, text_program_not_alone, text_not_text.
When the text reads, lines gives the line of each part of the program, by its path as validate's issues name it ({"cast": 2, "cast.B": 3, "scripts[0]": 5, "scripts[0].body[0]": 6, …}), and lineOf(lines, path) the line of an issue's path (the line of its longest start that has one: scripts[0].body[2].to is the line of scripts[0].body[2], and scripts[0].body[1].else[5] the line of that block of the else), so a writer with only the text can find what validate and playCheck tell (their problems carry a path). An inspect issue carries no path: it names its time (at_s), who, and the scene and the words of the line or caption it is about, and the summary gives each scene's start and lines, which find its line.
10.9 Error codes
Every error and warning of validate, every problem of parse, and every issue of engine/inspect.js has a stable code, lower-case words joined by _. schemas/errors.json (its JSON Schema is schemas/errors.schema.json) gives each code what it says in plain words, how to fix it, its place on https://jabbertoon.com/docs/errors/, and, where a suggestion can be made, the list it comes from (suggest_from). validate(program, {issues: true}) adds issues: [{level, code, path, message}], one per error and warning string, in their order (<path>: <message> is the string; the message alone when the path is empty, the program itself); without the option the result is as it always was. The Python port gives the same codes (validate(program, issues=True); fixtures/parity_codes.json). engine/inspect.js inspect(program, {catalog, packs}) reads a cartoon's plan and placements and reports what a person watching would see (a character partly out of the frame, two over each other, an empty stage, a line said off stage, a line, a caption, a move or a glide cut off when its scene ends, blocks a scene ends before, a caption a line hides, a scene squeezed to 0 s, a move that does not suit a body, a hat that never fires or fires only in the block editor, an unknown voice, a caption too long, more characters than the studio opens, and a move, a template, a mood, a grade or a background the studio does not have), with a summary of who is where and who says what when; playCheck(program) plays a program as a video would and reports what fails only when it runs (fails_when_played), or that it does not validate (invalid_program, with the code validate gives and its path). py/c4c_runtime/inspect.py is the same inspect (fixtures/parity_inspect.json).
catalog is the studio's catalog, data/catalog.json ({format: "jabbertoon-catalog", templates, moves, voices, moods, grades, hats, studio, …}; each move with what it works on); it holds no move's program. packs is the shipped moves, which a cartoon's moves given by id are played from: what loadPacks() gives, packs/index.json read as JSON, or a function (id, version) => program | pack as createRuntime takes. Without it a move given by id (A does sidle) is not played, so where it carries a character is not seen: the placement checks and the hat checks are approximate, and their why names the moves not played. With it, a move the packs do not have plays as idle, as in the studio, and is unknown_move. Every door's validate passes the shipped moves. maxSeconds (600) is how much of a cartoon the placements, the lines and the captions are checked in; playSeconds (600, PLAY_SECONDS, never less than maxSeconds) is how far it is played to see whether it fails when played, so the online door, which checks the first 120 s, finds a failure at 130 s as the local tool does. inLinkOrder(program) (Python in_link_order) is the program with its cast in the order a link gives it: a link carries canonical JSON, its cast's ids sorted (by their UTF-16 letters; ids such as 9 first, as JSON.parse lists them), and the studio adds the characters it opens in that order, so a later one is drawn over an earlier one and those with no x are placed by it (§7.8). Every door's validate, and the local tool's preview, render_video and frame (in the downloadable tool, not yet published), take the cast in that order, so what validate says is the picture its link shows (the local tool draws a project file as the studio opens that file, in its own order). The result:
summary:{kind, duration_s, cast: [{id, name, template, legs, look, voice}], scenes: [{name, start_s, end_s, place, grade, cuts: [{at_s, place, grade}], on_stage: [{who, x_from, x_to, facing}], lines: [{who, text, start_s, dur_s}], captions: [{text, start_s, dur_s}]}]}; a scene'splaceandgradeare the ones it opens with (a cut at its very start sets them), andcutslists every cut in it.on_stagegives where a character is drawn while it is in the picture, first and last (its placement moved by its move, below), and the way it faces then,1(right) or-1(left).- Where a character is: its placement (
x,y, its heighth) moved by its move'sdxanddy(pixels of a 1080-pixel-high picture; adxgoes the way the renderer draws it, mirrored by the character's facing times its art's,art faces) and stretched by itssxandsy; its footprint there is its template's box at rest, as wide as the template is drawn (FOOTPRINTS: 0.29 of its height for a person, 0.582 a kid, 1.543 a dog, 1.267 a cat, 0.567 a bird, 0.92 a monster; 0.6 for a template the studio does not have), with its face in it (the head, with its hair, ears and snout; the monster's eyes, brows and mouth; the top 30% for a template the studio does not have), mirrored the way it faces. Withbounds(frame, t)({id: {x0, y0, x1, y1}}in stage fractions, as the renderer'sboundsAtgives) the drawn box is used instead, its face at the same share of it. issues:[{code, at_s, who, says, fix, url}], in time order (at_snull for what holds the whole cartoon); an overlap also haswith, the other character; a name the studio does not have also hasdid_you_meanwhen one it has is near. The codes:offstage(partly out of the frame,partlyOut: more than 2% of its box's width past the left or the right edge or of its height past the top or the bottom,LIMITS.past_edge, aspastEdgemeasures it; or a quarter or more of its face out, for a quarter of a second or more: a dog at x 0.1 has its tail or its snout out, a person 0.97 of the picture tall its head; not while an enter or an exit glides it, nor while a move carries it a third of the stage or more from a place in the frame, as a walk in, a fly out or a run off and back does: a shorter move that takes it out from near an edge is told; when its place is in the frame (half of it, or its face), what it says gives the places, to a hundredth, that keep all of it in the picture all the while it stands there, its move's carry and stretch with it (a place from footprints keeps 0.02 of the stage from each edge, as a drawing's limbs reach a little past its footprint; one from the drawn boxes none), or says no place does and that a smaller size would, and names the move that takes it out),overlap(half a second or more: their boxes over half of the narrower one's width and height, one face over half or more of the other face, as two animals nose to nose are, or the one drawn in front, the later in the cast (in the link's order, above), over half or more of the face of the one behind it, as a cat standing in front of a dog's head is; what it says names the move that carries one onto the other, when one does, and the nearest place, to a hundredth, that keeps one of them clear of every other character with all of it in the picture all the while it stands there; when no place does at their sizes, the largest size, a tenth smaller at a time down to half, at which one of them has such a place, with that place; else it says none does: a move that keeps to its place, or one exits first). A while out of the frame or over each other that goes on across a new place (aplacethat gives x, y or h, anenteror anexit, in a later scene) is told once for each place, the place it offers then with the time of the place to change (placed at x 0.3 from 2.61 s); a place that holds for less than the while it would take to be told on its own (a glide on its way off) is told with the one before it. A character is on the stage for a viewer when half of its box, or its face, is in the picture:empty_stage(nobody on it for two seconds or more),talks_offstage(a line said while out of the picture for most of it, however it got there) andon_stageread that;line_cut,pinned_scene_squeezed,move_wrong_body(a move that moves nothing on this body while it moves something on others, or a move of the legs on a body with none, where only its whole body moves: a turn to the side counts as the whole body, v0.4.2),hat_never_fires,input_hat_in_video,unknown_voice,caption_too_long,cast_over_studio_limit,unknown_move(a move the packs do not give, or, without packs, the catalog does not list: in the studio the character idles instead),unknown_template,unknown_mood(a mood no face shows, in a line, a "looks" block or a move written into the cartoon),unknown_gradeandunknown_background(a scene's or a cut's place whose background, the place's own name when no places line names it, is not one of the studio's: beach, meadow, classroom, stage, space or city). What the director itself reports a scene lost when it ended is told too:line_cut,caption_cut(a caption cut off before itsforis up: "0 of 2 s shown" is never seen),move_cut(adoes … for N scut off),glide_cut(an enter, an exit or a glide cut off; an exit cut off leaves the character on the stage),blocks_never_run(blocks a script had not reached when its scene ended) andpinned_scene_squeezed; any other warning it gives isplay_warning, in its own words.caption_hiddenis a caption a line said over it takes the place of for most of its time. A cartoon that cannot start, or that fails while it plays (a line's who that is not in the cast, a formula's name the engine does not have, in a move that starts later), isfails_when_playedat its time, and what it says names why; it is checked to there. It is played toplaySeconds, pastmaxSeconds, to see whether it fails.checks_run:[{check, mode, why?}], one per check:full;approximate, and why (the placement checks withoutboundsuse each character's footprint, moved and stretched by its move, so a turn of its body and its limbs' own motion are not in them; withboundsthat gave no box for a character at some time, its footprint stood in; captions are counted by their letters; a cartoon longer thanmaxSecondsis checked to there;fails_when_playedisfullwhen it was played to its end or to where it fails, elseapproximate, "played to 600 s of …"); ornot_run, and why (no catalog, a move alone, a program that does not validate, a screenplay text not read withparsefirst, or one that cannot be read at all:inspectnever throws on its input, nor on its options:inspect(p, null)and a catalog with entries of the wrong shape are read past). A scene that never ends (aforeverwith a wait in the last scene) hasend_snull and is checked tomaxSeconds.
11. Games
Every game is in 3D: a program of kind game with "view": "depth", made by steps and played by engine/depth.js. The editor's 🎮 Game tab and the build tool take the same steps, and engine/depth_build.js checks each one: a refused step says where, why and the fix, and stops the rest. The first step says which kind of game it is:
{"op": "new", "kind": "walk", "name": ...}: on foot, in a place, with the people, the animals and the things in it.{"op": "new", "kind": "trench", "name": ...}: flown.trenchis a walled corridor in space, flown along;spaceis open space, flown freely;surfaceis low over metal;skyis a plane over the sea.
Every step, its fields and what it does, with a whole game made from blank, is in the guide's topic game (the get_guide tool, /for-ai/). A game's rules are written in this language's own words: a rule is a hat (WHEN) and a body (what to DO, in order).
A game seen from the side, from above or in space, with levels on a world of blocks (kind game with no view), was the retired flat (2D) game engine's. Its steps are refused, with the kinds above as the fix.
12. Worlds
A world of blocks as a cartoon's place was the retired flat (2D) world's: validate refuses one in words (world_place_retired). Every place is a World in 3D, in the editor.