Skip to content

rlaope/oh-my-hermes / skills/omh-show-reel

omh-show-reel

Unverified

[omh] Video to make from an idea or a product: an explainer, motion graphics, kinetic type, a logo intro, a 3D scene, a data-viz animation, a music visual, a short or a source-grounded product film, authored and rendered to a measured MP4 with locale/export QA and source delivery. Use when the user says: show-reel, show reel, showreel, product showcase video, animated product film, motion showcase, animated portfolio, launch film.

FileKindSize
SKILL.mdskill md11.7 KB
references/art-direction.mdmarkdown9.4 KB
references/assets-and-rights.mdmarkdown1.9 KB
references/audio-production.mdmarkdown5.0 KB
references/brief-and-locales.mdmarkdown5.2 KB
references/craft-audio.mdmarkdown19.9 KB
references/craft-brief.mdmarkdown12.2 KB
references/craft-design.mdmarkdown15.5 KB
references/craft-engine.mdmarkdown26.5 KB
references/craft-images.mdmarkdown9.3 KB
references/craft-qa.mdmarkdown13.2 KB
references/craft-story.mdmarkdown20.6 KB
references/craft-techniques-2.mdmarkdown15.2 KB
references/craft-techniques.mdmarkdown22.6 KB
references/craft-workflow.mdmarkdown32.3 KB
references/cut-sheet.mdmarkdown8.3 KB
references/full-contract.mdmarkdown6.8 KB
references/game-capture.mdmarkdown1.8 KB
references/genres.mdmarkdown4.8 KB
references/kinetic-type.mdmarkdown6.7 KB
references/launch-film.mdmarkdown5.4 KB
references/motion-techniques.mdmarkdown4.3 KB
references/procedure.mdmarkdown17.0 KB
references/render-qa-delivery.mdmarkdown12.2 KB
references/renderer-adapter.mdmarkdown9.4 KB
references/source-package.mdmarkdown1.4 KB
references/storyboard-and-evidence.mdmarkdown6.5 KB
toolkit/LICENSE.upstreamother1.1 KB
toolkit/README.mdmarkdown18.7 KB
toolkit/assets/engine/engine.jsscript21.6 KB
toolkit/assets/engine/fx.jsscript20.9 KB
toolkit/assets/engine/index.htmlother3.0 KB
toolkit/assets/engine/scenes.jsscript12.7 KB
toolkit/assets/sfx_presets.jsonconfig3.3 KB
toolkit/examples/README.mdmarkdown744 B
toolkit/examples/music-spec.jsonconfig372 B
toolkit/examples/timing.jsonconfig146 B
toolkit/scripts/codex_ref_image.shscript2.6 KB
toolkit/scripts/contact_sheet.pyscript8.7 KB
toolkit/scripts/eleven.pyscript19.5 KB
toolkit/scripts/finish.pyscript8.0 KB
toolkit/scripts/font-coverage.mjsscript2.8 KB
toolkit/scripts/mix.pyscript9.5 KB
toolkit/scripts/motion_check.pyscript11.3 KB
toolkit/scripts/music_tools.pyscript29.4 KB
toolkit/scripts/narrate.pyscript12.5 KB
toolkit/scripts/new_project.pyscript10.5 KB
toolkit/scripts/preflight.pyscript5.6 KB
toolkit/scripts/prep_images.pyscript5.8 KB
toolkit/scripts/qa_check.pyscript7.1 KB
toolkit/scripts/render.mjsscript22.6 KB
toolkit/scripts/synth_music.pyscript6.4 KB
toolkit/scripts/timeline.pyscript16.6 KB
toolkit/scripts/tools/cutout.swiftscript1.8 KB
toolkit/upstream-manifest.jsonconfig20.3 KB

references/craft-engine.md

