Skip to content
Skip to content
AI & scripting

JavaScript scene scripting

Chorono scripts use JavaScript to create and edit native layers, timelines and interactions. The result stays editable. Scripts run once during authoring; the player evaluates the resulting animation on each frame.

For Claude and Codex, use MCP run_script. It executes synchronous code in isolated QuickJS with no Node, DOM, network, imports or filesystem access. Prepare external data with the agent's normal tools, then include JSON in the script or import assets with MCP. The manual Script Console still uses the legacy browser runner and does not have the MCP sandbox's isolation or execution limits.

Start with Connect your AI agent with MCP and the Chorono agent skills if the editor is not connected yet. For the underlying editing model, inspect keyframe values and timeline timing before scripting a revision.

Discover and execute#

Start with list_sessions, get_capabilities, chorono://scripting and get_scene. Choose an explicit sessionId when multiple editors are connected. Capabilities describe the running version's object kinds, property schemas, particle presets and limits.

  1. Read the current scene and revision; preserve unrelated work.
  2. Call run_script({code,dryRun:true,expectedRevision,requestId}).
  3. Inspect the returned objects, timelines, logs and planId.
  4. Commit with apply_script_plan({planId,expectedRevision,requestId}) through the same running MCP server. Do not replay the script: the plan preserves generated ids. Plans expire after five minutes, a scene change, or a server restart; separate short-lived stdio server processes do not share plans.
  5. Inspect actual render_preview images, validate, then save_project.

An error discards the working scene. A successful commit is one undo step. Separate import, playback, runtime-event, preview, save and export operations use MCP tools; these are not filesystem or browser APIs inside scene.

Read and safely update existing data#

scene.snapshot() returns a full detached scene snapshot. scene.assets, assetCollections, parameters, triggers, bindings, parameterWires, stateMachines and initialState expose detached data. scene.composition() and scene.timelines also return copies.

scene.get(id) and scene.find(name) return layer handles; scene.layers lists handles. layer.data returns the complete detached layer. layer.get(path) reads a nested property.

const hero = scene.find('Hero card');
if (!hero) throw new Error('Hero card not found');
scene.log(hero.data, hero.get('style.fill.color'));
hero.patch({style:{stroke:{color:'#ffffff',width:2}}});
scene.log(scene.snapshot().layers.length, scene.assets.length);

layer.patch(partial) recursively merges objects and replaces arrays, preserving unspecified nested fields. layer.set(partial) keeps its original shallow replacement behavior: replacing audio, style, transform or another nested object replaces that whole object. Changing a detached snapshot does not edit the scene. Use handles or entity commands to commit edits. Layer identity cannot be changed through a patch.

Create a scene with several animations#

Adapt composition settings and ids when extending existing work. All times are milliseconds and rotations are degrees.

scene.composition({width:960,height:540,durationMs:4000,frameRate:30,backgroundColor:'#0b1220'});
const intro = scene.createTimeline({id:'intro',durationMs:2000});
const idle = scene.createTimeline({id:'idle',durationMs:2000,loop:true});
const hero = scene.add('rect');
hero.set({name:'Hero card'});
hero.pos = [90,160];
hero.size = [300,180];
hero.fill = '#2563eb';
hero.cornerRadius = 24;
intro.key(hero,'transform.x',0,90,'easeOut').key(hero,'transform.x',1800,480);
intro.key(hero,'style.fill.color',0,'#2563eb').key(hero,'style.fill.color',1800,'#f97316');
idle.key(hero,'transform.y',0,160);
idle.modifier('layers.'+hero.id+'.transform.y',{
  type:'sine',parameters:{amplitude:12,frequency:1}
});
scene.log(hero.id,intro.data,idle.data);

Timeline names do not sequence animations. Use absolute key times on one master timeline for a continuous film, or explicit state-machine transitions for interactive sequences. With overlapping tracks, inspect the combined result; do not assume values add.

