@algorisys/tinyfly 0.100.0 → 0.102.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/README.md +6 -6
  2. package/bin/tinyfly.mjs +16 -6
  3. package/docs/character-appearance.md +26 -0
  4. package/docs/editor-guide.md +1 -1
  5. package/docs/examples.md +1 -1
  6. package/docs/getting-started.md +1 -1
  7. package/docs/gsap-compat.md +1 -1
  8. package/docs/llm-guide.md +22 -4
  9. package/docs/maps.md +2 -2
  10. package/docs/scene-3d.md +140 -9
  11. package/docs/teaching.md +1 -1
  12. package/docs/video-rendering.md +198 -1
  13. package/lib/addons/adapters.js +431 -332
  14. package/lib/addons/characters.js +3889 -3773
  15. package/lib/addons/load-scene-oWNsYYC1.js +372 -0
  16. package/lib/addons/scene-3d-webgl.js +31 -31
  17. package/lib/addons/scene-3d.js +669 -314
  18. package/lib/addons/shading-0lPgnXmD.js +96 -0
  19. package/lib/browser/tinyfly-scene-3d-webgl.iife.js +2 -2
  20. package/lib/browser/tinyfly-scene-3d.iife.js +2 -2
  21. package/lib/browser/tinyfly.iife.js +15 -15
  22. package/lib/browser/tinyfly.js +6232 -5723
  23. package/lib/browser/tinyfly.umd.js +15 -15
  24. package/lib/engine/tinyfly-engine.js +1563 -1170
  25. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  26. package/lib/headless/headless.js +189 -6
  27. package/lib/types/adapters/canvas/framing.d.ts +27 -0
  28. package/lib/types/adapters/canvas/impossible.d.ts +15 -0
  29. package/lib/types/adapters/canvas/index.d.ts +4 -0
  30. package/lib/types/adapters/canvas/nested-zoom.d.ts +40 -0
  31. package/lib/types/adapters/canvas/zoom-blur.d.ts +49 -0
  32. package/lib/types/characters/character-script-3d.d.ts +21 -1
  33. package/lib/types/characters/character.d.ts +23 -3
  34. package/lib/types/characters/head/face.d.ts +19 -2
  35. package/lib/types/characters/index.d.ts +2 -1
  36. package/lib/types/characters/staging-3d.d.ts +56 -0
  37. package/lib/types/engine/authoring/beat-loop.d.ts +46 -0
  38. package/lib/types/engine/authoring/curve.d.ts +26 -0
  39. package/lib/types/engine/authoring/framing.d.ts +48 -0
  40. package/lib/types/engine/authoring/index.d.ts +4 -0
  41. package/lib/types/engine/authoring/periodic.d.ts +89 -0
  42. package/lib/types/engine/path/goo.d.ts +103 -0
  43. package/lib/types/engine/path/impossible.d.ts +92 -0
  44. package/lib/types/engine/path/index.d.ts +6 -0
  45. package/lib/types/engine/path/similarity.d.ts +48 -0
  46. package/lib/types/headless/audio-mix.d.ts +40 -0
  47. package/lib/types/headless/ffmpeg-args.d.ts +2 -0
  48. package/lib/types/headless/frame-renderer.d.ts +7 -1
  49. package/lib/types/headless/index.d.ts +2 -0
  50. package/lib/types/headless/loop-audio.d.ts +21 -0
  51. package/lib/types/headless/node-audio.d.ts +39 -0
  52. package/lib/types/headless/node-video.d.ts +2 -0
  53. package/lib/types/headless/video-scene.d.ts +21 -0
  54. package/lib/types/scene-3d/camera.d.ts +11 -2
  55. package/lib/types/scene-3d/geometry/mesh.d.ts +2 -0
  56. package/lib/types/scene-3d/geometry/primitives.d.ts +7 -0
  57. package/lib/types/scene-3d/impossible-3d.d.ts +29 -0
  58. package/lib/types/scene-3d/index.d.ts +7 -3
  59. package/lib/types/scene-3d/lighting.d.ts +58 -0
  60. package/lib/types/scene-3d/resolve-scene.d.ts +18 -2
  61. package/lib/types/scene-3d/scene-3d-adapter.d.ts +4 -0
  62. package/lib/types/scene-3d/scene-types.d.ts +43 -6
  63. package/lib/types/scene-3d/shading.d.ts +2 -0
  64. package/lib/types/scene-3d/shots.d.ts +162 -0
  65. package/lib/types/scene-3d/software-renderer.d.ts +40 -0
  66. package/llms-full.txt +395 -23
  67. package/llms.txt +29 -29
  68. package/package.json +1 -1
  69. package/skills/tinyfly/SKILL.md +11 -1
  70. package/lib/addons/load-scene-CQvcFWGJ.js +0 -331
  71. package/lib/addons/shading-o5T_v9DT.js +0 -89
package/llms-full.txt CHANGED
@@ -204,7 +204,7 @@ with a GSAP-style call (durations are in seconds here):
204
204
  ```html
205
205
  <div class="box" style="width:60px;height:60px;background:#4a9eff"></div>
206
206
 
207
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.100.0/cdn/tinyfly.iife.js"></script>
207
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly.iife.js"></script>
208
208
  <script>
209
209
  tinyfly.to('.box', { x: 200, duration: 1 })
210
210
  </script>
@@ -412,7 +412,7 @@ Without a build step, the all-in-one bundle exposes the same functions on a
412
412
  global — `tinyfly.to()`, `tinyfly.timeline()` and so on:
413
413
 
414
414
  ```html
415
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.100.0/cdn/tinyfly.iife.js"></script>
415
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly.iife.js"></script>
416
416
  <script>
417
417
  tinyfly.to('.box', { x: 200, duration: 1 })
418
418
  </script>
@@ -2278,7 +2278,7 @@ For simple website embedding without a build system.
2278
2278
  </html>