View on GitHub
> Translated in full from revfactory/showreel@64521220a2f8e91cb9894400c48c15b7f45205d6 `showreel/references/engine.md` (MIT, Copyright (c) 2026 Minho Hwang (revfactory); `toolkit/LICENSE.upstream`, provenance in `toolkit/upstream-manifest.json`). Read it for engine API, scene authoring, WebGL and 3D, splitting scenes across agents. `$S` is `toolkit/scripts` under the loaded skill directory. Commands here are upstream's; check the upstream command map in `toolkit/README.md` before running one. Content language follows `references/brief-and-locales.md`: Korean-first defaults apply only to Korean content, the craft bar applies to every locale; host install paths are placeholders here, upstream's default narration voice is named by role and chosen only through voice_policy, inline OMH notes mark where OMH policy overrides an upstream default, and the provider scripts are opt-in with the user's own key.

# Engine: How to Write Scenes, and Technique Code

Script paths on this page use `S=<skill_dir>/toolkit/scripts`, where `<skill_dir>` is this skill's folder.

## Contents

- Structure and rules
- API summary
- Order for writing scenes
- Technique code: text / numbers / photos / shapes and lines / canvas / transitions / narration and music sync
- WebGL: shaders and 3D
- Precomputed simulations
- Global layers (fx.js)
- Using the renderer
- Splitting the work
- Troubleshooting

## Structure and rules

```
<project>/reel/
  index.html    color and typeface tokens (:root), CSS shared by scenes
  engine.js     the engine (do not edit -- new_project.py overwrites it with the latest version)
  fx.js         global layers (grain, HUD, subtitles, flashes, etc.)
  timeline.js   generated by timeline.py (window.TL: cues, narration word times, music hits)
  scenes.js     scene code -- write only here (with many sections, split into scenes_s01.js ... and add script tags to index.html)
  _example_scenes.js  API usage examples (not loaded). Do not use it as the starting point for the visuals
  lib/          keep external scripts such as WebGL libraries here as files (do not rely on the network during a render)
  fonts/        filled by new_project.py
```

The server root is the project folder. Load images by relative path, such as `../assets/img/x.jpg`.

**Rules** -- The renderer jumps straight to arbitrary times, several workers split the timeline into ranges and draw them, and for motion blur it also captures fractional times between frames. Therefore:

1. The result of `render(lt)` must depend only on time. Do not accumulate values computed in a previous frame.
2. Do not use `Math.random()`, `Date.now()`, `performance.now()`, CSS `transition`/`animation`/`@keyframes`, or `requestAnimationFrame` loops. For randomness use `rand(i, salt)`; for jitter use `noise(t, seed)`. Calculations that need accumulation (physics simulations) are computed ahead of time in setup (see "Precomputed simulations" below).
3. Build the DOM in `setup` and only change styles in `render`. Do not create or remove elements in `render`.
4. Use cues instead of numbers for times: `cue('name')`, `cue('line.n03')`, `cue('music.hit2')`. Even if the narration is regenerated, the visuals follow it.
5. Finish exits 0.1 seconds before the scene ends. This is the most common cause of blank frames and ghosting at scene boundaries.

## API summary

```js
const { ease, prog, win, kf, spring, clamp, lerp, map, rand, noise, split, stagger, count, scramble, shake, pulse, level, inout, charTimes, sayChars, bar, beat, css, h, s, cue } = REEL;
REEL.config({ duration: 60, fps: 30, width: 1920, height: 1080, audio: '../audio/mix.wav' }); // audio is for preview only
REEL.scene({ id: 'intro', start: 0, end: cue('line.n03') - 0.3,
  setup(el) { /* build the DOM, SVG, canvas. Store them on this */ },
  render(lt, ctx) { /* lt = time within the scene. ctx = { t, dur, p } */ } });
REEL.img(src)        // preload an image (rendering waits until it is ready) → HTMLImageElement
REEL.TL              // timeline.js: { cues, vo:[{id,text,sub,start,end,words:[[word,start,end]]}], music:{bpm,beats,downbeats,hits} }
```