scene.useTimeline(id) chooses the target of subsequent Layer.key, scene.clone and scene.array calls. Without a script selection, the first timeline is used. The editor's selected tab does not choose this target. Timeline.key always uses its own id. Clone/array can explicitly override the timeline; inspect the current scripting resource for their signatures. scene.cloneTimeline(id,newId) duplicates tracks with fresh keyframe ids while sharing the objects.

Appearance and animation values#

Use scene.add(kind) with a kind from capabilities. Handles provide pos, size, opacity, rotation, scale, fill, text, cornerRadius, blendMode, plus font, stroke, shapeParam, parent, interactive, followPath, configureParticles and key.

Frame evaluation applies animated layer properties before rendering. This includes shape parameters, typography, effects, masks, repeater configuration and particle configuration. Values must fit the actual property schema. A property must exist in the renderer/model; an arbitrary property name does not create a new rendering feature.

Numeric values interpolate with easing. Color properties interpolate color channels; ordinary strings and booleans change at key boundaries. Vec2 values interpolate their components. Numeric controllers and modifiers remain numeric. Use scalar coordinate paths to animate existing path/spline points and handles while preserving topology; arbitrary whole-object/topology morphing is not supported.

Easing belongs to the starting keyframe: linear, hold, easeIn, easeOut, easeInOut, or {type:'customBezier',bezier:{cx1:0.2,cy1:0,cx2:0.3,cy2:1}}.

Timeline.data reads a full timeline. set, key, track, removeTrack, modifier and bake edit it. key takes layer-local properties such as transform.x; track methods take full targets such as layers.<id>.transform.x. Track patches expose out-of-range behavior, controllers, time warps, multiplier curves and modifiers. Bake numeric tracks when sampled keys are required.

Paths, particles and interactions#

Create paths with scene.addPath(points,{role:'motion',name:...}) or scene.addSpline(kind,params,options). Attach layer.followPath(path.id,{orientToPath:true}), then animate followPath.progress from 0 to 1. Use capability schemas for spline trim/style and particle/repeater data.

scene.addEmitter(preset,options) and configureParticles create native particle animations. Choose a real preset and inspect representative frames. Animated emitter settings are evaluated deterministically at the requested frame; scripts do not register particle callbacks.

Particle, spline and Scene Explorer domains#

NamespaceStructured script access
scene.particlePresets, layer.particlesDetached config/preset reads; validated deep config edits; emission, visuals, animation, randomness and rendering sections; deterministic integer/string seeds; scale/opacity/color life keys; native motion-modifier CRUD
layer.splineDetached geometry/bounds reads; primitive/contour creation; point and handle editing/locking; line/cubic/quadratic segment editing and splitting; contour closing/reversing; sub-shape removal/renaming; affine geometry transforms
scene.explorerTree/node/relationship reads; faceted search; grouping, ungrouping and reparenting; sibling render order; rename and bulk visibility/lock/solo/pin flags

Use domain commands for structural edits and reuse returned ids. A spline's coordinates are layer-local; its transform, parent and pivot are preserved. Deleting spline elements also removes their animation tracks in the same undoable edit. Instance domain data is readable, while edits require explicitly opening the source layer. Point/handle locks and locked/frozen affected hierarchies are respected.

Particle life keys use normalized positions 0..1; their easing belongs to the destination stop. life('color',stops) accepts supported CSS colors or 0..255 RGBA data. Native motion types are noiseDrift, sineWave, and spiral; modifier indices must be re-read after removal. Path/source-layer emitters reference existing geometry through area.pathLayerId / area.sourceLayerId. Circle/rectangle emitFromEdge and modifier phase are evaluated by the native engine. Flow graphs and extra burstMarkers are not implemented; the particle API rejects them.

Explorer reads use authored scene order and the script-selected timeline (or first timeline) at time 0 by default. node(id,{timelineId,timeMs}) includes complete layer data; nodes, tree and query return metadata. query({search:'type:spline',includeAncestors:true}) uses the same search grammar as the panel. Children/ancestors/descendants are id lists. UI selection, collapse, columns and temporary sorting/filter state are separate. World-preserving reparent/ungroup defaults to keepWorld:true; animated/bound transforms, shear, singular transforms and lossy group compositing require baking or an explicit local-space move.

