@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.
Files changed (59) hide show
  1. package/README.md +17 -6
  2. package/bin/tinyfly.mjs +9 -3
  3. package/docs/DEPLOYMENT.md +2 -0
  4. package/docs/api-reference.md +61 -0
  5. package/docs/dance.md +150 -1
  6. package/docs/editor-guide.md +11 -4
  7. package/docs/examples.md +22 -1
  8. package/docs/getting-started.md +1 -1
  9. package/docs/gsap-compat.md +1 -1
  10. package/docs/llm-guide.md +38 -3
  11. package/docs/maps.md +2 -2
  12. package/docs/scene-3d.md +138 -6
  13. package/docs/teaching.md +1 -1
  14. package/docs/video-rendering.md +44 -1
  15. package/lib/addons/adapters.js +168 -123
  16. package/lib/addons/characters.js +5802 -5506
  17. package/lib/addons/scene-3d-webgl.js +30 -30
  18. package/lib/addons/scene-3d.js +650 -341
  19. package/lib/browser/tinyfly-scene-3d-webgl.iife.js +2 -2
  20. package/lib/browser/tinyfly-scene-3d.iife.js +2 -2
  21. package/lib/browser/tinyfly.iife.js +14 -14
  22. package/lib/browser/tinyfly.js +5798 -5467
  23. package/lib/browser/tinyfly.umd.js +14 -14
  24. package/lib/engine/tinyfly-engine.js +1207 -1172
  25. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  26. package/lib/headless/headless.js +150 -6
  27. package/lib/types/adapters/canvas/framing.d.ts +27 -0
  28. package/lib/types/adapters/canvas/index.d.ts +1 -0
  29. package/lib/types/characters/capabilities.d.ts +1 -0
  30. package/lib/types/characters/character-script-3d.d.ts +34 -4
  31. package/lib/types/characters/dance-circle.d.ts +59 -0
  32. package/lib/types/characters/dance-contact.d.ts +52 -0
  33. package/lib/types/characters/human-dance.d.ts +86 -0
  34. package/lib/types/characters/index.d.ts +5 -1
  35. package/lib/types/characters/rig/reach.d.ts +6 -3
  36. package/lib/types/characters/staging-3d.d.ts +56 -0
  37. package/lib/types/engine/authoring/framing.d.ts +48 -0
  38. package/lib/types/engine/authoring/index.d.ts +1 -0
  39. package/lib/types/headless/audio-mix.d.ts +40 -0
  40. package/lib/types/headless/ffmpeg-args.d.ts +2 -0
  41. package/lib/types/headless/frame-renderer.d.ts +7 -1
  42. package/lib/types/headless/index.d.ts +1 -0
  43. package/lib/types/headless/node-audio.d.ts +19 -0
  44. package/lib/types/headless/node-video.d.ts +2 -0
  45. package/lib/types/headless/video-scene.d.ts +12 -0
  46. package/lib/types/scene-3d/index.d.ts +3 -0
  47. package/lib/types/scene-3d/lighting.d.ts +58 -0
  48. package/lib/types/scene-3d/resolve-scene.d.ts +5 -1
  49. package/lib/types/scene-3d/scene-3d-adapter.d.ts +2 -0
  50. package/lib/types/scene-3d/scene-types.d.ts +14 -2
  51. package/lib/types/scene-3d/shots.d.ts +162 -0
  52. package/lib/types/scene-3d/software-renderer.d.ts +40 -0
  53. package/llms-full.txt +474 -23
  54. package/llms.txt +29 -29
  55. package/package.json +1 -1
  56. package/skills/tinyfly/SKILL.md +32 -1
  57. package/lib/types/characters/polyline.d.ts +0 -12
  58. package/lib/types/characters/sketch.d.ts +0 -54
  59. package/lib/types/compat/gsap/playhead-crossings.d.ts +0 -47
package/README.md CHANGED
@@ -55,7 +55,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
55
55
  - **Immediate mode too** - A scene's `background` and `draw(ctx, { time })` functions paint each frame directly, Cairo/Processing-style, and mix freely with timeline targets
56
56
  - **Timing from narration** - `planNarration()` lays spoken lines out from their clip lengths (lead, gap, tail) into cues, scene spans and markers; `voiceNarration()` measures recorded clips with ffmpeg and writes the sample-aligned narration WAV