| Function | Description |
| --- | --- |
| `prog(t, start, dur, e=ease.snap)` | 0->1 over dur, starting at start |
| `win(t, a, b, inDur, outDur)` | 0->1->0, entering at a and leaving at b |
| `kf(t, [[t0,v0],[t1,v1,ease],…])` | Keyframe interpolation |
| `spring(t, t0, f=2.2, z=0.42)` | Damped spring 0->1 (slight overshoot) |
| `split(el, 'char'|'word', {mask})` | Array of character or word spans. Hangul is split by syllable |
| `stagger(t, start, each, dur, i, e)` | Delayed progress of the i-th element |
| `count(p, to, {decimals, from})` | Number string with thousands-separator commas |
| `scramble(final, p, t, seed)` | Resolves from random characters into the final string (Hangul into Hangul) |
| `shake(t, [[t0, amp, decay]])` | {x, y, r} shake |
| `pulse(t, [t0, …], decay)` | Decays from 1 at each hit |
| `inout(el, t, a, b, o)` | Enters at a from a lowered, blurred, enlarged state, and at b exits by being pushed upward while shrinking and blurring. Use this for exits instead of a fade |
| `charTimes(id, sub)`, `sayChars(spans, t, times)` | Per-character narration times; raises the characters one at a time in step with those times |
| `bar(n, frac)`, `beat(n)` | Time of the n-th bar or beat (1-based, same as the cue `bar1`) |
| `level(t, src)` | Loudness 0-1. Without src, the narration at that time; with a line id, that line; with `'music'`, the music energy (a curve made by `timeline.py`) |
| `ease.*` | linear, in/out/inOut Quad/Cubic/Quart/Expo, outQuint, outBack, outElastic, inOutSine, **snap** (entrance), **swift** (in-out), **exit** (exit), **pop** (chips) |

## Order for writing scenes

1. One `REEL.scene` per storyboard scene. Set the start and end with cues.
2. For each section, build a representative frame first and look at the still sheet (style frames, SKILL.md step 7). Once the sections look like different pieces of work and each frame is good enough to serve as a poster, build the rest.
3. Each time you write a scene, pull stills at that scene's start+0.5 s, cue+0.4 s, and end-0.6 s, and look at them.
4. If global layers (camera, flashes, subtitles, etc.) are needed, attach them last.

## Technique code

The code below consists of snippets to drop into `setup`/`render` as they are. Values assume 1920x1080.

### Text: an entrance rising inside a mask

```js
setup(el) {
  this.t1 = h('div', 'center display', el, '무대가 된다.'); css(this.t1, { top: '440px', fontSize: '200px' });
  this.c1 = split(this.t1, 'char', { mask: true });
},
render(lt) {
  const out = prog(lt, 3.2, 0.35, ease.exit);
  this.c1.forEach((c, i) => {
    const p = stagger(lt, 0.2, 0.04, 0.6, i);
    css(c, { transform: `translateY(${(1 - p) * 135 - out * 135}%)`, opacity: p > 0 ? 1 : 0, filter: `blur(${(1 - p) * 8}px)` });
  });
}
```

Because of the margin under the mask (.18em), at 110% the tops of the characters show through like a dash. Push them down to 135% and keep opacity at 0 before the entrance.

### Text: slam (landing on a hit)

```js
const T = cue('name');                                   // time at which the name is pronounced in the narration
const sp = prog(lt, T - start - 0.28, 0.3, ease.snap);   // starts 0.28 s before the hit and lands on the hit
css(this.name, { opacity: sp, transform: `scale(${lerp(1.9, 1, sp)})`, filter: `blur(${(1 - sp) * 24}px)` });
```

Duplicating the same text in the accent color, overlaying it with `mix-blend-mode: screen`, and making it grow and fade over the 0.5 seconds after the hit produces an afterimage (the code is in the opening scene of `reel/_example_scenes.js`).

### Text: scramble and typewriter

```js
this.tag.textContent = scramble('<section copy>', prog(lt, 0.2, 0.6, ease.linear), lt, 3);
const full = '<section copy>';                              // typewriter + blinking cursor
this.kick.textContent = full.slice(0, Math.floor(prog(lt, 0.4, 0.6, ease.linear) * full.length)) + (Math.floor(lt * 4) % 2 ? '▍' : ' ');
```

### Text: letters that hold a photo