2279
2279
  ```
2280
2280
 
2281
- Build the player with `npm run build:player` to generate `lib/player/tinyfly-player.iife.js`, or load it from the CDN: `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.100.0/cdn/tinyfly-player.iife.js`.
2281
+ Build the player with `npm run build:player` to generate `lib/player/tinyfly-player.iife.js`, or load it from the CDN: `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-player.iife.js`.
2282
2282
 
2283
2283
  ---
2284
2284
 
@@ -6536,7 +6536,7 @@ The dialog shows the generated HTML/JavaScript code with a **Copy Code** button.
6536
6536
  **Steps to embed:**
6537
6537
  1. Build the player: `npm run build:player`
6538
6538
  2. Copy `lib/player/tinyfly-player.iife.js` to your project (or load
6539
- `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.100.0/cdn/tinyfly-player.iife.js`
6539
+ `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-player.iife.js`
6540
6540
  instead; see [Deployment](DEPLOYMENT.md))
6541
6541
  3. Copy the generated code into your HTML
6542
6542
  4. Adjust the script `src` path if needed
@@ -7737,8 +7737,14 @@ loaded with `kinds: [characterObjects, propObjects]`; its controls are tracks
7737
7737
  on the object. Script it in world metres with `propScript3D` (`to: [x, z]`,
7738
7738
  `through: [[x, z], …]`, `face`), not with `propScript`, whose `to` is screen px.
7739
7739
  Characters in a 3D scene walk the same way with `characterScript3D`
7740
- (`{ do: 'walk', to: [x, z] }`, `pose`, `gag`, `face`, `place`); a rider is
7741
- seated with `propRide3D` and spliced into its script with `spliceTracks`. See `docs/props.md`.
7740
+ (`{ do: 'walk', to: [x, z] }`, `pose`, `gag`, `face`, `place`, `say` with a
7741
+ line, `look` at a point or `'camera'`); a rider is seated with `propRide3D`
7742
+ and spliced into its script with `spliceTracks`. A film from a 3D scene is a
7743
+ shot list (`shotTracks`, `transitionAt` + `drawTransition`), camera moves as
7744
+ tracks (`cameraMoveTracks`, `cameraHandheldTracks`), a mood from
7745
+ `lightingPreset('dusk')` with `ground()` and `shadow: true` on meshes, and
7746
+ sound from `renderMix`; draw it with `depthBuffer: true` when shapes cross.
7747
+ See `docs/props.md` and `docs/scene-3d.md`.
7742
7748
 
7743
7749
  ## Characters with a look
7744
7750
 
@@ -7752,8 +7758,11 @@ code: `build` (`child`, `tall`, `short`…), `hair` (a style name, or
7752
7758
  from. Age is hair, glasses and clothes, never a stoop; a `cane` in a hand or
7753
7759
  a `wheelchair()` to ride (`RIDING_POSES.wheeling`) is an accessory any
7754
7760
  character can have. Expressions come from `HUMAN_EXPRESSIONS`
7755
- and are pose fields, as are the face marks `blush`, `tears` and `sweat` (0–1),
7756
- so any face goes with any action or view. Hair and hats turn with the head:
7761
+ and are pose fields, as are the face marks `blush`, `tears` and `sweat` (0–1)
7762
+ and the close-up fields `pupil`, `lid` and `bulge`, so any face goes with any
7763
+ action or view; `drawCharacterHead(ctx, who, pose, { x, y, radius })` draws
7764
+ just the head big, and `face: { nose, inPupil }` adds a nose and a drawing in
7765
+ the pupils. Hair and hats turn with the head:
7757
7766
  don't draw a different hairstyle per view. Hanging hair swings on its own:
7758
7767
  after the character's tracks add `hairFollowTracks(target, tracks, who)` (or,
7759
7768
  posing per frame, `hairFollow` once and `hairMotionAt(keys, t)` each frame)
@@ -7834,12 +7843,21 @@ them before calling it done:
7834
7843
 
7835
7844
  ```bash
7836
7845
  npx @algorisys/tinyfly video scene.mjs --stills frames --times 0,800,1600,2400
7846
+ npx @algorisys/tinyfly video scene.mjs --loop-check # a looping video: does the frame at the duration match the first?
7837
7847
  ```
7838
7848
 
7839
7849
  A model that can read images should look at the PNGs: is the hand on the
7840
7850
  word, does the figure stand on the line, does the text land where it should?
7841
7851
  Fix, render again.
7842
7852
 
7853
+ **A video that loops** (Shorts, Reels): say `loop: true` on the scene and
7854
+ make every motion a function of `frame.time / frame.period` that repeats
7855
+ exactly: `wobble`, `loopEase`, `loopNoise` for motion, `nestedZoom` for a
7856
+ zoom that steps one level per loop, `bubblePath` with `period`, `beatPulse`
7857
+ on a tempo from `loopBeats`, and `cutAudioToLoop` for the sound. Whole
7858
+ numbers of turns and cycles only; `--loop-check` must say "closes". See the
7859
+ Loops chapter of `docs/video-rendering.md`.
7860
+
7843
7861
  ## The rules that trip models up
7844
7862
 
7845
7863
  - **Milliseconds in JSON, seconds in the GSAP-style API.** Timeline keyframes
@@ -7929,7 +7947,7 @@ path for all of that:
7929
7947
  </figure>
7930
7948
 
7931
7949
  <!-- once, anywhere on the page (a site-wide footer is fine) -->
7932
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.100.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
7950
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
7933
7951
  ```
7934
7952
 
7935
7953
  Every `[data-tinyfly-embed]` mounts when the page is ready, with no per-post
@@ -8271,6 +8289,7 @@ npx tinyfly video scene.mjs --stills stills/ # one PNG per caption line (els
8271
8289
  npx tinyfly video scene.mjs --stills stills/ --frames 0,79,88 # stills at chosen frames (or --times 0,2640 in ms)
8272
8290
  npx tinyfly video scene.mjs --loop-check # does it loop? (exit 1 when not)
8273
8291
  npx tinyfly video scene.mjs --scale 0.5 --fps 12 # quick preview
