@algorisys/tinyfly 0.101.0 → 0.103.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 +17 -6
- package/bin/tinyfly.mjs +9 -3
- package/docs/DEPLOYMENT.md +2 -0
- package/docs/api-reference.md +61 -0
- package/docs/dance.md +150 -1
- package/docs/editor-guide.md +11 -4
- package/docs/examples.md +22 -1
- package/docs/getting-started.md +1 -1
- package/docs/gsap-compat.md +1 -1
- package/docs/llm-guide.md +38 -3
- package/docs/maps.md +2 -2
- package/docs/scene-3d.md +138 -6
- package/docs/teaching.md +1 -1
- package/docs/video-rendering.md +44 -1
- package/lib/addons/adapters.js +168 -123
- package/lib/addons/characters.js +5802 -5506
- package/lib/addons/scene-3d-webgl.js +30 -30
- package/lib/addons/scene-3d.js +650 -341
- 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 +14 -14
- package/lib/browser/tinyfly.js +5798 -5467
- package/lib/browser/tinyfly.umd.js +14 -14
- package/lib/engine/tinyfly-engine.js +1207 -1172
- package/lib/engine/tinyfly-engine.umd.cjs +2 -2
- package/lib/headless/headless.js +150 -6
- package/lib/types/adapters/canvas/framing.d.ts +27 -0
- package/lib/types/adapters/canvas/index.d.ts +1 -0
- package/lib/types/characters/capabilities.d.ts +1 -0
- package/lib/types/characters/character-script-3d.d.ts +34 -4
- package/lib/types/characters/dance-circle.d.ts +59 -0
- package/lib/types/characters/dance-contact.d.ts +52 -0
- package/lib/types/characters/human-dance.d.ts +86 -0
- package/lib/types/characters/index.d.ts +5 -1
- package/lib/types/characters/rig/reach.d.ts +6 -3
- package/lib/types/characters/staging-3d.d.ts +56 -0
- package/lib/types/engine/authoring/framing.d.ts +48 -0
- package/lib/types/engine/authoring/index.d.ts +1 -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 +1 -0
- package/lib/types/headless/node-audio.d.ts +19 -0
- package/lib/types/headless/node-video.d.ts +2 -0
- package/lib/types/headless/video-scene.d.ts +12 -0
- package/lib/types/scene-3d/index.d.ts +3 -0
- package/lib/types/scene-3d/lighting.d.ts +58 -0
- package/lib/types/scene-3d/resolve-scene.d.ts +5 -1
- package/lib/types/scene-3d/scene-3d-adapter.d.ts +2 -0
- package/lib/types/scene-3d/scene-types.d.ts +14 -2
- 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 +474 -23
- package/llms.txt +29 -29
- package/package.json +1 -1
- package/skills/tinyfly/SKILL.md +32 -1
- package/lib/types/characters/polyline.d.ts +0 -12
- package/lib/types/characters/sketch.d.ts +0 -54
- package/lib/types/compat/gsap/playhead-crossings.d.ts +0 -47
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.103.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.103.0/cdn/tinyfly.iife.js"></script>
|
|
416
416
|
<script>
|
|
417
417
|
tinyfly.to('.box', { x: 200, duration: 1 })
|
|
418
418
|
</script>
|
|
@@ -1586,8 +1586,29 @@ quickPlay({
|
|
|
1586
1586
|
|
|
1587
1587
|
Practical examples for common animation patterns using the tinyfly API.
|
|
1588
1588
|
|
|
1589
|
+
## Festive Garba and Dandiya
|
|
1590
|
+
|
|
1591
|
+
The [Navratri example](https://tinyfly.app/examples/live-festive-dandiya)
|
|
1592
|
+
appears under 3D, Showcase, Video and Algorisys. Six festively dressed dancers
|
|
1593
|
+
circle, strike larger decorated sticks with partners, and alternate half
|
|
1594
|
+
and full spins. Its code uses native character dance, world foot contacts,
|
|
1595
|
+
partner IK and the 3D canvas renderer. It loops every 24 seconds.
|
|
1596
|
+
|
|
1597
|
+
From this repository, build the libraries first with `npm run build:libs`.
|
|
1598
|
+
Video rendering needs `ffmpeg` on PATH and `@napi-rs/canvas`; see
|
|
1599
|
+
[Rendering Video from Code](video-rendering.md).
|
|
1600
|
+
|
|
1601
|
+
```sh
|
|
1602
|
+
tinyfly video examples/headless-video/festive-dandiya.mjs --loop-check
|
|
1603
|
+
tinyfly video examples/headless-video/festive-dandiya.mjs -o festive-dandiya.mp4
|
|
1604
|
+
```
|
|
1605
|
+
|
|
1606
|
+
Add an `audio` path to the headless scene to use your own music. The browser
|
|
1607
|
+
example runs without bundled audio.
|
|
1608
|
+
|
|
1589
1609
|
## Table of Contents
|
|
1590
1610
|
|
|
1611
|
+
- [Festive Garba and Dandiya](#festive-garba-and-dandiya)
|
|
1591
1612
|
- [Basic: Fade In](#basic-fade-in)
|
|
1592
1613
|
- [Multi-Property Animation](#multi-property-animation)
|
|
1593
1614
|
- [Infinite Looping](#infinite-looping)
|
|
@@ -2278,7 +2299,7 @@ For simple website embedding without a build system.
|
|
|
2278
2299
|
</html>
|
|
2279
2300
|
```
|
|
2280
2301
|
|
|
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.
|
|
2302
|
+
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.103.0/cdn/tinyfly-player.iife.js`.
|
|
2282
2303
|
|
|
2283
2304
|
---
|
|
2284
2305
|
|
|
@@ -4006,6 +4027,67 @@ Dance and flips (see [Dance and Flips](dance.md)): the pose fields `leftWrist`/`
|
|
|
4006
4027
|
`DANCE_STYLES`, `DanceStyle`, `DanceMove`, `DanceKey`, `Groove`, `RoutineStep`, `MUDRAS`, `danceFrame()`, `dancePose()`, `danceTaps()`, `danceTravel()`, `danceTravelTrack()`, `stickToHuman()`, `mirrorHumanPose()`, `handProp()`, `DanceTap`, `TapName`, `routineBeats()`, `beatAt()`, `mirrorPose()`, `applyGroove()`, `danceStance()`, `dancer()`, `danceTracks()`, `bakeDanceTracks()`, `stickFigureTarget({ dance })` with the `beat` and `dancing` props, `resolveStickFrame()`;
|
|
4007
4028
|
`FLIPS`, `Flip`, `FlipKey`, `flipPose()`, `flipTravel()`, `flipTracks()`; `POSES.sideSplit` and `POSES.frontSplit`.
|
|
4008
4029
|
|
|
4030
|
+
Native v2 dance APIs (also from `@algorisys/tinyfly/characters`):
|
|
4031
|
+
|
|
4032
|
+
| API | Result / options |
|
|
4033
|
+
|---|---|
|
|
4034
|
+
| `HUMAN_DANCES` | JSON routines: `garba`, `garbaThreeClap`, `dandiya`, each eight beats at 120 BPM |
|
|
4035
|
+
| `humanDanceFrame(style, beat, base?)` | `HumanDanceFrame`: `{ pose, contact: { side, start, weight }, strike }`; `style` is a `HumanDanceName` or custom `HumanDanceStyle`; `base` defaults to `HUMAN_REST` |
|
|
4036
|
+
| `humanDanceTracks(target, options)` | `Track[]`; `HumanDanceTrackOptions`: required `style`, optional `bpm`, `beats`, `start` (ms), `pose`, `samplesPerBeat` (default 16); tempo and length default to the style |
|
|
4037
|
+
| `danceCircleAt(beat, options)` | `DanceCircleMember[]`: `{ character, pose, position, heading, strike, planted }`; absolute beat, world position and heading in degrees |
|
|
4038
|
+
| `danceCircleTracks(targets, options)` | Scene `Track[]` on targets such as `stage/dancer`; requires `beats`, defaults to 120 BPM, `start: 0` ms and 16 samples per beat; an explicit `count` must equal `targets.length` |
|
|
4039
|
+
| `danceJoint(partner, chain, joint)` | World `Vec3` with grounding, yaw, roll and placement; wrist/ankle index 2, toe index 3 |
|
|
4040
|
+
| `plantDanceFoot(partner, side, worldPoint, point = 'toe')` | `DanceFootPlant`: partner with adjusted `pose`, `position` and `reached`; `point` is `toe` or `ankle`; apply both pose and position |
|
|
4041
|
+
| `meetDandiya(a, b, options?)` | `DandiyaMeeting`: `{ a, b, sticks, point, reached }`; `a`/`b` are poses, `sticks` a pair of `DandiyaStick` (`{ grip, tip }`); options `sideA`, `sideB` (default right), `point`, `length` (default 0.22 of the shorter height) |
|
|
4042
|
+
|
|
4043
|
+
`HumanDanceStyle` is `{ label, bpm, beats, keys: [{ beat, pose }], strikes }`.
|
|
4044
|
+
Keys must be nonempty, strictly ordered within `[0, beats)`, with finite pose
|
|
4045
|
+
values; strike beats must lie in that interval. Frames interpolate smoothly
|
|
4046
|
+
and wrap the beat into the loop. Missing fields fall back to base, human/hand
|
|
4047
|
+
rest, then zero. `turn` and `roll` are controlled by the caller. The contact
|
|
4048
|
+
pattern alternates left/right at each integer beat, starting left, with full
|
|
4049
|
+
stance through 0.6 of a beat and smooth release; custom keys do not change it.
|
|
4050
|
+
`strike` peaks at 1 and fades to 0 a quarter beat either side of a hit.
|
|
4051
|
+
|
|
4052
|
+
`DanceCircleOptions` requires a positive `radius`; other fields are `center`
|
|
4053
|
+
([x,z], default [0,0]), `count` (default 8 in direct sampling), `beatsPerTurn`
|
|
4054
|
+
(32), `angle` (0 degrees, first dancer along +z), `direction` (1 clockwise
|
|
4055
|
+
viewed from above, or -1), `facing` (`inward` by default, `outward`, `tangent`
|
|
4056
|
+
or numeric degrees), `spins` (extra signed revolutions per orbit, default 0),
|
|
4057
|
+
`style` (`garba`), `character` (default height 1.7), `pose`, `plantFeet` (true).
|
|
4058
|
+
`DancePartner` is `{ character, pose, position: [x,y,z] }`, with placement,
|
|
4059
|
+
stick lengths and character height in the same units. Include world heading
|
|
4060
|
+
in `pose.turn` (quarter-turns) for contacts; object rotations are not read.
|
|
4061
|
+
`reached` uses a tolerance of 0.002 times the character height for foot plants
|
|
4062
|
+
or the shorter partner height for both stick tips.
|
|
4063
|
+
|
|
4064
|
+
The bakers return linear JSON keyframes and omit unchanged base/rest pose
|
|
4065
|
+
fields, so rendered targets need the same base pose. Pose tracks omit
|
|
4066
|
+
`turn`/`roll`; zero-roll circle tracks use `rotateY`, while rolled circles
|
|
4067
|
+
use pose `turn`/`roll` and `rotateY: 0`. Core bakers include hand fields;
|
|
4068
|
+
the editor filters them when hands are disabled. Partner IK and stick
|
|
4069
|
+
drawing are separate from the routines and circle bakes.
|
|
4070
|
+
See [Dance and Flips](dance.md#native-character-dances-circles-and-spins)
|
|
4071
|
+
for loop closure, contact handling and examples.
|
|
4072
|
+
|
|
4073
|
+
`characterScript3D(id, beats, options)` and `checkCharacterBeats3D(beats)`
|
|
4074
|
+
accept the `CharacterBeat3D` actions `spin` and `dance`:
|
|
4075
|
+
|
|
4076
|
+
| Action | Timing and behavior |
|
|
4077
|
+
|---|---|
|
|
4078
|
+
| `{ do: 'spin', turns?, for?, at? }` | Linear rotation from the current heading; signed/fractional `turns`, default 1, duration `for` in ms, default 1000 |
|
|
4079
|
+
| `{ do: 'dance', dance, bpm?, beats?, for?, at? }` | Named native routine, in place; defaults to style tempo and length; `for` alone derives beats at the BPM, while `beats` with `for` fits those beats into that duration |
|
|
4080
|
+
| `{ do: 'face', toward, for?, at? }` | Shortest turn to a heading (degrees) or [x,z]; explicit duration applies even without a turn |
|
|
4081
|
+
|
|
4082
|
+
Dance entry blends for `min(150 ms, duration / 4)` within the action,
|
|
4083
|
+
preserving prior holds and heading/roll. Missing hand fields start at
|
|
4084
|
+
`HAND_REST`; explicit zeros are retained. `at` must be finite and non-negative;
|
|
4085
|
+
`for`, `bpm`, `beats` must be finite and positive, and `turns` finite.
|
|
4086
|
+
See [3D Scenes](scene-3d.md#characters) for script options and result tracks.
|
|
4087
|
+
`capabilities().character.dances` lists native human dance names;
|
|
4088
|
+
`capabilities().stickFigure.dances` continues to map stick-figure styles to
|
|
4089
|
+
their move names.
|
|
4090
|
+
|
|
4009
4091
|
### Beats
|
|
4010
4092
|
|
|
4011
4093
|
In the engine (`@algorisys/tinyfly`), pure:
|
|
@@ -5589,11 +5671,16 @@ tempo, then click **🕺 Dance from playhead**. Or pick a flip (front, back,
|
|
|
5589
5671
|
layout, scissor, side flip, cartwheel, back handspring, split leap, toe touch)
|
|
5590
5672
|
and click **🤸 Flip at playhead**. Both write ordinary keyframes from the
|
|
5591
5673
|
playhead, a few a beat, keeping the character's keys before and after, so
|
|
5592
|
-
every step can be edited afterwards.
|
|
5674
|
+
every step can be edited afterwards. Native **Garba · two clap**, **Garba ·
|
|
5675
|
+
three clap** and **Dandiya · partner strikes** are also available as eight-beat
|
|
5676
|
+
whole routines. Their body-local steps keep the character's current view
|
|
5677
|
+
and existing turn/roll tracks, without mirroring the steps when facing left.
|
|
5678
|
+
Circle travel, planted-foot formations and paired stick contacts use the
|
|
5679
|
+
code APIs; the menu keys the dance on the spot. With cartoon gloves or natural hands, dances key the hand
|
|
5593
5680
|
shapes too. When an audio element has a tempo, **Follow beat** (on by default)
|
|
5594
5681
|
dances at the music's tempo and starts on the beat nearest the playhead. Popping's glides
|
|
5595
5682
|
and moonwalk travel from where the character stands (an x track, the planted foot staying put); facing
|
|
5596
|
-
left,
|
|
5683
|
+
left, converted stick-figure dances are mirrored and glide the other way. Flips travel from where the character is (an x track), the way it
|
|
5597
5684
|
faces: pick the *Side* or *Side (left)* view first. Facing left, a front-on
|
|
5598
5685
|
flip (a cartwheel, a side flip) is the mirror image: it steps off on the other
|
|
5599
5686
|
foot and wheels left. See [Dance and Flips](dance.md).
|
|
@@ -5704,7 +5791,9 @@ red box. In the property panel:
|
|
|
5704
5791
|
outline. **Lights**: colour and intensity.
|
|
5705
5792
|
- **Characters**: a look (*Clean*, *Pencil*, *Silhouette* drawn by their pens
|
|
5706
5793
|
in perspective, or *Solid*) and **🕺 Dance from playhead** with any dance
|
|
5707
|
-
style.
|
|
5794
|
+
style, including native garba (two/three clap) and dandiya whole routines.
|
|
5795
|
+
The 3D Scene menu uses the style's default tempo and omits hand tracks;
|
|
5796
|
+
native styles keep the object's heading and pose turn/roll independent.
|
|
5708
5797
|
- **Props**: which prop from the catalog (car, truck, bus, tractor, cart, train
|
|
5709
5798
|
car, bike, motorbike, tree, house, helicopter, airplane, horse, dog, cat, cow,
|
|
5710
5799
|
songbird, crow, chicken), its look (*Clean*, *Pencil*, *Silhouette*, or
|
|
@@ -6536,7 +6625,7 @@ The dialog shows the generated HTML/JavaScript code with a **Copy Code** button.
|
|
|
6536
6625
|
**Steps to embed:**
|
|
6537
6626
|
1. Build the player: `npm run build:player`
|
|
6538
6627
|
2. Copy `lib/player/tinyfly-player.iife.js` to your project (or load
|
|
6539
|
-
`https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
6628
|
+
`https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly-player.iife.js`
|
|
6540
6629
|
instead; see [Deployment](DEPLOYMENT.md))
|
|
6541
6630
|
3. Copy the generated code into your HTML
|
|
6542
6631
|
4. Adjust the script `src` path if needed
|
|
@@ -7707,7 +7796,7 @@ npx @algorisys/tinyfly capabilities --json # the same as data
|
|
|
7707
7796
|
It lists the easings, track kinds, every property each canvas shape can
|
|
7708
7797
|
animate (with units and ranges), the stick figure's joints, poses,
|
|
7709
7798
|
expressions, gags, gaits, beat actions, dances, flips and hand shapes, the v2
|
|
7710
|
-
character's poses, expressions, builds, hairstyles, facial hair, glasses,
|
|
7799
|
+
character's poses, native dances, expressions, builds, hairstyles, facial hair, glasses,
|
|
7711
7800
|
hats and cast, the code panel's languages, every surface's anchors and
|
|
7712
7801
|
edits (code panel, whiteboard, chart), camera shots and the teaching
|
|
7713
7802
|
helpers. It is generated from the code, so it can't
|
|
@@ -7737,8 +7826,43 @@ loaded with `kinds: [characterObjects, propObjects]`; its controls are tracks
|
|
|
7737
7826
|
on the object. Script it in world metres with `propScript3D` (`to: [x, z]`,
|
|
7738
7827
|
`through: [[x, z], …]`, `face`), not with `propScript`, whose `to` is screen px.
|
|
7739
7828
|
Characters in a 3D scene walk the same way with `characterScript3D`
|
|
7740
|
-
(`{ do: 'walk', to: [x, z] }`, `pose`, `gag`, `face`, `place`
|
|
7741
|
-
|
|
7829
|
+
(`{ do: 'walk', to: [x, z] }`, `pose`, `gag`, `face`, `place`, `say` with a
|
|
7830
|
+
line, `look` at a point or `'camera'`); a rider is seated with `propRide3D`
|
|
7831
|
+
and spliced into its script with `spliceTracks`. A film from a 3D scene is a
|
|
7832
|
+
shot list (`shotTracks`, `transitionAt` + `drawTransition`), camera moves as
|
|
7833
|
+
tracks (`cameraMoveTracks`, `cameraHandheldTracks`), a mood from
|
|
7834
|
+
`lightingPreset('dusk')` with `ground()` and `shadow: true` on meshes, and
|
|
7835
|
+
sound from `renderMix`; draw it with `depthBuffer: true` when shapes cross.
|
|
7836
|
+
See `docs/props.md` and `docs/scene-3d.md`.
|
|
7837
|
+
|
|
7838
|
+
Native garba/dandiya use `humanDanceFrame(style, beat, base)` or
|
|
7839
|
+
`humanDanceTracks(target, { style, bpm, beats })`, keeping heading independent
|
|
7840
|
+
of local limb motion. `danceCircleAt` / `danceCircleTracks` coordinate a
|
|
7841
|
+
formation's x/z travel, facing and foot plants. Sparse clip fields use base,
|
|
7842
|
+
human/hand rest or zero defaults throughout the loop and JSON bakes.
|
|
7843
|
+
Contacts alternate left/right each integer beat, starting left, with stance
|
|
7844
|
+
through 0.6 of the beat; custom keys do not change this. For different
|
|
7845
|
+
footwork use `plantFeet: false` and your own `plantDanceFoot` contacts.
|
|
7846
|
+
Circle bakes require `beats` and default to 120 BPM (not the custom style's
|
|
7847
|
+
tempo); explicit `count` must match the targets. Render with the bake's base
|
|
7848
|
+
pose and build, since unchanged pose fields are omitted. Whole orbits and
|
|
7849
|
+
routines close only when the extra body spins also total whole revolutions.
|
|
7850
|
+
Zero-roll circle bakes use `rotateY`; with nonzero `pose.roll`, they use
|
|
7851
|
+
pose `turn` (quarter-turns), include roll, and set `rotateY: 0` to preserve
|
|
7852
|
+
yaw before roll and grounding. Supply roll when baking; apply all tracks
|
|
7853
|
+
together without adding heading twice. Apply both `pose` and
|
|
7854
|
+
`position` from `plantDanceFoot`; ankle/toe IK preserves authored `leg.*.rotate`
|
|
7855
|
+
hip turn-out. `meetDandiya` gives paired poses and 3D
|
|
7856
|
+
grip/tip segments with a `reached` flag. Build contact characters from the
|
|
7857
|
+
rendered dancers' options so body proportions, line width and hands match.
|
|
7858
|
+
Scripted dance entry and hand pose transitions use `HAND_REST` for missing
|
|
7859
|
+
hand fields, preserving relaxed hands during preceding holds and explicit zeros.
|
|
7860
|
+
Use `{ do: 'spin', turns: 2,
|
|
7861
|
+
for: 1500 }` for full rotations: `face` takes the shortest route, so facing
|
|
7862
|
+
360° does not spin. A script dance stays in place; `for` alone derives its
|
|
7863
|
+
beat count at the BPM, and `beats` with `for` fits the beats into that duration.
|
|
7864
|
+
Stick geometry and paired IK are separate from native frames and circle
|
|
7865
|
+
bakes. See `docs/dance.md`.
|
|
7742
7866
|
|
|
7743
7867
|
## Characters with a look
|
|
7744
7868
|
|
|
@@ -7941,7 +8065,7 @@ path for all of that:
|
|
|
7941
8065
|
</figure>
|
|
7942
8066
|
|
|
7943
8067
|
<!-- once, anywhere on the page (a site-wide footer is fine) -->
|
|
7944
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
8068
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
|
|
7945
8069
|
```
|
|
7946
8070
|
|
|
7947
8071
|
Every `[data-tinyfly-embed]` mounts when the page is ready, with no per-post
|
|
@@ -8283,6 +8407,7 @@ npx tinyfly video scene.mjs --stills stills/ # one PNG per caption line (els
|
|
|
8283
8407
|
npx tinyfly video scene.mjs --stills stills/ --frames 0,79,88 # stills at chosen frames (or --times 0,2640 in ms)
|
|
8284
8408
|
npx tinyfly video scene.mjs --loop-check # does it loop? (exit 1 when not)
|
|
8285
8409
|
npx tinyfly video scene.mjs --scale 0.5 --fps 12 # quick preview
|
|
8410
|
+
npx tinyfly video scene.mjs --codec prores # a ProRes 422 HQ .mov for editing elsewhere
|
|
8286
8411
|
```
|
|
8287
8412
|
|
|
8288
8413
|
Runnable scenes are in [`examples/headless-video/`](../examples/headless-video/):
|
|
@@ -8411,6 +8536,38 @@ Scene modules may use top-level `await`, or default-export an async function.
|
|
|
8411
8536
|
`assembleNarration(plan, clips, sampleRate)` and `encodeWav(samples, sampleRate)`
|
|
8412
8537
|
are the pure steps underneath, for audio you generate yourself.
|
|
8413
8538
|
|
|
8539
|
+
### A sound mix
|
|
8540
|
+
|
|
8541
|
+
A film's sound is layers: a music bed, the narration, effects at the moments
|
|
8542
|
+
things happen, with the music ducked under the voice. `renderMix` decodes
|
|
8543
|
+
every file with ffmpeg, mixes them and writes one WAV for the scene's
|
|
8544
|
+
`audio`:
|
|
8545
|
+
|
|
8546
|
+
```js
|
|
8547
|
+
import { renderMix } from '@algorisys/tinyfly/headless'
|
|
8548
|
+
|
|
8549
|
+
const audio = await renderMix(
|
|
8550
|
+
[
|
|
8551
|
+
{ id: 'bed', file: 'music/bed.mp3', loop: true, gain: 0.6, fadeOut: 1500, duck: { under: 'voice', amount: 0.7 } },
|
|
8552
|
+
{ id: 'voice', file: 'build/narration.wav' },
|
|
8553
|
+
{ file: 'sfx/tap.wav', at: [1200, 2650, 4100], gain: 0.8 }, // a sound effect at three moments
|
|
8554
|
+
{ file: 'sfx/thud.wav', at: landings.map((t) => t + 40) }, // or at every landing a script reports
|
|
8555
|
+
],
|
|
8556
|
+
{ output: 'build/mix.wav', duration: END, baseDir: here }
|
|
8557
|
+
)
|
|
8558
|
+
export default { /* … */ audio }
|
|
8559
|
+
```
|
|
8560
|
+
|
|
8561
|
+
Each layer has `start` (ms) or `at` (times for a sound effect), `gain`,
|
|
8562
|
+
`fadeIn` and `fadeOut`, `loop` for a bed shorter than the film, and `duck:
|
|
8563
|
+
{ under, amount, attack, release }` to make way for another layer while it
|
|
8564
|
+
sounds. The whole mix is soft-limited so peaks never clip. `mixAudio(layers,
|
|
8565
|
+
{ sampleRate, duration, master })` is the pure step on samples. For cuts and
|
|
8566
|
+
dances on the music's beat, `detectTempo(samples, sampleRate)` finds the
|
|
8567
|
+
grid; `snapShotsToBeats(shots, grid)` moves each cut to the nearest beat,
|
|
8568
|
+
and `danceTracks(target, { bpm: grid.bpm, start: nextBeat(grid, t) })`
|
|
8569
|
+
dances to it.
|
|
8570
|
+
|
|
8414
8571
|
## Characters
|
|
8415
8572
|
|
|
8416
8573
|
`@algorisys/tinyfly/characters` has a poseable stick figure. A pose is a set of
|
|
@@ -9067,6 +9224,12 @@ draw(ctx, frame) {
|
|
|
9067
9224
|
stay put while the camera moves.
|
|
9068
9225
|
- `drawingRate: 12` holds the timeline's poses for two frames of 24 fps ("on
|
|
9069
9226
|
twos"), as hand-drawn animation is timed.
|
|
9227
|
+
- `motionBlur: { samples: 4, shutter: 0.5 }` makes each frame the average of
|
|
9228
|
+
four drawings spread over the shutter's open time (half the frame, a 180°
|
|
9229
|
+
shutter): fast moves streak as a camera's do. Deterministic, `samples`
|
|
9230
|
+
times the work.
|
|
9231
|
+
- `supersample: 2` draws at twice the size and scales down: smoother edges
|
|
9232
|
+
on thin lines and small text (four times the work).
|
|
9070
9233
|
|
|
9071
9234
|
See [acting.md](acting.md) for camera shots, beat scripts and the rest of the
|
|
9072
9235
|
cartoon acting tools.
|
|
@@ -9091,6 +9254,7 @@ await renderVideo(scene, {
|
|
|
9091
9254
|
output: 'out.mp4',
|
|
9092
9255
|
baseDir: '.', // relative audio and font paths resolve against this
|
|
9093
9256
|
scale: 1, crf: 20, preset: 'medium',
|
|
9257
|
+
codec: 'h264', // or 'prores' for a .mov
|
|
9094
9258
|
onProgress: (done, total) => {},
|
|
9095
9259
|
})
|
|
9096
9260
|
await renderStills(scene, { dir: 'stills' })
|
|
@@ -9147,7 +9311,10 @@ room) was ported call for call to Canvas 2D and rendered at 1920×1080, 24 fps,
|
|
|
9147
9311
|
rendering) and `ffmpeg`. Rendering defines `globalThis.Path2D` from the canvas
|
|
9148
9312
|
package when it is missing, because path targets use it.
|
|
9149
9313
|
- Output is H.264 MP4 (`yuv420p`, odd sizes padded to even), with AAC audio when
|
|
9150
|
-
`audio` is set; video stops at the shorter of picture and sound.
|
|
9314
|
+
`audio` is set; video stops at the shorter of picture and sound. `codec:
|
|
9315
|
+
'prores'` (or `--codec prores`) writes ProRes 422 HQ (10-bit, PCM audio) in
|
|
9316
|
+
a `.mov` for an editor; any size works, 1080p and 4K included; `renderStills`
|
|
9317
|
+
gives a PNG sequence.
|
|
9151
9318
|
- `image` targets need images loaded with the canvas package's `loadImage`.
|
|
9152
9319
|
|
|
9153
9320
|
---
|
|
@@ -9170,8 +9337,8 @@ On a page with no build step, load the maps add-on after the browser bundle; it
|
|
|
9170
9337
|
adds to the same `tinyfly` global:
|
|
9171
9338
|
|
|
9172
9339
|
```html
|
|
9173
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
9174
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
9340
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly.iife.js"></script>
|
|
9341
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly-maps.iife.js"></script>
|
|
9175
9342
|
```
|
|
9176
9343
|
|
|
9177
9344
|
It is a separate script because the offline world map it carries adds about
|
|
@@ -10558,6 +10725,154 @@ renders to video and syncs to music exactly.
|
|
|
10558
10725
|
|
|
10559
10726
|
Try it on the Examples page: **Dance Floor (Characters)**.
|
|
10560
10727
|
|
|
10728
|
+
## Native character dances, circles and spins
|
|
10729
|
+
|
|
10730
|
+
For v2 characters use `humanDanceFrame(style, beat, basePose)`, with
|
|
10731
|
+
`style` set to `garba`, `garbaThreeClap` or `dandiya`, or a custom `HumanDanceStyle`.
|
|
10732
|
+
These stylised eight-beat routines author limbs in the body's own 3D space,
|
|
10733
|
+
including weight shifts, knee lifts, clap preparation and recovery. `turn`
|
|
10734
|
+
and `roll` stay with the caller, so the same steps work from the front, back
|
|
10735
|
+
or either side. `HUMAN_DANCES` is plain JSON: copy a routine's `keys`,
|
|
10736
|
+
`strikes`, `beats`, `bpm` and `label` to customise it. Keys are ordered by beat,
|
|
10737
|
+
within `[0, beats)`, and loop back to the first key. Sparse keys use the full
|
|
10738
|
+
clip's field union at every beat: a missing value uses the caller's base pose,
|
|
10739
|
+
then the human or hand rest value, then zero for other fields. Both bakers
|
|
10740
|
+
preserve these numeric fields even when first authored at a later key.
|
|
10741
|
+
The frame also contains `contact: { side, start, weight }`: the support side,
|
|
10742
|
+
the absolute integer planting beat, and a weight that is 1 through stance
|
|
10743
|
+
and fades smoothly to 0 before the next beat. `strike` is 1 at a clap or
|
|
10744
|
+
stick-strike beat and fades linearly to 0 a quarter beat either side. Foot plants
|
|
10745
|
+
assume left/right alternation at each integer beat, starting with the left
|
|
10746
|
+
foot, and stance through 0.6 of each beat. Custom keys do not change this
|
|
10747
|
+
contact pattern. For hops, longer stances or reversed support, set
|
|
10748
|
+
`plantFeet: false` and supply your own contacts with `plantDanceFoot`.
|
|
10749
|
+
|
|
10750
|
+
```js
|
|
10751
|
+
import { character, drawCharacter, humanDanceFrame, humanDanceTracks, danceCircleAt, danceCircleTracks } from '@algorisys/tinyfly/characters'
|
|
10752
|
+
|
|
10753
|
+
const who = character({ height: 220, hands: 'cartoon', handStyle: 'natural' })
|
|
10754
|
+
const frame = humanDanceFrame('garba', time * 120 / 60000, { turn: 2 })
|
|
10755
|
+
drawCharacter(ctx, who, frame.pose) // back view, without mirroring the step
|
|
10756
|
+
|
|
10757
|
+
const tracks = humanDanceTracks('dancer', { style: 'garba', bpm: 120, beats: 8 })
|
|
10758
|
+
// Ordinary JSON keyframes; turn/roll tracks can animate independently.
|
|
10759
|
+
|
|
10760
|
+
const members = danceCircleAt(time * 120 / 60000, {
|
|
10761
|
+
radius: 1.8, count: 8, beatsPerTurn: 32, facing: 'inward', style: 'garba',
|
|
10762
|
+
})
|
|
10763
|
+
// Each member: character, pose, position [x,y,z], heading (degrees), strike,
|
|
10764
|
+
// planted. Heading is already included in pose.turn for direct drawing.
|
|
10765
|
+
|
|
10766
|
+
const circleTracks = danceCircleTracks(['stage/a', 'stage/b'], {
|
|
10767
|
+
radius: 1.8, beatsPerTurn: 32, beats: 32, bpm: 120,
|
|
10768
|
+
})
|
|
10769
|
+
// Scene tracks: x/y/z, rotateY, and local pose fields; no doubled pose.turn.
|
|
10770
|
+
```
|
|
10771
|
+
|
|
10772
|
+
`humanDanceTracks(target, { style, bpm?, beats?, start?, pose?, samplesPerBeat? })`
|
|
10773
|
+
defaults to the style's tempo and beat count, `start: 0` ms, `HUMAN_REST`
|
|
10774
|
+
and 16 samples per beat. It samples from beat 0 through `beats`, with
|
|
10775
|
+
linear JSON keys at `start + beat * 60000 / bpm`; between samples playback
|
|
10776
|
+
approximates the smoothly interpolated frame. It omits `turn`, `roll` and
|
|
10777
|
+
fields that stay at the supplied base/rest value. Give the target the same
|
|
10778
|
+
base pose, since omitted fields are not reset. Hand fields are included;
|
|
10779
|
+
use a hand rig to display them or filter `hand.*` tracks for dot hands.
|
|
10780
|
+
|
|
10781
|
+
Circle positions use `center: [x,z]`, `radius`, initial `angle` (degrees),
|
|
10782
|
+
`direction: 1 | -1`, and equal spacing. Facing can be `inward`, `outward`,
|
|
10783
|
+
`tangent`, or a fixed numeric heading. `spins` adds independent body turns
|
|
10784
|
+
per orbit, including negative or fractional turns. Defaults are
|
|
10785
|
+
`center: [0,0]`, `count: 8`, `beatsPerTurn: 32`, `angle: 0`, `direction: 1`
|
|
10786
|
+
(clockwise viewed from above), `facing: 'inward'`, `spins: 0`, `style: 'garba'`
|
|
10787
|
+
and `plantFeet: true`; `radius` must be positive. At angle 0 the first
|
|
10788
|
+
dancer stands along +z; heading 0 faces +z, 90 faces +x.
|
|
10789
|
+
Height and placement use the same units (default 1.7 metres).
|
|
10790
|
+
`danceCircleTracks(targets, options)` requires `beats`, takes its member
|
|
10791
|
+
count from `targets.length`, and defaults to 120 BPM, `start: 0` ms and
|
|
10792
|
+
16 samples per beat, even when a custom style has a different tempo.
|
|
10793
|
+
Its linear keys omit unchanged base/rest pose fields but always include
|
|
10794
|
+
world placement; give the rendered characters the same base pose and build.
|
|
10795
|
+
With zero roll, circle bakes put heading in object `rotateY` (degrees) and
|
|
10796
|
+
omit pose `turn`; start with neutral object rotation and pose `turn: 0`.
|
|
10797
|
+
With a nonzero `pose.roll`, they instead bake heading into pose `turn`
|
|
10798
|
+
(quarter-turns), include the supplied `roll`, and write `rotateY: 0`. This
|
|
10799
|
+
keeps native yaw before roll, including its grounding and foot contacts.
|
|
10800
|
+
Apply these tracks together and do not add the same heading as object yaw.
|
|
10801
|
+
Set roll in the bake options so the contact solver uses that roll too.
|
|
10802
|
+
Use `character: who` for a custom build. Support toes are held at their
|
|
10803
|
+
planting point through the first 0.6 beat, then released smoothly;
|
|
10804
|
+
`plantFeet: false` disables this. `planted: false` also reports an unreachable
|
|
10805
|
+
plant, a releasing stance, or disabled planting. Keep travel per step within
|
|
10806
|
+
leg reach. To close a loop, use complete orbits and routines, an even number
|
|
10807
|
+
of beats for the alternating contacts, and a whole number of extra body
|
|
10808
|
+
revolutions (`spins * orbits`). Fractional spins can require multiple orbits
|
|
10809
|
+
to close. Run the video loop check for the whole scene.
|
|
10810
|
+
|
|
10811
|
+
For a custom path or pivot, `plantDanceFoot({ character, pose, position },
|
|
10812
|
+
side, worldPoint, 'toe' | 'ankle')` returns the adjusted **pose and position**
|
|
10813
|
+
and a `reached` flag. Apply both outputs: the vertical position correction
|
|
10814
|
+
transfers weight to the supporting leg. It does not translate sideways to
|
|
10815
|
+
hide an unreachable target. The default point is `toe`; `reached` means
|
|
10816
|
+
the joint is within 0.002 times the character height of the target.
|
|
10817
|
+
`danceJoint(partner, chain, joint)` reads a world-space joint with pose yaw,
|
|
10818
|
+
roll, grounding and position applied: arm index 2 is the wrist, leg index 2
|
|
10819
|
+
the ankle, and leg index 3 the toe. Include heading in `pose.turn`
|
|
10820
|
+
(quarter-turns); these contact helpers do not read scene object rotations.
|
|
10821
|
+
Foot IK preserves authored `leg.left.rotate` and
|
|
10822
|
+
`leg.right.rotate` hip turn-out when placing either ankle or toe, including
|
|
10823
|
+
straight-leg contacts at full reach.
|
|
10824
|
+
|
|
10825
|
+
For partner dandiya use `meetDandiya(a, b, { sideA, sideB, point, length })`,
|
|
10826
|
+
where each partner has `{ character, pose, position: [x,y,z] }`. Both grips
|
|
10827
|
+
and stick tips are solved in world space. It returns `a`/`b` poses, two
|
|
10828
|
+
`sticks` (`grip` → `tip` segments), the shared `point`, and `reached`. Defaults:
|
|
10829
|
+
right hands, chest-height contact, stick length 0.22 of the shorter height.
|
|
10830
|
+
The default point is halfway between the partners in x/z and at the higher
|
|
10831
|
+
position y plus 0.62 times the shorter height. `reached` means both tips
|
|
10832
|
+
are within 0.002 times that height of the point; inspect it before applying
|
|
10833
|
+
an unreachable solve. Neither partner's position changes. The returned
|
|
10834
|
+
poses set the selected hands to the `hold` shape. Dandiya frames and circle
|
|
10835
|
+
bakes supply choreography, not stick geometry or automatic partner IK;
|
|
10836
|
+
call `meetDandiya` and draw its segments yourself.
|
|
10837
|
+
Blend strike poses with `humanDanceFrame('dandiya', beat).pose` between hits,
|
|
10838
|
+
using its `strike` envelope; draw the returned sticks at each arm's depth.
|
|
10839
|
+
Construct the contact character from the same options as the rendered dancers,
|
|
10840
|
+
including height, head size, figure, limb proportions, line width and hands.
|
|
10841
|
+
The festive live and headless examples use `character(people[0])` so their
|
|
10842
|
+
solver and displayed bodies share the same geometry.
|
|
10843
|
+
|
|
10844
|
+
In a 3D beat script, use `{ do: 'dance', dance: 'garba', bpm: 120, beats: 8 }`
|
|
10845
|
+
and `{ do: 'spin', turns: 2, for: 1500 }`. Spin preserves the full signed
|
|
10846
|
+
rotation, unlike `face`, which deliberately chooses the shortest route.
|
|
10847
|
+
`spin` starts from the current heading, defaults to one positive revolution
|
|
10848
|
+
over 1000 ms, and turns at constant angular speed; negative and fractional
|
|
10849
|
+
`turns` are allowed. `dance` defaults to the style's BPM and one routine.
|
|
10850
|
+
With only `for`, its beat count is `for * bpm / 60000`; with both `beats`
|
|
10851
|
+
and `for`, that many beats are fitted into `for` ms, overriding the tempo.
|
|
10852
|
+
The script dances in place: use circle helpers for travel and foot plants.
|
|
10853
|
+
`at` must be finite and non-negative; `for`, `bpm` and `beats` must be
|
|
10854
|
+
finite and positive, and `turns` must be finite. Invalid beats are reported
|
|
10855
|
+
by `checkCharacterBeats3D` and rejected by `characterScript3D`.
|
|
10856
|
+
`face` honors an explicit `for` duration even when already facing the target.
|
|
10857
|
+
Scripted dances blend in for up to 150 ms within their duration, preserving
|
|
10858
|
+
a preceding hold, including relaxed hands. Missing hand fields use `HAND_REST`
|
|
10859
|
+
for both the start anchor and entry blend; explicit values, including zero,
|
|
10860
|
+
are preserved. Hand pose transitions use the same rest fallback.
|
|
10861
|
+
Unchanged action-start anchors preserve the preceding
|
|
10862
|
+
transition's endpoint easing; the next action keeps its own easing.
|
|
10863
|
+
Circle track `count`, when given, must match the target count.
|
|
10864
|
+
Garba, three-clap garba and dandiya are also in the editor's Character and
|
|
10865
|
+
3D Scene dance menus. The Character menu follows the audio's beat grid.
|
|
10866
|
+
Native styles offer a whole routine, without individual moves; their tracks
|
|
10867
|
+
do not replace existing view or spin tracks. The Character menu keys hands
|
|
10868
|
+
only with Cartoon gloves or Natural hands. The 3D Scene menu uses the style's
|
|
10869
|
+
default tempo and omits hand tracks.
|
|
10870
|
+
|
|
10871
|
+
See `examples/headless-video/garba-circle.mjs` for a complete looping scene.
|
|
10872
|
+
The Examples page also includes **Navratri: Festive Garba & Dandiya**, with
|
|
10873
|
+
festive clothing, larger decorated sticks, partner strikes and half/full
|
|
10874
|
+
spins. Render `examples/headless-video/festive-dandiya.mjs` for its video.
|
|
10875
|
+
|
|
10561
10876
|

|
|
10562
10877
|
|
|
10563
10878
|
The sheet is `examples/headless-video/dance-sheet.mjs`.
|
|
@@ -10793,7 +11108,8 @@ move (or the whole routine) and a tempo, then **🕺 Dance from playhead**. Or
|
|
|
10793
11108
|
pick a flip and **🤸 Flip at playhead**. Both write ordinary keyframes, a few
|
|
10794
11109
|
a beat, and keep the character's keys before and after. Glides and the
|
|
10795
11110
|
moonwalk also write an `x` track from where the character stands. A character
|
|
10796
|
-
facing left (the *Side (left)* view)
|
|
11111
|
+
using a converted stick-figure style and facing left (the *Side (left)* view)
|
|
11112
|
+
dances the mirror image (`mirrorHumanPose()`:
|
|
10797
11113
|
sides swap, it turns, tips and rolls the other way) and glides the other way;
|
|
10798
11114
|
it turns between 3 (side-on, facing left) and 4 (front-on), never round the
|
|
10799
11115
|
back. With **Hands:
|
|
@@ -10962,8 +11278,11 @@ for a neon glow: `{ color: '#000000', emissive: '#ff2bd6', shading: 'unlit' }`.
|
|
|
10962
11278
|
`roughness` and `metalness` are for the realistic look (three.js, a later
|
|
10963
11279
|
milestone); the stylized renderers ignore them, so one material serves both.
|
|
10964
11280
|
|
|
10965
|
-
The scene can have `background`
|
|
10966
|
-
|
|
11281
|
+
The scene can have `background` (a colour, or a sky as a vertical gradient
|
|
11282
|
+
`{ top, bottom }`), `fog: { color, near, far }` (metres from the camera) and
|
|
11283
|
+
`ground` (the height blob shadows lie at, default 0). A mesh with `shadow:
|
|
11284
|
+
true` (or `{ opacity, ground }`) gets a soft blob shadow on the ground under
|
|
11285
|
+
it, which spreads and fades as the mesh lifts off. A scene with no lights gets a soft default (ambient plus a key
|
|
10967
11286
|
light from upper right). Outlines fade into the fog too. `nearFade: { from, to }` fades geometry
|
|
10968
11287
|
nearer the camera than `to` metres, gone at `from`, so a dive passes through
|
|
10969
11288
|
things as if they were glass (also an option of `resolveScene3D`).
|
|
@@ -10996,6 +11315,85 @@ so instead of picking a winner.
|
|
|
10996
11315
|
the group. `orbitPosition(target, yaw, pitch, distance)` and
|
|
10997
11316
|
`dollyPosition(eye, target, amount)` place cameras for keyframes.
|
|
10998
11317
|
|
|
11318
|
+
## Shots and cameras
|
|
11319
|
+
|
|
11320
|
+
A film is a shot list, as data, over the same scene and timeline:
|
|
11321
|
+
|
|
11322
|
+
```js
|
|
11323
|
+
import { shotTracks, shotMarkers, transitionAt, withActiveCamera, cameraMoveTracks, cameraHandheldTracks } from '@algorisys/tinyfly/scene-3d'
|
|
11324
|
+
import { drawTransition, drawLetterbox } from '@algorisys/tinyfly/adapters'
|
|
11325
|
+
|
|
11326
|
+
const shots = [
|
|
11327
|
+
{ id: 'establish', start: 0, end: 4000, camera: 'wide', label: 'Dolly in' },
|
|
11328
|
+
{ id: 'orbit', start: 4000, end: 7500, camera: 'orbiter', transition: { kind: 'crossfade', duration: 700 } },
|
|
11329
|
+
{ id: 'close', start: 7500, end: 10000, camera: 'close', transition: { kind: 'dipToBlack', duration: 600 } },
|
|
11330
|
+
]
|
|
11331
|
+
const tracks = [
|
|
11332
|
+
...shotTracks(shots, 'set'), // the activeCamera track: a cut is one keyframe
|
|
11333
|
+
...cameraMoveTracks({ scene: 'set', camera: 'wide', start: 0, end: 4000,
|
|
11334
|
+
from: { target: [0, 0.8, 0], yaw: 20, pitch: 18, distance: 11 }, to: { distance: 7 } }), // a dolly
|
|
11335
|
+
...cameraHandheldTracks([], { scene: 'set', camera: 'close', start: 7500, end: 10000,
|
|
11336
|
+
base: { position: [1.2, 1.4, 3.6], lookAt: [0, 0.75, 1.3] }, seed: 'close' }),
|
|
11337
|
+
]
|
|
11338
|
+
```
|
|
11339
|
+
|
|
11340
|
+
- **Shots** are `{ id, start, end, camera, label?, transition? }`;
|
|
11341
|
+
`checkShots` names overlaps, bad ends and a transition on the first shot;
|
|
11342
|
+
`shotAt(shots, time)` is the shot playing; `shotMarkers` gives the
|
|
11343
|
+
timeline's markers (stills and captions step through them).
|
|
11344
|
+
- **Transitions** (`cut`, `crossfade`, `dipToBlack`, `wipe` with a
|
|
11345
|
+
`direction`) start at the shot's start and last `duration` ms. Any frame can
|
|
11346
|
+
ask `transitionAt(shots, time)` which two shots to draw and how far along
|
|
11347
|
+
(0..1); `drawTransition(ctx, transition, { width, height, draw(ctx,
|
|
11348
|
+
cameraId) })` draws both and blends them (a crossfade mixes, a dip covers
|
|
11349
|
+
the cut, a wipe sweeps the new shot in), with `withActiveCamera(values,
|
|
11350
|
+
sceneId, cameraId)` to draw the shot going out. Pure and frame-addressable:
|
|
11351
|
+
the film renders the same in any order.
|
|
11352
|
+
- **Camera moves** are presets that write `position`, `lookAt` (and `fov`)
|
|
11353
|
+
tracks on the camera: `cameraMoveTracks({ from, to, easing, every })` with
|
|
11354
|
+
poses as an orbit round a target (`yaw`, `pitch`, `distance`), or a fixed
|
|
11355
|
+
`position` with a moving `lookAt`, or a `fov`: change `yaw` for an orbit,
|
|
11356
|
+
`distance` for a dolly, `pitch` and `distance` for a crane, `lookAt` for a
|
|
11357
|
+
pan or tilt, `fov` for a zoom, or any mix. `cameraFollowTracks({ subjectAt,
|
|
11358
|
+
offset, lag })` keeps a camera on a moving subject. `cameraHandheldTracks(
|
|
11359
|
+
tracks, { amount, aim, rate, seed })` adds a deterministic handheld shake
|
|
11360
|
+
onto a move's tracks or a still camera's `base`.
|
|
11361
|
+
- **Aspect and safe areas**: `drawLetterbox(ctx, canvas, '2.39:1')` paints
|
|
11362
|
+
the bars (in a video's `overlay`), `frameRect`, `frameSize` and `safeAreas`
|
|
11363
|
+
are the geometry, `drawSafeAreas` draws the action and title guides for
|
|
11364
|
+
stills. `FRAME_ASPECTS` has 16:9, 2.39:1, 4:3, 1:1, 9:16 and 4:5.
|
|
11365
|
+
|
|
11366
|
+
`examples/headless-video/film-shots.mjs` is a three-shot film with a dolly, a
|
|
11367
|
+
crossfade into an orbit, a dip to black into a handheld close-up, letterboxed.
|
|
11368
|
+
|
|
11369
|
+
## Sets and light for mood
|
|
11370
|
+
|
|
11371
|
+
A set is objects like any other; what sets the mood is its light, its sky and
|
|
11372
|
+
its fog, and those come as presets:
|
|
11373
|
+
|
|
11374
|
+
```js
|
|
11375
|
+
import { lightingPreset, lightingTracks, ground } from '@algorisys/tinyfly/scene-3d'
|
|
11376
|
+
|
|
11377
|
+
const light = lightingPreset('dusk') // or 'day', 'night', 'stage'
|
|
11378
|
+
const floor = ground({ size: 20 })
|
|
11379
|
+
const scene = {
|
|
11380
|
+
id: 'set', camera: 'cam', background: light.background, fog: light.fog,
|
|
11381
|
+
materials: { ...floor.materials, red: { color: '#ef4444', shading: 'toon' } },
|
|
11382
|
+
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 }],
|
|
11383
|
+
}
|
|
11384
|
+
// Day turning to night over four seconds: tracks on the same lights.
|
|
11385
|
+
const tracks = lightingTracks('day', 'night', { scene: 'set', start: 0, end: 4000 })
|
|
11386
|
+
```
|
|
11387
|
+
|
|
11388
|
+
Every preset uses the same light ids (`key`, `fill`, `sky`, and `spot` on
|
|
11389
|
+
the stage), so `lightingTracks(from, to, { scene, start, end })` keys each
|
|
11390
|
+
light's `color`, `intensity`, `position` and `target` from one mood to the
|
|
11391
|
+
other (a spot only one mood has fades in or out); the sky and fog are the
|
|
11392
|
+
scene's to set per shot. `ground({ size, color, segments, y })` is a floor
|
|
11393
|
+
on layer −1 with its material; props from the catalog (trees, houses,
|
|
11394
|
+
furniture) are the set pieces, placed by preset name (see Props). Blob
|
|
11395
|
+
shadows under meshes are `shadow: true`; projected shadows are planned.
|
|
11396
|
+
|
|
10999
11397
|
## Lines and trails
|
|
11000
11398
|
|
|
11001
11399
|
Two more kinds of object draw a band that faces the camera, as wide as
|
|
@@ -11041,7 +11439,7 @@ front of the meshes. For trails on a plain 2D canvas, see `drawTrail` in
|
|
|
11041
11439
|
loadScene3D(json): LoadedScene3D // validates and builds meshes once (throws with every problem)
|
|
11042
11440
|
validateScene3D(json, tracks?): string[] // problems as sentences, empty when fine
|
|
11043
11441
|
resolveScene3D(loaded, values, { width, height, time?, valuesAt? }): ResolvedScene3D // pure: matrices, camera, lights, sorted triangles
|
|
11044
|
-
drawScene3D(ctx, loaded, values, { width, height, time?, valuesAt? | stateAt? })
|
|
11442
|
+
drawScene3D(ctx, loaded, values, { width, height, time?, valuesAt? | stateAt?, depthBuffer? }) // resolve and draw, in one call
|
|
11045
11443
|
new Scene3DAdapter(new Canvas2DRenderer(ctx), { width, height, valuesAt? }) // registerScene, applyState(state), render()
|
|
11046
11444
|
```
|
|
11047
11445
|
|
|
@@ -11111,7 +11509,8 @@ A character faces +z before any turn and stands on its object's ground: its
|
|
|
11111
11509
|
lowest point at the object's y, so at y 0 it stands on a floor at y 0. Its
|
|
11112
11510
|
pose fields are tracks on its object, next to `x`, `rotateY` and the rest:
|
|
11113
11511
|
`stage/tum` `arm.right.spread`, `stage/tum` `turn`. Every dance and flip
|
|
11114
|
-
plays in 3D: `
|
|
11512
|
+
plays in 3D: `const frame = danceFrame(style, beat)` followed by
|
|
11513
|
+
`stickToHuman(frame.pose, frame.hands)` gives the pose, and
|
|
11115
11514
|
`mirrorHumanPose()` its mirror image for a partner. Its `turn`, `roll`,
|
|
11116
11515
|
`lift` and ground contact behave as they do front-on; seen front-on through a
|
|
11117
11516
|
flat camera, a character is exactly the 2D figure.
|
|
@@ -11119,6 +11518,25 @@ flat camera, a character is exactly the 2D figure.
|
|
|
11119
11518
|
**Walking in metres.** `characterScript3D(id, beats, { scene, position, heading, height })`
|
|
11120
11519
|
scripts a character in world metres, as `propScript3D` does props:
|
|
11121
11520
|
|
|
11521
|
+
It also accepts `{ do: 'spin', turns: 2, for: 1500 }` (signed full turns,
|
|
11522
|
+
linear angular motion) and `{ do: 'dance', dance: 'garba', bpm: 120, beats: 8 }`.
|
|
11523
|
+
`face` still takes the shortest turn and can use `for` to set its duration.
|
|
11524
|
+
An explicit duration is consumed even when no turn is needed. `spin`
|
|
11525
|
+
defaults to one revolution over 1000 ms; negative or fractional `turns`
|
|
11526
|
+
are allowed. A native `dance` stays in place, using the style's tempo and
|
|
11527
|
+
beat count by default. With only `for`, beats follow the BPM; with both
|
|
11528
|
+
`beats` and `for`, those beats are fitted into that duration.
|
|
11529
|
+
For circle formations with planted toes and independent facing/spins use
|
|
11530
|
+
`danceCircleTracks(['stage/a', 'stage/b'], { radius: 1.8, beatsPerTurn: 32,
|
|
11531
|
+
beats: 32, bpm: 120 })`. These write ordinary world-position, `rotateY` and
|
|
11532
|
+
native pose tracks. For nonzero `pose.roll`, heading uses pose `turn`
|
|
11533
|
+
(quarter-turns) with `rotateY: 0`, preserving native yaw before roll and
|
|
11534
|
+
grounding. Supply roll when baking and apply all returned tracks together.
|
|
11535
|
+
Use the same character build and base pose for baking and rendering; omitted
|
|
11536
|
+
base/rest fields are not reset. Partner stick contacts require `meetDandiya`
|
|
11537
|
+
and drawing its returned segments separately.
|
|
11538
|
+
See [Native character dances](dance.md#native-character-dances-circles-and-spins).
|
|
11539
|
+
|
|
11122
11540
|
```js
|
|
11123
11541
|
import { characterScript3D } from '@algorisys/tinyfly/characters'
|
|
11124
11542
|
|
|
@@ -11139,6 +11557,21 @@ phase) with the distance, one stride per cycle, so the feet stay planted, plus
|
|
|
11139
11557
|
the stepping pose as it draws, on the pose it holds: a wave carries on while it
|
|
11140
11558
|
walks. Objects take `gait` and `walking` as fields too.
|
|
11141
11559
|
|
|
11560
|
+
**Speaking and looking.** `{ do: 'say', say: 'A pot of water!' }` lip-syncs
|
|
11561
|
+
the line on the character's mouth (the same `lipSyncOver` the 2D scripts use)
|
|
11562
|
+
with a talking head, and lasts as long as the line (`speechLength(text)`, or
|
|
11563
|
+
`for`). `{ do: 'look', look: [x, z] }` turns the head and eyes toward a point
|
|
11564
|
+
at eye height (`[x, y, z]` for any height, `'camera'` for the viewer with
|
|
11565
|
+
`options.camera`); `lookFields(from, at)` is the maths. To keep looking at
|
|
11566
|
+
something that moves, `characterLookAtTracks(tracks, { scene, character,
|
|
11567
|
+
at: { object: 'didi' } | { camera: 'cam' } | [x, y, z] | (time) => [x, y, z],
|
|
11568
|
+
start, end, objects })` keys `head.turn`, `head.nod`, `lookX` and `lookY`
|
|
11569
|
+
from where both are at every moment; `objectPositionAt(tracks, target,
|
|
11570
|
+
base)` is the sampler it uses. For several figures, `stageSpots({ count,
|
|
11571
|
+
shape: 'line' | 'arc' | 'circle' | 'cluster', spacing, centre })` gives
|
|
11572
|
+
positions and headings that do not overlap: a line across, an arc facing its
|
|
11573
|
+
middle, a circle facing in, or a seeded loose group.
|
|
11574
|
+
|
|
11142
11575
|
**Riding.** `propRide3D({ prop, propId, propTracks, scene, placement, anchor, riderId, pose, start, end, mount?, dismount? })`
|
|
11143
11576
|
keeps a rider's hips on a prop's seat anchor (a horse's `saddle`, a bike's or
|
|
11144
11577
|
a cart's `seat`) as the prop moves, turns, bobs with its stride and pitches,
|
|
@@ -11307,8 +11740,9 @@ renderer.render(resolveScene3D(scene, values, { width: canvas.width, height: can
|
|
|
11307
11740
|
trails, go on `overlay`, a 2D canvas laid over the GL one (in front of the meshes);
|
|
11308
11741
|
solid characters are meshes and sort properly.
|
|
11309
11742
|
|
|
11310
|
-
It runs on a page or in a Worker (OffscreenCanvas). Node has no WebGL2
|
|
11311
|
-
headless video uses the Canvas 2D renderer
|
|
11743
|
+
It runs on a page or in a Worker (OffscreenCanvas). Node has no WebGL2;
|
|
11744
|
+
headless video uses the Canvas 2D renderer, or its software depth buffer
|
|
11745
|
+
(below) when shapes cut through each other. The cross-browser checks
|
|
11312
11746
|
(`npm run e2e -- --check scene-3d-webgl`) compile it in Chromium, Firefox and
|
|
11313
11747
|
WebKit, compare its silhouettes with the Canvas 2D renderer's and check the
|
|
11314
11748
|
depth buffer.
|
|
@@ -11324,6 +11758,20 @@ modest, or use a layer. Each triangle has one colour, so smooth shading is
|
|
|
11324
11758
|
smoothed per triangle, not per pixel; more segments look rounder. The WebGL2
|
|
11325
11759
|
renderer (above) has a depth buffer and per-pixel light.
|
|
11326
11760
|
|
|
11761
|
+
**A software depth buffer** draws right where the painter's order cannot:
|
|
11762
|
+
`drawScene3D(ctx, scene, values, { …, depthBuffer: true })`, or
|
|
11763
|
+
`new Scene3DAdapter(new SoftwareRenderer(ctx), …)`. Every triangle is
|
|
11764
|
+
rasterised into a pixel buffer with a depth per pixel (`rasterizeResolvedScene`
|
|
11765
|
+
gives the bytes and depths without a canvas), so crossing beams, huge floors
|
|
11766
|
+
and long meshes need no `layer` or segments; see-through meshes blend over
|
|
11767
|
+
what is behind them, and ink is depth-tested so an outline never shows
|
|
11768
|
+
through what is in front. Each triangle keeps its one shaded colour and its
|
|
11769
|
+
fog, edges are hard (no anti-aliasing), and objects drawn whole (characters
|
|
11770
|
+
in their pen looks, lines, trails) go on top of the meshes, as on the WebGL2
|
|
11771
|
+
overlay. It costs about three times the painter's time and works anywhere
|
|
11772
|
+
the Canvas 2D renderer does. Layers keep their meaning: a lower layer is
|
|
11773
|
+
drawn first and a higher one paints over it whatever the depths.
|
|
11774
|
+
|
|
11327
11775
|
Rendering speed in Node: a 1280×720 scene of a few thousand triangles renders
|
|
11328
11776
|
at a few frames a second; parallel rendering for long films is planned.
|
|
11329
11777
|
|
|
@@ -11720,6 +12168,8 @@ The project uses a separate OSS (Open Source Software) repository for public rel
|
|
|
11720
12168
|
Files listed in `.ossignore` are excluded from OSS publishing:
|
|
11721
12169
|
- `scripts/` - Internal publishing scripts
|
|
11722
12170
|
- `CLAUDE.md` - Internal AI instructions
|
|
12171
|
+
- `.no-mistakes.yaml` - Internal release validation configuration (Codex reviewer,
|
|
12172
|
+
tests with two workers, and the TypeScript check)
|
|
11723
12173
|
|
|
11724
12174
|
### Publishing Process
|
|
11725
12175
|
|
|
@@ -13765,7 +14215,7 @@ magnet.addEventListener('pointerleave', () => {
|
|
|
13765
14215
|
|
|
13766
14216
|
<!-- capabilities: generated from the library -->
|
|
13767
14217
|
|
|
13768
|
-
# tinyfly capabilities (v0.
|
|
14218
|
+
# tinyfly capabilities (v0.103.0)
|
|
13769
14219
|
|
|
13770
14220
|
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).
|
|
13771
14221
|
|
|
@@ -13988,7 +14438,7 @@ A prop is a 3D rig of simple parts drawn with the characters’ pens (clean, pen
|
|
|
13988
14438
|
- `horse() · dog() · cat() · cow()`: animals (quadruped(spec) makes your own): gaits with footfall patterns keyed in step with the distance, sit, jump, their calls, species actions
|
|
13989
14439
|
- `songbird() · crow() · chicken()`: birds (bird(spec) makes your own): hop, walk, peck, flap, fly and land (a chicken flutters), their calls; wings fold and beat in rhythm
|
|
13990
14440
|
- `{ kind: 'prop', prop: 'car', position, rotation, values } with loadScene3D(scene, { kinds: [characterObjects, propObjects] })`: props in 3D scenes, by preset name, seen in perspective by the scene camera; controls are tracks on the object
|
|
13991
|
-
- `characterScript3D(id, beats, { scene, position?, heading?, height?, pose? })`: a v2 character in
|
|
14441
|
+
- `characterScript3D(id, beats, { scene, position?, heading?, height?, pose? })`: a v2 character in world metres: gaits, face (shortest turn), spin (signed turns and duration), dance (native style, bpm, beats), hold, pose, gag; checkCharacterBeats3D checks the beats
|
|
13992
14442
|
- `propRide3D({ prop, propId, propTracks, scene, placement, anchor, riderId, pose, start, end, mount?, dismount? })`: a character riding a prop in a 3D scene: hips on a seat anchor (saddle, seat) as it moves, hopping on and off; RIDING_POSES.astride / .seated / .driving / .cycling / .wheeling (a wheelchair)
|
|
13993
14443
|
- `propScript3D(id, prop, beats, { scene, position?, heading?, values? })`: props scripted in world metres for 3D scenes: moves to [x, z] or through points (wheels and strides keyed with the distance), face, hold, and their actions; checkPropBeats3D checks the beats
|
|
13994
14444
|
- `propPreset(name, options?)`: a prop preset by name (did-you-mean on a wrong one)
|
|
@@ -14042,6 +14492,7 @@ Scenery: `scenery({ x, y, width, height, kind: sky | room, hour, clouds, wind, r
|
|
|
14042
14492
|
## Character (v2 human)
|
|
14043
14493
|
|
|
14044
14494
|
Poses: `rest`, `wave`, `cheer`, `point`, `handsOnHips`, `think`, `shrug`, `sit`, `kneel`, `crouch`, `crawl`, `lieDown`, `sleep`, `stretch`, `sitFloor`, `carry`, `cane`, `lift`, `push`, `pull`, `drink`, `phone`, `read`, `type`. Expressions: `neutral`, `happy`, `joyful`, `sad`, `crying`, `surprised`, `shocked`, `angry`, `furious`, `worried`, `scared`, `confused`, `skeptical`, `thinking`, `sleepy`, `disgusted`, `smug`, `wink`, `laughing`, `afraid`, `bored`, `tired`, `embarrassed`, `proud`, `determined`, `affectionate`, `hurt`, `suspicious`, `relieved`, `excited`. Gags: `take`, `doubleTake`, `windUp`, `land`, `tremble`, `deflate`.
|
|
14495
|
+
Native dances: `garba`, `garbaThreeClap`, `dandiya`; `humanDanceFrame(style, beat, base)` keeps body heading independent; `humanDanceTracks(target, options)` bakes JSON pose tracks. `danceCircleAt(beat, { radius, count, beatsPerTurn, facing, spins })` gives a formation with planted toes; `danceCircleTracks(targets, options)` bakes scene tracks. `plantDanceFoot(partner, side, worldPoint)` returns pose AND position; `meetDandiya(a, b)` solves both stick tips to one shared world point and reports unreachable contacts.
|
|
14045
14496
|
|
|
14046
14497
|
Appearance options of `character({ … })`, all plain data that turns with the head (see docs/character-appearance.md):
|
|
14047
14498
|
|