Web sims

sims/README.md

When to use this instead of Remotion

• Hundreds of moving things with their own rules (agents, particles, crawlers).
• A 3D object or machine the camera moves around or flies through.
• Anything that is easier to write as a three.js or canvas page than as React.

src/

Workflow

1. Agree on the idea, the hero moment and the length with the user. Default format: 1080×1350 layout (4:5), 60 fps, 20–24 s.
2. Put every beat in a

   timeline.json

   next to the sim (chapters, the hero moment, camera keys). Sound scripts read the same file.
3. Start from the closest example:

   crawlers

   (agents on DOM text),

   dossier

   (the same plus screen-space overlays),

   engine

   (three.js object with cutaway, chapters, fly-through, exploded view, generated sound).
4. Simulate anything stateful once at load;

   render(t)

   only reads it.
5. Build:

   node sims/build.mjs <name>

   .
6. Review with stills at every beat:

   node sims/capture.mjs <name> --stills 0,2,5,8,12,16,20 --cols 4 --out out/sims/<name>-review.png

   . Open the sheet and check it like the review loop says: frame 0 strong, one focal point per frame, nothing blown out by bloom, text readable on a phone, labels never cover the subject. Fix and repeat.
7. Sound: a music track (

   --music

   , the sim gets

   cfg.beats

   and should hit the drop), a generated bed (

   python3 sims/<name>/sound.py

   like

   sims/engine/sound.py

   ), or both mixed with ffmpeg first.
8. Capture:

   node sims/capture.mjs <name> --size 1080x1350 --out out/sims/<name>.mp4

   and look at a sheet of the final file before calling it done.

Lessons from the examples

• Bloom eats detail: keep emissive and additive layers under ~1.0 and raise them only for the one hero moment.
• Glossy metal plus a low sun gives white streaks. Use roughness ≥ 0.45 and envMapIntensity ≈ 0.5 on big surfaces.
• One hero object beats a crowd. If parts hide the subject, move them out of the way or fade them.
• Chapters + a one-line caption per step + labels with real numbers make a simulation read as an explanation, not just eye candy.
• A camera that flies through the object is worth more than ten orbits.