8292
+ npx tinyfly video scene.mjs --codec prores # a ProRes 422 HQ .mov for editing elsewhere
8274
8293
  ```
8275
8294
 
8276
8295
  Runnable scenes are in [`examples/headless-video/`](../examples/headless-video/):
@@ -8399,6 +8418,38 @@ Scene modules may use top-level `await`, or default-export an async function.
8399
8418
  `assembleNarration(plan, clips, sampleRate)` and `encodeWav(samples, sampleRate)`
8400
8419
  are the pure steps underneath, for audio you generate yourself.
8401
8420
 
8421
+ ### A sound mix
8422
+
8423
+ A film's sound is layers: a music bed, the narration, effects at the moments
8424
+ things happen, with the music ducked under the voice. `renderMix` decodes
8425
+ every file with ffmpeg, mixes them and writes one WAV for the scene's
8426
+ `audio`:
8427
+
8428
+ ```js
8429
+ import { renderMix } from '@algorisys/tinyfly/headless'
8430
+
8431
+ const audio = await renderMix(
8432
+ [
8433
+ { id: 'bed', file: 'music/bed.mp3', loop: true, gain: 0.6, fadeOut: 1500, duck: { under: 'voice', amount: 0.7 } },
8434
+ { id: 'voice', file: 'build/narration.wav' },
8435
+ { file: 'sfx/tap.wav', at: [1200, 2650, 4100], gain: 0.8 }, // a sound effect at three moments
8436
+ { file: 'sfx/thud.wav', at: landings.map((t) => t + 40) }, // or at every landing a script reports
8437
+ ],
8438
+ { output: 'build/mix.wav', duration: END, baseDir: here }
8439
+ )
8440
+ export default { /* … */ audio }
8441
+ ```
8442
+
8443
+ Each layer has `start` (ms) or `at` (times for a sound effect), `gain`,
8444
+ `fadeIn` and `fadeOut`, `loop` for a bed shorter than the film, and `duck:
8445
+ { under, amount, attack, release }` to make way for another layer while it
8446
+ sounds. The whole mix is soft-limited so peaks never clip. `mixAudio(layers,
8447
+ { sampleRate, duration, master })` is the pure step on samples. For cuts and
8448
+ dances on the music's beat, `detectTempo(samples, sampleRate)` finds the
8449
+ grid; `snapShotsToBeats(shots, grid)` moves each cut to the nearest beat,
8450
+ and `danceTracks(target, { bpm: grid.bpm, start: nextBeat(grid, t) })`
8451
+ dances to it.
8452
+
8402
8453
  ## Characters
8403
8454
 
8404
8455
  `@algorisys/tinyfly/characters` has a poseable stick figure. A pose is a set of
@@ -8814,6 +8865,141 @@ The numbers are PSNR (higher is more alike; fast or trembling motion makes
8814
8865
  every step lower). From code: `checkLoop(scene)` returns the same report, and
8815
8866
  `psnr(a, b)` / `loopReport(frames)` work on any RGBA frames.
8816
8867
 
8868
+ ### A scene that loops
8869
+
8870
+ Say so with `loop: true`: the duration is the period. `tinyfly video` then
8871
+ runs the loop check before it encodes anything and stops (exit 1) if the loop
8872
+ does not close; every frame carries `period`, which the periodic helpers and
8873
+ 3D trails without a `period` of their own use.
8874
+
8875
+ ```js
8876
+ import { wobble, loopNoise, loopEase } from '@algorisys/tinyfly'
8877
+
8878
+ export default {
8879
+ width: 1280, height: 720, duration: 4000, loop: true,
8880
+ draw(ctx, frame) {
8881
+ const sway = wobble(frame.time, { period: frame.period, cycles: 2, amplitude: 12 }) // a sine, two whole cycles
8882
+ const drift = loopNoise(frame.time, { period: frame.period, seed: 'tree' }) * 30 // smooth noise round a circle
8883
+ const breathe = loopEase(frame.time, { period: frame.period, easing: 'ease-in-out' }) // 0 → 1 → 0, eased
8884
+ },
8885
+ }
8886
+ ```
8887
+
8888
+ | Helper | Repeats exactly every `period` |
8889
+ |---|---|
8890
+ | `wobble(t, { period, cycles, amplitude, phase, shape })` | A sine (or `triangle`, `square`) with a whole number of cycles |
8891
+ | `loopEase(t, { period, cycles, easing, phase })` | 0 → 1 → 0, the easing on the way up and mirrored down |
8892
+ | `loopNoise(t, { period, seed, cycles, octaves, phase })` | Seeded value noise read round a circle, about −1..1: the end meets the start |
8893
+ | `torusNoise(t, along, { period, periodAlong, seed, … })` | Noise periodic in time and along a length (ripples, grass, a flag) |
8894
+ | `phaseOf(t, period, cycles)`, `pingPong(u)` | The building blocks: where in the cycle, and there-and-back |
8895
+
8896
+ Each is a pure function of time, so frames render in any order and the loop
8897
+ check reports "closes", not "seamless".
8898
+
8899
+ ### Sound for a loop
8900
+
8901
+ A loop's sound must come round with its picture. `cutAudioToLoop(file, {
8902
+ output, period, crossfade, fadeIn, fadeOut })` (Node) decodes a drone, a
8903
+ riser or a beat, trims it to the period with its end blended into its start
8904
+ (tiling it first if it is shorter) and writes the WAV to pass as the scene's
8905
+ `audio`; `loopSamples` is the pure step on samples. For motion on the beat,
8906
+ `loopBeats(period, grid)` cuts a tempo to the loop (the nearest whole number
8907
+ of beats, the bpm nudged to fit exactly), `beatPulse(time, grid, { attack,
8908
+ decay, barAccent })` spikes to 1 on every beat and decays, and
8909
+ `beatPeriod(grid, beats)` is the length of so many beats. For motion that
8910
+ follows the sound itself, `audioEnvelope(samples, sampleRate, { fps,
8911
+ smoothing })` gives a level per frame (rising at once, letting go slowly,
8912
+ loudest 1) and `envelopeAt(levels, time, fps, period)` reads it at any time,
8913
+ wrapped for the loop:
8914
+
8915
+ ```js
8916
+ import { decodeAudio, cutAudioToLoop } from '@algorisys/tinyfly/headless'
8917
+ import { audioEnvelope, envelopeAt, loopBeats, beatPulse, detectTempo } from '@algorisys/tinyfly'
8918
+
8919
+ const PERIOD = 4000
8920
+ const audio = await cutAudioToLoop('drone.wav', { output: 'build/drone-loop.wav', period: PERIOD, baseDir: here })
8921
+ const samples = await decodeAudio(audio, { sampleRate: 48000 })
8922
+ const levels = audioEnvelope(samples, 48000, { fps: 30 })
8923
+ const { grid } = loopBeats(PERIOD, detectTempo(samples, 48000))
8924
+ export default {
8925
+ width: 1280, height: 720, duration: PERIOD, loop: true, audio,
8926
+ draw(ctx, frame) {
8927
+ const level = envelopeAt(levels, frame.time, 30, frame.period) // 0..1 with the sound
8928
+ const pulse = beatPulse(frame.time, grid) // 1 on each beat, decaying
8929
+ },
8930
+ }
8931
+ ```
8932
+
8933
+ ### Nested zooms (Droste)
8934
+
8935
+ A picture inside itself, the camera diving in: after one step every level is
8936
+ where the next one was, so a video one step long loops. `similarityAbout(
8937
+ scale, turn, centre)` is the step (a scale, a turn and a move as one value;
8938
+ `powSimilarity(step, k)` is a fraction of it, `composeSimilarity` chains
8939
+ them, `similarityFixedPoint` is the centre everything converges on), and
8940
+ `nestedZoom` draws the levels:
8941
+
8942
+ ```js
8943
+ import { similarityAbout } from '@algorisys/tinyfly'
8944
+ import { nestedZoom } from '@algorisys/tinyfly/adapters'
8945
+
8946
+ const step = similarityAbout(0.5, 12, { x: 640, y: 360 })
8947
+ export default {
8948
+ width: 1280, height: 720, duration: 3000, loop: true, background: '#05030c',
8949
+ draw(ctx, frame) {
8950
+ nestedZoom(ctx, {
8951
+ step,
8952
+ phase: frame.time / frame.period, // 0..1: how far into one step
8953
+ extent: 1600, // how far a level's drawing reaches at level 0, px
8954
+ coversAbove: 1.1, // a level this big fills the frame: nothing behind it is drawn
8955
+ draw(ctx, level, scale) { drawFrame(ctx, level) }, // in level-0 coordinates
8956
+ })
8957
+ },
8958
+ }
8959
+ ```
8960
+
8961
+ Levels smaller than `minSize` px (default 1) are skipped, and so is
8962
+ everything behind a level at or above `coversAbove`, so a zoom of twenty
8963
+ levels draws the five or six that show. `draw` gets the level number (0 is
8964
+ the one at natural size at phase 0, 1 the one inside it) and its screen
8965
+ scale, to keep line widths readable; colour or detail that should travel with
8966
+ the zoom is a function of `level - phase`. `examples/headless-video/nested-zoom.mjs`
8967
+ is a looping neon zoom built this way; `nestedZoomTransform(step, level,
8968
+ phase)` gives a level's similarity for drawing it some other way.
8969
+
8970
+ A Droste *face*: `drawCharacterHead` draws a character's head big, and its
8971
+ `face.inPupil` hook draws inside each pupil, clipped to it, so the head can
8972
+ hold itself (see [Close-ups](character-appearance.md#close-ups)). Anything
8973
+ that should change with a level's size on screen rather than with time (the
8974
+ eyes opening as a head grows, a colour cooling with depth) is a `curve`:
8975
+ `curve([{ at: 20, value: 0 }, { at: 300, value: 1, easing: 'ease-out' }])(radius)`
8976
+ reads keyframes and easings at any input, holding beyond its ends.
8977
+
8978
+ ### Dives and impossible objects
8979
+
8980
+ Two post-effects for a dive, both deterministic. `applyZoomBlur(ctx, { centre,
8981
+ strength, samples, blend })` streaks the finished frame out from a point (a
8982
+ fixed set of scaled copies, averaged, or added with `blend: 'add'` for neon);
8983
+ `drawDiveLines(ctx, { centre, count, inner, outer, length, phase, seed, color,
8984
+ blend })` streams seeded lines past the camera, and `phase: phaseOf(time,
8985
+ period)` moves them one line along per loop so they repeat exactly.
8986
+
8987
+ The impossible objects are built the way the sculptures are: real boxes that
8988
+ line up from one viewpoint. `penroseTriangle({ size, thickness, centre, scale })`
8989
+ and `penroseStairs({ steps, tread, rise, width, base, centre, scale })` give
8990
+ boxes and their visible faces in drawing order for the isometric view (along
8991
+ the (1, 1, 1) diagonal, z up); `drawIsometricFaces(ctx, faces, { top, left,
8992
+ right, fill, outline })` fills them. The triangle's third beam ends one
8993
+ diagonal from where the first began, so on screen the loop closes (the first
8994
+ beam is drawn again over the third's end); the stairs climb all the way round
8995
+ and the last step meets the first. `projectIsometric`, `isometricBoxFaces`
8996
+ and `isometricFaces` are the building blocks for your own. In a 3D scene,
8997
+ `penroseTriangle3D({ length, thickness, material })` returns the three beams
8998
+ and an orthographic camera down the diagonal: from it the loop closes, from
8999
+ anywhere else it is three beams (its third corner shows the beams' ends,
9000
+ as a real sculpture's does; a `rotateY` track on a group round it breaks and
9001
+ remakes the illusion).
9002
+
8817
9003
  ## Bloom
8818
9004
 
8819
9005
  `bloom: true` (or options) adds a glow around everything bright, after each
@@ -8890,6 +9076,25 @@ beads where segments overlap and no seams between them. `ribbon(points)` and
8890
9076
  `line` and `trail` objects, sorted by depth among the meshes (see
8891
9077
  [3D Scenes](scene-3d.md#lines-and-trails)).
8892
9078
 
9079
+ ## Satisfying matter
9080
+
9081
+ Goo as geometry, every shape a pure function of its inputs:
9082
+
9083
+ | Helper | Gives |
9084
+ |---|---|
9085
+ | `metaballContours(balls, { threshold, cell, smooth })` | The outlines of balls (`{ x, y, r }`) that merge through necks as they near and split as they part, as closed polygons; `metaballField` is the field itself |
9086
+ | `dripPath({ x, y, length, width, progress })` | A drip under a surface: a neck thinning to a thread and a head swelling as `progress` runs 0 → 1 |
9087
+ | `bubblePath({ x, y, r, grow, time, period, wobble })` | A bubble growing from nothing (with a little swell on the way) whose surface quivers with the time; with `period` the quiver repeats exactly |
9088
+ | `bubblePop({ x, y, r, progress, pieces })` | The pop: arcs of the rim flying out and shrinking, gone at 1 |
9089
+ | `squashStretch(amount, { keep })`, `scalePoints(points, scale, about)` | Stretch taller (or squash, negative) with the width giving way so the area (or the `volume`) stays; apply it about the point a blob lands on |
9090
+
9091
+ ```js
9092
+ draw(ctx, frame) {
9093
+ const balls = [{ x: 400, y: 300, r: 60 }, { x: 400 + wobble(frame.time, { period: frame.period, amplitude: 90 }), y: 300, r: 40 }]
9094
+ for (const loop of metaballContours(balls, { cell: 3 })) fillPolygon(ctx, loop, '#b6ff3b')
9095
+ }
9096
+ ```
9097
+
8893
9098
  ## Camera, overlay and drawing on twos
8894
9099
 
8895
9100
  - `camera: true` sees the scene through the tracks of the `Camera` target:
@@ -8901,6 +9106,12 @@ beads where segments overlap and no seams between them. `ribbon(points)` and
8901
9106
  stay put while the camera moves.
8902
9107
  - `drawingRate: 12` holds the timeline's poses for two frames of 24 fps ("on
8903
9108
  twos"), as hand-drawn animation is timed.
9109
+ - `motionBlur: { samples: 4, shutter: 0.5 }` makes each frame the average of
9110
+ four drawings spread over the shutter's open time (half the frame, a 180°
9111
+ shutter): fast moves streak as a camera's do. Deterministic, `samples`
9112
+ times the work.
9113
+ - `supersample: 2` draws at twice the size and scales down: smoother edges
9114
+ on thin lines and small text (four times the work).
8904
9115
 
8905
9116
  See [acting.md](acting.md) for camera shots, beat scripts and the rest of the
8906
9117
  cartoon acting tools.
@@ -8925,6 +9136,7 @@ await renderVideo(scene, {
8925
9136
  output: 'out.mp4',
8926
9137
  baseDir: '.', // relative audio and font paths resolve against this
8927
9138
  scale: 1, crf: 20, preset: 'medium',
9139
+ codec: 'h264', // or 'prores' for a .mov
8928
9140
  onProgress: (done, total) => {},
8929
9141
  })
8930
9142
  await renderStills(scene, { dir: 'stills' })
@@ -8981,7 +9193,10 @@ room) was ported call for call to Canvas 2D and rendered at 1920×1080, 24 fps,
8981
9193
  rendering) and `ffmpeg`. Rendering defines `globalThis.Path2D` from the canvas
8982
9194
  package when it is missing, because path targets use it.
8983
9195
  - Output is H.264 MP4 (`yuv420p`, odd sizes padded to even), with AAC audio when
8984
- `audio` is set; video stops at the shorter of picture and sound.
9196
+ `audio` is set; video stops at the shorter of picture and sound. `codec:
9197
+ 'prores'` (or `--codec prores`) writes ProRes 422 HQ (10-bit, PCM audio) in
9198
+ a `.mov` for an editor; any size works, 1080p and 4K included; `renderStills`
9199
+ gives a PNG sequence.
8985
9200
  - `image` targets need images loaded with the canvas package's `loadImage`.
8986
9201
 
8987
9202
  ---
@@ -9004,8 +9219,8 @@ On a page with no build step, load the maps add-on after the browser bundle; it
9004
9219
  adds to the same `tinyfly` global:
9005
9220
 
9006
9221
  ```html