```js
css(this.word, { backgroundImage: 'url(../assets/img/stage.jpg)', backgroundSize: 'cover',
  backgroundPosition: `${50 + lt * 6}% 50%`, WebkitBackgroundClip: 'text', backgroundClip: 'text', color: 'transparent',
  WebkitTextStroke: '1.5px rgba(255,236,200,.6)' });
```

### Text: light sweep

```js
css(this.name, { backgroundImage: 'linear-gradient(105deg, var(--ink) 40%, var(--accent) 50%, var(--ink) 60%)', backgroundSize: '300% 100%',
  WebkitBackgroundClip: 'text', color: 'transparent', backgroundPosition: `${lerp(100, -100, prog(lt, 1.2, 1.1, ease.inOutSine))}% 0` });
```

### Numbers: count-up

```js
this.num.textContent = count(prog(lt, 0.3, 1.6, ease.outQuart), 12840000);   // 12,840,000
css(this.num, { fontFamily: 'var(--num)', fontSize: '320px', fontVariantNumeric: 'tabular-nums' });
```

Use `tabular-nums` so the width does not wobble as the digits change. Attach units ("명" (people), "%") small, in the body typeface.

### Photos: Ken Burns + a scrim on the text side

```js
setup(el) {
  this.im = REEL.img('../assets/img/city.jpg');
  this.wrap = h('div', 'full', el); this.wrap.appendChild(this.im);
  css(this.im, { width: '100%', height: '100%', objectFit: 'cover', filter: 'saturate(.8) brightness(.85)' });
  h('div', 'full', el).style.background = 'linear-gradient(90deg, rgba(0,0,0,.82) 0%, rgba(0,0,0,0) 60%)';
},
render(lt, ctx) {
  css(this.im, { transform: `scale(${lerp(1.08, 1.18, ctx.p)}) translateX(${lerp(0, -2, ctx.p)}%)` });
}
```

### Photos: 3D card + clip wipe

```js
const open = prog(lt, 0.15, 0.7, ease.swift);
css(this.card, { clipPath: `inset(0 ${(1 - open) * 100}% 0 0)`,
  transform: `perspective(1600px) rotateY(${lerp(-18, -6, open)}deg)`, boxShadow: '0 40px 90px rgba(0,0,0,.6)' });
```

### Photos: cutout + rim light

```js
// A transparent PNG made with prep_images.py --cutout. The cutout is used as a mask so the section palette's light falls only on the inner edge of the person
css(this.rim, { WebkitMaskImage: 'url(../assets/img/person_cut.png)', WebkitMaskSize: 'contain', WebkitMaskRepeat: 'no-repeat',
  background: 'linear-gradient(100deg, var(--accent), transparent 45%)', mixBlendMode: 'screen' });
css(this.person, { filter: 'drop-shadow(0 0 30px var(--accent))' });
```

### Shapes and lines: drawing SVG lines (node graphs, maps, diagrams)

```js
setup(el) {
  this.svg = s('svg', { width: 1920, height: 1080, viewBox: '0 0 1920 1080' }, el); this.svg.style.position = 'absolute';
  this.path = s('path', { d: 'M200,540 C600,200 1000,880 1700,540', fill: 'none', stroke: 'var(--accent)', 'stroke-width': 3 }, this.svg);
  this.len = this.path.getTotalLength();                 // setup runs while the screen is visible, so the length can be measured
  this.path.style.strokeDasharray = this.len;
},
render(lt) { this.path.style.strokeDashoffset = this.len * (1 - prog(lt, 0.3, 1.2, ease.swift)); }
```

Light the nodes one per beat: `const k = REEL.TL.music?.beats?.filter(b => b <= t).length`.

### Shapes: giant outline marquee

```js
css(this.marq, { fontFamily: 'var(--num)', fontSize: '340px', whiteSpace: 'nowrap', color: 'transparent',
  WebkitTextStroke: '2px rgba(243,239,230,.12)', transform: `translateX(${-200 - lt * 120}px)` });
```

### Canvas: particles gathering into text

The calculation is in the setup and render code of the end card in `reel/_example_scenes.js`. Do not copy its colors, typefaces, or composition. The essentials are as follows.

