All servers / Design / PinePaper Studio MCP server
PinePaper Studio MCP server
MCP Server for PinePaper Studio - Create animated graphics with AI
Tested by ConnectATDScore 89 out of 100. Tested 2026-11-19 on package version 1.6.40. Package: @pinepaper.studio/mcp-server · source
Score breakdown
| Runs | 18 / 20 | |
|---|---|---|
| Tool descriptions | 19 / 20 | |
| Package safety | 20 / 20 | |
| Maintenance | 20 / 20 | |
| Adoption | 12 / 20 |
What we saw
- Starts and answers the MCP handshake: yes (2.2 seconds including download)
- Tools offered: 71
- Last published: 2026-11-18
- Weekly downloads (npm): 1,133
- License: MIT · Direct dependencies: 1
Want this server set up for your team?
ConnectATD builds AI automation and wires up MCP servers like this one. Tell us what you are trying to do.
Talk to ConnectATDTools and how they are described
Agents choose tools from these descriptions. Under each name you can see how many of its parameters are explained.
pinepaper_set_background_color1 of 1 parameter describedSet the canvas background color. Pass a hex color string (e.g. "#0f172a").
pinepaper_set_canvas_size3 of 3 parameters describedSet canvas dimensions: width+height, or a studio preset key alone — instagram-post (1080x1080), instagram-story / tiktok (1080x1920), youtube-thumbnail (1280x720), full-hd-1080p (1920x1080), twitter-post (1200x675). Platform names (instagram, youtube) are not preset keys; an unknown key is refused with the list.
pinepaper_get_canvas_sizeno parametersGet current canvas width and height.
pinepaper_clear_canvasno parametersRemove all items from the canvas. Item ids start again at item_1.
pinepaper_refresh_pageno parametersReload the PinePaper browser page for a clean start.
pinepaper_create_item13 of 13 parameters describedCreate a text, shape, or graphic on the canvas. Returns an itemId for later reference; properties.id chooses it ("sun"), so replays address the same ids. A closed shape with a strokeColor and no fill is an outline. ITEM TYPES: text, circle, star, rectangle, triangle, polygon, ellipse, path, line, arc, pentagon, hexagon, diamond, arrow, heart, disk, circle-outline, arrow-right, speech-bubble, speech-bubble-square, speech-bubble-pointed, thought-bubble, double-bubble, quote-bubble, comment-box, callout-box, shader, field. STYLING: gradients (color object with stops), shadows, blend modes, opacity. See inputSchema for properties.
pinepaper_modify_item8 of 8 parameters describedModify an existing item's properties. DO NOT USE FOR ANIMATIONS: - For looping animations → pinepaper_animate - For keyframe/timed animations → pinepaper_keyframe_animate - animationType passed here will be IGNORED USE WHEN: - Changing color, size, position of an existing item - Updating text content - Adjusting styling properties - Adding/changing gradients, shadows, or blend modes MODIFIABLE PROPERTIES: - position: {x, y} or separate x, y - color/fillColor: Fill color (solid string OR gradient object); null, 'transparent' or 'none' removes the fill - fillOpacity (0..1): the solid fill's own alpha, apart from opacity; on the current studio it is kept when a later fillColor changes the fill. The result's fillOpacity says whether the studio applied it. - strokeColor: Outline color (solid string OR gradient object) - strokeWidth: Outline thickness - fontSize: Text size - content: Text content - opacity: Transparency (0-1) - rotation: Rotation in degrees - skewX / skewY: shear in degrees about the item's centre; matrix: [a, b, c, d, tx, ty] affine. For mockups (a box face, a screen at an angle). APPLIED to the current shape, so calling again compounds — the result's affine says so. - scale: Size multiplier - shadowColor: Shadow color - shadowBlur: Shadow blur radius - shadowOffset: Shadow offset [x, y] - blendMode: Blend mode (normal, multiply, screen, overlay, etc.) - pathData: SVG path data — RESHAPE the geometry itself, not just its styling. This is how you straighten a hand-drawn box or correct a traced outline without deleting and recreating the item, which would lose its id and every relation and keyframe pointing at it. Requires an FxTool build from 2026-08 or later: before that the property was silently dropped while the same call applied the fill and stroke and reported success. GRADIENT OBJECT FORMAT: {type: "linear"|"radial", stops: [{color: "#fff", offset: 0}, {color: "#000", offset: 1}], origin: [x,y], destination: [x,y]} LETTER-COLLAGE PROPS (non-destructive — registry ids, animations, relations, effects, deformations all preserved): - palette (collage group): Swap palette name in-place. e.g. "wordle", "spring", "sunset", "magazine". Walks existing letters, rewrites tile + text fills. No geometry change. - collageStyle (collage group): Swap visual style — "tile" | "magazine" | "paperCut" | "fold" | "gradient" | "image" | "particle". Geometry rebuilds; every registryId is preserved via graft. - palette + collageStyle (collage group): Combine in one call to apply both atomically. - bgColor (single letter group, child of a collage): Tile/background fill for that one letter. - textColor (single letter group): PointText fill for that one letter. Use the collage group's id for palette/collageStyle; use a child letter's id for bgColor/textColor. Prefer this over destructive recreation.
pinepaper_import_image17 of 17 parameters describedImport a raster image onto the canvas from an http(s) URL, a data: URL, or a LOCAL FILE PATH (the server reads the file). Returns an itemId for the imported image. USE WHEN: - User wants to add a photo, PNG, JPG, or other raster image - Importing images from URLs - Adding backgrounds or reference images - User provides an image URL IMPORTANT - IMPORTED IMAGES ARE FULL ITEMS: The imported image becomes a first-class item in PinePaper's registry. It gets an itemId and can participate in the full relation and animation system — you can orbit it, attach things to it, apply masks, animate it with keyframes, etc., just like any natively created shape. OPTIONAL MASK: Apply a mask shape during import to clip the image: - circle: Circular crop - rounded: Rounded rectangle crop - hexagon: Hexagonal crop - star: Star-shaped crop SIZE CONSTRAINTS: Use maxWidth/maxHeight to constrain the image dimensions while preserving aspect ratio. - maxEdge: the longest edge the studio STORES the image at (px), or 'native' to keep every pixel. The result says when it was stored smaller. - nativeSize: true places the image at its source footprint even if it was stored smaller. - smoothing: 'off' (nearest-neighbour, for pixel art) | 'low' (default) | 'medium' | 'high'. Chromium draws 'low', 'medium' and 'high' the same; the visible choice is 'off' or not. Asking for 'medium' or 'high' is applied, and the reply says so in smoothingNote. - shadowColor / shadowBlur / shadowOffset: a drop shadow on the placed image, the same keys pinepaper_modify_item takes. - name: a name for the image, so a batch patch or any tool that takes an item can address it by name instead of its id. EXAMPLES: - Import photo: url: "https://example.com/photo.jpg" - Import with mask: url: "https://example.com/avatar.png", mask: "circle" - Import at position: url: "https://example.com/bg.jpg", position: {x: 400, y: 300}, maxWidth: 800
pinepaper_beat_cuts2 of 9 parameters describedCut on the music: analyse a track's beats (or take beat times you already have), fit a beat grid, and return cut points on every beat, every bar, or every N beats — optionally splitting a video or audio clip at each one. The song is the backbone of the edit: when the music is generated, cut the picture to its beats and bars and use the whole song. Do not trim the song to fit shots that were planned first. - source: the music — an upload id, URL, data: URL or local file path. Or beats: [seconds] to skip the analysis. - every: 'beat' (default) | 'bar' | N beats. beatsPerBar (default 4). range: [from, to] seconds. - bpm: the tempo, if you know it (the grid's phase is still fitted to the music). Otherwise the studio's detection and its usual confusions (double, half, 3:4, 4:3 …) are scored against the music and the best is used; bpmHint: [min, max] keeps the choice in a range. The result lists the candidates, and says lowConfidence with a warning when the tempo is uncertain — pass bpm then. - clipId: split this clip at each cut, in order; cuts outside the clip are skipped and listed. Returns cuts (seconds), the grid (bpm, phase, period, confidence) and, with clipId, the pieces' ids.
pinepaper_camera_director6 of 6 parameters describedDirect a cinematic camera walkthrough of the scene from a high-level SHOT LIST. Compiles to a single camera_animates keyframe track (one camera — WYSIWYG between the editor view and any export size). Great for "give me a camera tour", "pan across the scene", "zoom into each item in turn". ACTIONS: - auto: auto-generate a walkthrough — one medium push-in shot per top-level item, smooth eased moves. Options: order ("reading" default | "reverse" | "creation"), hold (dwell seconds), establishing (open on a wide shot of everything), loop. Returns the generated shots. - shots: apply an explicit shot list. Each shot: { subjects: "everything" | [itemIds], framing: "tight"|"medium"|"wide" (or a zoom number), hold, moveIn ("push-in"|"pan"), ease ("smooth"|"linear"|"settle"|"snap"), transition (seconds to travel in) }. Pair with pinepaper_agent_export (framing: "camera") to render the walkthrough as video. EXAMPLES: - Auto tour: { action: "auto", establishing: true, hold: 1.5, loop: true } - Explicit: { action: "shots", shots: [ { subjects: "everything", framing: "wide", hold: 1 }, { subjects: ["hero_1"], framing: "tight", moveIn: "push-in", hold: 2 } ] }
pinepaper_media37 of 37 parameters describedBring VIDEO and AUDIO onto the canvas from a URL, and control playback. Uploaded video is a first-class canvas item (drag, scale, animate, export like any shape); audio rides the timeline. ACTIONS: - upload_video: { url (required), position?, fit? ('contain' default | 'cover' | 'none' = source pixels), scale? (a multiplier on that fit — with fit 'none', on the source pixels), timeOffset? (timeline start, s) or atPlayhead?: true (start at the current playback time), clipInPoint?, clipOutPoint? (trim, s) } → { id, duration, width, height, name } - upload_audio: { url (required), volume? (0–1, default 1), loop?, muted?, timeOffset? or atPlayhead? } → { id, registryId, duration, name }. Pass loop EXPLICITLY — loop:true for a music bed, loop:false for a voice-over or sting; when omitted, the studio's own default applies and differs between builds. - list: → all media [{ id, kind, duration, … }] - remove: { id } → removed boolean - set_playback_rate: { id, rate (0.25–4) } → applies to video or audio - set_clip: { id, inPoint, outPoint (media-time s, outPoint > inPoint), timeOffset? (canvas s: also MOVE the clip to start there) } → re-trim an ALREADY-uploaded clip (video or audio). A studio that cannot move clips refuses timeOffset rather than ignoring it. - split: { id, at (canvas s) } → cut a clip in two: { leftId, rightId, leftMediaId, rightMediaId, at }. The first half keeps its id. Refused (not claimed) where the studio cannot split or the time is outside the clip. - add_transition: { fromItemId (ends at the cut), toItemId (starts at it), transition?: { type: 'crossfade'|'dip', seconds, color } } → the same in preview and export. Split a clip, then transition between its halves, or join two clips that meet. - For an IMAGE on the timeline, import it with pinepaper_import_image, then give it bornAt / ttl (seconds on screen) with pinepaper_modify_item. NOTES: - The server fetches the URL (or reads a local path / data: URL) and hands the page the bytes, so it does not need to be CORS-permitted. - Use the returned id with set_playback_rate / set_clip / remove, and (for video) modify/animate it like any item. VIDEO EDITING: - set_time_remap: { id, remapTrack: [{time, value, easing?}, …] | null } — canvas-time → SOURCE-time curve: speed ramps, freeze frames, reverse. null restores 1:1. - speed_ramp: { id, segments: [{duration, speed}, …] } — the human way to say a remap. speed 0 freezes, negative reverses. - match_cut: { fromItemId, toItemId, subject? (detect|bounds), label?, at?, settle?, fade?, consent? } — cut between two shots with the SUBJECT aligned across the cut (on-device detection; first use returns {needsConsent, cost} until consent: true). - apply_track_matte: { id, matteItemId, channel? (luma|alpha|red), invert?, strength?, hideMatte?, live? } — the matte item's pixels drive the target's alpha. The classic: a headline filled with footage. live: true keeps the cut tracking an ANIMATING matte (kinetic mask reveal); otherwise it bakes once, destructively (recorded in data.filterChain for round-trip). - stop_live_matte: { id } — stop a live matte, keep the last cut. MAKE ONE LIKE THIS — a reference video's FORMAT, never its content: - analyze_reference: { id, thumbnails? } — the uploaded reference clip (upload_video it first) → cuts (to the frame), shots (length, colours), pacing, beat, and card: the same facts as plain text. Read the card before planning. - remake_from_reference: { texts, duration?, clear? } — builds a new piece on the last analysed reference: one card per shot, cut at its cut times, in each shot's colours, the headline popping on its beats. texts are YOUR words, one per shot. Nothing of the footage, its words or its sound is copied; the reference clip stays in the project muted. One undo step. EXAMPLE: { action: 'upload_video', url: 'https://…/clip.mp4', scale: 0.5, timeOffset: 1 }
pinepaper_text_style13 of 13 parameters describedDisplay TEXT STYLES and variable-font axes — the stacked-layer titles a fill+stroke+shadow cannot make, and weight/width/slant as animatable properties. ACTIONS: - apply_style: { itemId, styleKey, palette?, variant?, content?, fontFamily?, fontSize? } — render a text item as a layered display title (offset copies, outlines, fills). The result GROUP ADOPTS the text's registry id, so existing relations/keyframes/handles keep pointing at it. fontFamily: 'suggested' opts into the face the style was designed around (arcade wants a pixel face — a layer stack can outline any typeface but cannot pixellate one); never automatic. - set_font_axes: { itemId, axes: { weight?, width?, slant? } } — STANDARD variable-font axes only (Canvas 2D has no font-variation-settings, so custom foundry axes are unreachable — platform limit, stated, not silent). Returns {applied, rejected}: CHECK rejected — an axis silently ignored is the failure this surface exists to prevent. All three are ordinary animatable properties: keyframe fontWeight and type breathes between weights. - list_styles: {} — styles + palettes + axes, for pickers. Call this first; styleKey strings come from here. - list: {} — the same as list_styles. - cursive: { text, cursiveOptions?: { x?, y?, scale? (1), strokeColor? ('#ffffff'), strokeWidth? (2), nib? ('monoline' | 'broad' | {angle?, width?, contrast?, taper?}), animate? (false), duration? (2), easing? ('easeOut'), timeOffset? (0), singleStroke?, showGhost?, tension? } } → { itemId, strokes, width } — writes the words as STROKED handwriting, a path rather than a glyph. x, y is where the pen STARTS (the left end of the first letter), not the centre: to centre a word, set x to the centre minus half its width (the returned width; about 125 × scale px for nine letters). showGhost adds a faint full-word outline under the write-on; it does not move the word. animate: true writes it on by itself over duration seconds (from timeOffset), no keyframes needed; otherwise pinepaper_animate's draw-on applies to it. Unknown cursiveOptions keys are refused. - wrap: { itemId, maxWidth } — breaks a text item into lines no wider than maxWidth (canvas units). unwrap: { itemId } — restores the single line; wrap is not destructive. - to_collage: { itemId, text?, collageOptions? } — rebuilds a text item as a letter collage (same vocabulary as pinepaper_create_letter_collage); text defaults to the item's content. OVER PHOTOGRAPHS, PASS A PALETTE — NEVER THE DEFAULT. Measured on a real render of captions over photographs: highlighter, sticker, caption and badge read correctly at the default palette. neon needs one on a dark photo. chrome, cutout and glitch are off-brief at the default palette over any photograph — they are designed against flat backgrounds and the default palette assumes one. A style that is hard to read still reports success, so this is a judgement the tool cannot make for you. MEASURE THE WIDTH BEFORE COMMITTING TO A SIZE. glitch at 80px in a monospace face overflows a 1920 canvas at 36 characters. Layered styles draw offset copies, so the group is WIDER than the text — use 'wrap' first, or shorten the line, rather than discovering it in an export. EXAMPLE: { action: 'apply_style', itemId: 'title_1', styleKey: 'arcade', fontFamily: 'suggested' }
pinepaper_design_medium32 of 32 parameters describedThe THIRD design axis: the MEDIUM — what physically makes the marks. Register is which design language a piece speaks; level is how well it is executed; a medium is a set of physical constraints that produce characteristic marks. All three are independent: an embroidered schematic is a technical register at a refined level in a thread medium, and no single better/worse ranking can say that. READ THIS BEFORE PROMISING A MEDIUM. Naming a medium does not create its marks. Every medium declares a FIDELITY: - native — the characteristic marks ARE vector geometry (vector, thread, ink, cutPaper) - stylised — a recognisable impression; the limitation is stated on the entry (charcoal, oil) - absent — no vertex-level expression; the tool REFUSES with the reason instead of producing flat shapes in its colours (encaustic) Call resolve before telling a user you will render in a medium. "yes, but as an impression" is the true answer for half of them, and a flat approximation misrepresents a medium rather than approximating it. ACTIONS: - apply: { itemId, medium, options? } — on a PHOTO (an image item), watercolor and oil run as the watercolor / painterly image filters and report fidelity 'stylised' (an image filter, not paint simulated over geometry); other media are refused for photos, with the reason. On shapes — render an item in ANY medium the engine can make: thread, ink, watercolor, hatch, cutPaper, charcoal, oil. One engine entry point; a medium this studio cannot apply is refused with the reason: pass it on. ink / charcoal (where the studio applies them) restyle a path, text, or group of them IN PLACE — same itemId, keyframes and relations kept — with a boiling hand-drawn line; raster and video exports boil, SVG/Lottie get the colour and width only. Their options: color, amplitude (px), wavelength (px), fps (boil rate, 12), seed, boil (default true), width (px, paths), keepColor. watercolor options: color, brush, water 0..1, opacity, edge 0..1 (the dark rim), angle, bleed, seed. oil (stylised): color, brush, length, density, toneRange, relief, angle, seed. cutPaper (vector: survives SVG/PDF/video): color, facet, jitter, shadow, shadowColor, shadowOpacity, shadowOffset [dx, dy], seed. The result replaces the source in the stacking order and hides it; applying again replaces; one undo step. - ink colour: unless options.color or options.keepColor is given, ink marks are drawn in the brush default, a near-black (#16141c), whatever the item's own colour. On a dark background they disappear: pass options.color (a light ink) or options.keepColor: true (the item's own colour). - list_media: every medium with fidelity, definition and limitation. Read it rather than assuming a fixed set — the catalogue grows (hatch and watercolor are recent additions). - resolve: { medium } → { ok, fidelity, reason, markMaker }. ok:false with a reason is a real answer — pass it on rather than trying anyway. - list_stitches: the thread stitches with their params. - apply_thread: render an item in thread. Its own silhouette is the region and its own fill is the thread colour, so an existing drawing becomes stitched rather than needing to be redrawn. The source is HIDDEN, not destroyed. - apply_hatch: rule an item with hatching. Same deal — silhouette is the region, source is hidden, re-hatching replaces. - list_flow_fields: the 7 fields that bend a hatch line. - list_hatch_options: the hatch defaults. - sdf_stroke: { points, width? (8), softness? (0.2), color?, opacity?, resolution? (2), name? } → itemId — a smooth, anti-aliased brush stroke along points ({x, y, pressure?} or [x, y, pressure?], canvas px; pressure 0..1 thins the line there), made as an image item (registered, one undo step). Runs on the CPU; a stroke too large for its bitmap budget is refused with the fix. A studio without the SDF brush refuses with the reason. THE DIRECTION FIELD IS THE WHOLE THING. Stitches that all lie the same way are hatching; stitches that follow the form are needlep…
pinepaper_text_effect11 of 11 parameters describedAnimate text CHARACTER BY CHARACTER — the terminaltexteffects vocabulary, reimplemented from source). ⚠️ THIS REPLACES THE TEXT ITEM. Unlike pinepaper_text_style (which ADOPTS the text's registry id), this EXPLODES the text into one item per character and REMOVES the original. Any relation, keyframe, or handle pointing at the source id DIES with it. Pass keepSource: true to leave the original in place. The returned `ids` array is your entire new handle set. ACTIONS: - list: {} — every effect as {key, label, definition}. Call this first; effect keys come from here. - apply: { itemId, effect, duration?, seed?, gradient?, gradientStops?, gradientDirection?, gradientSteps?, keepSource?, options? } — explode and animate. WHAT YOU GET: ordinary keyframe-animated items. It scrubs on the timeline, survives undo and session restore, and exports through the existing MP4 / SMIL / Lottie paths — this is not a frame-callback effect that renders on screen and vanishes from your export. Every effect ends AT REST, so `duration` is the settle time and the text is readable afterwards. COLOR: by default the resting characters are painted with a GRADIENT across the text block — that is what the upstream effects do and what their reference frames show. Pass gradient: false to keep the text's authored fill, or gradientStops to choose your own. DETERMINISM: seed defaults to 1, so the same text + effect + seed animates identically every run. Vary seed for a different scatter of the same effect. EFFECT KEYS (37): scattered, expand, spray, slice, bouncyballs, pour, slide, print, randomsequence, wipe, sweep, highlight, middleout, fireworks, blackhole, unstable, crumble, rings, swarm, orbittingvolley, overflow, decrypt, errorcorrect, matrix, binarypath, rain, burn, smoke, thunderstorm, bubbles, waves, beams, laseretch, spotlights, synthgrid, vhstape, colorshift. EXAMPLE: { action: 'apply', itemId: 'title_1', effect: 'decrypt', duration: 3, gradientStops: ['#00ff9c', '#0066ff'] }
pinepaper_design_system12 of 12 parameters describedLicensed design systems (Material 3, Carbon, Polaris, Fluent 2, USWDS, GOV.UK…) as W3C DTCG tokens, plus 18 aesthetic styles that compose a scene. list_systems | get_system | list_easings (named curves with licence + authored provenance) | list_motion (the curves plus the duration scale) | list_styles | compose (draw:false returns the scene as data; compose sets the canvas to the size it laid out for, and says so).
pinepaper_stick32 of 32 parameters describedThe vendored stick-figure kit. figure: pose, walk, travel, prop, garment, hair, expressions over time. set: kind room (floor + wall) | tabletop (object, surfaceY) | chair (facing) | table | counter | door | shelf (items) | window. Distinct from pinepaper_character, which places a figure from the design graph by concept.
pinepaper_story6 of 6 parameters describedProse becomes a scene. distill (beats only, draws nothing), from_text (distill + assemble), apply_spec, plan_book.
pinepaper_interchange4 of 4 parameters describedInterchange formats the platform exporter does not cover: export_lottie, export_dotlottie, import_lottie, export_glb (needs perspective objects), export_bvh (needs a rig, skeletonId), export_png_sequence (pass duration and fps). Exports are written to a FILE; the result gives filePath. import_lottie takes the Lottie JSON itself (object or string), not a URL or path, and returns itemId.
pinepaper_sound24 of 24 parameters describedSynthesis. Catalogues: list_instruments|list_percussion|list_sfx. Play: play_tone|play_chord|play_percussion|play_sfx|play_spec|play_from_text. Read: chord_frequencies|from_text|timbre_from_path. Canvas: create draws a sound AS an editable waveform path; sequence {cues: [{t, spec | preset + note}]} places a whole bed in one call; set_placement {itemId, placement: {startTime, duration}}; remove {itemId}; stop_all. timbre_from_path reads any drawn path back as harmonic content. Define: define_instrument {name, partials} | define_percussion / define_sfx {name, partials or noise}. render_soundtrack writes every placed sound to a WAV file. play_tone takes note ('A4'), not hz; a play with no voice fails.
pinepaper_world3d40 of 40 parameters describedA real 3D WORLD under the canvas — depth-buffered terrain, sky, sun shadows, an addressable actor stage and a directed camera. ADDITIVE: Paper.js keeps every vector item, hit-test and export path; the world composites underneath the (transparent) Paper canvas. ACTIONS: - create: { spec? ('forest' | 'snowMountain' | 'field' | 'jungle' | a full spec object), character? (true/config → a walkable character), control? (true: a viewer walks the character with the keyboard — arrows/WASD, Space jumps, Shift runs — when the scene plays in the studio; the editor's own shortcuts pause while it is on) } → { configurableKeys, control } - describe: {} → the ENGINE'S OWN parameter schema — every world parameter with type, range and description. Call this before configure; the tool does not restate the schema, so it cannot drift from the engine. - configure: { patch } — live deep-merged change to anything describe lists (colours, fog, sun, terrain amplitude/ridge, seed…). Schema-validated: a wrong key errors NAMING the right one, never a silent no-op. - add_actor: { actorId?, x, z, height?, sprite? (a canvas item id), live? } → { actorId }. live: true re-rasterizes the item as it animates — a RIGGED character (walk cycle, expressions) PERFORMS in the world instead of standing there as a photograph of itself. - remove_actor / list_actors / set_actor_pose: { actorId, pose: { x?, z?, angle? } } — the setter a timeline, sequencer or agent drives frame by frame. - set_camera: { camera: { mode: 'follow' | 'fixed' | 'orbit', target? (actorId), radius?, speed?, eye?, lookAt? } } - add_object: { object: { x, z, height?, color? } } (y defaults to sitting ON the terrain) / remove_object: { objectId } - remove_world: {} — tears the world down; the Paper canvas was always its own layer and is untouched. UNITS: positions, sizes, ranges and radii are WORLD units (metres). rotY is RADIANS everywhere on the mesh path (pass mesh.rotYDegrees to write degrees); lathe arc is DEGREES. Colours take hex or [r, g, b] in 0..1. These act on an existing world: call create first. MESHES — a canvas path becomes real geometry: - extrude_path: { pathId, mesh?: { id?, depth? (1), unitsPerPixel? (0.01: canvas px → world units), upright? (stand the drawing up; default flat, a floor plan), placement? ('centered' default: centred on x/z, base at y | 'canvas'), caps?, segments?, flatness?, x?, y?, z?, rotY?, rotYDegrees?, scale?, doubleSided?, color?, metalness?, roughness?, uniforms? } } → { meshId }. The path is unchanged. - lathe_path: { pathId, mesh?: same fields, plus arc? (DEGREES, 360 = full solid); segments? = steps round the revolution } → { meshId } - list_meshes: {} → { count, meshes } (long vertex arrays summarised to their length) - remove_mesh: { meshId } - set_mesh_instances: { meshId, instances: [[x, y, z, scale, rotY (RADIANS), variant], …] } — replaces the copies a mesh draws, six numbers each. LIGHTS — point lights, at most 8 (the ninth is refused by name): - add_light: { light: { id?, x? (0), y? (3), z? (0), color? (hex or linear [r, g, b], may exceed 1), intensity? (6), range? (20) } } → { lightId, light } - set_light: { lightId, light: any of the add_light fields } — moves or retunes in place. - remove_light: { lightId } · list_lights: {} → { lights } MATERIALS — a NAMED, SHARED surface: one edit restyles every object using it. - add_material: { material: { id?, color?, emissive?, emissiveIntensity?, metalness? (0..1), roughness? (0..1), clearcoat?, clearcoatRoughness?, sheenColor?, sheenRoughness? } } → { materialId, material }. metalness / roughness reach pixels on the MESH path only. - set_material: { materialId, material: any of the add_material fields } · remove_material: { materialId } · list_materials: {} → { materials } IMPORT: - import_obj: { source (the .obj file TEXT), importOptions?: { id?, x?, y?, z?, rotY? (RADIANS), scale?, doubleSided?, uniforms?, color? ([r, g, b] 0..1; .mtl is never read) } } → { meshIds, warnings } - import_gltf: { s…
pinepaper_character13 of 13 parameters describedPlace a CHARACTER from the design graph and DIRECT it — no geometry, no bones, no poses. The knowledge of how a figure is built and how it moves lives in the graph; this asks for it by name and states WHAT happens. The alternative is thirty-odd exactly-right calls — create the skeleton, add each bone with the right parent and angle, create each shape, attach each to the right bone, then author poses — where one mistake anywhere leaves a broken figure. { concept: "pp:Character", at: { x: 470, y: 250 }, height: 300, beats: [ { at: 1.0, channel: "blink" }, { at: 1.8, channel: "say", until: 4.2 }, { at: 5.0, channel: "headTurn", value: -0.8 } ] } CHANNELS ARE DECLARED BY THE CONCEPT, not by you. Ask pinepaper_query_ontology for a concept to see the ones it has. Four kinds exist: - transform: one part deformed with an attack, a hold and a release — a blink is the eyes flattening in scaleY and easing back. This is what gives a gesture a MIDDLE; a swap between two drawings has only two ends and reads as flashing. - cycle: a repeating throw that runs for as long as you ask — a pigeon's head bob, a tail flick. Amplitude is a fraction of the part, so it means the same at any size. - shift: every part moved together, for a turn a flat drawing cannot rotate into. - alternate / speak: swaps between drawn states, for shapes that genuinely differ rather than deform. BEATS ARE INSTANTS OR SPANS. `at` is when it happens; `until` is how long for a channel that occupies time. `value` is how far, for channels that take a magnitude. WHAT YOU GET BACK: the items and keyframe tracks the beats compile to. They are ordinary scene items afterwards — modify, animate and relate them like anything else. WALKING, POSES, ACTIONS: a concept character moves through its channels and has no skeleton, so a walk, a pose or a rigging call acts on nothing (and the reply says so). For a figure that walks, poses and acts, make it with pinepaper_original_character, which is rigged. NOT LIP SYNC. `say` opens and closes a mouth for the length of a line. Matching phonemes needs the word timings a voice track carries; pass `timings` if you have them and each entry drives one mouth opening.
pinepaper_rigging55 of 55 parameters describedRig and animate with SKELETONS — bones, IK chains, and pose keyframes (FxTool RiggingSystem). Build a skeleton, attach canvas items to bones, then drive it with poses. Includes the S12 "breakdown-pose" controls that turn robotic pose-to-pose into believable motion. WORKFLOW: create_skeleton → add_bone (×N, parent them into a hierarchy) → attach_item (bind shapes to bones) → optionally create_ik_chain → animate with add_pose_keyframe (or save_pose then reference it). POSE MOTION — build a performance out of saved poses: - START HERE on a rig you did not build yourself: list_bones gives the ids an inline pose needs ({ boneId: angleDeg }), and list_pose_libraries + load_pose_library give a fresh rig a stock walk/run/jump set to work with. A newly rigged character has ZERO saved poses, so without one of these there is nothing to sequence. - save_pose / list_poses / load_pose / interpolate_poses: the pose library. A pose is a snapshot of bone angles; everything below is a graph over these. - play_pose_sequence: one clip. Keys name a saved pose id or an inline { boneId: angleDeg } map. ONE sequence per skeleton — starting another replaces it. - stitch_poses: join CLIPS into one continuous performance (walk ×3 → jump → land → idle) and install it as a single sequence. This is how you get a transition rather than a cut. · A cyclic clip (loop: true) is entered at the phase CLOSEST to where the previous clip ended, so the legs do not teleport mid-stride. matchPhase: false to disable. · Every seam reports 'residual' — the angular mismatch, in degrees, that the blend could not remove. Near zero is a real match; a large number means the blend is HIDING a cut. Read it. · plan: true returns the seams without touching the skeleton, so you can check the joins first. - move_root: a deterministic locomotion track, keyed in SCENE SECONDS on the same clock as the pose sequence. Without it a walk cycle is a march on the spot; with a last keyframe shorter than the performance, the figure arrives early and stands there. - auto_walk / auto_breath / auto_idle / auto_jump: one-call procedural layers. breath and idle find their bones BY NAME (spine/chest/body, head/hip/spine) and refuse with that list if the rig uses other names. - bake_animation: { skeletonId, options?: { duration? (2), fps? (30), detach? (true), write? (true) } } → { written, keyframes, detached, wrote } — freeze the whole rig into plain item keyframes for export. Needs items ATTACHED to bones. It DETACHES the items (the bones stop driving them, so the keyframes are what plays); pass options.detach:false to keep the rig driving. - add_secondary_motion: spring chains for tails, hair, cloth. skin_path: per-vertex deformation of a curved path. ACTIONS: - create_skeleton: { name?, rootPosition? } → { skeletonId } - add_bone: { skeletonId, name?, parentBoneId? (omit for root), length? (80), angle? (deg), flexibility? (0 rigid…1), segments? } → { boneId } - attach_item: { skeletonId, boneId, itemId, attachPoint? (0 joint…1 tip, 0.5) } - create_ik_chain: { skeletonId, boneIds[] (≥2, ordered), solverType? (fabrik|two_bone|ccd), iterations?, tolerance?, strength?, poleVector? } → { chainId } - add_pose_keyframe: { skeletonId, time (s), pose (a saved pose id OR a { boneId: angleDeg } map), easing?, and BREAKDOWN controls: favor? (−1..1 spacing bias), breakdown? (flag), curve? ([x1,y1,x2,y2] cubic-bezier ease, overrides easing), boneOffsets? ({ boneId: 0..0.95 lag } for overlap/follow-through), movingHold? (drift a held pose toward the next key), holdDrift? } - set_target_path: { skeletonId, chainId, waypoints[] ({x,y,out?,in?} bezier tangents), duration?, loop? } — the IK effector travels an ARC, not a straight line - save_pose: { skeletonId, name? } → { poseId } (snapshot current bone angles) - save_shape_key: { skeletonId, name? } → { shapeKeyId } (per-item visual delta for facial-style blends) - import_bvh: { bvhText, view? (side|front), fps? (15; 0 = every frame), height? (320px), r…
pinepaper_lint_scene4 of 4 parameters describedAudit the LIVE scene's relational structure (FxTool S12-E2) — read-only, nothing is changed. Answers "is this scene composed with relations, or just a pile of absolutely-positioned items?" and proposes fixes. RETURNS: - relations: every relation bound — [{ from, fromName?, to, type, params }], the first 200 (relationCount says how many when there are more). Relations bound by a name pattern ("dot-*") are listed once per group in edit.groups instead (groupedRelations counts them). Use it to find the relation to change, then a batch relation op with update: true. - customRelations: each pinepaper_register_custom_relation definition the scene uses (name, params; computeFunction / applyFunction with withSource: true). registeredUnused names any registered that no relation uses. - edit: the exact ops that change this scene (per relation, per group with add / remove member ops; per custom motion with withSource: true, since the call that redefines one needs its source). With only: 'edit' the reply is just this section. - density: { itemCount, relationalItemCount, relationalDensity (0..1 — fraction of items touching the relation graph), edgeCount, componentCount }. A low relationalDensity means items are placed by hardcoded coordinates and won't hold together if something moves. - suggestions: structural relations for unrelated item pairs that ALREADY sit in a structural configuration — [{ from, to, type (on_top_of/below/beside/inside/centered_on/aligned_with), params, confidence }], ranked by confidence. Apply the good ones with pinepaper_add_relation to make the layout robust. USE WHEN: - After building a scene, to check it's relation-driven rather than coordinate-driven - To discover which items SHOULD be related (labels on shapes, a badge on a card, stacked elements) but aren't - Before export, as a composition-quality gate PARAMS: { eps? (bounds-match tolerance px, default 4), cap? (max suggestions, default 20), only? ('edit'), withSource? (custom relation source, default false) }
pinepaper_add_relation6 of 6 parameters describedAdd a behavior relation between two items (orbits, follows, attached_to, etc.). Relations are compositional — an item can have multiple. RELATION TYPES: orbits, follows, attached_to, maintains_distance, points_at, mirrors, parallax, bounds_to, anchored_in_world, spring_follow, repels, attracts, wiggle, animates, grows_from, staggered_with, indicates, circumscribes, wave_through, morphs_to, group_morphs_to, moves_along_path, construction_reveal, triggers_animation, then, after, on_complete, at_beat, phase_wave, ring_forming, flock, soundtrack_cue, syncs_with, tours, synced_to_audio, localizes_sound, expresses, camera_follows, camera_tracks, camera_animates, is_midpoint_of, lies_on_line, is_centroid_of, is_circumcenter_of, concentric_with, driven_by, time_expression, on_click_fire, on_pointer_enter_fire, on_pointer_exit_fire, on_key_fire, on_event_fire_after, on_event_fire_if, on_event_add_relation, on_event_remove_relation, on_event_set_color, on_event_set_property, on_event_set_property_from_template, on_event_set_visibility, on_event_set_active, on_event_step_active, on_event_set_data, on_event_increment, on_event_toggle, on_event_store_set, on_event_store_increment, on_event_play_sound, looks_at, reacts_to, drag_to_turn, on_enter_set_color, on_enter_set_property, on_enter_set_property_from_template, on_enter_set_visibility, on_enter_set_data, on_enter_increment, on_enter_toggle, on_exit_set_color, on_exit_set_property, on_exit_set_property_from_template, on_exit_set_visibility, on_exit_set_data, on_exit_increment, on_exit_toggle, exclusive_group, menubar_group, restores_from, on_top_of, below, beside, inside, centered_on, aligned_with, part_of, connects_to, attached_to_tail, head_points_to. A name registered with pinepaper_register_custom_relation this session is accepted too. UNITS: orbits speed is revolutions per second (0.5 = one turn every 2 s); angles are degrees.
pinepaper_register_custom_relation8 of 8 parameters describedSECURITY SWITCH: needs a server started with PINEPAPER_ALLOW_CODE=1 (off by default; only the person running the server can turn it on). Otherwise it is refused and nothing runs. PARAMS ARE DEFINITIONS, not values: { gap: { type: 'number', default: 60, min: 0 } } (type is number | string | boolean | array | object). Once registered, the name is a valid relationType for pinepaper_add_relation in this session. Register a custom relation type with compute and apply functions. For motion without code, use time_expression. USE WHEN: - Creating physics-based behaviors (attraction, repulsion, collision) - Building custom animation effects not covered by built-in relations - Implementing game mechanics (health bars following characters, damage indicators) - Creating procedural animations (wobble, shake, spring physics) COMPUTE FUNCTION (runs in Web Worker - pure math only): - Receives: ctx = { fromPosition: {x,y}, toPosition: {x,y}, params, delta, time } - Must return: object with computed values (e.g., { x, y, rotation, scale, opacity }) - No DOM access, no Paper.js - pure JavaScript only - Must be stateless APPLY FUNCTION (runs on main thread - can use Paper.js): - Receives: item (paper.Item), target (paper.Item), computed (from compute), params - Updates actual Paper.js item properties - Can access full Paper.js API EXAMPLE - Repulsion: computeFunction: ` const dx = fromPosition.x - toPosition.x; const dy = fromPosition.y - toPosition.y; const dist = Math.sqrt(dx * dx + dy * dy); if (dist > params.maxDistance) return fromPosition; const force = (params.maxDistance - dist) / params.maxDistance * params.force; return { x: fromPosition.x + (dx/dist) * force * delta, y: fromPosition.y + (dy/dist) * force * delta }; ` applyFunction: ` if (computed) { item.position.x = computed.x; item.position.y = computed.y; } `
pinepaper_execute_custom_code2 of 2 parameters describedSECURITY SWITCH: needs a server started with PINEPAPER_ALLOW_CODE=1 (off by default; only the person running the server can turn it on). Otherwise it is refused and nothing runs. Execute arbitrary JavaScript code in the PinePaper context. USE WHEN: - Advanced Paper.js operations not covered by other tools - Complex mathematical calculations - Custom item registration - Accessing PinePaper APIs directly - Prototyping new features - A scene whose repetition is the point: dozens of items built in a loop. This is the cheapest route by an order of magnitude — a 63-item animated scene is ~4k characters here against ~147k as keyframe tool calls — because the loop collapses the repetition instead of restating it per item. Synchronous build work is bounded by the governor's 4s deadline, which such a scene fits easily. ENGINE SEMANTICS THAT BITE RAW-JS AUTHORS. The tool schemas protect tool callers from these; writing JS opts out of that protection, and each of these fails SILENTLY: - app.create() returns a Paper.js item whose .id is a NUMBER. The id every tool and relation wants is the STRING at item.data.registryId ('item_1'). Passing the number to addAnimation throws "Cannot create property 'data' on number". - app.create() with an unknown type returns undefined and creates nothing — 'rect' is not 'rectangle'. The schema catches that for tool callers; a loop does not. - app.addAnimation(id, keyframeArray, options) takes a real ARRAY. A JSON string installs nothing, silently, and the scene exports frozen. It also returns without error on an id that does not resolve. - Keyframes live at item.data.keyframes. app.keyframeItems is not the live store, so probing it reports false negatives. - transformOrigin is IGNORED by the keyframe engine: rotation always pivots on the item's bounding-box centre (the same point as its position). On an asymmetric shape (triangle, star, text) that is not the shape's centroid, so it swings slightly off the visual middle; a full turn returns it home. For true joint pivots use pinepaper_rigging bones, or keyframe computed x/y per joint. - Bone angles are RADIANS in the engine and relative to the parent, though pinepaper_rigging converts degrees for you — that conversion is the tool's, not the engine's. WHAT THE CHEAP ROUTE COSTS, so the choice is deliberate: items built and animated in raw JS carry NO behavioral record. No graph edge, nothing SMIL or widget export can lift, nothing the ontology can read — the scene renders and cannot describe itself. Relations are the canonical behavior surface here, so for motion that is a function of time prefer pinepaper_add_relation with 'time_expression' (still ~5.7x cheaper than keyframes), and for a whole group moving together staggered_with or wave_through. Reach for a loop when the geometry is procedural, not merely to avoid the typing. AVAILABLE GLOBALS: - app: PinePaper application instance - app.create(type, params): Create items - app.executeGenerator(name, params): Run a generator — including a CUSTOM one you defined as app.<name> = function(params, options) { ...draw with paper... }. That is the whole draw contract: no registration step is required - app.registerItem(item, type, properties): THE DECISION THAT MATTERS when you draw your own. It returns a registry id and makes that item a first-class object: the USER can click it, select it and change its colour, and you can address it afterwards with modify_item, animate it, keyframe it, point a relation at it, or read it back through get_items and the ontology. An UNregistered path is pixels — it renders and exports identically, and nothing can ever touch it again without redrawing the scene. So register what someone might want to change (the kettle, the title, the sun) and leave the bulk unregistered (a thousand snow specks, a hatch field), which is exactly why generator output is only partly registered: it is a memory decision, and when you write the generator it is YOUR decision - app.addAnimati…
pinepaper_animate7 of 7 parameters describedApply a simple LOOP animation to an item. These are continuous animations that repeat infinitely. USE WHEN: - "make it pulse" → animationType: pulse - "rotating logo" → animationType: rotate - "bouncing text" → animationType: bounce - "fading effect" → animationType: fade - "wobbling button" → animationType: wobble - "sliding header" → animationType: slideLeftRight (or slideUpDown) - "scrolling banner" → animationType: scrollLeft (also scrollRight/Up/Down) - "typewriter effect" → animationType: typewriter (text only) DO NOT USE WHEN: - User specifies exact timing ("fade in over 3 seconds") → Use keyframe animation - User wants sequential animations ("first fade, then rotate") → Use keyframe animation - User describes relationships ("orbit around") → Use relations ANIMATION TYPES (18 — the list the driver actually switches on): - pulse: Scale up/down rhythmically - breathe: A slower, softer pulse - rotate: Continuous rotation - swing: Pendulum rotation about the top - bounce: Vertical bouncing motion - jelly: Squash-and-stretch wobble - shake: Rapid small displacement - wobble: Side-to-side wobbling - fade: Opacity cycling - glow: Cycling luminance - slideLeftRight / slideUpDown: Sliding on one axis - scrollLeft / scrollRight / scrollUp / scrollDown: Continuous scroll, wrapping - path: Travel along an assigned path - typewriter: Character-by-character reveal - ripple: An opacity wave. On a GROUP it sweeps through the children outward from origin, each a little later; on a single item it pulses the item. - undulate: A vertical lift wave, swept through a group's children the same way (intensity 0.4 ≈ 14 px). ripple and undulate take waveform (the shape of one cycle) and origin (where the wave starts on a group). SVG and Lottie exports draw them static; export MP4, WebM or GIF to keep the wave. There is NO 'slide'. An unknown type is stored and then ignored — the item sits still while its data claims otherwise, and the call still reports success — so use the exact names above.
pinepaper_keyframe_animate12 of 12 parameters describedApply keyframe-based animation with precise timing and property control. USE WHEN: - "fade in over 3 seconds" - "move from left to right in 2 seconds" - "change color from red to blue" - "first fade in, then rotate, then fade out" - Any animation with specific timing or sequential stages BEFORE AUTHORING DENSE TRACKS — three routes are cheaper, and two of them keep the scene describable. Measured on the same 63-item, 32-keyframes-each scene: - Motion that is a FUNCTION OF TIME (bob, pulse, sweep, phase-offset wave) → pinepaper_add_relation with relationType 'time_expression'. One call per property instead of one keyframe per sample: 26k characters against 147k. It also survives into the design graph, save/reload and widget export, which keyframes generated from a formula do not describe. - PER-ITEM VARIATION across many items → staggered_with or wave_through express the whole group in ONE call. That collapses the 63-fold repetition a per-item time_expression still pays for. - GENUINELY PROCEDURAL scenes → pinepaper_execute_custom_code with app.create + app.addAnimation (which attaches keyframe tracks programmatically, so the keyframes are generated rather than typed), at 4k characters for the same scene — cheapest by an order of magnitude, because a loop collapses the repetition entirely. The trade is real and worth making deliberately: raw JS leaves NO behavioral record — no graph edge, nothing SMIL or widget export can lift, nothing the ontology can read. Scene building fits the governor's 4s synchronous deadline easily (it is the injected loop guards, not the 10s async-tail budget, that bites a build loop). - TEXT THAT CHANGES OVER TIME -> 'content' IS keyframeable, and it is DISCRETE: it holds the current word until the next keyframe and does not tween. One thing worth knowing before you build a cascade out of it. A cascade of N words is N keyframes you have to write out, which is the reason to prefer the call below rather than any limitation. For the common case prefer pinepaper_execute_custom_code with app.textSequence(itemOrId, words, { interval }): ONE item cycling its words in one call, against one item per word with opacity tracks faking the cut. It returns { ok: false, reason } on an id it cannot resolve. Keyframes are for motion that is AUTHORED, not computed. A track of hundreds of entries produced from a formula is the signal that one of the three above is the right route. ANIMATABLE PROPERTIES: - position: [x, y] array (a { x, y } object is also accepted and normalized) - x, y: Individual coordinates - scale: Uniform scale - scaleX, scaleY: Axis scaling - rotation: Degrees. Keys interpolate as plain numbers, with no short way round: 350 to 10 sweeps back through 180. Key 350 to 370 to cross zero. - opacity: 0-1 - fillColor: Color string - strokeColor: Color string - strokeWidth, width, height, radius, shadowBlur, shadowColor: Numbers / colours - fontSize: Number - skewX, skewY (current studio): degrees, clamped to ±89; they combine with rotation and scale. An older studio stores them without drawing and the result names them in ignoredProperties; there, a shear is a transform matrix track. - TEXT (current studio): fontStyle ('normal' / 'italic' / 'oblique', discrete — switches at the next key), textAlign ('left' / 'center' / 'right', discrete; the anchor stays put), lineHeight (px, or a multiple of fontSize up to 5), letterSpacing (px, or a CSS length such as '0.1em'), wordSpacing (px or a CSS length), textTransform and textDecoration (discrete). An older studio stores these keys without drawing them; the result names any it did not animate (ignoredProperties). fontWeight keys STEP: a font with fixed weights switches from one weight to the next once, partway through the move, and does not ramp (a variable font ramps). Key fontSize or scale for a smooth change. Where the studio measures it, the reply's governor.engineWarnings says so: font_weight_snap { from, to, at, atTime } (at: the weight where the face c…
pinepaper_get_animatable_properties1 of 1 parameter describedWhich properties can be animated — on an ITEM, or on each mask type. - With { itemId }: what THAT item can animate, filtered by its type, from the engine's own table. Each entry carries an 'interpolates' flag, and two of them are FALSE: content and blendMode are DISCRETE — they hold until the next keyframe rather than blending toward it. Treating content as tweenable is what makes every word in a cycler land half a beat early. The result also reports the default easing and every easing name the engine accepts. - With no itemId: the older MASK-TYPE table. Needs a studio that publishes the item-side table; without one, the tool says so and pinepaper_keyframe_animate's own ANIMATABLE PROPERTIES section is the fallback.
pinepaper_manage_scenes7 of 7 parameters describedManage multiple saved scenes (canvas snapshots). Save, load, organize, and transfer scenes for multi-scene storyboards and presentations. ACTIONS: - save: Save current canvas state as a named scene. Params: name (string) - load: Load a saved scene onto canvas. Params: sceneId, transition (none|fade|zoom-in|zoom-out) - list: List all saved scenes with metadata - delete: Delete a scene. Params: sceneId - rename: Rename a scene. Params: sceneId, name - duplicate: Clone a scene. Params: sceneId - reorder: Reorder scenes. Params: sceneIds (ordered array) - info: Get scene details. Params: sceneId - export: Export all scenes as JSON - import: Import scenes from JSON. Params: scenesJson, merge (boolean) WORKFLOW — Multi-Scene Storyboard: 1. Create your first scene → save(name: "Intro") 2. Clear canvas, create second scene → save(name: "Chapter 1") 3. Repeat for all scenes 4. Use pinepaper_scene_playback to play them as a slideshow
pinepaper_scene_playback10 of 10 parameters describedControl sequential scene chain playback — play saved scenes as a slideshow presentation. ACTIONS: - create_chain: Create a playback chain from scene IDs. Params: sceneIds (array), loop (bool), autoPlay (bool), defaultDuration (seconds), defaultTransition (none|fade|zoom-in|zoom-out), transitionDuration (seconds) - play: Start playing the chain - pause: Pause playback - resume: Resume paused playback - stop: Stop playback and reset - toggle_loop: Enable/disable looping. Params: enabled (bool) - jump: Jump to specific scene index. Params: index (0-based) NOTE: defaultDuration and transitionDuration are in SECONDS (converted to ms internally). EXAMPLE — Slideshow: 1. Save 3 scenes with pinepaper_manage_scenes 2. create_chain with sceneIds, defaultDuration: 5, loop: true 3. play
pinepaper_compose18 of 20 parameters describedArrange items into a NAMED COMPOSITION and film it — "here are four photos, lay them out nicely and give me a clip". ACTIONS: - list_patterns: ~25 patterns with slot counts and when-to-use definitions. CALL THIS FIRST and CHOOSE FROM THE LIST — do not fall back to a remembered favourite. The catalogue spans media grids, no-crop mosaics, typographic cards (title, quote, magazine cover, before/after), vector slots (badge, logo lockup), and video shapes (lower-third, picture-in-picture). - list_reveals: temporal reveals (how items ARRIVE over time — staggers, cascades, beat-driven hard cuts). A composition without a reveal is a still. - list_styles: visual style bundles (tone treatments + spacing + the motion each implies). - apply: Arrange items. Params: pattern, itemIds (IN SLOT ORDER — the order is the composition), reveal + revealOptions ({ duration, beats }), style, text (fills the pattern's own text slots), assets (SVG for vector slots), audio + grid (beat-sync the cuts to a track), treatment, applyCamera, craft. - list_treatments / set_treatment: camera treatments; re-film via rootId. PICKING WELL: match the pattern to the CONTENT (count, aspect ratios, whether type or video is involved) — the list_patterns definitions state this per pattern. Vary reveals and styles across a session; identical choices on every scene is a sign the list was never consulted. WHAT THIS RETURNS, AND WHY IT MATTERS: apply positions ONE root and wires structural relations (beside / below / on_top_of) for the rest — it does not set a coordinate per item. The composition therefore stays live: move the root and everything follows, swap in a taller image and its neighbours re-flow. It also records pp:composedAs / pp:fillsSlot so the scene can be queried and re-filmed later. Prefer this over positioning images yourself. Hand-placed coordinates are what pinepaper_lint_scene flags as a badly-composed scene, and they do not survive an artboard change.
pinepaper_brand_kit5 of 5 parameters describedApply a brand kit — colours, fonts and roles — across the scene. ACTIONS: - plan: Report what WOULD change (count, per-role breakdown, WCAG contrast audit) WITHOUT touching the canvas. Call this first on an unfamiliar scene; a whole-scene recolour is hard to eyeball afterwards. - apply: Commit it. A history snapshot is taken FIRST, so one undo puts everything back. - set: { kit } — apply it AND make it the ACTIVE brand for the rest of the piece: every shape created afterwards (create_item, batch create, agent_batch_execute) takes colors.primary, and every text colors.text with the heading font from 32 px up (body below), wherever the call names none. Pass noBrand: true in an item's properties to opt it out. Use set at the start of a multi-beat piece so beat 5 matches beat 1. It lives with the studio session: set it again after a reload. - get: the active brand (or null). clear: stop inheriting (what is on the canvas keeps its colours). - from_url: { url, screenshots? } — read the product's REAL brand from its own site before animating anything: screenshots down the page, the logo (header image or SVG, else the site icon), and a proposed kit from the colours and fonts the site's CSS computes (buttons and links weigh most). Saved to files; the result lists them. Read in an isolated browser context: the studio is not touched. Review the kit against the screenshots, then plan / apply it. Use the brand you are given, never an invented one. KIT SHAPE — only name and colors.primary are required: { "name": "Acme", "colors": { "primary": "#e11d48", "secondary": "#0ea5e9", "accent": "#f59e0b", "background": "#ffffff", "text": "#111111" }, "fonts": { "heading": "Inter", "body": "Inter" } } Missing roles are filled from what is present (secondary←primary, accent←secondary, background←white, text←whatever is readable on the background) and reported as warnings, so a kit with just a primary is a valid thing to send. Items are matched to roles by their current styling. Pass selectionOnly to restrict to the selection. Both actions return a WCAG contrast audit, so you can see failing pairs before shipping them.
pinepaper_audio_beats6 of 11 parameters describedDetect beats in audio and bake an item's animation onto them. ACTIONS: - analyze: Onsets, BPM, confidence and duration. Params: source (asset id, data URL or URL), sensitivity, minGap. Read-only — run it first to see what the track gives you. - animate_to_beat: Write a keyframe track that pulses on the beat. Params: itemId, plus EITHER source (analyze first) OR beats[] (times you already have). grid:true uses an even pulse from the detected tempo instead of the raw onsets — the difference between following the rhythm and following the beat. property (default scale), base, accent, decay shape the hit. Analysis runs ONCE and produces keyframes, deliberately not a live analyser: a keyframe track survives MP4, SVG/SMIL and Lottie export, and gives the same answer on every run. A live analyser node survives none of them.
pinepaper_image_filter9 of 9 parameters describedApply image filters to raster items: a GPU set, plus painted watercolor / painterly looks for photos. ACTIONS: - apply: Apply a single filter. Params: itemId, filterName, params - chain: Apply multiple filters in sequence. Params: itemId, filters (array of {name, params}) - analyze_palette: { itemId, maxSwatches? (8) } → { swatches: [{hex, share}…] largest-area-first } — READ an image's palette. The natural loop: analyze image A → recolor_palette (or the paletteMap filter) on image B with A's hexes. - recolor_palette: { itemId, mapping ({from,to}[] or {'#old':'#new'}), amount?, preserveShading? } — swap colours, keep the shading (GPU). Available filters (GPU raster set): - Color: grayscale, sepia, brightness, contrast, saturation, invert, posterize (levels), hsl (hue/saturation/lightness), colorTint (color, intensity, blendMode), colorMatrix (matrix), duotone (shadow, highlight, mix), paletteMap (swatches[], amount, preserveShading — recolor to a fixed palette) - Stylize: vignette (intensity, radius), edgeDetect, halftoneDots (size, angle), halftoneCMYK (size), dither (levels), grain (amount, seed), scanlines (intensity, period), chromaticAberration (amount), blur (radius) - Light (additive): bloom (amount, threshold, radius), glow, halation (warm-fringed bloom; color), lightShafts (amount, threshold, decay, density, x, y, color — volumetric rays from a point) - Keying: lumaKey (threshold, softness, invert) - Pixel art: pixelate (size or cells across, levels, dither, palette [colours] — e.g. a PICO-8 set), where the studio has it - Painted (CPU, STILL images only, where the studio has them): watercolor (strength, seed, radius, edges, bleed, granulation, paper, washes — layered washes, pigment rims, paper grain), painterly (strength, seed, radius, stroke, texture, edges, vivid — brush strokes along the form). About 1 s per 1080p image; the same seed paints the same picture; values are clamped and unknown params are warned about. A video is refused (they cannot run per frame): apply to a still or a captured frame. A studio without them refuses with its list of filters. - SECOND-INPUT (params.map = another item's id, resolved to its pixels): displace (amount, dispersion, map, mapChannel — the map's brightness pushes pixels), refract (displace with per-channel dispersion — glass), trackMatte (channel, invert, strength — prefer pinepaper_media apply_track_matte for the live version), datamosh (amount, block, map? — self-moshes without a map) RECIPE — grunge poster: chain [grain, scanlines, vignette]. Glass header: refract with map = a gradient item. HARD-EDGED LOOKS NEED SMOOTHING OFF: posterize, dither, halftone and pixel looks are exact at 1:1, but a raster that is then scaled, skewed or rotated is RESAMPLED with smoothing, which blends the flat levels back into a gradient (measured: posterize then skew → 256 tones again). Set smoothing 'off' on the image (pinepaper_import_image, or pinepaper_modify_item {smoothing: 'off'}) to keep the levels. CHAIN ORDER MATTERS: each filter runs on the previous one's output. duotone then halftoneDots comes out grey (the ink colour is lost); halftoneDots then duotone keeps it. If a chain loses its colour, move the colour-mapping filter (duotone, paletteMap, colorTint) to the end. (Scene-wide filters — sharpen/emboss/noise/vintage etc. — are a different surface: use pinepaper_add_filter.)
pinepaper_background6 of 6 parameters describedSet, clear, or query the canvas background. ACTIONS: - set: Set background. Params: mode (color|pattern|generator), color, pattern, generator, generatorParams - clear: Remove background entirely - get: Get current background settings
pinepaper_query6 of 6 parameters describedQuery canvas items and spatial information. ACTIONS: - get_by_id: Get detailed item info. Params: itemId - hit_test: Find items at coordinates. Params: x, y, tolerance, all (bool) - is_empty: Check if canvas has any items
pinepaper_query_capabilities10 of 10 parameters describedDiscover and match capabilities across the engine — text styles, character-level text effects, generators, vertex deforms, and behavioral relations. ACTIONS: - list: List all available capabilities or filter by kind (style, effect, generator, deform, relation, etc.). - choose: Mood- and context-weighted recommendation based on subject/prompt words and target feeling. - coverage: Report total indexable and describable capabilities across categories. - find: Direct lookup of a capability by key to inspect its description and how to apply it (applyWith). - catalogue: { catalogue: 'rig_presets' | 'shader_effects' | 'stroke_decorations' | 'precomps' | 'images' | 'segment_edit_kinds' | 'shatter_orders' | 'world_meshes' | 'relation_presets' } — the registries 'list' does not gather. - studio: {} — which engine methods THIS studio has, so you learn what will refuse before calling it. MOOD VOCABULARY FOR CHOOSE: - reveal: resolve, reveal, appear, emerge, decode, decrypt, unscramble, form, assemble - triumphant: burst, launch, firework, bloom, spark, explode, shine, glow, celebrate, rise - failure: crumble, fall, collapse, burn, decay, dissolve, break, shatter, sink, error - calm: drift, float, gentle, slow, settle, fade, wave, ripple, pour - technical: binary, matrix, grid, scan, code, digital, circuit, data, print, terminal - energetic: bounce, swarm, spray, shoot, fast, rapid, scatter, slam, volley EXAMPLE — Choose effect for a victory card: { "action": "choose", "kind": "effect", "mood": "triumphant", "subject": "celebrate correct answer", "seed": "quiz_q1" }
pinepaper_deform13 of 13 parameters describedApply vertex deformation presets to items for organic motion effects. ACTIONS: - apply: Apply looping deformation. Params: itemId, preset, frequency, amplitude (0-1), phase, loop, axis, turns, waves, maxDisplacement, speed, steps - trigger: One-shot deformation (auto-removes). Params: itemId, preset, amplitude, speed - remove: Restore original geometry. Params: itemId PRESETS: fold, squeeze, squash, pinch, bulge, twist, ripple, wave, breathe, melt, shear, inflate, wobble PHASES: sin, blink, linear, pingpong, once, elastic, heartbeat, stepped
pinepaper_create_letter_collage13 of 13 parameters describedCreate stylized text with per-letter customization. Perfect for word games, ransom notes, gradient text, and creative typography. USE WHEN: - Creating Wordle-style word displays - Making magazine cutout/ransom note text - Designing gradient-filled text - Building creative typography effects - Creating paper craft style lettering STYLE TYPES: - tile: Wordle/Scrabble colored backgrounds (use with tile palettes) - magazine: Mixed fonts/colors like cutouts - paperCut: Shadow/depth like cut paper - fold: Origami-style folded letters - gradient: Each letter with gradient fill (use with gradient palettes) - image: Letters filled with image - particle: Each glyph sampled into a cloud of colored dots (re-typable "particle font"); reuses tile palettes. Optional particleSpacing / particleDotSize tune density. TILE PALETTES: - Game: wordle, scrabble - Vibrant: candy, neon, rainbow - Soft: pastel, cotton - Natural: earth, ocean, forest, sunset - Professional: corporate, minimal, slate - Seasonal: christmas, halloween, spring - Magazine: magazine, newspaper, vintage - Paper Craft: paperCraft, origami, craftPaper GRADIENT PALETTES: rainbow, sunset, ocean, fire, gold, rose, ice, cyberpunk, neonGlow, purplePink EXAMPLES: - Wordle style: {text: "HELLO", style: "tile", palette: "wordle"} - Ransom note: {text: "SECRET", style: "magazine", palette: "newspaper"} - Gradient text: {text: "RAINBOW", style: "gradient", gradientPalette: "rainbow"} - Neon style: {text: "GLOW", style: "tile", palette: "neon"}
pinepaper_apply_effect3 of 3 parameters describedApply a visual effect to an item. EFFECT OR EMITTER: apply_effect is a live look on an item. For particles a saved scene, a template, the cloud render and every export must reproduce frame for frame — confetti at 2 s, a trail behind a moving item — use pinepaper_emitter: its particles are a pure function of its spec and the scene time. USE WHEN: - Adding sparkle/glitter effects - Creating burst/explosion, fire, smoke effects - Weather effects (rain, snow) - Celebration effects (confetti) - Enhancing visual impact (ripple, glow, electric) SIZE IS A MULTIPLIER, NOT PIXELS — and this is the one that bites hardest. Every effect derives its scale from the ITEM'S OWN BOUNDS, and 'size' multiplies that. glow computes a radius from max(width, height) and pulses it to '1 + (size - 1)', so size: 30 on a modest item asks for a disc thousands of pixels across, gets one, and reports success. Typical values are 1.5 to 3 — glow's own default is 1.5. Pass a pixel count here and you will be wrong by about two orders of magnitude. A recent studio warns about it (kind: 'glow-size-unit'); an older one does not. EFFECTS (27: particles, then the shader auras from heatmap on): - sparkle: Glitter/sparkle particles (color, speed, size) - blast: Explosion burst effect (color, radius, count) - smoke: Rising smoke plumes (color, speed, size, drift, height, growthRate) - fire: Animated fire/flames (color, colors, speed, size, height, turbulence) - rain: Falling rain drops (color, count, speed, angle, spread) - snow: Falling snowflakes (color, count, speed, spread, particleLife) - confetti: Celebration confetti (colors, count, radius, gravity, size, spread, interval, repeat) - ripple: Expanding ring ripples (color, speed, maxRadius, ringCount, strokeWidth) - glow: Pulsing glow aura (color drives the shadow halo; speed, intensity, size; optional fill — interior tint decoupled from color; fillOpacity 0..1 multiplies intensity opacity) - electric: Lightning bolts (color, speed, boltCount, length, flickerRate) - bubbles: Rising transparent bubbles (color drives the rim; count, speed, size, spread; optional fill — interior tint, default null = outlined-only; fillOpacity 0..1, default 0.25 when fill is set) - dust: Ambient drifting motes (color, count, speed, size, spread) - fireflies: Glowing wandering dots (color, count, speed, size, spread) - shockwave: Expanding concentric rings — burst type (speed, maxRadius, count, thickness) - trail: Fading afterimages following movement (speed, count, size, fadeRate) - aurora: Shimmering northern-lights curtain ribbons undulating around the item (color, speed, count, size, spread) - orbit_swirl: Small glowing orbs circling the item on spiralling elliptical orbits (color, speed, count, size, maxRadius). The particle swirl; vortex is the shader aura - glitch: RGB chromatic-aberration slices jittering across the item bounds (color, speed, count, size) - petals: Blossom petals tumbling and swaying across the item (color, speed, count, size, spread) SHADER AURAS (WebGL2, silhouette-clipped — same tool, routed to the aura system): - heatmap: Thermal shimmer aura (palette 0=Hot 1=Cool 2=Violet) - liquid_metal: Flowing metallic sheen (palette 0=Chrome 1=Gold 2=Copper) - gem_smoke: Crystalline smoke wisps - electric_arc: Branching discharge filaments with a hot core and inverse-square bloom. Stepped flicker, not a sine — a stroke is a train of return strokes, which reads far more electric than a smooth pulse. - vortex: The bright band is a RING, not a disc — condensation tracks the steepest pressure gradient, so the core is hollow, and differential rotation shears the field rather than spinning one picture round. - rain_veil: Drifting sheets of falling rain across the silhouette. - caustics: Refracted light patterns, as through moving water. - ink_bleed: Ink wicking outward into the surface, as on absorbent paper. Routable since the engine began publishing every aura name and warming the subsystem before routing; it was defi…
pinepaper_add_filter2 of 2 parameters describedAdd a visual filter effect to the canvas. Filters are scene-wide effects that can be stacked. USE WHEN: - User wants visual effects like blur, grayscale, vintage look - Creating mood or atmosphere (cinematic, dreamy, noir) - Post-processing the entire scene - User says "make it look vintage", "add blur", "black and white" AVAILABLE FILTERS (the engine's own list, with each one's parameters): - grayscale: Convert to black and white — intensity 0..1, default 1 - sepia: Apply warm sepia tone — intensity 0..1, default 1 - brightness: Adjust image brightness — value -100..100, default 0 - contrast: Adjust image contrast — value -100..100, default 0 - saturation: Adjust color saturation — value -100..100, default 0 - invert: Invert colors — intensity 0..1, default 1 - blur: Apply gaussian blur — radius 0..20, default 5 - noise: Add film grain effect — intensity 0..100, default 20; monochrome (boolean), default true; grainSize 1..4; refresh 0..8; seed 0..99999, default 0; blend add|multiply, default add - vignette: Add vignette darkening — intensity 0..1, default 0.5; radius 0..1, default 0.5; color (color); falloff 0.5..4, default 2 - vintage: Retro vintage look — intensity 0..1, default 1 - colorOverlay: Add color tint — color (color), default #ff0000; intensity 0..1, default 0.3; blendMode multiply|overlay|screen, default overlay - sharpen: Increase image sharpness — intensity 0..100, default 50 - emboss: 3D emboss effect — intensity 0..1, default 1 - posterize: Reduce color levels — levels 2..32, default 4 - hsl: Shift hue, saturation, lightness — hue -180..180, default 0; saturation -100..100, default 0; lightness -100..100, default 0 - colorTint: Tint image toward a color — intensity 0..1, default 0.3; color (color), default #ff0000; blendMode multiply|screen|overlay, default overlay - edgeDetect: Sobel edge detection — strength 0..4, default 1.0 - halftoneDots: Black-and-white halftone dot pattern — size 2..32, default 6; angle 0..3.14, default 0.4 - halftoneCMYK: CMYK halftone separations (newspaper rosette) — size 2..32, default 6 - dither: Ordered Bayer 4x4 dithering — levels 2..16, default 2 'saturate' is accepted as saturation. EXAMPLES: - "Make it black and white" → filterType: "grayscale" - "Add vintage look" → filterType: "vintage", params: {intensity: 0.8} - "Blur the background" → filterType: "blur", params: {radius: 5} - "Increase contrast" → filterType: "contrast", params: {value: 30} - "Print it like a comic" → filterType: "halftoneCMYK", params: {size: 6} - "8-bit / retro screen" → filterType: "dither", params: {levels: 4} Filters can be stacked - call multiple times to combine effects.
pinepaper_get_items0 of 1 parameter described[Utility] Get all or filtered items from the canvas. USE WHEN: - Listing REGISTERED items - Finding items by type - Checking animated items - Scene inspection AFTER A GENERATOR, THIS IS A PARTIAL VIEW. A generator may register some, all or none of what it paints: measured on a cleared canvas, drawSunsetScene registers 6 of its 27 objects, drawSunburst 1 of 18, and drawPattern none of its 15. That is by design — a large procedural field would cost memory per path — but it means the canvas can look partly addressable while the rest is silently absent, which is worse for a caller than either extreme. Do not infer canvas contents from this after running a generator; ask app.config.currentBackgroundGenerator / generatorParams for what ran.
pinepaper_get_relation_statsno parameters[Utility] Get statistics about active relations in the scene. USE WHEN: - Debugging relation system - Understanding scene complexity - Analytics and reporting
pinepaper_export_scene2 of 2 parameters describedExport the scene: a SUMMARY for inspection by default, or with full: true a RESTORABLE project document saved to a file. SUMMARY (default) — for reading the scene, not for saving it: - items (id, type, position, bounds, active window), relations, decorative items, backgroundColor, canvasSize - It does NOT carry keyframe tracks, rigging or scene chains, so a scene rebuilt from it has no motion. The result says so (note). FULL (full: true) — to save work and restore it later: - The engine's own project document (relations, keyframes, rigging, connectors, scene chains, animation config), written to a file because it can be megabytes. - Returns filePath, bytes and counts (items, animated items, keyframes, relations). Restore with pinepaper_import_scene { path } and compare the counts. USE WHEN: - full: true — saving a scene to come back to, a backup, a hand-off to another session - summary — debugging composition, checking what is on the canvas
pinepaper_styled_scene4 of 4 parameters describedOne composition, drawn in a built-in STYLE, as one canvas item that redraws itself every exported frame. No drawing code: pick a style, optionally shape the composition, then export. STYLES: cut (paper cut-out with soft drop shadows and paper grain); ink (ink line and hatching, boiling on twos (12 fps)); watercolor (translucent watercolour glazes on cold-press paper); dither (1-bit ordered (Bayer) dither in two inks); flow (contour streamlines on dark ground, animated along their length); ascii (ASCII broadcast with scanlines and a timecode). Default watercolor; the studio also takes its aliases (watercolour, papercut, 1bit…), and an unknown style is refused with the list. THE COMPOSITION is data (spec). Every key is optional; omitted keys take the 'valley' preset, a valley going from dream to cost over 8 s: size [W, H], duration, transition {name, start, length}, camera {zoom: [from, to], pan}, palette, sun, clouds, ridges, foreground, river, settlements, structure, pylons, vegetation, effects {steam, ripples, scars}, hud {label}. THEN EXPORT FOR ITS DURATION: the result carries duration, and the scene runs that long. Pass it as agent_export's duration; a different length cuts the scene short or holds its last frame. KNOW: - Calling again with the same id REPLACES the scene, which is how to change style. - dither and ascii need a Chrome renderer (WebKit ignores the canvas filter they use). - The scene redraws every frame through a render hook. After a page reload it is a still image until this is called again. - It sits below every other item, sized to cover the canvas, so titles and overlays go on top as usual. EXAMPLE: { style: 'ink', duration: 6 }
pinepaper_look2 of 8 parameters describedRestyle what is already drawn — one item, a group and everything in it, or the WHOLE SCENE — as a named look: palette remapped in place (colour keyframes too), strokes, type, image treatment, texture, background and a framing device. Ids, keyframes and relations are kept; it survives a project round trip; remove restores it pixel for pixel. This is "the same subject, in style X". ACTIONS: - list: every look with its FIDELITY — the engine's own grade: native (the medium itself), faithful (close, its approximations named), impression (an evocation, not the real style). - describe: { look } — the recipe, its fidelity, what it approximates, and the engine call per part. Read it before promising a look. - apply: { look, target? ('scene' default | an itemId), scope? ('item' | 'subtree' | 'scene') } → what it restyled, and the fidelity. An impression comes with a warning — present it as an approximation, not the finished style; a faithful look lists what it approximates. - remove: { target } — restore what was there. get: { target } — the look on it now. - grid: { looks?, cols?, cellWidth?, t? } — a contact sheet of the scene in several looks, to choose from: the PNG is the reply's `data` (a data URL, as agent_export returns it), with cells [{ id, name, fidelity }]. look is an id from list, or a look spec. An unknown look is refused with the known ones. Looks act on what is THERE: they restyle a drawing, they do not redraw a subject from scratch in another medium.
pinepaper_original_character0 of 9 parameters describedMake an ORIGINAL character from a base rig and a declarative variant — no drawing code, and nothing anyone else owns. Every variant keeps its base's parts and rig, so expressions, walks, poses and pinepaper_choreograph (which drives its root) all work on it. ACTIONS: - bases: the bases (person, robot, cat, bird, blob) with their roles. - describe: { base? } — every legal palette key, feature value, accessory (and its slot), proportion range and look. READ IT FIRST: a value it does not list is refused by name and nothing is drawn. - random: { base, seed, fixed? } — a distinct, valid variant; the same seed gives the same one. fixed is shared by every member (a look, proportions) while each draws its own signature — a cast of 12 is twelve seeds with one fixed. - create: { base, variant?: { palette, features, look, seed, name }, at: { x, y }, height? (320) | scale?, rig? (true) } → itemId (the root), rigId, parts { role: id }. y is the FEET. FEATURES: hair, eyes, eyeColor, nose, mouth, ears, brows, accessories (12 slots, one per slot), proportions { headScale, bodyScale, limbLength }. LOOKS on a rig: flat, ink, charcoal, paper-cutout, pixel. watercolor / oil / hatch are refused with the reason. INTERACTION (pinepaper_add_relation, source = the character's itemId): - looks_at → an item id, or target 'cursor': the face follows it. - reacts_to → an event or another character; params reaction (hop | jolt | shake | nod | an expression), after, duration, amount. - drag_to_turn (no target): dragging turns the head; params max, sensitivity, turn (keyframeable), spring. - a sound on the reaction: on_event_play_sound on the same event. EXAMPLE: { action: 'create', base: 'person', at: { x: 480, y: 900 }, variant: { palette: { skin: '#e8b48a', hair: '#2b1d16', outfit: '#3a7bd5', accent: '#f2c14e' }, features: { hair: 'bun', eyes: 'almond', mouth: 'smile', accessories: ['cape'] }, look: 'ink', name: 'Mira' } }
pinepaper_morph_sequence4 of 6 parameters describedONE element through many states, with no cuts: each state grows out of the last (a pill becomes an input field becomes a dot becomes a card). The one-take UI-launch idiom, from one call. { itemId, states: [{ at, duration? (0.8), to: itemId | shape: { itemType, position, properties? }, hideTarget? }], easing?, camera?, sound?, hideTarget? } - Each state is the shape the element morphs INTO, starting at `at` seconds. Name an existing item (to) or describe one (shape); either way the reference is hidden (hideTarget: false keeps it visible, per state or for the whole call) and the element keeps its own id throughout. States run one after another; an overlap is refused. - easing: linear | easeIn | easeOut | easeInOut (default easeInOut) — the four the morph supports. - camera: true (or { fill, easing }) keys the camera on the SAME timing: it holds while a state rests and moves with each morph, framing the new state to `fill` of the frame (default 0.45). - sound: true puts a whoosh at each morph start (or name any catalogue sound). Shapes morph by kind: path → path point by point, circle → circle by radius, text → text by font, across kinds by a particle transition. Colours and size morph too. RETURNS: states [{ at, duration, targetId }], end (seconds), camera { keyframes }, sounds. EXAMPLE — pill → field → dot: { itemId: "item_1", camera: true, sound: true, states: [ { at: 1, shape: { itemType: "rectangle", position: { x: 960, y: 540 }, properties: { width: 640, height: 88, cornerRadius: 44, color: "#ffffff" } } }, { at: 3, shape: { itemType: "circle", position: { x: 960, y: 540 }, properties: { radius: 18, color: "#111111" } } } ] }
pinepaper_emitter2 of 3 parameters describedParticles as an ITEM whose every frame is a pure function of its spec and the scene time — so the preview, capture_frames, every export, a saved project, a template and the cloud render all draw the same particles, scrubbing backwards included. The serialisable, cloud-safe choice; pinepaper_apply_effect is a live look on an item. ACTIONS: - create: { spec } → itemId - set: { itemId, spec } — merges the spec's top-level keys onto the emitter's. An array it names replaces the old array whole: set with bursts: [one] leaves one burst. To add a burst, pass all of them; the reply's burstsReplaced gives the counts before and after. SPEC: - mode: 'burst' (default) — bursts: [{ t, x, y, count, …per-burst overrides }]: a pop of particles at scene time t. - mode: 'trail' (or give target) — target (an item id), rate (per second), emitWindows [[t0, t1], …] (when it sheds), window [t0, t1] (when the WHOLE trail shows: it switches on and off at those times, with what was shed before t0 already there), offset ([dx, dy] or {x, y}): particles shed from a moving item. rate, start and end are trail settings: a burst emitter does not read them. - look and physics (per emitter or per burst): shape ('circle' | 'rect' | 'dash' | 'star' | 'confetti', or an array; size is a circle's diameter, a rect's or confetti's width (height is half of it), and a star's extent is 0.8 of it; a dash is a thin line drawn forward from the particle along its velocity; confetti tumbles, with a seeded tilt and a darker back, and a rect does not), palette [colours], colorEnd (a colour, or a list cycled like palette) and opacityEnd (a number or [min, max]): what each particle ramps to over its life, as sizeEnd (a studio before FxTool #401 drops both), size / sizes / sizeEnd, speed + angle ranges or velocities ([[vx, vy], …] px/s, or [{x, y}, …]; particle i takes velocities[i % length], so give one per particle — the reply warns when count and the list differ), gravity (px/s², +down), drag (slows the launch velocity only: what gravity adds is not damped, so a falling particle has no terminal velocity), friction, lifetime, fadeIn / fadeOut, spin, opacity, jitter, jitterGrow, seed. UNITS (a number, or a [min, max] range picked per particle where it says range): - spawn: where particles start, as a box [width, height] in px on the canvas axes, centred on the burst point (one number is a square). It is not a range and does not turn with angle: spawn [0, 200] is a vertical line of start points whatever the angle. Default [0, 0], a single point. - count: particles per burst, at most 10000 on the current studio (2000 on older studios) — a larger count is drawn at the cap and the reply warns with the number drawn. For more, add a second burst at the same t. - speed: px/s (range). angle: degrees, 0 = right, 90 = down (range). gravity: px/s². lifetime: seconds (range, > 0). size: px (range). - gravity, drag, friction, opacity, sizeEnd and jitter also take a range on the current studio, sampled per particle; an older studio draws the midpoint and warns emitter-range-not-read. - fadeIn / fadeOut: SECONDS at the start / end of each particle's life. fadeOut is capped at that particle's lifetime (a 0.5 s life cannot fade for 2 s; it fades over its whole life instead), and the current studio warns when it caps one. Omitted (or fade: 'linear'), the particle fades linearly over its WHOLE life; fade: 'none' turns both off. - spin: DEGREES PER SECOND, positive = clockwise on screen (range; spinAlternate flips every other particle). It turns rect, confetti, star and dash particles; a circle has no orientation, so spin on circles shows nothing (the current studio warns when every particle is a circle). - jitter: PIXELS — on the current studio each particle is displaced up to ±jitter px on each axis from its path, at full size from birth; jitterGrow: true keeps the older ramp (zero at birth, the full ±jitter at the end of life). Older studios (before jitterGrow) displace up to ±jitter/2, growing…
pinepaper_instances9 of 14 parameters describedThousands to a million similar marks as ONE item: a crowd, a swarm, a starfield, rain, sand, a confetti field. Reach for it past about 5,000 similar marks; ordinary items cost memory and time per item, and this costs one item. For bursts that are born and die, use pinepaper_emitter. ACTIONS: - rules: the motion rules (with their params and determinism), layouts and shapes this studio has. Read it before create; the lists are the studio's, not a copy. - create: { count, seed?, palette? (up to 16), size? (px or [min, max]), shape?, colorMode? ('random' | 'gradient'), opacity?, x?, y?, init?: { layout, width?, height?, radius?, thickness?, length?, angle? }, motion?: { rule, ...params } } → { itemId, count, drawn, subsampled, path, rule, determinism }. - modify: { itemId, ...the fields to change } — motion and init merge field by field. - describe: { itemId } → its spec, count, drawn, path and determinism. WHAT THE REPLY TELLS YOU: drawn is how many marks are actually drawn. When the studio draws a subset (a cap for its drawing path), drawn is less than count and subsampled is true: the same marks every frame, and the receipt says so. determinism.scope 'everywhere' means every mark is in the same place at the same time on any machine, so two exports give the same frames (compare their frameDigest). Whether the encoded file is byte-identical is the encoder's business, not the swarm's: see the export's bitExact. A rule whose scope is narrower says so in rules and in the export receipt. A rule, layout or shape the studio does not have is refused by name with its list.
pinepaper_render_hook0 of 6 parameters describedSECURITY SWITCH: register needs a server started with PINEPAPER_ALLOW_CODE=1 (off by default; only the person running the server can turn it on). list and unregister always work. Custom per-frame drawing that a saved scene CARRIES: SOURCE TEXT, compiled and run under the governor's loop guards with seeded Math, saved in the project document, the template and undo, and re-installed on load. (A raw function added with code is not saved — pinepaper_export_scene { full: true } names any such as unserialized.) ACTIONS: - register: { id, source, layer? ('above' | 'below'), deterministic? (true), seed? } — source evaluates to (ctx, t, info) => {}: ctx in canvas coordinates, t the scene time in seconds, info { width, height, frame, seed }. 'above' draws over every item, 'below' under them. deterministic reseeds Math.random from (seed, frame) each call, so a frame always draws the same. - unregister: { id } list: the saved hooks. Reach for it when no tool draws the look (a scanline overlay, a custom texture pass). For particles, pinepaper_emitter is data rather than code. EXAMPLE: { action: 'register', id: 'scanlines', layer: 'above', source: "(ctx, t, info) => { ctx.globalAlpha = 0.08; for (let y = (t * 40) % 4; y < info.height; y += 4) ctx.fillRect(0, y, info.width, 1); }" }
pinepaper_choreograph3 of 3 parameters describedMake any item ACT: a list of beats compiled to one keyframe track with anticipation, squash and stretch, contact and settle — the timing a hand animator would key, from one call. BEATS run one after another: [{ at, verb, ...params }]. Positions are the actor's CENTRE in canvas px; a squash keeps its BOTTOM on the ground. - pop: scales up from nothing with an overshoot (an entrance in place). - drop { to? }: falls and lands with a squash. Already in the air (after a fly), it falls from where it is; on the ground or below the landing point, it comes in from above the frame. - hop { to?, height? }: crouch, launch stretched, arc, land squashed, settle. Without to it hops in place. - bounce { times? (3), height?, decay? (0.6), to? }: bounces that lose height; with to it travels while bouncing. - roll { to }: rolls without slipping — it turns by the distance over its radius (right = clockwise). - fly { to, arc? }: an arc through the air, nose up on the rise and down on the fall. - peek { edge (left|right|top|bottom), amount? (0.5), hold? (1) }: slides partly in from a frame edge, waits, ducks back out. - shake { intensity? }: a startled shiver. squash { amount? }: an in-place squash and recover (a reaction, a landing hit). - enter { from (edge), to? }: slides in from an edge with an overshoot. exit { edge }: a small anticipation, then away off that edge. Each verb has a default duration; pass duration to change it. WHAT IT RETURNS: keyframes written, the duration, and where the actor ends (and whether that is on screen). Beats that overlap, an unknown verb, or roll / fly without a destination are refused by name. ACTORS: a shape, a group, an imported SVG character, a photo cut-out — anything with one transform. Its own scale and rotation are kept (a beat squashes relative to them). A figure placed by pinepaper_character is several parts with their own tracks and no single transform, so choreograph its parts' group only if you grouped a STATIC figure; otherwise direct it with character beats. SOUND: sound: true puts a sound on every moment the motion makes — the pop, each launch, every landing (a bounce's landings get quieter as the bounces shrink), a shake — placed on the timeline and baked into the video. sound: { contact: 'kick', whoosh: false, gain: 0.6 } picks or silences them by catalogue name (SFX such as beep, pop, whoosh, zap; drums such as kick, snare, clap, tabla-na, djembe-tone; or your own from define_sfx; pinepaper_sound list_percussion and list_sfx name them all). The reply lists the sounds placed. A sound due before 0.06 s is placed at 0.06 s (movedFrom says so): an MP4 encoder swallows the first ~50 ms of audio. MIX WITH: pinepaper_character / text expressions on top; pinepaper_apply_effect (confetti, shockwave) at a landing; pinepaper_sound at the same times. Call choreograph BEFORE keyframing the actor's other properties (colour, fill): the beat keys carry position, scale, rotation and opacity only, and the result warns if the actor already animates something else. EXAMPLE — a ball comes to life and crosses the frame: { itemId: "item_1", beats: [ { at: 0, verb: "pop" }, { at: 0.6, verb: "bounce", times: 3, to: [700, 820] }, { at: 2.4, verb: "roll", to: [1200, 820] }, { at: 3.5, verb: "fly", to: [1600, 300] } ] }
pinepaper_relight6 of 6 parameters describedLight the 3D world layer (pinepaper_world3d) with point and directional lights — a post pass, so the lit side of every surface reads brighter in the preview and the export. ACTIONS: - set: { lights, ambient?, strength?, enabled?, preview? } — install or replace the rig. Up to 8 lights: point: { type: 'point', x, y, z? (120), radius? (400), color?, intensity? (1), specular? (32) } directional: { type: 'directional', dir: [dx, dy, dz], color?, intensity? } [0, 0, -1] faces the viewer Coordinates are export-frame px; colours are '#rrggbb' or [r, g, b]. ambient default 0.2, strength (normal-map) default 2. The result reports cost: the pass runs on the CPU, about 0.42 s per 1080p frame, so a 10 s MP4 at 30 fps takes about 2 minutes longer. - get: the current rig. - clear: remove it. - list_lights: the light types. LIMITS — say them before you promise a look: - Applied in the preview and in PNG, PDF, MP4 and WebM exports. GIF and APNG are NOT relit (agent_export says so when it happens). - Normals come from the world's brightness, not real depth, so it reads as raking light over the picture rather than true 3D shading. - It lights the 3D world layer only, not 2D items drawn over it. - The rig is NOT saved with the project: set it again after reloading. - A studio without the relight pass refuses with the reason. EXAMPLE: { action: 'set', lights: [{ type: 'point', x: 1500, y: 200, z: 300, radius: 1200, color: '#ffd9a0', intensity: 1.4 }], ambient: 0.15 }
pinepaper_import_scene3 of 3 parameters describedRestore a scene from a project document saved by pinepaper_export_scene { full: true }. REPLACES the current scene. The engine validates the document before applying it: a truncated file, a foreign JSON blob or a document from a newer major version is refused, not half-applied. Returns counts (items, animated items, keyframes, relations): compare them with the export's to confirm nothing was lost. - path: the file the export wrote (absolute, or relative to the server's working directory). - strict: false loads a document with validation problems anyway and returns them as warnings (default true: refuse). - registerCustomRelations: true registers the custom relation definitions the file carries (a full export saves them with the scene) before loading, so its relations of those types run. Their compute and apply code runs in the studio, so pass it only for a file you trust; without it the result names them and they stay unregistered.
pinepaper_browser_connect2 of 2 parameters describedConnect to PinePaper Studio. Pass headless: false to show the browser window.
pinepaper_browser_disconnectno parametersDisconnect from the browser.
pinepaper_browser_screenshotno parametersTake a screenshot of the current canvas.
pinepaper_browser_statusno parametersCheck browser connection status.
pinepaper_agent_start_job6 of 6 parameters describedCALL THIS when the user asks to create any animation, video, graphic, or visual content. Do NOT create standalone HTML pages, React apps, or use frontend design skills — PinePaper tools ARE the implementation. If tools fail, report the error — never fall back to HTML pages. Pass description for creative direction and canvasPreset for platform sizing. WORKFLOW: start_job → batch_execute (ONE call) → end_job → export.
pinepaper_agent_end_job2 of 2 parameters describedFinish the current job and get a screenshot. Show it to the user.
pinepaper_agent_reset3 of 3 parameters describedQuick canvas reset. Faster than refresh_page.
pinepaper_agent_batch_execute4 of 4 parameters describedExecute multiple operations in a single call — canvas setup, items, animations, effects, playback. Call ONCE per pipeline — calling twice doubles all items. This is the GLUE: a styled scene, a character, a story or a crafted title has its own tool (styled_scene, character, story, text_style), called first; shapes over a generator backdrop is the stock look. OPERATION TYPES (20): set_canvas_size, set_background, execute_generator, create, modify, delete, group, animate, keyframe_animate, relation, apply_mask, apply_effect, play_timeline, ring, grid, orbit, stagger, patch, create_many, timeline. create takes position {x, y} or [x, y]. timeline takes GSAP-shaped tweens {to, vars, from, duration, at, stagger, ease, repeat, yoyo} and compiles them onto keyframe tracks (x/y are offsets from home). VARIABLE REFERENCES: "$0", "$1" etc. reference the items this batch makes, in op order: create and group ops are numbered, nothing else. properties.id on a create chooses the item's id.
pinepaper_export_store3 of 3 parameters describedRecover an export the studio is still holding. A long export is not returned inline — the studio keeps the encoded file and pinepaper_agent_export pages it out to a file for you. When that PAGING half fails, the render has already succeeded and the bytes are sitting in the store. This is how you go and get them, instead of re-rendering something that already exists. ACTIONS: - list: {} — what is held, newest first: {id, format, size, createdAt}. The id IS the stored filename and the store is origin-persistent, so ids survive a page reload; an id lost with a dropped tool result is recoverable here. - save: {exportId} — page it out to a file and release it once the file is whole. Returns a filePath, the same shape agent_export returns. Safe to repeat: reading a held export mutates nothing, so a failed save can simply be run again. - release: {exportId} — drop it WITHOUT saving. The store is the only copy; this is not undoable. WHEN TO REACH FOR IT: - An export failed with "Failed to write data to data pipe". That is the browser's transport refusing to carry one oversized value, not the encoder failing — the bytes may already be in the store. Call 'list' BEFORE re-rendering. - An export error named an exportId and a byte count reached. That error is a true promise: call 'save' with the id. RETENTION, AND THE ONE WAY TO LOSE WORK: Held exports last until released, or until a LATER export needs the space — and eviction drops the OLDEST first. Rendering five chunks and paging them out at the end can evict chunk 1 to make room for chunk 5. Save or release each export before starting the next one. An id dropped this way usually says "evicted" rather than "not found", including after a page reload — but that record is best-effort browser storage, so a miss can still be genuinely ambiguous. Treat the absence of "evicted" as "unknown", never as proof the export never existed.
pinepaper_agent_export31 of 31 parameters describedExport video, stills, animation, ads, captions or audio. Formats: svg, png, gif, mp4, webm, pdf, jpg, webp, apng, html5-ad, playable, srt, vtt, scc, wav. Quality: draft, standard, high — compression, and a default frame rate (15/30/60) that fps overrides. Video size control is scale 0.1-1, not a bitrate; scale 0.5 + quality draft is the fast preview. Framing: canvas (default) or camera (camera_animates viewport — video formats only).
pinepaper_agent_analyzeno parametersAnalyze what's on the canvas and get export recommendations.
pinepaper_get_canvas_ontology3 of 3 parameters describedCapture the REGISTERED canvas as compact pp: ontology triples + a structured item summary. It reads the item registry, so it inherits the same blind spot as pinepaper_get_items: a generator may register some, all or none of what it paints — drawSunsetScene 6 of 27 objects, drawPattern none of 15 — so a scene built by a generator is described partially or not at all. That is deliberate (memory per path), not a gap to work around. USE THIS instead of pinepaper_get_items when you need to REASON about composition (what's on the canvas, how items relate, what's animated). Typical scenes shrink 3-10× compared to a raw item dump while preserving relations, animations, effects, masks, and collage styling. OUTPUT (a snapshot of FxTool's canvas state): - canvasWidth, canvasHeight, canvasPreset - itemCount, itemTypes ([unique]), hasAnimations, relationCount - items: capped item summaries with positions, colors, group structure, collage metadata, keyframes, effects, deformations - triples: a TripleLanguage-serialized pp: triple block (compact tokenized form). Read this for structural reasoning. - viewport (when includeViewport: true): zoom + center + hasCameraAnimation flag OPTIONS: - maxItems (default 50): cap on item summaries. Larger scenes are truncated, not paginated — pinepaper_query_ontology and pinepaper_get_items remain available for full enumeration. - maxChildren (default 10): cap on per-group child summaries. - includeViewport (default false): include zoom/pan/camera-animation flag. NOTE: Requires FxTool with the canvas-ontology promotion. Returns { success: false, error } with a clear hint when running against an older build.
pinepaper_query_ontology8 of 8 parameters describedQuery the PinePaper design knowledge graph — explore types, properties, edges, hierarchy, and patterns. USE WHEN: - Discovering available item types, relation types, or generators - Checking what properties a type supports and which are animatable - Navigating the type hierarchy (parent/child relationships) - Understanding how types relate to each other QUERIES (14): Listing: - list_types: All item types (filter by category, includeAbstract) - list_edges: All relation/edge types (filter by category) - list_generators: every generator the engine can run — the built-ins AND the registry, merged and awaited, which on a current studio is about 74 rather than the 3 this once reported. A generator you registered at runtime DOES appear. A custom draw function passed to execute_generator does not, because it was never registered; that is the one gap. If the registry chunk has not finished loading the result says partial: true and names the retry rather than presenting the built-ins as the whole set, and an older studio that cannot merge the registry answers with the built-ins under that same flag. - list_effects: All visual effect types - list_patterns: All detected design patterns - list_math_functions: All math functions used in animations Hierarchy: - type_hierarchy: Ancestry chain for a ppType (e.g. pp:Circle → pp:CanvasShape → pp:CanvasElement) - type_children: Direct subtypes of a ppType - is_subtype: Check if typeA is a subtype of typeB Properties: - type_properties: All properties for a ppType (inherited + direct) - animatable_properties: Only animatable properties for a ppType Lookup: - node_type: Map an itemType string (e.g. "circle") to its pp: type - edge_type: Map a relationName string (e.g. "orbits") to its pp: edge - edge_info: Full metadata for an edge type
pinepaper_tool_guide2 of 2 parameters describedGet detailed docs for any tool or category. Call with no args for the full workflow guide. For a scripted build of shapes, text, keyframes and relations exported to a file, PINEPAPER_TOOLKIT=lane serves a seven-tool agent lane whose descriptions carry the whole contract.
pinepaper_set_toolkit3 of 3 parameters describedSwitch available tools. Toolkits: agent, diagram, map, font, full, minimal, lane (the eight-tool agent lane), starter (its first five). Verbosity: verbose, compact, minimal.
pinepaper_physics17 of 17 parameters describedRigid body physics simulation (Box2D/Planck.js). ACTIONS: - init: Start physics world. Params: gravity ({x, y}, default {x:0, y:980}) - add_body: Register item as physics body. Params: itemId, bodyType (static|dynamic|kinematic), mass, friction, restitution, fixedRotation, shape (auto|circle|rect) - remove_body: Remove from physics. Params: itemId - apply_force: Continuous force in px/s². Params: itemId, force ({x, y}) - apply_impulse: Instant velocity change. Params: itemId, impulse ({x, y}) - set_velocity: Set linear velocity. Params: itemId, velocity ({x, y}) - get_state: Get body position/velocity/rotation. Params: itemId - create_ground: Static floor plane. Params: y, width - create_joint: Connect two bodies. Params: itemId, targetItemId, jointType (revolute|distance|weld|prismatic), jointParams
Tested in a sandbox with an empty environment: no API keys, a throwaway folder, nothing from a real account. A passing test shows the server runs and responds. It is not a security audit.