9007
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.100.0/cdn/tinyfly.iife.js"></script>
9008
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.100.0/cdn/tinyfly-maps.iife.js"></script>
9222
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly.iife.js"></script>
9223
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-maps.iife.js"></script>
9009
9224
  ```
9010
9225
 
9011
9226
  It is a separate script because the offline world map it carries adds about
@@ -9505,6 +9720,32 @@ tracks animate them): `blush` (rosy cheeks, with hatch lines past 0.5),
9505
9720
  `tears` (a drop under each eye, running down past 0.6) and `sweat` (a bead at
9506
9721
  the temple).
9507
9722
 
9723
+ ## Close-ups
9724
+
9725
+ For a face filling the frame there are three more pose fields and a bigger
9726
+ drawing:
9727
+
9728
+ - `pupil` (1 the usual size): bigger for excitement or a dive into it,
9729
+ smaller for fear. `lid` (0..1) lowers the upper lids over the eye (sleepy,
9730
+ suspicious, bored). `bulge` (0..1) pops the eyes out of the head, whites and
9731
+ all. `scared`, `afraid`, `sleepy`, `suspicious` and `excited` use them.
9732
+ - `face: { nose: true }` adds a small nose; `face: { teeth, tongue }` are
9733
+ above.
9734
+ - `drawCharacterHead(ctx, who, pose, { x, y, radius, time })` draws just the
9735
+ head (hair, hat, glasses, ears, the face), its centre at `x`, `y` and its
9736
+ radius `radius` px, in the character's look with the line weight scaled to
9737
+ the size. The pose turns and nods it and sets the face.
9738
+ - `face: { inPupil(ctx, pupil) }` draws inside each pupil, the context
9739
+ clipped to its circle on screen (`{ x, y, r, side }`): another scene, or the
9740
+ same head again for a Droste face:
9741
+
9742
+ ```js
9743
+ function head(ctx, x, y, r, depth = 0) {
9744
+ const who = character({ hair: 'spiky', face: { nose: true, inPupil: depth < 4 ? (c, p) => head(c, p.x, p.y, p.r, depth + 1) : undefined } })
9745
+ drawCharacterHead(ctx, who, humanPose({ bulge: 0.9, pupil: 1.5 }), { x, y, radius: r })
9746
+ }
9747
+ ```
9748
+
9508
9749
  ## Everyday actions, held items and meeting hands
9509
9750
 
9510
9751
  The motion and everyday-life sheets add poses to `HUMAN_POSES`: `sleep`,
@@ -10732,7 +10973,7 @@ number or three), `parent` (an earlier object it moves with), `visible`, and
10732
10973
  |---|---|
10733
10974
  | `group` | (just a transform: move several objects together, or carry a camera) |
10734
10975
  | `mesh` | `geometry`, `material` (a key of `materials`) |
10735
- | `camera` | `projection: 'perspective'` with `fov` (vertical, degrees), or `'orthographic'` with `height` (metres); `near`, `far`; optional `lookAt: [x, y, z]` |
10976
+ | `camera` | `projection: 'perspective'` with `fov` (vertical, degrees), or `'orthographic'` with `height` (metres); `near`, `far`; optional `lookAt: [x, y, z]`, `up` (which way is up for it, default +y) and `roll` (degrees about the view axis, clockwise on screen) |
10736
10977
  | `light` | `light: 'ambient' \| 'directional' \| 'point' \| 'spot'`, `color`, `intensity` (1 is full light); directional and spot shine from their position toward `target` (default the origin); point and spot fade to nothing at `range`; spot's cone is `angle` (half-angle, default 30°) |
10737
10978
 
10738
10979
  **Geometry**: `box` (`size: [w, h, d]`), `sphere` (`radius`, `segments`),
@@ -10742,7 +10983,11 @@ facing up, `segments` per side), and `extrude`: any SVG `path` made solid,
10742
10983
  `depth` metres thick and scaled to `width` metres wide (default 1), with
10743
10984
  `curveSegments` points per curve (default 12). Subpaths inside others are
10744
10985
  holes (an "o", a ring); outlines inside holes are solid again. The path's y
10745
- (down) is flipped to 3D's y (up). All centred on the origin.
10986
+ (down) is flipped to 3D's y (up). All centred on the origin. A raw `mesh`
10987
+ takes `positions` (flat x, y, z runs), `indices` (triples, counter-clockwise
10988
+ from outside), optional `normals` per vertex (flat ones are computed) and
10989
+ `colors`, one per face or one per vertex (blended per face), over the
10990
+ material's colour: warped beams, terrain, anything exported from a tool.
10746
10991
 
10747
10992
  ```js