1. In setup, draw the text on an offscreen canvas (the fonts are already loaded).
2. Sample the pixels that have alpha at 5px intervals to make target points.
3. For each particle, set the start point and delay with `rand`.
4. In render, compute the position with `lerp(start, target, ease(progress))`. Do not use the previous position.
5. Use `globalCompositeOperation = 'lighter'` so overlapping areas get brighter.

### Canvas: deterministic flow and data rain

Always compute particle positions as `f(i, t)`. For example, dots flowing across the screen: `x = (rand(i,1)*W + t*speed_i) % W`, `y = rand(i,2)*H + noise(t*0.3, i)*20`. Clear the canvas and redraw it every frame. If you need trails, draw several past times (t-0.03, t-0.06...) with the same formula.

### Transitions: color-field wipe

```js
const wi = prog(lt, 0, 0.22, ease.swift), wo = prog(lt, 0.22, 0.3, ease.swift);
css(this.wipe, { transform: `scaleX(${wo > 0 ? 1 - wo : wi})`, transformOrigin: wo > 0 ? '100% 50%' : '0% 50%' });
```

### Transitions: push

For a transition that pushes the whole next scene up from below, **do not give the background to the scene `section` (el); give it to the moving inner root.** If the section has the background, it covers the previous scene while it slides in, and 2-3 frames go blank.

```js
setup(el) { this.root = h('div', 'full', el); css(this.root, { background: 'var(--bg)' }); /* content goes inside this.root */ },
render(lt) { css(this.root, { transform: `translateY(${(1 - prog(lt, 0, 0.35, ease.swift)) * 100}%)` }); }
```

### Transitions: zoom through

```js
const z = prog(lt, endAt - 0.3, 0.3, ease.inExpo);        // last 0.3 s of the scene
css(this.root, { transform: `scale(${1 + z * 8})`, transformOrigin: '975px 548px', filter: `blur(${z * 6}px)` });
// a short FX.flash 0.1 at the start of the next scene
```

`transformOrigin` is the point you zoom into (a pupil, the hole in the letter 'ㅇ' (the Hangul letter ieung), a monitor).

### Narration sync: popping up word by word

```js
const line = REEL.TL.vo.find(v => v.id === 'n05');        // words: [[word, start, end], …] follow the pronunciation spelling (tts)
line.words.forEach(([w, t0], i) => { const p = prog(t, t0 - 0.06, 0.25); css(this.ws[i], { opacity: p, transform: `translateY(${(1 - p) * 40}px)` }); });
```

Build the on-screen text separately, from the on-screen spelling, and take only the times from `words`. If the word counts differ, use `cues` to name only the words you need.

### Music sync: reacting to beats and hits

```js
const hits = REEL.TL.music?.hits || [];
const b = pulse(t, hits, 0.25);                           // decays from 1 at each hit
css(this.glow, { opacity: 0.3 + 0.5 * b, transform: `scale(${1 + 0.04 * b})` });
```

Align scene boundaries to the nearest value among the `downbeats`. When the cuts land on the beat, the edit comes alive.

### Reacting to loudness: waveforms and a border that glows while speaking

`timeline.py` puts loudness curves into `timeline.js`: at 20ms intervals for each narration line, and at 50ms intervals for the music. If you change the narration or the music, you only need to rerun `timeline.py`.

```js
// Voice introduction: while speaking, the bar waveform follows the actual voice
bars.forEach((b, i) => {
  const v = level(t - (bars.length - 1 - i) * 0.03);          // each bar takes a value 30ms further back → a flowing waveform
  b.style.transform = `scaleY(${0.06 + 0.94 * v})`;
});
css(this.frame, { boxShadow: `0 0 ${40 * level(t, 'n12')}px var(--accent)` });  // reacts only to a specific line
css(this.bg, { opacity: 0.35 + 0.4 * level(t, 'music') });  // background brightness follows the music energy
```

Use it as is for large motions such as bar height, and scale it down to 0.3-0.5x for conspicuous values such as brightness and size. The value changes every frame, so if the flicker is severe, average it, as in `(level(t) + level(t - 0.04) + level(t - 0.08)) / 3`.

## WebGL: shaders and 3D