See the domain API reference and complete path-emitter example for method signatures, returned ids and constraints.

Interaction definitions#

scene.addParam, scene.addTrigger, scene.wire, scene.addBinding and scene.addStateMachine define interactions. Read existing definitions before editing them. scene.stateMachine(id) opens an existing machine. Machine handles expose detached data, metadata/state/transition editing and setInitial. Scene entity commands update/remove parameters, triggers, wires and bindings. Consult chorono://scripting for exact signatures.

Dispatch runtime events and parameter overrides with control_runtime, then inspect get_runtime and live previews. Authoring scripts do not provide scene.on, scene.update, asynchronous event listeners, macro recording or per-frame callbacks.

Audio and files#

scene.audioClip(assetId,{timelineId,startMs,name}) reuses an imported audio asset. Its returned handle supports audioGain, audioFades, moveAudio, trimAudio and splitAudio; these share the editor's native non-destructive audio commands. splitAudio returns the right-hand clip. Set a key time when changing animated gain. Raw layer timing patches do not implement audio trimming semantics.

Import new files with MCP import_asset. render_preview produces PNG; audio preview/export produces WAV. Validate and save a portable project with save_project; report its returned path and warnings. Three.js/modeling APIs are outside this script surface.

Limits#

The current MCP limits are 128 KiB script text, 2 seconds, 32 MiB QuickJS memory and 20,000 commands per run; scene totals are 5,000 layers, 100 timelines and 50,000 keyframes. Read connected capabilities for exact limits. These are workload limits, not a playback frame-rate guarantee.

See the MCP reference and authoring skill.

A good place to start
Getting started / Chorono documentationChorono documentationLearn Chorono with editable animation examples. Install the editor, edit keyframes, build loops and connect Claude Code or Codex through MCP. Cre…Getting started / Install ChoronoInstall ChoronoSet up the free, open-source animation editor on your computer and start a local browser session. This guide installs the browser editor, its loc…Getting started / Create your first editable animationCreate your first editable animationOpen an editable Chorono example, change its text and colors, inspect the timeline, then save and reopen your first 2D animation. Start with a re…Workspace / Chorono editor workspaceChorono editor workspaceFind the canvas, layers, properties, timeline and resource tools in the Chorono editor. Choose a guide for each part of your animation workflow.…Workspace / Canvas and drawing toolsCanvas and drawing toolsNavigate the canvas, draw shapes and splines, use snapping and edit motion keys in Chorono. Use the canvas to arrange the objects in your composi…Workspace / Choose a drawing or transform toolChoose a drawing or transform toolUse Select, Pan, Pen, Move, Rotate, Scale and Anchor tools without losing track of the active editing mode. Choose the tool that matches the edit…Workspace / Select exactly the objects you needSelect exactly the objects you needUse box, lasso, circle, paint and rule-based selection to work with several animation layers. When several objects overlap, clicking each one can…Workspace / Align objects with guides and snappingAlign objects with guides and snappingSet grid, object, point, guide, pixel, angle and scale snapping for precise placement in Chorono. Snapping helps a dragged object settle on an ex…Workspace / Edit Bézier points and spline curvesEdit Bézier points and spline curvesDraw editable paths, adjust points and handles, and extend or close a spline in Chorono. A curve is easier to control when you can see the points…Workspace / Edit animation positions on the canvasEdit animation positions on the canvasUse Motion Keys to adjust position keys, draw a movement and control how the path is timed. Motion Keys bring position editing onto the canvas. T…Workspace / Layers and scene hierarchyLayers and scene hierarchySelect, name, group and organize scene objects in Chorono using the Layers panel and Scene Explorer. A layer is an editable object in your Choron…Workspace / Draw and edit basic shapesDraw and edit basic shapesCreate rectangles, circles, polygons and procedural shapes, then adjust their geometry in Properties. Basic shapes are a useful starting point fo…
Explore the docs