10748
10993
  { id: 'star', kind: 'mesh', material: 'gold',
@@ -10766,9 +11011,14 @@ for a neon glow: `{ color: '#000000', emissive: '#ff2bd6', shading: 'unlit' }`.
10766
11011
  `roughness` and `metalness` are for the realistic look (three.js, a later
10767
11012
  milestone); the stylized renderers ignore them, so one material serves both.
10768
11013
 
10769
- The scene can have `background` and `fog: { color, near, far }` (metres from
10770
- the camera). A scene with no lights gets a soft default (ambient plus a key
10771
- light from upper right).
11014
+ The scene can have `background` (a colour, or a sky as a vertical gradient
11015
+ `{ top, bottom }`), `fog: { color, near, far }` (metres from the camera) and
11016
+ `ground` (the height blob shadows lie at, default 0). A mesh with `shadow:
11017
+ true` (or `{ opacity, ground }`) gets a soft blob shadow on the ground under
11018
+ it, which spreads and fades as the mesh lifts off. A scene with no lights gets a soft default (ambient plus a key
11019
+ light from upper right). Outlines fade into the fog too. `nearFade: { from, to }` fades geometry
11020
+ nearer the camera than `to` metres, gone at `from`, so a dive passes through
11021
+ things as if they were glass (also an option of `resolveScene3D`).
10772
11022
 
10773
11023
  ## Animating it
10774
11024
 
@@ -10783,8 +11033,9 @@ live in the same timeline as everything else.
10783
11033
  | `visible` | any object | 0 or 1 (children hide with their parent) |
10784
11034
  | `opacity` | meshes | 0..1, times the material's |
10785
11035
  | `color` | meshes, lights | a colour, over the material's or light's |
11036
+ | `outlineWidth`, `outlineColor` | meshes | px and a colour, over the material's outline (0 switches it off) |
10786
11037
  | `intensity`, `target` | lights | |
10787
- | `fov` / `height`, `lookAt` | cameras | |
11038
+ | `fov` / `height`, `lookAt`, `roll` | cameras | |
10788
11039
  | `color`, `width`, `opacity` | lines, trails | |
10789
11040
  | `length` | trails | ms |
10790
11041
  | `activeCamera` | the scene, target `<sceneId>` | a camera's id: **a cut is one keyframe** |
@@ -10797,6 +11048,85 @@ so instead of picking a winner.
10797
11048
  the group. `orbitPosition(target, yaw, pitch, distance)` and
10798
11049
  `dollyPosition(eye, target, amount)` place cameras for keyframes.
10799
11050
 
11051
+ ## Shots and cameras
11052
+
11053
+ A film is a shot list, as data, over the same scene and timeline:
11054
+
11055
+ ```js
11056
+ import { shotTracks, shotMarkers, transitionAt, withActiveCamera, cameraMoveTracks, cameraHandheldTracks } from '@algorisys/tinyfly/scene-3d'
11057
+ import { drawTransition, drawLetterbox } from '@algorisys/tinyfly/adapters'
11058
+
11059
+ const shots = [
11060
+ { id: 'establish', start: 0, end: 4000, camera: 'wide', label: 'Dolly in' },
11061
+ { id: 'orbit', start: 4000, end: 7500, camera: 'orbiter', transition: { kind: 'crossfade', duration: 700 } },
11062
+ { id: 'close', start: 7500, end: 10000, camera: 'close', transition: { kind: 'dipToBlack', duration: 600 } },
11063
+ ]
11064
+ const tracks = [
11065
+ ...shotTracks(shots, 'set'), // the activeCamera track: a cut is one keyframe
11066
+ ...cameraMoveTracks({ scene: 'set', camera: 'wide', start: 0, end: 4000,
11067
+ from: { target: [0, 0.8, 0], yaw: 20, pitch: 18, distance: 11 }, to: { distance: 7 } }), // a dolly
11068
+ ...cameraHandheldTracks([], { scene: 'set', camera: 'close', start: 7500, end: 10000,
11069
+ base: { position: [1.2, 1.4, 3.6], lookAt: [0, 0.75, 1.3] }, seed: 'close' }),
11070
+ ]
11071
+ ```
11072
+
11073
+ - **Shots** are `{ id, start, end, camera, label?, transition? }`;
11074
+ `checkShots` names overlaps, bad ends and a transition on the first shot;
11075
+ `shotAt(shots, time)` is the shot playing; `shotMarkers` gives the
11076
+ timeline's markers (stills and captions step through them).
11077
+ - **Transitions** (`cut`, `crossfade`, `dipToBlack`, `wipe` with a
11078
+ `direction`) start at the shot's start and last `duration` ms. Any frame can
11079
+ ask `transitionAt(shots, time)` which two shots to draw and how far along
11080
+ (0..1); `drawTransition(ctx, transition, { width, height, draw(ctx,
11081
+ cameraId) })` draws both and blends them (a crossfade mixes, a dip covers
11082
+ the cut, a wipe sweeps the new shot in), with `withActiveCamera(values,
11083
+ sceneId, cameraId)` to draw the shot going out. Pure and frame-addressable:
11084
+ the film renders the same in any order.
11085
+ - **Camera moves** are presets that write `position`, `lookAt` (and `fov`)
11086
+ tracks on the camera: `cameraMoveTracks({ from, to, easing, every })` with
11087
+ poses as an orbit round a target (`yaw`, `pitch`, `distance`), or a fixed
11088
+ `position` with a moving `lookAt`, or a `fov`: change `yaw` for an orbit,
11089
+ `distance` for a dolly, `pitch` and `distance` for a crane, `lookAt` for a
11090
+ pan or tilt, `fov` for a zoom, or any mix. `cameraFollowTracks({ subjectAt,
11091
+ offset, lag })` keeps a camera on a moving subject. `cameraHandheldTracks(
11092
+ tracks, { amount, aim, rate, seed })` adds a deterministic handheld shake
11093
+ onto a move's tracks or a still camera's `base`.
11094
+ - **Aspect and safe areas**: `drawLetterbox(ctx, canvas, '2.39:1')` paints
11095
+ the bars (in a video's `overlay`), `frameRect`, `frameSize` and `safeAreas`
11096
+ are the geometry, `drawSafeAreas` draws the action and title guides for
11097
+ stills. `FRAME_ASPECTS` has 16:9, 2.39:1, 4:3, 1:1, 9:16 and 4:5.
11098
+
11099
+ `examples/headless-video/film-shots.mjs` is a three-shot film with a dolly, a
11100
+ crossfade into an orbit, a dip to black into a handheld close-up, letterboxed.
11101
+
11102
+ ## Sets and light for mood
11103
+
11104
+ A set is objects like any other; what sets the mood is its light, its sky and
11105
+ its fog, and those come as presets:
11106
+
11107
+ ```js
11108
+ import { lightingPreset, lightingTracks, ground } from '@algorisys/tinyfly/scene-3d'
11109
+
11110
+ const light = lightingPreset('dusk') // or 'day', 'night', 'stage'
11111
+ const floor = ground({ size: 20 })
11112
+ const scene = {
11113
+ id: 'set', camera: 'cam', background: light.background, fog: light.fog,
11114
+ materials: { ...floor.materials, red: { color: '#ef4444', shading: 'toon' } },
11115
+ objects: [camera, ...light.objects, ...floor.objects, { id: 'box', kind: 'mesh', geometry: { type: 'box', size: [1, 1, 1] }, material: 'red', position: [0, 0.5, 0], shadow: true }],
11116
+ }
11117
+ // Day turning to night over four seconds: tracks on the same lights.
11118
+ const tracks = lightingTracks('day', 'night', { scene: 'set', start: 0, end: 4000 })
11119
+ ```
11120
+
11121
+ Every preset uses the same light ids (`key`, `fill`, `sky`, and `spot` on
11122
+ the stage), so `lightingTracks(from, to, { scene, start, end })` keys each
11123
+ light's `color`, `intensity`, `position` and `target` from one mood to the
11124
+ other (a spot only one mood has fades in or out); the sky and fog are the
11125
+ scene's to set per shot. `ground({ size, color, segments, y })` is a floor
11126
+ on layer −1 with its material; props from the catalog (trees, houses,
11127
+ furniture) are the set pieces, placed by preset name (see Props). Blob
11128
+ shadows under meshes are `shadow: true`; projected shadows are planned.
11129
+
10800
11130
  ## Lines and trails
10801
11131
 
10802
11132
  Two more kinds of object draw a band that faces the camera, as wide as
@@ -10842,7 +11172,7 @@ front of the meshes. For trails on a plain 2D canvas, see `drawTrail` in
10842
11172
  loadScene3D(json): LoadedScene3D // validates and builds meshes once (throws with every problem)
10843
11173
  validateScene3D(json, tracks?): string[] // problems as sentences, empty when fine
10844
11174
  resolveScene3D(loaded, values, { width, height, time?, valuesAt? }): ResolvedScene3D // pure: matrices, camera, lights, sorted triangles
10845
- drawScene3D(ctx, loaded, values, { width, height, time?, valuesAt? | stateAt? }) // resolve and draw, in one call
11175
+ drawScene3D(ctx, loaded, values, { width, height, time?, valuesAt? | stateAt?, depthBuffer? }) // resolve and draw, in one call
10846
11176
  new Scene3DAdapter(new Canvas2DRenderer(ctx), { width, height, valuesAt? }) // registerScene, applyState(state), render()
10847
11177
  ```
10848
11178
 
@@ -10940,6 +11270,21 @@ phase) with the distance, one stride per cycle, so the feet stay planted, plus
10940
11270
  the stepping pose as it draws, on the pose it holds: a wave carries on while it
10941
11271
  walks. Objects take `gait` and `walking` as fields too.
10942
11272
 
11273
+ **Speaking and looking.** `{ do: 'say', say: 'A pot of water!' }` lip-syncs
11274
+ the line on the character's mouth (the same `lipSyncOver` the 2D scripts use)
11275
+ with a talking head, and lasts as long as the line (`speechLength(text)`, or
11276
+ `for`). `{ do: 'look', look: [x, z] }` turns the head and eyes toward a point
11277
+ at eye height (`[x, y, z]` for any height, `'camera'` for the viewer with
11278
+ `options.camera`); `lookFields(from, at)` is the maths. To keep looking at
11279
+ something that moves, `characterLookAtTracks(tracks, { scene, character,
11280
+ at: { object: 'didi' } | { camera: 'cam' } | [x, y, z] | (time) => [x, y, z],
11281
+ start, end, objects })` keys `head.turn`, `head.nod`, `lookX` and `lookY`
11282
+ from where both are at every moment; `objectPositionAt(tracks, target,
11283
+ base)` is the sampler it uses. For several figures, `stageSpots({ count,
11284
+ shape: 'line' | 'arc' | 'circle' | 'cluster', spacing, centre })` gives
11285
+ positions and headings that do not overlap: a line across, an arc facing its
11286
+ middle, a circle facing in, or a seeded loose group.
11287
+
10943
11288
  **Riding.** `propRide3D({ prop, propId, propTracks, scene, placement, anchor, riderId, pose, start, end, mount?, dismount? })`
10944
11289
  keeps a rider's hips on a prop's seat anchor (a horse's `saddle`, a bike's or
10945
11290
  a cart's `seat`) as the prop moves, turns, bobs with its stride and pitches,
@@ -11069,6 +11414,18 @@ objects, prepares them once, and each frame returns meshes (shaded and sorted
11069
11414
  with the scene's) and drawables (drawn whole at their depth). Pass it in
11070
11415
  `loadScene3D(scene, { kinds })`.
11071
11416
 
11417
+ ## Impossible objects
11418
+
11419
+ `penroseTriangle3D({ length, thickness, material, id, position, distance })`
11420
+ returns three box objects (beams along x, up y and along z, each starting
11421
+ where the last ends) and an orthographic camera on the (1, 1, 1) diagonal
11422
+ from which the third beam's end meets the first's start on screen. Add the
11423
+ objects with a material of that name and the camera, or place your own camera
11424
+ along the diagonal; from anywhere else the loop is open. The third corner
11425
+ shows the beams' ends as a real sculpture's does. For a clean drawing see the
11426
+ 2D `penroseTriangle` and `penroseStairs` in
11427
+ [Video from code](video-rendering.md#dives-and-impossible-objects).
11428
+
11072
11429
  ## The WebGL2 renderer
11073
11430
 
11074
11431
  `@algorisys/tinyfly/scene-3d/webgl` (`tinyfly-scene-3d-webgl.iife.js` for
@@ -11096,8 +11453,9 @@ renderer.render(resolveScene3D(scene, values, { width: canvas.width, height: can
11096
11453
  trails, go on `overlay`, a 2D canvas laid over the GL one (in front of the meshes);
11097
11454
  solid characters are meshes and sort properly.
11098
11455
 
11099
- It runs on a page or in a Worker (OffscreenCanvas). Node has no WebGL2, so
11100
- headless video uses the Canvas 2D renderer. The cross-browser checks
11456
+ It runs on a page or in a Worker (OffscreenCanvas). Node has no WebGL2;
11457
+ headless video uses the Canvas 2D renderer, or its software depth buffer
11458
+ (below) when shapes cut through each other. The cross-browser checks
11101
11459
  (`npm run e2e -- --check scene-3d-webgl`) compile it in Chromium, Firefox and
11102
11460
  WebKit, compare its silhouettes with the Canvas 2D renderer's and check the
11103
11461
  depth buffer.
@@ -11113,6 +11471,20 @@ modest, or use a layer. Each triangle has one colour, so smooth shading is
11113
11471
  smoothed per triangle, not per pixel; more segments look rounder. The WebGL2
11114
11472
  renderer (above) has a depth buffer and per-pixel light.
11115
11473
 
11474
+ **A software depth buffer** draws right where the painter's order cannot:
11475
+ `drawScene3D(ctx, scene, values, { …, depthBuffer: true })`, or
11476
+ `new Scene3DAdapter(new SoftwareRenderer(ctx), …)`. Every triangle is
11477
+ rasterised into a pixel buffer with a depth per pixel (`rasterizeResolvedScene`
11478
+ gives the bytes and depths without a canvas), so crossing beams, huge floors
11479
+ and long meshes need no `layer` or segments; see-through meshes blend over
11480
+ what is behind them, and ink is depth-tested so an outline never shows
11481
+ through what is in front. Each triangle keeps its one shaded colour and its
11482
+ fog, edges are hard (no anti-aliasing), and objects drawn whole (characters
11483
+ in their pen looks, lines, trails) go on top of the meshes, as on the WebGL2
11484
+ overlay. It costs about three times the painter's time and works anywhere
11485
+ the Canvas 2D renderer does. Layers keep their meaning: a lower layer is
11486
+ drawn first and a higher one paints over it whatever the depths.
11487
+
11116
11488
  Rendering speed in Node: a 1280×720 scene of a few thousand triangles renders
11117
11489
  at a few frames a second; parallel rendering for long films is planned.
11118
11490
 
@@ -13554,7 +13926,7 @@ magnet.addEventListener('pointerleave', () => {
13554
13926
 
13555
13927
  <!-- capabilities: generated from the library -->
13556
13928
 
13557
- # tinyfly capabilities (v0.100.0)
13929
+ # tinyfly capabilities (v0.102.0)
13558
13930
 
13559
13931
  Generated from the library itself: every name below is accepted, and names not listed are rejected (beat scripts, code panels and `checkTracks` say which name was probably meant).
13560
13932
 
@@ -13840,7 +14212,7 @@ Appearance options of `character({ … })`, all plain data that turns with the h
13840
14212
  - `glasses`: `round`, `square`, `sunglasses`; `hat`: `cap`, `beanie`, `hardHat`, `sunHat`, `bowler`; `ears: true`; `face: { teeth, tongue }` (shown when the mouth opens); `feet`: `round`, `flat`, `pointed`, `big`
13841
14213
  - `outfit`: `{ shirt, trousers, sleeves: short | long | none, bottom: trousers | shorts | skirt, collar, tie: colour, over: apron | labCoat | hoodie | cardigan | overalls | sari, overColor, shoes: boots, shoeColor }`
13842
14214
  - `castMember(name, height)`: `boy`, `girl`, `youngMan`, `youngWoman`, `man`, `woman`, `grandpa`, `grandma`, `doctor`, `cook`, `builder`, `courier`, `teacher`, `farmer`
13843
- - Face marks (pose fields, 0–1): `blush`, `tears`, `sweat`
14215
+ - Face marks (pose fields, 0–1): `blush`, `tears`, `sweat`; close-up fields `pupil` (size, 1 usual), `lid` (upper lids lowered, 0–1), `bulge` (eyes out of the head, 0–1); `face: { nose: true, inPupil(ctx, pupil) }`; `drawCharacterHead(ctx, who, pose, { x, y, radius })` draws just the head big
13844
14216
  - Hair in motion (pose fields): `hair.swing` (degrees round the head, + toward its left), `hair.trail` (head radii back), `hair.lift` (head radii up); key them with `hairFollowTracks(target, tracks, who)` after the character's tracks, or `hairFollow` + `hairMotionAt` when posing per frame
13845
14217
  - `holding`: `mug` (left or right), `phone` (left or right), `book` (one hand or both), `bag` (left or right), `briefcase` (left or right), `umbrella` (left or right), `broom` (left or right), `cane` (left or right), `parcel` (both); pose fields `held.left`, `held.right`, `held.both` (below 0.5 lets go); `handGrip(joints, side)`
13846
14218
  - `meetHands(kind, a, b)` (stand them `meetingSpacing(kind, a, b)` apart): `handshake`, `highFive`, `fistBump`, `handOver`; `embrace(a, b)` (a hug, `embraceSpacing` apart); `helpUp(helper, sitter, progress)` (0 on the floor, hand taken; 1 standing; `helpUpSpacing` apart)