@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.
- package/README.md +6 -6
- package/bin/tinyfly.mjs +16 -6
- package/docs/character-appearance.md +26 -0
- package/docs/editor-guide.md +1 -1
- package/docs/examples.md +1 -1
- package/docs/getting-started.md +1 -1
- package/docs/gsap-compat.md +1 -1
- package/docs/llm-guide.md +22 -4
- package/docs/maps.md +2 -2
- package/docs/scene-3d.md +140 -9
- package/docs/teaching.md +1 -1
- package/docs/video-rendering.md +198 -1
- package/lib/addons/adapters.js +431 -332
- package/lib/addons/characters.js +3889 -3773
- package/lib/addons/load-scene-oWNsYYC1.js +372 -0
- package/lib/addons/scene-3d-webgl.js +31 -31
- package/lib/addons/scene-3d.js +669 -314
- package/lib/addons/shading-0lPgnXmD.js +96 -0
- package/lib/browser/tinyfly-scene-3d-webgl.iife.js +2 -2
- package/lib/browser/tinyfly-scene-3d.iife.js +2 -2
- package/lib/browser/tinyfly.iife.js +15 -15
- package/lib/browser/tinyfly.js +6232 -5723
- package/lib/browser/tinyfly.umd.js +15 -15
- package/lib/engine/tinyfly-engine.js +1563 -1170
- package/lib/engine/tinyfly-engine.umd.cjs +2 -2
- package/lib/headless/headless.js +189 -6
- package/lib/types/adapters/canvas/framing.d.ts +27 -0
- package/lib/types/adapters/canvas/impossible.d.ts +15 -0
- package/lib/types/adapters/canvas/index.d.ts +4 -0
- package/lib/types/adapters/canvas/nested-zoom.d.ts +40 -0
- package/lib/types/adapters/canvas/zoom-blur.d.ts +49 -0
- package/lib/types/characters/character-script-3d.d.ts +21 -1
- package/lib/types/characters/character.d.ts +23 -3
- package/lib/types/characters/head/face.d.ts +19 -2
- package/lib/types/characters/index.d.ts +2 -1
- package/lib/types/characters/staging-3d.d.ts +56 -0
- package/lib/types/engine/authoring/beat-loop.d.ts +46 -0
- package/lib/types/engine/authoring/curve.d.ts +26 -0
- package/lib/types/engine/authoring/framing.d.ts +48 -0
- package/lib/types/engine/authoring/index.d.ts +4 -0
- package/lib/types/engine/authoring/periodic.d.ts +89 -0
- package/lib/types/engine/path/goo.d.ts +103 -0
- package/lib/types/engine/path/impossible.d.ts +92 -0
- package/lib/types/engine/path/index.d.ts +6 -0
- package/lib/types/engine/path/similarity.d.ts +48 -0
- package/lib/types/headless/audio-mix.d.ts +40 -0
- package/lib/types/headless/ffmpeg-args.d.ts +2 -0
- package/lib/types/headless/frame-renderer.d.ts +7 -1
- package/lib/types/headless/index.d.ts +2 -0
- package/lib/types/headless/loop-audio.d.ts +21 -0
- package/lib/types/headless/node-audio.d.ts +39 -0
- package/lib/types/headless/node-video.d.ts +2 -0
- package/lib/types/headless/video-scene.d.ts +21 -0
- package/lib/types/scene-3d/camera.d.ts +11 -2
- package/lib/types/scene-3d/geometry/mesh.d.ts +2 -0
- package/lib/types/scene-3d/geometry/primitives.d.ts +7 -0
- package/lib/types/scene-3d/impossible-3d.d.ts +29 -0
- package/lib/types/scene-3d/index.d.ts +7 -3
- package/lib/types/scene-3d/lighting.d.ts +58 -0
- package/lib/types/scene-3d/resolve-scene.d.ts +18 -2
- package/lib/types/scene-3d/scene-3d-adapter.d.ts +4 -0
- package/lib/types/scene-3d/scene-types.d.ts +43 -6
- package/lib/types/scene-3d/shading.d.ts +2 -0
- package/lib/types/scene-3d/shots.d.ts +162 -0
- package/lib/types/scene-3d/software-renderer.d.ts +40 -0
- package/llms-full.txt +395 -23
- package/llms.txt +29 -29
- package/package.json +1 -1
- package/skills/tinyfly/SKILL.md +11 -1
- package/lib/addons/load-scene-CQvcFWGJ.js +0 -331
- 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.
|
|
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.
|
|
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.
|
|
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.
|
|
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`
|
|
7741
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
9008
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
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`
|
|
10770
|
-
|
|
10771
|
-
|
|
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? })
|
|
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
|
|
11100
|
-
headless video uses the Canvas 2D renderer
|
|
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.
|
|
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)
|