57
57
  - **Characters** - A poseable stick figure (`@algorisys/tinyfly/characters`): named poses, facial expressions (brows, eyes that widen, close and look around, mouth shapes), squash and stretch, rubber-hose limbs, blending, walk cycles and talking, all driven by timeline tracks. **Characters v2**: one skeleton in 3D drawn flat, turning front to side to back, resting on whatever touches the ground, reaching for points, in clean, pencil or silhouette looks, and a 🧍 Character element in the editor you pose and keyframe. **Character appearance**: 34 hairstyles, 20 facial-hair styles, glasses, hats and ears as plain data on the head (they turn with it through all eight views), builds from toddler to tall, a recurring cast (`castMember`), 30 expressions with blush, tears and sweat, and hair that swings after a turn or a run and settles (`hairFollowTracks` keys the lag from the character's own tracks, so drawing stays stateless); four-legged animals' ears lay back on a run the way their tails already trail. Clothes are data too (`outfit.over`: an apron, a lab coat, a hoodie, a cardigan, overalls, a sari; boots), a mouth opens on teeth and a tongue, feet come in shapes, two people hug and help each other up (`embrace`, `helpUp`), and a cane in the hand or a wheelchair to ride are accessories any character can have, not part of an age ([guide](docs/character-appearance.md))
58
- - **Dance and flips** - The stick figure dances disco, hip hop, breaking toprock, jazz, K-pop, Bollywood, Bhangra, Bharatanatyam (with mudras), the Charleston, tap (foot strikes as data, for tap sounds) and popping (side glide, moonwalk, forward glide, which travel with the planted foot staying put), and does front, back, layout, scissor and side flips, cartwheels, back handsprings, split leaps, toe touches and full splits. Wrists, ankles, foot turn-out, whole-body `spin` and `rise` are pose fields; moves are keyed in beats, so any tempo plays them; styles, grooves and routines are plain JSON (`danceFrame()`, `danceTracks()`, `flipPose()`, `flipTracks()`). In the editor a 🧍 Character dances from the playhead, in time with the music: an Audio element's tempo is detected (`detectTempo()`) or tapped, the timeline shows its beats and bars, and keyframes snap to them. See [docs/dance.md](docs/dance.md)
58
+ - **Dance and flips** - The stick figure dances disco, hip hop, breaking toprock, jazz, K-pop, Bollywood, Bhangra, Bharatanatyam (with mudras), the Charleston, tap (foot strikes as data, for tap sounds) and popping (side glide, moonwalk, forward glide, which travel with the planted foot staying put), and does front, back, layout, scissor and side flips, cartwheels, back handsprings, split leaps, toe touches and full splits. Wrists, ankles, foot turn-out, whole-body `spin` and `rise` are pose fields; moves are keyed in beats, so any tempo plays them; styles, grooves and routines are plain JSON (`danceFrame()`, `danceTracks()`, `flipPose()`, `flipTracks()`). In the editor a 🧍 Character dances from the playhead, in time with the music: an Audio element's tempo is detected (`detectTempo()`) or tapped, the timeline shows its beats and bars, and keyframes snap to them. Native v2 garba (two/three clap) and dandiya add body-local poses, circle formations with planted toes, paired stick-tip contacts, and timed full spins (`humanDanceFrame`, `danceCircleTracks`, `meetDandiya`, `characterScript3D`). Sparse custom keys keep numeric hand and pose values through JSON playback; rolled circles preserve native yaw-before-roll and foot grounding. Foot IK preserves authored hip turn-out for ankle and toe plants. Scripted dance entry preserves relaxed or explicitly posed hands through preceding holds. Script action boundaries retain preceding easing; festive examples solve contacts with their rendered body options. See [docs/dance.md](docs/dance.md)
59
59
  - **Maps** - Animated maps on OpenStreetMap tiles or an offline world outline (also in pencil): the camera flies in, pins drop, routes draw themselves while a marker travels them; a 🗺 Map element in the editor with a one-click trip
60
60
  - **Pencil sketch style** - Hand-drawn strokes with line boil (`sketch` style, `sketchPen`) for a pencil-test, Pencilmation-like look, on the stick figure and on canvas rect / circle / line / path shapes (also from the editor's Properties panel); a `drawOn` track draws any of those shapes on; the wobble is seeded by time, so renders stay deterministic
61
61
  - **The drawing hand** - `drawnPathTarget()` draws a sketched stroke on from a `draw` track while a cartoon hand holds the pencil at its end in a writing grip; the same hand can hold the eraser. `handAt()` gives one hand for a whole scene: it follows each stroke, lifts and glides to the next, and enters and leaves the page
@@ -100,7 +100,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
100
100
  - **Loop check** - `tinyfly video scene.mjs --loop-check` renders five frames and says whether a video loops: whether the frame at the duration matches the first, and whether the last → first seam looks like any other step (exit 1 when it does not). `--frames 0,79,88` renders stills at chosen frames. See [docs/video-rendering.md](docs/video-rendering.md#loops) A scene with `loop: true` is checked before it renders, its frames carry the `period`, and periodic helpers repeat exactly over it: `wobble`, `loopEase`, `loopNoise` (seeded noise round a circle), `torusNoise`; `nestedZoom` draws a Droste picture (a `similarityAbout` step, one level per loop, only the visible levels); `applyZoomBlur` and `drawDiveLines` for dives; the Penrose triangle and stairs as boxes that line up from one viewpoint (`penroseTriangle`, `penroseStairs`, `penroseTriangle3D`); goo as geometry: metaballs that merge and split (`metaballContours`), drips (`dripPath`), bubbles that grow, wobble and pop (`bubblePath`, `bubblePop`) and area-keeping squash and stretch (`squashStretch`)
101
101
  - **Bloom** - `bloom: true` on a video scene adds a deterministic glow around bright things (bright pass, blur, add; no `ctx.filter`), and 3D materials take `emissive` light that shines in the dark and feeds it. `applyBloom(ctx)` works on any 2D canvas. See [docs/video-rendering.md](docs/video-rendering.md#bloom)
102
102
  - **Light trails** - `trailSamples` + `drawTrail` draw comets and light streaks on any 2D canvas: a tapering, fading band with a round head, smooth at any speed, and deterministic (the trail is where the thing was, asked of the timeline, not a frame history). 3D scenes get `line` and `trail` objects whose segments sort by depth among the meshes. See [docs/video-rendering.md](docs/video-rendering.md#light-trails) and [docs/scene-3d.md](docs/scene-3d.md#lines-and-trails)
103
- - **3D scenes** - `@algorisys/tinyfly/scene-3d`: cameras, lights, meshes (box, sphere, cylinder, cone, torus, floor, any SVG path extruded) and props from the catalog (also from the editor's 3D Scene palette) as JSON in metres, animated by ordinary tracks (`stage/box`), cut between cameras with one keyframe, drawn on a plain canvas with flat, smooth or toon shading, ink outlines and fog: in the browser, in Workers, and to MP4 in Node. Characters stand in scenes and dance, seen by any camera, in their pen looks (clean, pencil) or as solid figures (`characterObjects`); props (cars, houses, trees, animals, birds) stand in them by preset name (`propObjects`), sorted a column at a time so figures walk round them rightly, and lit by the scene's lights (a sunset, a night with lit windows). Both are scripted in world metres (`propScript3D`, `characterScript3D`): drive or walk to a point or along a path, wheels and feet keeping pace with the ground. In the editor, a 🧊 3D Scene element builds them without code: add shapes, characters and lights, key them, dance from the playhead, cut between cameras. No WebGL needed (about 7 KB gzipped, its own entry and CDN script); for big or tangled scenes the optional WebGL2 renderer (`@algorisys/tinyfly/scene-3d/webgl`) adds a depth buffer and light per pixel. See [docs/scene-3d.md](docs/scene-3d.md)
103
+ - **3D scenes** - `@algorisys/tinyfly/scene-3d`: cameras, lights, meshes (box, sphere, cylinder, cone, torus, floor, any SVG path extruded) and props from the catalog (also from the editor's 3D Scene palette) as JSON in metres, animated by ordinary tracks (`stage/box`), cut between cameras with one keyframe, drawn on a plain canvas with flat, smooth or toon shading, ink outlines and fog: in the browser, in Workers, and to MP4 in Node. Characters stand in scenes and dance, seen by any camera, in their pen looks (clean, pencil) or as solid figures (`characterObjects`); props (cars, houses, trees, animals, birds) stand in them by preset name (`propObjects`), sorted a column at a time so figures walk round them rightly, and lit by the scene's lights (a sunset, a night with lit windows). Both are scripted in world metres (`propScript3D`, `characterScript3D`): drive or walk to a point or along a path, wheels and feet keeping pace with the ground. In the editor, a 🧊 3D Scene element builds them without code: add shapes, characters and lights, key them, dance from the playhead, cut between cameras. No WebGL needed (about 7 KB gzipped, its own entry and CDN script); for big or tangled scenes the optional WebGL2 renderer (`@algorisys/tinyfly/scene-3d/webgl`) adds a depth buffer and light per pixel. A software depth buffer (`depthBuffer: true`) draws crossing shapes and see-through meshes right in Node too. Films are shot lists as data: `shotTracks` cuts between cameras, `transitionAt` and `drawTransition` crossfade, dip or wipe between shots, `cameraMoveTracks` writes orbits, dollies, cranes, pans and zooms as tracks, `cameraHandheldTracks` adds a seeded shake, and `drawLetterbox` frames it at any aspect. See [docs/scene-3d.md](docs/scene-3d.md)
104
104
  - **3D transforms** - Cards, images, text and shapes turn in 3D (`rotateX`, `rotateY`, `z`, `perspective`, `backfaceVisibility`) and land on the same pixels in DOM, SVG, Canvas (true perspective, also headless) and WebGL, checked against each browser's own CSS. One documented transform order everywhere; Tilt / Turn / Depth / Perspective fields in the editor; 3D Card Flip and Cover Flow samples. Quaternion tracks with `interpolation: "slerp"` turn without gimbal lock; the engine's `vec3`, `quat` and `mat4` helpers are plain arrays. The first steps of [3D support](docs/3d-support-plan.md). See [docs/3d-rotations.md](docs/3d-rotations.md)
105
105
  - **Shape morph** - 🌀 Tween one path into another over the timeline (engine-level path interpolation); plays in every renderer, export, and embed
106
106
  - **Grid, snapping & guides** - ▦ 20px grid, 🧲 snapping of drag/resize to grid/element-edges/artboard with live alignment guides, and 📏 rulers with draggable guides
@@ -137,6 +137,11 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
137
137
  - **Learn** - An interactive course at `/learn`: short steps with live code, a preview you can scrub, and checks that read what your code compiled to. Nine modules, 28 lessons, 67 steps: Foundations (animation as JSON), the GSAP-style API, the Editor (build in the studio, Copy JSON, compare with code), Motion craft (timing, anticipation, springs), Text and SVG, Interaction (hover, quickTo, drag and throw, Flip, canvas), Scroll (reveals, scrub, pinning, velocity, smooth scrolling with parallax), Accessibility and performance (a real reduced-motion mode, keyboard parity, transforms, pausing off-screen work), and a Capstone that rebuilds the Agency Landing Page section by section, from the pointer-lit hero canvas to the magnetic button. Mistakes that would fail silently (a selector that matches nothing, `drawSVG` on a non-shape, a spring on a colour) show as plain-language warnings beside the code, and the last step of each module offers **Copy as page** and, for JSON lessons, **Open in editor**. The course is also in `llms-full.txt`
138
138
  - **Examples** - One page (`/examples`, the **Examples** toolbar button), and a shareable page for every example at `/examples/<id>` for every ready-made animation: editable examples open in the editor as a new project, code examples show their timeline JSON and HTML to copy. Includes a full-page **Agency Landing Page** showcase and a **GSAP-style** section of 41 runnable `live.to()` demos (Flip layouts and shared elements, pinned horizontal scroll, line mask reveals, spring release, canvas from object tweens, motion paths, orbits, shape and menu morphs, scramble text, draggable throws, swipe cards, 3D card flips, magnetic button, proximity grid, marquee, split text, SVG draw…), and every card has **Copy code** for a complete standalone HTML page. Hover-to-play previews, search, and filters for kind and category (GSAP-style, Showcase, Basics, Motion, Text, UI, Loaders, Effects, Data, Camera, Scroll, and **Algorisys** product demos)
139
139
 
140
+ Try [Navratri: Festive Garba & Dandiya](https://tinyfly.app/examples/live-festive-dandiya):
141
+ six dancers circle with decorated clothes and sticks, partner strikes and
142
+ half/full spins. Its [headless scene](examples/headless-video/festive-dandiya.mjs)
143
+ renders the same 24-second loop to video, without bundled audio.
144
+
140
145
  ## Documentation
141
146
 
142
147
  - [Getting Started](docs/getting-started.md) — Installation, setup, and your first animation
@@ -237,7 +242,7 @@ GSAP-shaped functions at the top level. Teaching embeds are included: add
237
242
  itself.
238
243
 
239
244
  ```html
240
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly.iife.js"></script>
245
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly.iife.js"></script>
241
246
  <script>
242
247
  tinyfly.to('.box', { x: 200, rotate: 90, duration: 1, ease: 'power2.out' })
243
248
 
@@ -273,7 +278,7 @@ A teaching figure needs no code at all:
273
278
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON with markers… }</script>
274
279
  <figcaption>Appending to a full slice</figcaption>
275
280
  </figure>
276
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
281
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
277
282
  ```
278
283
 
279
284
  See [Teaching Animations](docs/teaching.md).
@@ -372,7 +377,7 @@ Without a build step, the player bundle puts the same functions on a `tinyfly` g
372
377
  <div data-tinyfly="box" style="width: 60px; height: 60px; background: #4a9eff;"></div>
373
378
  </div>
374
379
 
375
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-player.iife.js"></script>
380
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly-player.iife.js"></script>
376
381
  <script>
377
382
  tinyfly.play('#animation', './animation.json', { loop: -1 })
378
383
  </script>
@@ -481,7 +486,7 @@ Or skip the code entirely with declarative embeds (see [Teaching Animations](doc
481
486
  <svg viewBox="0 0 720 200">…</svg>
482
487
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON… }</script>
483
488
  </figure>
484
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
489
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
485
490
  ```
486
491
 
487
492
  ### Audio / Video Sync
@@ -724,6 +729,12 @@ npm run e2e
724
729
  npm run build
725
730
  ```
726
731
 
732
+ The private repository's `.no-mistakes.yaml` selects the Codex reviewer and
733
+ uses `npm run test:run -- --maxWorkers 2` for tests and
734
+ `npx tsc -p tsconfig.app.json --noEmit` for its lint/type check.
735
+ It is excluded from the OSS mirror; the project needs no runtime configuration
736
+ for this validation.
737
+
727
738
  ### Publishing to npm
728
739
 
729
740
  ```bash
package/bin/tinyfly.mjs CHANGED
@@ -27,7 +27,7 @@
27
27
  * JavaScript (RSS, email, print, previews).
28
28
  *
29
29
  * tinyfly video <scene.mjs> [-o <out.mp4>] [--stills <dir>] [--frames <i,j,…> | --times <ms,ms,…>]
30
- * [--loop-check] [--scale <n>] [--fps <n>] [--crf <n>] [--no-audio] [--srt <file>] [--vtt <file>]
30
+ * [--loop-check] [--scale <n>] [--fps <n>] [--crf <n>] [--codec h264|prores] [--no-audio] [--srt <file>] [--vtt <file>]
31
31
  * Render a scene module to an MP4 without a browser. The module's default
32
32
  * export is a VideoScene (or a function returning one): a timeline and
33
33
  * canvas targets, a draw(ctx, frame) function, or both. --stills writes
@@ -86,7 +86,7 @@ const usage = () => {
86
86
  ' tinyfly validate <timeline.json> [<timeline.json> …] [--markup <file>]\n' +
87
87
  ' tinyfly render <timeline.json> <markup file> [--at start|end|<ms>|<marker id>]\n' +
88
88
  ' tinyfly video <scene.mjs> [-o <out.mp4>] [--stills <dir>] [--frames <i,j,…> | --times <ms,…>] [--loop-check]\n' +
89
- ' [--scale <n>] [--fps <n>] [--crf <n>] [--no-audio] [--srt <file>] [--vtt <file>]'
89
+ ' [--scale <n>] [--fps <n>] [--crf <n>] [--codec h264|prores] [--no-audio] [--srt <file>] [--vtt <file>]'
90
90
  )
91
91
  process.exit(2)
92
92
  }
@@ -162,6 +162,11 @@ async function video() {
162
162
  const scale = numberFlag('--scale')
163
163
  const fps = numberFlag('--fps')
164
164
  const crf = numberFlag('--crf')
165
+ const codec = flag('--codec')
166
+ if (codec && codec !== 'h264' && codec !== 'prores') {
167
+ console.error('tinyfly: --codec is h264 or prores')
168
+ process.exit(2)
169
+ }
165
170
  const silent = has('--no-audio')
166
171
  const loopCheck = has('--loop-check')
167
172
  const framesList = listFlag('--frames')
@@ -214,7 +219,7 @@ async function video() {
214
219
  console.error(`stills: ${files.length} PNG(s) in ${stillsDir}`)
215
220
  return
216
221
  }
217
- const out = output ?? join(baseDir, `${basename(scenePath, extname(scenePath))}.mp4`)
222
+ const out = output ?? join(baseDir, `${basename(scenePath, extname(scenePath))}.${codec === 'prores' ? 'mov' : 'mp4'}`)
218
223
  let lastPercent = -1
219
224
  const started = Date.now()
220
225
  const result = await headless.renderVideo(scene, {
@@ -223,6 +228,7 @@ async function video() {
223
228
  scale,
224
229
  fps,
225
230
  crf,
231
+ codec,
226
232
  audio: silent ? false : undefined,
227
233
  onProgress: (done, total) => {
228
234
  const percent = Math.floor((done / total) * 20) * 5
@@ -45,6 +45,8 @@ The project uses a separate OSS (Open Source Software) repository for public rel
45
45
  Files listed in `.ossignore` are excluded from OSS publishing:
46
46
  - `scripts/` - Internal publishing scripts
47
47
  - `CLAUDE.md` - Internal AI instructions
48
+ - `.no-mistakes.yaml` - Internal release validation configuration (Codex reviewer,
49
+ tests with two workers, and the TypeScript check)
48
50
 
49
51
  ### Publishing Process
50
52
 
@@ -1653,6 +1653,67 @@ Dance and flips (see [Dance and Flips](dance.md)): the pose fields `leftWrist`/`
1653
1653
  `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()`;
1654
1654
  `FLIPS`, `Flip`, `FlipKey`, `flipPose()`, `flipTravel()`, `flipTracks()`; `POSES.sideSplit` and `POSES.frontSplit`.
1655
1655
 
1656
+ Native v2 dance APIs (also from `@algorisys/tinyfly/characters`):
1657
+
1658
+ | API | Result / options |
1659
+ |---|---|
1660
+ | `HUMAN_DANCES` | JSON routines: `garba`, `garbaThreeClap`, `dandiya`, each eight beats at 120 BPM |
1661
+ | `humanDanceFrame(style, beat, base?)` | `HumanDanceFrame`: `{ pose, contact: { side, start, weight }, strike }`; `style` is a `HumanDanceName` or custom `HumanDanceStyle`; `base` defaults to `HUMAN_REST` |
1662
+ | `humanDanceTracks(target, options)` | `Track[]`; `HumanDanceTrackOptions`: required `style`, optional `bpm`, `beats`, `start` (ms), `pose`, `samplesPerBeat` (default 16); tempo and length default to the style |
1663
+ | `danceCircleAt(beat, options)` | `DanceCircleMember[]`: `{ character, pose, position, heading, strike, planted }`; absolute beat, world position and heading in degrees |
1664
+ | `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` |
1665
+ | `danceJoint(partner, chain, joint)` | World `Vec3` with grounding, yaw, roll and placement; wrist/ankle index 2, toe index 3 |
1666
+ | `plantDanceFoot(partner, side, worldPoint, point = 'toe')` | `DanceFootPlant`: partner with adjusted `pose`, `position` and `reached`; `point` is `toe` or `ankle`; apply both pose and position |
1667
+ | `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) |
1668
+
1669
+ `HumanDanceStyle` is `{ label, bpm, beats, keys: [{ beat, pose }], strikes }`.
1670
+ Keys must be nonempty, strictly ordered within `[0, beats)`, with finite pose
1671
+ values; strike beats must lie in that interval. Frames interpolate smoothly
1672
+ and wrap the beat into the loop. Missing fields fall back to base, human/hand
1673
+ rest, then zero. `turn` and `roll` are controlled by the caller. The contact
1674
+ pattern alternates left/right at each integer beat, starting left, with full
1675
+ stance through 0.6 of a beat and smooth release; custom keys do not change it.
1676
+ `strike` peaks at 1 and fades to 0 a quarter beat either side of a hit.
1677
+
1678
+ `DanceCircleOptions` requires a positive `radius`; other fields are `center`
1679
+ ([x,z], default [0,0]), `count` (default 8 in direct sampling), `beatsPerTurn`
1680
+ (32), `angle` (0 degrees, first dancer along +z), `direction` (1 clockwise
1681
+ viewed from above, or -1), `facing` (`inward` by default, `outward`, `tangent`
1682
+ or numeric degrees), `spins` (extra signed revolutions per orbit, default 0),
1683
+ `style` (`garba`), `character` (default height 1.7), `pose`, `plantFeet` (true).
1684
+ `DancePartner` is `{ character, pose, position: [x,y,z] }`, with placement,
1685
+ stick lengths and character height in the same units. Include world heading
1686
+ in `pose.turn` (quarter-turns) for contacts; object rotations are not read.
1687
+ `reached` uses a tolerance of 0.002 times the character height for foot plants
1688
+ or the shorter partner height for both stick tips.
1689
+
1690
+ The bakers return linear JSON keyframes and omit unchanged base/rest pose
1691
+ fields, so rendered targets need the same base pose. Pose tracks omit
1692
+ `turn`/`roll`; zero-roll circle tracks use `rotateY`, while rolled circles
1693
+ use pose `turn`/`roll` and `rotateY: 0`. Core bakers include hand fields;
1694
+ the editor filters them when hands are disabled. Partner IK and stick
1695
+ drawing are separate from the routines and circle bakes.
1696
+ See [Dance and Flips](dance.md#native-character-dances-circles-and-spins)
1697
+ for loop closure, contact handling and examples.
1698
+
1699
+ `characterScript3D(id, beats, options)` and `checkCharacterBeats3D(beats)`
1700
+ accept the `CharacterBeat3D` actions `spin` and `dance`:
1701
+
1702
+ | Action | Timing and behavior |
1703
+ |---|---|
1704
+ | `{ do: 'spin', turns?, for?, at? }` | Linear rotation from the current heading; signed/fractional `turns`, default 1, duration `for` in ms, default 1000 |
1705
+ | `{ 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 |
1706
+ | `{ do: 'face', toward, for?, at? }` | Shortest turn to a heading (degrees) or [x,z]; explicit duration applies even without a turn |
1707
+
1708
+ Dance entry blends for `min(150 ms, duration / 4)` within the action,
1709
+ preserving prior holds and heading/roll. Missing hand fields start at
1710
+ `HAND_REST`; explicit zeros are retained. `at` must be finite and non-negative;
1711
+ `for`, `bpm`, `beats` must be finite and positive, and `turns` finite.
1712
+ See [3D Scenes](scene-3d.md#characters) for script options and result tracks.
1713
+ `capabilities().character.dances` lists native human dance names;
1714
+ `capabilities().stickFigure.dances` continues to map stick-figure styles to
1715
+ their move names.
1716
+
1656
1717
  ### Beats
1657
1718
 
1658
1719
  In the engine (`@algorisys/tinyfly`), pure:
package/docs/dance.md CHANGED
@@ -11,6 +11,154 @@ renders to video and syncs to music exactly.
11
11
 
12
12
  Try it on the Examples page: **Dance Floor (Characters)**.
13
13
 
14
+ ## Native character dances, circles and spins
15
+
16
+ For v2 characters use `humanDanceFrame(style, beat, basePose)`, with
17
+ `style` set to `garba`, `garbaThreeClap` or `dandiya`, or a custom `HumanDanceStyle`.
18
+ These stylised eight-beat routines author limbs in the body's own 3D space,
19
+ including weight shifts, knee lifts, clap preparation and recovery. `turn`
20
+ and `roll` stay with the caller, so the same steps work from the front, back
21
+ or either side. `HUMAN_DANCES` is plain JSON: copy a routine's `keys`,
22
+ `strikes`, `beats`, `bpm` and `label` to customise it. Keys are ordered by beat,
23
+ within `[0, beats)`, and loop back to the first key. Sparse keys use the full
24
+ clip's field union at every beat: a missing value uses the caller's base pose,
25
+ then the human or hand rest value, then zero for other fields. Both bakers
26
+ preserve these numeric fields even when first authored at a later key.
27
+ The frame also contains `contact: { side, start, weight }`: the support side,
28
+ the absolute integer planting beat, and a weight that is 1 through stance
29
+ and fades smoothly to 0 before the next beat. `strike` is 1 at a clap or
30
+ stick-strike beat and fades linearly to 0 a quarter beat either side. Foot plants
31
+ assume left/right alternation at each integer beat, starting with the left
32
+ foot, and stance through 0.6 of each beat. Custom keys do not change this
33
+ contact pattern. For hops, longer stances or reversed support, set
34
+ `plantFeet: false` and supply your own contacts with `plantDanceFoot`.
35
+
36
+ ```js
37
+ import { character, drawCharacter, humanDanceFrame, humanDanceTracks, danceCircleAt, danceCircleTracks } from '@algorisys/tinyfly/characters'
38
+
39
+ const who = character({ height: 220, hands: 'cartoon', handStyle: 'natural' })
40
+ const frame = humanDanceFrame('garba', time * 120 / 60000, { turn: 2 })
41
+ drawCharacter(ctx, who, frame.pose) // back view, without mirroring the step
42
+
43
+ const tracks = humanDanceTracks('dancer', { style: 'garba', bpm: 120, beats: 8 })
44
+ // Ordinary JSON keyframes; turn/roll tracks can animate independently.
45
+
46
+ const members = danceCircleAt(time * 120 / 60000, {
47
+ radius: 1.8, count: 8, beatsPerTurn: 32, facing: 'inward', style: 'garba',
48
+ })
49
+ // Each member: character, pose, position [x,y,z], heading (degrees), strike,
50
+ // planted. Heading is already included in pose.turn for direct drawing.
51
+
52
+ const circleTracks = danceCircleTracks(['stage/a', 'stage/b'], {
53
+ radius: 1.8, beatsPerTurn: 32, beats: 32, bpm: 120,
54
+ })
55
+ // Scene tracks: x/y/z, rotateY, and local pose fields; no doubled pose.turn.
56
+ ```
57
+
58
+ `humanDanceTracks(target, { style, bpm?, beats?, start?, pose?, samplesPerBeat? })`
59
+ defaults to the style's tempo and beat count, `start: 0` ms, `HUMAN_REST`
60
+ and 16 samples per beat. It samples from beat 0 through `beats`, with
61
+ linear JSON keys at `start + beat * 60000 / bpm`; between samples playback
62
+ approximates the smoothly interpolated frame. It omits `turn`, `roll` and
63
+ fields that stay at the supplied base/rest value. Give the target the same
64
+ base pose, since omitted fields are not reset. Hand fields are included;
65
+ use a hand rig to display them or filter `hand.*` tracks for dot hands.
66
+
67
+ Circle positions use `center: [x,z]`, `radius`, initial `angle` (degrees),
68
+ `direction: 1 | -1`, and equal spacing. Facing can be `inward`, `outward`,
69
+ `tangent`, or a fixed numeric heading. `spins` adds independent body turns
70
+ per orbit, including negative or fractional turns. Defaults are
71
+ `center: [0,0]`, `count: 8`, `beatsPerTurn: 32`, `angle: 0`, `direction: 1`
72
+ (clockwise viewed from above), `facing: 'inward'`, `spins: 0`, `style: 'garba'`
73
+ and `plantFeet: true`; `radius` must be positive. At angle 0 the first
74
+ dancer stands along +z; heading 0 faces +z, 90 faces +x.
75
+ Height and placement use the same units (default 1.7 metres).
76
+ `danceCircleTracks(targets, options)` requires `beats`, takes its member
77
+ count from `targets.length`, and defaults to 120 BPM, `start: 0` ms and
78
+ 16 samples per beat, even when a custom style has a different tempo.
79
+ Its linear keys omit unchanged base/rest pose fields but always include
80
+ world placement; give the rendered characters the same base pose and build.
81
+ With zero roll, circle bakes put heading in object `rotateY` (degrees) and
82
+ omit pose `turn`; start with neutral object rotation and pose `turn: 0`.
83
+ With a nonzero `pose.roll`, they instead bake heading into pose `turn`
84
+ (quarter-turns), include the supplied `roll`, and write `rotateY: 0`. This
85
+ keeps native yaw before roll, including its grounding and foot contacts.
86
+ Apply these tracks together and do not add the same heading as object yaw.
87
+ Set roll in the bake options so the contact solver uses that roll too.
88
+ Use `character: who` for a custom build. Support toes are held at their
89
+ planting point through the first 0.6 beat, then released smoothly;
90
+ `plantFeet: false` disables this. `planted: false` also reports an unreachable
91
+ plant, a releasing stance, or disabled planting. Keep travel per step within
92
+ leg reach. To close a loop, use complete orbits and routines, an even number
93
+ of beats for the alternating contacts, and a whole number of extra body
94
+ revolutions (`spins * orbits`). Fractional spins can require multiple orbits
95
+ to close. Run the video loop check for the whole scene.
96
+
97
+ For a custom path or pivot, `plantDanceFoot({ character, pose, position },
98
+ side, worldPoint, 'toe' | 'ankle')` returns the adjusted **pose and position**
99
+ and a `reached` flag. Apply both outputs: the vertical position correction
100
+ transfers weight to the supporting leg. It does not translate sideways to
101
+ hide an unreachable target. The default point is `toe`; `reached` means
102
+ the joint is within 0.002 times the character height of the target.
103
+ `danceJoint(partner, chain, joint)` reads a world-space joint with pose yaw,
104
+ roll, grounding and position applied: arm index 2 is the wrist, leg index 2
105
+ the ankle, and leg index 3 the toe. Include heading in `pose.turn`
106
+ (quarter-turns); these contact helpers do not read scene object rotations.
107
+ Foot IK preserves authored `leg.left.rotate` and
108
+ `leg.right.rotate` hip turn-out when placing either ankle or toe, including
109
+ straight-leg contacts at full reach.
110
+
111
+ For partner dandiya use `meetDandiya(a, b, { sideA, sideB, point, length })`,
112
+ where each partner has `{ character, pose, position: [x,y,z] }`. Both grips
113
+ and stick tips are solved in world space. It returns `a`/`b` poses, two
114
+ `sticks` (`grip` → `tip` segments), the shared `point`, and `reached`. Defaults:
115
+ right hands, chest-height contact, stick length 0.22 of the shorter height.
116
+ The default point is halfway between the partners in x/z and at the higher
117
+ position y plus 0.62 times the shorter height. `reached` means both tips
118
+ are within 0.002 times that height of the point; inspect it before applying
119
+ an unreachable solve. Neither partner's position changes. The returned
120
+ poses set the selected hands to the `hold` shape. Dandiya frames and circle
121
+ bakes supply choreography, not stick geometry or automatic partner IK;
122
+ call `meetDandiya` and draw its segments yourself.
123
+ Blend strike poses with `humanDanceFrame('dandiya', beat).pose` between hits,
124
+ using its `strike` envelope; draw the returned sticks at each arm's depth.
125
+ Construct the contact character from the same options as the rendered dancers,
126
+ including height, head size, figure, limb proportions, line width and hands.
127
+ The festive live and headless examples use `character(people[0])` so their
128
+ solver and displayed bodies share the same geometry.
129
+
130
+ In a 3D beat script, use `{ do: 'dance', dance: 'garba', bpm: 120, beats: 8 }`
131
+ and `{ do: 'spin', turns: 2, for: 1500 }`. Spin preserves the full signed
132
+ rotation, unlike `face`, which deliberately chooses the shortest route.
133
+ `spin` starts from the current heading, defaults to one positive revolution
134
+ over 1000 ms, and turns at constant angular speed; negative and fractional
135
+ `turns` are allowed. `dance` defaults to the style's BPM and one routine.
136
+ With only `for`, its beat count is `for * bpm / 60000`; with both `beats`
137
+ and `for`, that many beats are fitted into `for` ms, overriding the tempo.
138
+ The script dances in place: use circle helpers for travel and foot plants.
139
+ `at` must be finite and non-negative; `for`, `bpm` and `beats` must be
140
+ finite and positive, and `turns` must be finite. Invalid beats are reported
141
+ by `checkCharacterBeats3D` and rejected by `characterScript3D`.
142
+ `face` honors an explicit `for` duration even when already facing the target.
143
+ Scripted dances blend in for up to 150 ms within their duration, preserving
144
+ a preceding hold, including relaxed hands. Missing hand fields use `HAND_REST`
145
+ for both the start anchor and entry blend; explicit values, including zero,
146
+ are preserved. Hand pose transitions use the same rest fallback.
147
+ Unchanged action-start anchors preserve the preceding
148
+ transition's endpoint easing; the next action keeps its own easing.
149
+ Circle track `count`, when given, must match the target count.
150
+ Garba, three-clap garba and dandiya are also in the editor's Character and
151
+ 3D Scene dance menus. The Character menu follows the audio's beat grid.
152
+ Native styles offer a whole routine, without individual moves; their tracks
153
+ do not replace existing view or spin tracks. The Character menu keys hands
154
+ only with Cartoon gloves or Natural hands. The 3D Scene menu uses the style's
155
+ default tempo and omits hand tracks.
156
+
157
+ See `examples/headless-video/garba-circle.mjs` for a complete looping scene.
158
+ The Examples page also includes **Navratri: Festive Garba & Dandiya**, with
159
+ festive clothing, larger decorated sticks, partner strikes and half/full
160
+ spins. Render `examples/headless-video/festive-dandiya.mjs` for its video.
161
+
14
162
  ![Every dance style's moves and every flip](model-sheet/dance-and-flips.png)
15
163
 
16
164
  The sheet is `examples/headless-video/dance-sheet.mjs`.
@@ -246,7 +394,8 @@ move (or the whole routine) and a tempo, then **🕺 Dance from playhead**. Or
246
394
  pick a flip and **🤸 Flip at playhead**. Both write ordinary keyframes, a few
247
395
  a beat, and keep the character's keys before and after. Glides and the
248
396
  moonwalk also write an `x` track from where the character stands. A character
249
- facing left (the *Side (left)* view) dances the mirror image (`mirrorHumanPose()`:
397
+ using a converted stick-figure style and facing left (the *Side (left)* view)
398
+ dances the mirror image (`mirrorHumanPose()`:
250
399
  sides swap, it turns, tips and rolls the other way) and glides the other way;
251
400
  it turns between 3 (side-on, facing left) and 4 (front-on), never round the
252
401
  back. With **Hands:
@@ -181,11 +181,16 @@ tempo, then click **🕺 Dance from playhead**. Or pick a flip (front, back,
181
181
  layout, scissor, side flip, cartwheel, back handspring, split leap, toe touch)
182
182
  and click **🤸 Flip at playhead**. Both write ordinary keyframes from the
183
183
  playhead, a few a beat, keeping the character's keys before and after, so
184
- every step can be edited afterwards. With cartoon gloves, dances key the hand
184
+ every step can be edited afterwards. Native **Garba · two clap**, **Garba ·
185
+ three clap** and **Dandiya · partner strikes** are also available as eight-beat
186
+ whole routines. Their body-local steps keep the character's current view
187
+ and existing turn/roll tracks, without mirroring the steps when facing left.
188
+ Circle travel, planted-foot formations and paired stick contacts use the
189
+ code APIs; the menu keys the dance on the spot. With cartoon gloves or natural hands, dances key the hand
185
190
  shapes too. When an audio element has a tempo, **Follow beat** (on by default)
186
191
  dances at the music's tempo and starts on the beat nearest the playhead. Popping's glides
187
192
  and moonwalk travel from where the character stands (an x track, the planted foot staying put); facing
188
- left, a character dances the mirror image and glides the other way. Flips travel from where the character is (an x track), the way it
193
+ 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
189
194
  faces: pick the *Side* or *Side (left)* view first. Facing left, a front-on
190
195
  flip (a cartwheel, a side flip) is the mirror image: it steps off on the other
191
196
  foot and wheels left. See [Dance and Flips](dance.md).
@@ -296,7 +301,9 @@ red box. In the property panel:
296
301
  outline. **Lights**: colour and intensity.
297
302
  - **Characters**: a look (*Clean*, *Pencil*, *Silhouette* drawn by their pens
298
303
  in perspective, or *Solid*) and **🕺 Dance from playhead** with any dance
299
- style.
304
+ style, including native garba (two/three clap) and dandiya whole routines.
305
+ The 3D Scene menu uses the style's default tempo and omits hand tracks;
306
+ native styles keep the object's heading and pose turn/roll independent.
300
307
  - **Props**: which prop from the catalog (car, truck, bus, tractor, cart, train
301
308
  car, bike, motorbike, tree, house, helicopter, airplane, horse, dog, cat, cow,
302
309
  songbird, crow, chicken), its look (*Clean*, *Pencil*, *Silhouette*, or
@@ -1128,7 +1135,7 @@ The dialog shows the generated HTML/JavaScript code with a **Copy Code** button.
1128
1135
  **Steps to embed:**
1129
1136
  1. Build the player: `npm run build:player`
1130
1137
  2. Copy `lib/player/tinyfly-player.iife.js` to your project (or load
1131
- `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-player.iife.js`
1138
+ `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly-player.iife.js`
1132
1139
  instead; see [Deployment](DEPLOYMENT.md))
1133
1140
  3. Copy the generated code into your HTML
1134
1141
  4. Adjust the script `src` path if needed
package/docs/examples.md CHANGED
@@ -2,8 +2,29 @@
2
2
 
3
3
  Practical examples for common animation patterns using the tinyfly API.
4
4
 
5
+ ## Festive Garba and Dandiya
6
+
7
+ The [Navratri example](https://tinyfly.app/examples/live-festive-dandiya)
8
+ appears under 3D, Showcase, Video and Algorisys. Six festively dressed dancers
9
+ circle, strike larger decorated sticks with partners, and alternate half
10
+ and full spins. Its code uses native character dance, world foot contacts,
11
+ partner IK and the 3D canvas renderer. It loops every 24 seconds.
12
+
13
+ From this repository, build the libraries first with `npm run build:libs`.
14
+ Video rendering needs `ffmpeg` on PATH and `@napi-rs/canvas`; see
15
+ [Rendering Video from Code](video-rendering.md).
16
+
17
+ ```sh
18
+ tinyfly video examples/headless-video/festive-dandiya.mjs --loop-check
19
+ tinyfly video examples/headless-video/festive-dandiya.mjs -o festive-dandiya.mp4
20
+ ```
21
+
22
+ Add an `audio` path to the headless scene to use your own music. The browser
23
+ example runs without bundled audio.
24
+
5
25
  ## Table of Contents
6
26
 
27
+ - [Festive Garba and Dandiya](#festive-garba-and-dandiya)
7
28
  - [Basic: Fade In](#basic-fade-in)
8
29
  - [Multi-Property Animation](#multi-property-animation)
9
30
  - [Infinite Looping](#infinite-looping)
@@ -694,7 +715,7 @@ For simple website embedding without a build system.
694
715
  </html>
695
716
  ```
696
717
 
697
- 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.101.0/cdn/tinyfly-player.iife.js`.
718
+ 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`.
698
719
 
699
720
  ---
700
721
 
@@ -185,7 +185,7 @@ with a GSAP-style call (durations are in seconds here):
185
185
  ```html
186
186
  <div class="box" style="width:60px;height:60px;background:#4a9eff"></div>
187
187
 
188
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly.iife.js"></script>
188
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly.iife.js"></script>
189
189
  <script>
190
190
  tinyfly.to('.box', { x: 200, duration: 1 })
191
191
  </script>
@@ -74,7 +74,7 @@ Without a build step, the all-in-one bundle exposes the same functions on a
74
74
  global — `tinyfly.to()`, `tinyfly.timeline()` and so on:
75
75
 
76
76
  ```html
77
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly.iife.js"></script>
77
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly.iife.js"></script>
78
78
  <script>
79
79
  tinyfly.to('.box', { x: 200, duration: 1 })
80
80
  </script>
package/docs/llm-guide.md CHANGED
@@ -18,7 +18,7 @@ npx @algorisys/tinyfly capabilities --json # the same as data
18
18
  It lists the easings, track kinds, every property each canvas shape can
19
19
  animate (with units and ranges), the stick figure's joints, poses,
20
20
  expressions, gags, gaits, beat actions, dances, flips and hand shapes, the v2
21
- character's poses, expressions, builds, hairstyles, facial hair, glasses,
21
+ character's poses, native dances, expressions, builds, hairstyles, facial hair, glasses,
22
22
  hats and cast, the code panel's languages, every surface's anchors and
23
23
  edits (code panel, whiteboard, chart), camera shots and the teaching
24
24
  helpers. It is generated from the code, so it can't
@@ -48,8 +48,43 @@ loaded with `kinds: [characterObjects, propObjects]`; its controls are tracks
48
48
  on the object. Script it in world metres with `propScript3D` (`to: [x, z]`,
49
49
  `through: [[x, z], …]`, `face`), not with `propScript`, whose `to` is screen px.
50
50
  Characters in a 3D scene walk the same way with `characterScript3D`
51
- (`{ do: 'walk', to: [x, z] }`, `pose`, `gag`, `face`, `place`); a rider is
52
- seated with `propRide3D` and spliced into its script with `spliceTracks`. See `docs/props.md`.
51
+ (`{ do: 'walk', to: [x, z] }`, `pose`, `gag`, `face`, `place`, `say` with a
52
+ line, `look` at a point or `'camera'`); a rider is seated with `propRide3D`
53
+ and spliced into its script with `spliceTracks`. A film from a 3D scene is a
54
+ shot list (`shotTracks`, `transitionAt` + `drawTransition`), camera moves as
55
+ tracks (`cameraMoveTracks`, `cameraHandheldTracks`), a mood from
56
+ `lightingPreset('dusk')` with `ground()` and `shadow: true` on meshes, and
57
+ sound from `renderMix`; draw it with `depthBuffer: true` when shapes cross.
58
+ See `docs/props.md` and `docs/scene-3d.md`.
59
+
60
+ Native garba/dandiya use `humanDanceFrame(style, beat, base)` or
61
+ `humanDanceTracks(target, { style, bpm, beats })`, keeping heading independent
62
+ of local limb motion. `danceCircleAt` / `danceCircleTracks` coordinate a
63
+ formation's x/z travel, facing and foot plants. Sparse clip fields use base,
64
+ human/hand rest or zero defaults throughout the loop and JSON bakes.
65
+ Contacts alternate left/right each integer beat, starting left, with stance
66
+ through 0.6 of the beat; custom keys do not change this. For different
67
+ footwork use `plantFeet: false` and your own `plantDanceFoot` contacts.
68
+ Circle bakes require `beats` and default to 120 BPM (not the custom style's
69
+ tempo); explicit `count` must match the targets. Render with the bake's base
70
+ pose and build, since unchanged pose fields are omitted. Whole orbits and
71
+ routines close only when the extra body spins also total whole revolutions.
72
+ Zero-roll circle bakes use `rotateY`; with nonzero `pose.roll`, they use
73
+ pose `turn` (quarter-turns), include roll, and set `rotateY: 0` to preserve
74
+ yaw before roll and grounding. Supply roll when baking; apply all tracks
75
+ together without adding heading twice. Apply both `pose` and
76
+ `position` from `plantDanceFoot`; ankle/toe IK preserves authored `leg.*.rotate`
77
+ hip turn-out. `meetDandiya` gives paired poses and 3D
78
+ grip/tip segments with a `reached` flag. Build contact characters from the
79
+ rendered dancers' options so body proportions, line width and hands match.
80
+ Scripted dance entry and hand pose transitions use `HAND_REST` for missing
81
+ hand fields, preserving relaxed hands during preceding holds and explicit zeros.
82
+ Use `{ do: 'spin', turns: 2,
83
+ for: 1500 }` for full rotations: `face` takes the shortest route, so facing
84
+ 360° does not spin. A script dance stays in place; `for` alone derives its
85
+ beat count at the BPM, and `beats` with `for` fits the beats into that duration.
86
+ Stick geometry and paired IK are separate from native frames and circle
87
+ bakes. See `docs/dance.md`.
53
88
 
54
89
  ## Characters with a look
55
90
 
package/docs/maps.md CHANGED
@@ -14,8 +14,8 @@ On a page with no build step, load the maps add-on after the browser bundle; it
14
14
  adds to the same `tinyfly` global:
15
15
 
16
16
  ```html
17
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly.iife.js"></script>
18
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.101.0/cdn/tinyfly-maps.iife.js"></script>
17
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly.iife.js"></script>
18
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly-maps.iife.js"></script>
19
19
  ```
20
20
 
21
21
  It is a separate script because the offline world map it carries adds about