---

name: threejs-animatic description: >- Build a three.js animatic ("animatronic", 3D previz, blockout) of a multi-shot video: every storyboard shot becomes a schematic 3D scene drawn in code, with jointed mannequins and poses, master sets in real metres and props, a real camera per shot (START/END keys, lens in mm, move and ease), timed to the music or voiceover, reviewed in the browser with a top-down set map of every camera frustum, approved, exported as a camera plan, rendered to MP4 frame by frame (headless Chrome or HyperFrames), then used as the @video1 reference for Seedance 2.5 video-to-video on varg so the generated shots keep the approved camera and blocking. Use when someone asks for a three.js animatic or animatronic, a 3D previz or blockout, camera blocking, a camera plan, shot sizes and lenses, a grey-box of a storyboard, previz to Seedance, a reference video for video-to-video, or a look blockout (reference pictures as textures on the blockout, stills for look approval). Includes a working starter project (no npm). license: MIT metadata: author: vargHQ version: "1.0.0" compatibility: >- Starter: a browser, Bun, Google Chrome or Chromium, ffmpeg; three.js loads from jsDelivr (pinned). HyperFrames path: npx hyperframes. Generation: the varg MCP (https://mcp.varg.ai/mcp) and credits on the varg account.

three.js animatic: approve camera and blocking in code, then let Seedance redraw it

AI video models redraw the world on every call: cameras wander, rooms change layout between shots, a person ends up as big as their car. A three.js animatic fixes camera, geography, scale and timing for free, before the paid step. It is a grey-box: it approves where things are and how the camera sees them, never the look. The approved clip then goes to Seedance 2.5 as @video1, and the generated shots keep that camera and blocking.

Distilled from real production sessions: a 36-shot vertical music video (previz → 13 Seedance runs), product and launch films, and a deterministic three.js film rendered through HyperFrames.

When to use it, and which tool

| project | do | |---|---| | 1–3 shots, simple camera | skip the animatic: a still per shot, approve, then image-to-video | | 3–15 shots, one or two places | this skill + starter/: hand-key the cameras, review, render, pack | | a storyboard of 15+ shots, songs, many locations | this skill for the craft, plus the varg-previz skill for its full app: auto cameras from storyboard words ("MCU, 3/4 left, push in"), pack.json + board builder, story structure and sheet guides (in this repo: varg-previz) | | the animatic itself is the film (3D product shot, explainer) | this skill, render path B (HyperFrames) with HTML text on top, plus the optional look blockout | | the look must be approved before paid generation | the optional look blockout (below): reference pictures on the grey set, stills only |

Quick start

cp -r <this skill>/starter my-film/previz && cd my-film/previz
bun serve.ts                          # http://localhost:8777/  review UI: shot view, set map, timeline, panel
bun tools/check.ts                    # headless: UI screenshot, frames per shot, contact sheet, seek-safety test
bun tools/capture.ts                  # renders/animatic.mp4, frame-exact, 24 fps

The demo is generic: two mannequins at a cafe table, a drone flies in and lands; 3 shots, 10 s, 16:9, 120 BPM. Replace js/config.js (format, bpm), js/sets.js (the place), js/shots.js (shots + blocking). The rest is the engine. starter/README.md lists every key and file.

The workflow

1. Brief. Write the director's words verbatim, dated, in brief.md. Lock format (aspect, length, fps), music or VO, BPM. Every later note gets applied to brief, shot list and animatic in the same pass.
2. Shot list. One entry per shot: id, start/end (cuts on bar lines when there is music; the hook in the first 2–3 s), picture (what we see), action (what happens, written for the video model), camera words, subjects to check. In the starter this is SHOTS in js/shots.js; long projects keep a storyboard.json.
3. Master sets. One set per location, built from primitives in real metres from one master plate, with every story object named in S.o. → references/sets-and-blocking.md
4. Mannequin blocking. Jointed mannequins posed from a pose library, blended by time ramps; the action is blocked ONCE in world time (BLOCKING(S, T)), and every shot is only a camera on it. → references/mannequin-rig.md
5. Cameras. Per shot a START and END key (position, look-at target on the subject, lens, roll), an ease and a path (line, or arc for orbits). Key them in code, then fix them by eye in the UI (1/2, drag, write). → references/camera-language.md
6. Review. Shot view + top-down set map with every START/END frustum + automatic warnings (out of frame, on the edge, blocked, camera inside geometry). Run bun tools/check.ts and LOOK at checks/sheet.png (START, middle, last frame before each cut). Do not report a shot as fine without having seen it.
7. Approve. Mark each shot approved / needs a fix with a note, ⌘S. If the direction is still open, approve stills first (capture.ts --stills) on a board, animate after.
8. Camera plan. "export plan" writes camera_plan.md (size, angle, lens, move, positions, status, notes) and camera_plan.json for prompts and tools.
9. Render the MP4. Path A: bun tools/capture.ts (headless Chrome over CDP, frame i = t i/fps, ffmpeg). Path B: bun tools/make_hf.ts → npx hyperframes render hf when the animatic needs HTML text, audio or Studio edits. Both call the same film.pose(t). → references/seek-safe-rendering.md
10. Seedance pack. Group shots into runs (one location, consecutive shots, 4–30 s), render each run as a greyscale clip with --shots … --grey, pick image references for exactly what is in frame, write the prompt. → references/seedance-v2v-pack.md
11. Generate on varg. Upload, estimate_cost, a yes from the person paying, ONE run first, then the batch. QA every output against its @video1, cut it back onto the timeline with the run's placement file.

Spend nothing before step 11 except cheap stills. Steps 1–9 are free, and notes cost least there.

Optional: look blockout (separate from the grey export)

The grey-box approves camera and blocking; a look blockout approves the look on the same set, for free. Reference pictures and generated matte paintings go onto the grey geometry as textures (backgrounds, ground, a few hero surfaces) with js/look.js; geometry, cameras and blocking stay code. Render one still per shot (bun tools/capture.ts --look --stills), put each next to its reference, list the gaps, fix one area at a time, up to 3 rounds, then the person approves the stills. A first version that "looks like a toy" gets a detail pass (textures, light matching the reference, small props for scale). → references/look-blockout.md

• Use it when the animatic itself is the final video (code-rendered), or to approve the look before paid generation. Turn it on only after camera and blocking are approved.
• Never feed a textured render as the greyscale @video1 unless that is deliberate. The v2v reference stays capture.ts --grey without --look; the look reaches Seedance through image references and the Look: line.
• Off by default: without ?look=1 / --look the review UI and every export are the plain grey film.

Camera cheat sheet

Size = frame height at the look-at target, 2·d·tan(vFOV/2):

| ECU | CU | MCU | MS | MLS | FS | WS | EWS | |---|---|---|---|---|---|---|---| | < 0.2 m | < 0.4 m | < 0.7 m | < 1.1 m | < 1.5 m | < 2.4 m | < 8 m | ≥ 8 m |

For objects divide by height / 1.8 (a 0.3 m bottle: 0.17). Angle from pitch: < −60° top, −60…−15° high, ±15° eye level, 15…60° low, > 60° worm's eye; roll > 5° dutch.

Lens (full-frame equivalent, 36 mm on the long side) → three.js vertical FOV:

| lens | 18 | 24 | 35 | 50 | 65 | 85 | 135 | |---|---|---|---|---|---|---|---| | 16:9 vFOV | 58.7° | 45.7° | 32.3° | 22.9° | 17.7° | 13.6° | 8.6° | | 9:16 vFOV | 90.0° | 73.7° | 54.4° | 39.6° | 31.0° | 23.9° | 15.2° |

Moves as keys: push in / pull out = p along the view, same t; zoom = fov only; truck = p and t sideways; crane = p.y; pan/tilt = t only; orbit = p around a fixed t with path arc; whip = whip ease; impact = shake: [s]. One move per shot.

Grammar: keep all cameras of a dialogue on one side of the 180° line (check the map); match eyelines; change angle by ≥ 30° or one size between consecutive shots of a subject; cut on action or on the beat; vary the coverage. Narrow frames: horizontal half-FOV = atan(tan(vFOV/2)·W/H); at 9:16 and vFOV 55° that is 16°.

Lessons and gotchas (from real sessions)

Building

• One location = one master set = one master plate. Wides and close-ups share it, or layouts and faces drift.
• Real metres and a 1.8 m mannequin beside every vehicle, product or creature. Models otherwise draw a person as big as their ship. Judge shot size against the main subject (a ship by its length, not by a person).
• Mannequins need real limbs, a head with a nose, and feet. Capsules come back as logs or bollards.
• Separate characters by luminance (light top vs dark top): the Seedance reference is greyscale.
• Keep poses clean and props in hands rare. Seedance copies poses literally: arms tangled around a helmet and a card in a fist both came back as artefacts. Simplify in the previz, say the detail in the prompt.
• Light every set with a hemisphere fill plus one key. A one-light mesh facing away renders as a black cutout; a dark creature against black space vanished until it got a rim light.
• No text, noise, TV static or glitch walls in the previz: text comes back garbled, static comes back as mush.
• Block action once in world time; per-shot cheats only where the wide cannot see them.

Reviewing

• Look at every frame. In one 36-shot pass the automatic and visual checks found: a camera inside a bulkhead (the shot showed only wall), a headrest hiding the subject, a head 33° below the axis with a 30° half-FOV (out of frame in 9:16), a drone flying straight into the lens, a glowing prop covering the frame, a wide that lost both subjects. The top-down frustum map shows most of these at a glance.
• Auto cameras and first guesses are starting points: expect to fix about a third of them by eye.
• Previz is where coverage variety is decided: all-frontal medium shots were the main review complaint once.
• Story notes are cheap here and expensive later ("the reveal must be more epic", "too long a pause between scenes", "make the weapon readable"): re-block and re-time in the animatic, not in generation.
• Record notes verbatim with dates; apply each one everywhere in the same pass.

Rendering

• What is on screen must be a pure function of t: seeded random, no clocks, no state between frames, speeds integrated in closed form. HyperFrames renders frames in parallel workers out of order. tools/check.ts proves it by comparing pixels across render orders.
• Render frame by frame (capture.ts or HyperFrames), never by screen recording.
• Headless Chrome: --headless=new --use-angle=swiftshader --enable-unsafe-swiftshader; a plain --screenshot also needs --virtual-time-budget=8000 or it captures before the first WebGL frame.
• HyperFrames + three.js: data-duration on the root is required; pin three (and three/addons/) in the import map; heavy setup goes on window.__hf.buildReady; check the last frame before each cut.
• Verify the tail of a padded run clip: the blocking keeps going while the camera holds, and later action can walk into frame.
• Review-UI bugs met for real: a body state class equal to a compone