Motion 3D skill

Motion 3D

Chunky extruded type and simple solids in a clean studio: a floor that melts into the background, one key light, soft shadows, a camera that drifts. The whole film is one HTML file that can draw any moment from the time alone, so it previews in Chrome, renders frame-exact, and loops without a seam.

The skill folder is ${CLAUDE_SKILL_DIR}; the reference files call it <skill>. If the variable shows up literally or empty in your shell (you opened this file directly, as a subagent or from a copy), it is the folder that holds this SKILL.md: put that absolute path in every command below.

A film lives in the user's project at videos/<film>/ (BRIEF.md, DESIGN.md, src/film.html, fonts/, the built <film>.html, stills/, renders/).

Ground rules

• True claims only. Every word on screen comes from the product's own live pages and is logged with its URL in BRIEF.md. A product with no live site takes its words from the user's brief only. See reference/brief.md.
• Only what is the user's to extrude. Type from an open font, the user's own SVG logo, and primitives. Never another company's logo or a model of someone else's product.
• Four words a beat, one call to action.
• seek(t) is pure. No timers, Date, Math.random, state or CSS animation; seeded randomness only. Geometry is built once, after the fonts load.
• One file. Fonts embedded as base64; the renderer is inline; nothing loads over the network. The build enforces it.
• The loop is seamless. The default is a cycle loop: every spin and orbit turns a whole number of times, every keyed move comes back (a full turn counts), and loopcheck finds the seam as smooth as any other instant.
• Look before you ship. Numbers pass while frames look wrong; read the stills and the decoded frames.
• The user decides what leaves the machine. Get a yes before any commit, push or upload.

Workflow

0. Once per machine. node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" doctor checks Node 20+, playwright-core, a Chromium, ffmpeg with libx264, ffprobe, npm and tar, and prints the exact command for anything missing. WebGL2 runs on the GPU, or on Chromium's software renderer when there is none (slower, same pixels every time). Re-run it until it says DOCTOR OK.
1. Brief intake. Name the video type first (a launch bumper, a feature highlight, a testimonial, an event promo...): reference/video-types.md gives each type its length, formats, beats and the styles that fit. Read the product's live site, then ask at most one round of questions (the word or logo to build, the message, which formats to deliver (1:1, 4:5, 9:16, 16:9), duration, palette). Defaults: 1080 x 1080 only, 10 s, 60 fps, 120 BPM, cycle loop, the template's palette or the brand's colours. For a logo, ask for the SVG. Fill templates/BRIEF.md into videos/<film>/BRIEF.md. See reference/brief.md.
2. Copy and staging. 1 to 3 beats: the hero (the word or the logo), what moves round it, a call to action in flat labels. At most 4 words of 3D type. Show the user and proceed unless they object; when nobody can answer, write them into BRIEF.md and proceed.
3. Design spec. Fill templates/DESIGN.md into videos/<film>/DESIGN.md: palette and materials, the light, the camera and its moves, every object with its size, place, material and motion on the tempo grid, the loop, and what changes in each other format. Read reference/3d-design.md, reference/engine.md and reference/springs.md.
4. Build and frame. Copy templates/film.html to videos/<film>/src/film.html and transcribe DESIGN.md into its FILM block (edit nothing below it). Fetch the fonts, build, and check the framing:

   node "${CLAUDE_SKILL_DIR}/scripts/fonts.mjs" videos/<film>
   node "${CLAUDE_SKILL_DIR}/scripts/build.mjs" videos/<film>
   node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" layout videos/<film>    # triangles, on-screen boxes at 0 s
   node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" at videos/<film> 0 2.5 5 7.5   # sharp stills to look at
   

   Move the camera (target, distance, pitch) until the hero sits in the live area with room to move. For each other format, add --format 9:16 (or 16:9, 4:5) to layout and at, and write its patch in FILM.formats: the camera fits the hero by itself, the patch redesigns the rest (engine.md, Formats). See reference/fonts.md and reference/core.md.
5. Stills and critique. node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" stills videos/<film> runs the automated critique (glyph coverage, words, the 3D type inside the live area through the loop and big enough to read, mesh counts, label contrast and placement, the loop and its cycles, the composition's balance) and writes stills at every key moment plus stills/contact.png. Run it once per delivered format, with --format 9:16 and so on (stills land in stills/9x16/). Read them for silhouettes, intersections, shadows and legibility; fix and repeat. See reference/review.md.
6. Render and verify.

   node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" loopcheck videos/<film>   # purity 0, the seam continuous
   node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" render videos/<film>      # MP4, GIF, poster (start it in the background)
   node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" verify videos/<film>      # ffprobe facts, tags, decoded pixels
   node "${CLAUDE_SKILL_DIR}/scripts/render.mjs" mp4frames videos/<film>   # decoded review frames + PSNR
   

   Run loopcheck, render, verify and mp4frames once per delivered format, with the same --format (the outputs carry it: renders/<film>-9x16.mp4, preview-9x16.gif, poster-9x16.png). Look at stills/mp4/contact.png and a strip of the whole film. Report the files, their sizes and the verify, loopcheck and mp4frames lines. See reference/render.md and reference/loops.md.

Pass criteria

• The hero reads in every frame of every delivered format: 3D type inside the live area at every sampled moment, its cap height at least 60 px on screen, front faces light against the background.
• The composition row passes at every delivered format, and each format looks designed for its frame, not a square picture floating in it.
• Nothing passes through anything: no ring through a letter, no orb through the floor, no letter through its neighbour while it flips.
• One key light, soft shadows grounding every object on the floor; the floor meets the background with no visible horizon.
• Every spin and orbit a whole number of turns per loop; every keyed value back where it started.
• Motion blur on moving frames; flat labels sharp.
• The deliverable MP4 is H.264, yuv420p, BT.709-tagged in the stream, faststart, exactly DUR x FPS frames.

Known pitfalls

• A torus spinning about its own axis looks still; tilt it and orbit it (loop: { orbit: [1, 0] }) so the tilt turns.
• Anything whose lowest point dips below the floor is cut by it. Keep pos.y at least the object's lower extent.
• The palette gate is not run for 3D: shading, antialiasing and motion blur make in-between colours at every silhouette. The lighting is hue-preserving (a surface is its colour times a light level, plus white), so surfaces keep their hue.
• Thin strokes and small counters in a light face extrude into slivers and break the bevel; use heavy display faces (Unbounded 800 to 900, Archivo Black).
• A letter flipping about x sweeps through its neighbours if the tracking is tight; give flipping type +30 to +60 tracking.
• The software renderer is slow: without a GPU, a 1080 x 1080 subframe with 4x MSAA and soft shadows takes 0.1 to 0.3 s, so the 10 s demo renders in 4 to 8 minutes (slow drifts take 2 subframes, fast flips up to 9). Keep scenes under about 100k triangles, and moves that need dozens of subframes rare.
• In a narrower format the camera's distance is multiplied by the fit, keys included: a patch sets camera.dist as it would be at 1:1, and a patch that sets pitch or target changes the fit too (it is measured from the rest camera).
• Contrast is checked on the material colours, but the lit front face is darker than its colour by up to a third: keep light type on a dark background or the reverse.