In the renderer (headless Chrome), WebGL2 shaders and three.js (r160 `build/three.min.js`) scenes render, a different frame comes out for each time, and `--sub 4` motion blur works too (confirmed 2026-10). The rules are the same as for other scenes: drawing happens only inside `render(lt)`, and only as a function of time.

- Create the context with `preserveDrawingBuffer: true`. This keeps frames from coming out black because the buffer is empty at capture time.
- Fix the canvas size at `REEL.W × REEL.H` pixels and set the CSS size to match. The scene coordinates do not change even in a `--scale 0.5` draft.
- Put the licensed library files you were given (or that exist in the approved dependency root) into `reel/lib/` and load them in `index.html`, before `engine.js`, with `<script src="lib/three.min.js"></script>`. Do not rely on a CDN during a render.
- For the three.js animation mixer, set the time with `mixer.setTime(lt)`. Do not use `clock.getDelta()`.
- To render Hangul in 3D, draw the text on a 2D canvas and attach it as a `THREE.CanvasTexture`, or lift points sampled from the text pixels (T04) into 3D coordinates.

Shader (a fragment shader on a single full-screen quad):

```js
setup(el) {
  const c = h('canvas', '', el); c.width = REEL.W; c.height = REEL.H;
  css(c, { position: 'absolute', left: 0, top: 0, width: REEL.W + 'px', height: REEL.H + 'px' });
  const gl = this.gl = c.getContext('webgl2', { preserveDrawingBuffer: true, antialias: true });
  const sh = (type, src) => { const o = gl.createShader(type); gl.shaderSource(o, src); gl.compileShader(o);
    if (!gl.getShaderParameter(o, gl.COMPILE_STATUS)) throw new Error(gl.getShaderInfoLog(o)); return o; };
  const pr = this.pr = gl.createProgram();
  gl.attachShader(pr, sh(gl.VERTEX_SHADER, `#version 300 es
in vec2 p; void main(){ gl_Position = vec4(p, 0., 1.); }`));
  gl.attachShader(pr, sh(gl.FRAGMENT_SHADER, `#version 300 es
precision highp float; uniform float t; uniform vec2 r; out vec4 o;
void main(){ vec2 u = (gl_FragCoord.xy - .5 * r) / r.y;
  float d = length(u) - .3 - .05 * sin(10. * atan(u.y, u.x) + t * 6.);
  o = vec4(mix(vec3(1., .3, .1), vec3(.05, .1, .3), smoothstep(0., .01, d)), 1.); }`));
  gl.linkProgram(pr);
  gl.bindBuffer(gl.ARRAY_BUFFER, gl.createBuffer());
  gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 1, -1, -1, 1, 1, 1]), gl.STATIC_DRAW);
  const loc = gl.getAttribLocation(pr, 'p'); gl.enableVertexAttribArray(loc); gl.vertexAttribPointer(loc, 2, gl.FLOAT, false, 0, 0);
},
render(lt) {
  const gl = this.gl; gl.viewport(0, 0, REEL.W, REEL.H); gl.useProgram(this.pr);
  gl.uniform1f(gl.getUniformLocation(this.pr, 't'), lt);
  gl.uniform2f(gl.getUniformLocation(this.pr, 'r'), REEL.W, REEL.H);
  gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
}
```

three.js:

```js
setup(el) {
  const r = this.r = new THREE.WebGLRenderer({ antialias: true, preserveDrawingBuffer: true });
  r.setPixelRatio(1); r.setSize(REEL.W, REEL.H, false); el.appendChild(r.domElement);
  css(r.domElement, { position: 'absolute', left: 0, top: 0, width: REEL.W + 'px', height: REEL.H + 'px' });
  this.scene = new THREE.Scene();
  this.cam = new THREE.PerspectiveCamera(35, REEL.W / REEL.H, 0.1, 100); this.cam.position.set(0, 0, 8);
  this.m = new THREE.Mesh(new THREE.TorusKnotGeometry(1.4, 0.45, 256, 32),
    new THREE.MeshStandardMaterial({ color: 0xff5a1f, metalness: 0.6, roughness: 0.25 }));
  const key = new THREE.DirectionalLight(0xffffff, 3); key.position.set(3, 4, 5);
  this.scene.add(this.m, key, new THREE.AmbientLight(0x404060, 1.2));
},
render(lt) { this.m.rotation.set(lt * 0.8, lt * 1.3, 0); this.r.render(this.scene, this.cam); }
```

Note: you do not need to draw while the scene is off (`display:none`). Make randomness in a shader with a deterministic hash such as `fract(sin(dot(...)))`. A large shader can take tens of ms per frame, so look at the draft render time and estimate the final render time from it.

## Precomputed simulations

For motion that needs the previous state, such as cloth flapping or fragments colliding and piling up, compute it in setup all the way to the end at a fixed interval (1/fps or finer), store it in an array, and in render read it by time and interpolate. Set the randomness of the initial values with `rand(i, salt)`. This way the same image comes out no matter which time a render worker starts drawing from.

```js
setup() {
  const N = 400, steps = Math.ceil((this._e - this._s) * 120);          // scene length (s) × 120 steps. The engine fills _s and _e before setup
  const S = this.states = new Float32Array((steps + 1) * N * 2);
  let x = Array.from({ length: N }, (_, i) => rand(i, 1) * REEL.W), y = Array.from({ length: N }, (_, i) => -rand(i, 2) * 600);
  let vx = x.map((_, i) => (rand(i, 3) - 0.5) * 200), vy = x.map(() => 0);
  for (let k = 0; k <= steps; k++) {
    for (let i = 0; i < N; i++) {
      S[(k * N + i) * 2] = x[i]; S[(k * N + i) * 2 + 1] = y[i];
      vy[i] += 2400 / 120; x[i] += vx[i] / 120; y[i] += vy[i] / 120;
      if (y[i] > 900) { y[i] = 900; vy[i] *= -0.45; vx[i] *= 0.8; }  // bounces off the floor
    }
  }
  this.N = N; this.steps = steps;
},
render(lt) {
  const f = Math.min(this.steps, lt * 120), k = Math.floor(f), a = f - k, k2 = Math.min(this.steps, k + 1), S = this.states;
  for (let i = 0; i < this.N; i++) {
    const px = S[(k * this.N + i) * 2] * (1 - a) + S[(k2 * this.N + i) * 2] * a;
    const py = S[(k * this.N + i) * 2 + 1] * (1 - a) + S[(k2 * this.N + i) * 2 + 1] * a;
    // draw with px, py
  }
}
```

`this._s` and `this._e` are the scene's start and end times (in seconds), which the engine fills in before it calls setup. If the number of steps times the number of elements goes past tens of millions, setup takes a long time, so reduce the element count or the interval.

## More expressions

Isometric cities, Hangul jamo assembly, variable-weight waves, glass and chrome type, prism light rays, beat grids, data pulses, mechanical counters, 3D device UI, punch-ins, match cuts, beat montages, afterimages, and more are in `craft-techniques.md`, together with code. The rules on sync, the first frame, flashes, and determinism at the very start of that document apply to every scene.

## Global layers (fx.js)

All of these are optional. Call only what the concept needs, at the end of `scenes.js`. The call order is the top-to-bottom order. Do not attach letterbox, grain, vignette, and HUD all together out of habit (the "obvious screens" in `craft-design.md`).

```js
FX.camera({ shakes: [[cue('name'), 14, 0.4]], drift: 0.6 });          // shake and drift for the whole scene
FX.flash([[cue('name'), 0.2, 0.12]]);                                  // [time, length, intensity (≤0.15), color]
FX.leak([[cue('scene.s02'), 1.4, 'rgba(255,170,70,.9)', 0.7]]);
FX.letterbox(t => 1 - prog(t, cue('name') - 0.1, 0.5, ease.swift) + prog(t, 57, 0.5, ease.swift));  // 1=closed
FX.vignette({ strength: 0.6 });
FX.grain({ opacity: 0.09 });
FX.hud({ left: '<label>', chapters: [[0, '<section name>'], ['scene.s01', '<section name>']], from: 3, to: 57 });
FX.subtitles({ size: 40 });                                            // burns in the sub of TL.vo. "nosub" lines are left out of the burn-in only (they stay in the SRT; to leave them out of the SRT use "nosrt")
// For vertical (9:16) video, the HUD and subtitles automatically avoid the app UI areas (top 250px, bottom 420px)
```

## Using the renderer

```bash
node $S/render.mjs --dir reel --serve                                  # preview URL (you may also give it to the user)
node $S/render.mjs --dir reel --stills 1.2,4.5,9 --outdir qa/stills    # stills at the given times
node $S/render.mjs --dir reel --every 0.5 --from 8 --to 16 --outdir qa/stills_s01
node $S/render.mjs --dir reel --out out/draft.mp4 --scale 0.5          # draft
node $S/render.mjs --dir reel --out out/video.mp4 --sub 4 --format png # final (motion blur)
```

- The first line of the log lists the loaded fonts. If the typeface you want is not there, check `fonts/fonts.css`.
- Exit code 2 is a page error. Fix the `[pageerror]` in the log.
- The render log shows only `console.error` and `console.warn` messages that start with `[REEL]`. Leave debug values from scene code with `console.warn('[REEL] …')`.
- The final render is saved in chunks (2 seconds each), so if it is interrupted, running the same command again resumes the render. If you change settings, it renders again from the beginning.
- If another render is running on the same computer, it becomes more than 10x slower. Cut it down with `--workers 2`.

## Splitting the work

For a showreel with many sections or a video longer than 3 minutes, split the code per section (or chapter) into `scenes_s01.js`, `scenes_s02.js` and add script tags to `index.html`. Keep shared helpers in `scenes_common.js`. For a showreel whose art direction differs per section, you can hand the sections to subagents, one each, and build them concurrently. The main agent checks that the concept holds, and takes the transitions between sections and the overall critique.

When handing a section to a subagent, put the following contract in the prompt.

- Read first: this document (craft-engine.md), craft-design.md, its own section's row in `concept.md` (medium, palette, typeface, motion, technical challenge, how it connects), `reel/scenes_common.js`, and its own section's part of `timeline.json`
- Bar: the "Standards this skill meets" table at the very top of SKILL.md. Its section must read as one independent piece of work
- Edit scope: only `reel/scenes_sNN.js` and that section's files in `reel/lib/` and `assets/`. Do not fix problems in shared files; report them
- Keep working files inside the project folder. Do not use `/tmp`
- Safe area, subtitle area, no unintended hold longer than 1 second, cues within ±3 frames, no new information in the last 10 frames, no `Math.random`
- Verification: for each scene, pull stills at start+0.5, cue+0.4, and end-0.6 s, plus frame strips of the key moments (at 0.033-0.1 s intervals), into `qa/stills_sNN/`; check the sheets with Read and fix things, then report
- Keep the report short (no pasted code): the scenes built, the paths of the sheets checked, problems in shared code, and what it sees itself as the weakest point of this section. Return the report as response text. If a subagent is told to write a report file, the execution environment may block it, so if a record is needed, the main agent saves the report it received to a file

## Troubleshooting

| Symptom | Cause and fix |
| --- | --- |
| Elements of another scene show through | The engine turns scenes off with `display:none`. If the element was created outside the scene (`REEL.top`, etc.), hide it yourself |
| Text is visible on the first frame and then disappears | Check that the pre-entrance state (opacity 0, translate) is applied in `render` even when lt=0 |
| Text width or position is off | Measuring in `setup` works (it runs after the fonts load). Do not measure during the render |
| The image jumps at worker boundaries | There is accumulated state. Rewrite render as a function of time |
| Rendering is slow | Reduce full-screen `filter: blur()` and large `box-shadow`. Keep canvas particles within 2,000-10,000, and create gradient objects in setup |
| Blank frames at scene boundaries | Make something, anything, move in the next scene within 6-20 frames of its start. Finish exits 0.1 s before the cut |
| Cropping at 9:16 | Change width/height in `REEL.config` and write coordinates as ratios of `REEL.W`/`REEL.H` |
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 323kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 323kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 323kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall