@algorisys/tinyfly 0.102.0 → 0.104.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/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.102.0/cdn/tinyfly.iife.js"></script>
207
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.104.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.102.0/cdn/tinyfly.iife.js"></script>
415
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.104.0/cdn/tinyfly.iife.js"></script>
416
416
  <script>
417
417
  tinyfly.to('.box', { x: 200, duration: 1 })
418
418
  </script>
@@ -1586,8 +1586,38 @@ quickPlay({
1586
1586
 
1587
1587
  Practical examples for common animation patterns using the tinyfly API.
1588
1588
 
1589
+ ## Colour Anime Cast
1590
+
1591
+ Open [Colour Anime Cast](https://tinyfly.app/examples/live-anime-cast) to inspect
1592
+ eight male and female characters across children, young adults, adults and
1593
+ older adults. Switch expressions, cycle moods, show face close-ups or enable
1594
+ a full turnaround. `ANIME_CAST` and `castMember` supply editable JSON options;
1595
+ `face.style: 'anime'` uses the same blink, gaze, brow and mouth fields as the
1596
+ original face. See [Character Appearance](character-appearance.md#colour-anime-cast).
1597
+
1598
+ ## Festive Garba and Dandiya
1599
+
1600
+ The [Navratri example](https://tinyfly.app/examples/live-festive-dandiya)
1601
+ appears under 3D, Showcase, Video and Algorisys. Six festively dressed dancers
1602
+ circle, strike larger decorated sticks with partners, and alternate half
1603
+ and full spins. Its code uses native character dance, world foot contacts,
1604
+ partner IK and the 3D canvas renderer. It loops every 24 seconds.
1605
+
1606
+ From this repository, build the libraries first with `npm run build:libs`.
1607
+ Video rendering needs `ffmpeg` on PATH and `@napi-rs/canvas`; see
1608
+ [Rendering Video from Code](video-rendering.md).
1609
+
1610
+ ```sh
1611
+ tinyfly video examples/headless-video/festive-dandiya.mjs --loop-check
1612
+ tinyfly video examples/headless-video/festive-dandiya.mjs -o festive-dandiya.mp4
1613
+ ```
1614
+
1615
+ Add an `audio` path to the headless scene to use your own music. The browser
1616
+ example runs without bundled audio.
1617
+
1589
1618
  ## Table of Contents
1590
1619
 
1620
+ - [Festive Garba and Dandiya](#festive-garba-and-dandiya)
1591
1621
  - [Basic: Fade In](#basic-fade-in)
1592
1622
  - [Multi-Property Animation](#multi-property-animation)
1593
1623
  - [Infinite Looping](#infinite-looping)
@@ -2278,7 +2308,7 @@ For simple website embedding without a build system.
2278
2308
  </html>
2279
2309
  ```
2280
2310
 
2281
- Build the player with `npm run build:player` to generate `lib/player/tinyfly-player.iife.js`, or load it from the CDN: `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-player.iife.js`.
2311
+ 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.104.0/cdn/tinyfly-player.iife.js`.
2282
2312
 
2283
2313
  ---
2284
2314
 
@@ -4006,6 +4036,67 @@ Dance and flips (see [Dance and Flips](dance.md)): the pose fields `leftWrist`/`
4006
4036
  `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
4037
  `FLIPS`, `Flip`, `FlipKey`, `flipPose()`, `flipTravel()`, `flipTracks()`; `POSES.sideSplit` and `POSES.frontSplit`.
4008
4038
 
4039
+ Native v2 dance APIs (also from `@algorisys/tinyfly/characters`):
4040
+
4041
+ | API | Result / options |
4042
+ |---|---|
4043
+ | `HUMAN_DANCES` | JSON routines: `garba`, `garbaThreeClap`, `dandiya`, each eight beats at 120 BPM |
4044
+ | `humanDanceFrame(style, beat, base?)` | `HumanDanceFrame`: `{ pose, contact: { side, start, weight }, strike }`; `style` is a `HumanDanceName` or custom `HumanDanceStyle`; `base` defaults to `HUMAN_REST` |
4045
+ | `humanDanceTracks(target, options)` | `Track[]`; `HumanDanceTrackOptions`: required `style`, optional `bpm`, `beats`, `start` (ms), `pose`, `samplesPerBeat` (default 16); tempo and length default to the style |
4046
+ | `danceCircleAt(beat, options)` | `DanceCircleMember[]`: `{ character, pose, position, heading, strike, planted }`; absolute beat, world position and heading in degrees |
4047
+ | `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` |
4048
+ | `danceJoint(partner, chain, joint)` | World `Vec3` with grounding, yaw, roll and placement; wrist/ankle index 2, toe index 3 |
4049
+ | `plantDanceFoot(partner, side, worldPoint, point = 'toe')` | `DanceFootPlant`: partner with adjusted `pose`, `position` and `reached`; `point` is `toe` or `ankle`; apply both pose and position |
4050
+ | `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) |
4051
+
4052
+ `HumanDanceStyle` is `{ label, bpm, beats, keys: [{ beat, pose }], strikes }`.
4053
+ Keys must be nonempty, strictly ordered within `[0, beats)`, with finite pose
4054
+ values; strike beats must lie in that interval. Frames interpolate smoothly
4055
+ and wrap the beat into the loop. Missing fields fall back to base, human/hand
4056
+ rest, then zero. `turn` and `roll` are controlled by the caller. The contact
4057
+ pattern alternates left/right at each integer beat, starting left, with full
4058
+ stance through 0.6 of a beat and smooth release; custom keys do not change it.
4059
+ `strike` peaks at 1 and fades to 0 a quarter beat either side of a hit.
4060
+
4061
+ `DanceCircleOptions` requires a positive `radius`; other fields are `center`
4062
+ ([x,z], default [0,0]), `count` (default 8 in direct sampling), `beatsPerTurn`
4063
+ (32), `angle` (0 degrees, first dancer along +z), `direction` (1 clockwise
4064
+ viewed from above, or -1), `facing` (`inward` by default, `outward`, `tangent`
4065
+ or numeric degrees), `spins` (extra signed revolutions per orbit, default 0),
4066
+ `style` (`garba`), `character` (default height 1.7), `pose`, `plantFeet` (true).
4067
+ `DancePartner` is `{ character, pose, position: [x,y,z] }`, with placement,
4068
+ stick lengths and character height in the same units. Include world heading
4069
+ in `pose.turn` (quarter-turns) for contacts; object rotations are not read.
4070
+ `reached` uses a tolerance of 0.002 times the character height for foot plants
4071
+ or the shorter partner height for both stick tips.
4072
+
4073
+ The bakers return linear JSON keyframes and omit unchanged base/rest pose
4074
+ fields, so rendered targets need the same base pose. Pose tracks omit
4075
+ `turn`/`roll`; zero-roll circle tracks use `rotateY`, while rolled circles
4076
+ use pose `turn`/`roll` and `rotateY: 0`. Core bakers include hand fields;
4077
+ the editor filters them when hands are disabled. Partner IK and stick
4078
+ drawing are separate from the routines and circle bakes.
4079
+ See [Dance and Flips](dance.md#native-character-dances-circles-and-spins)
4080
+ for loop closure, contact handling and examples.
4081
+
4082
+ `characterScript3D(id, beats, options)` and `checkCharacterBeats3D(beats)`
4083
+ accept the `CharacterBeat3D` actions `spin` and `dance`:
4084
+
4085
+ | Action | Timing and behavior |
4086
+ |---|---|
4087
+ | `{ do: 'spin', turns?, for?, at? }` | Linear rotation from the current heading; signed/fractional `turns`, default 1, duration `for` in ms, default 1000 |
4088
+ | `{ 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 |
4089
+ | `{ do: 'face', toward, for?, at? }` | Shortest turn to a heading (degrees) or [x,z]; explicit duration applies even without a turn |
4090
+
4091
+ Dance entry blends for `min(150 ms, duration / 4)` within the action,
4092
+ preserving prior holds and heading/roll. Missing hand fields start at
4093
+ `HAND_REST`; explicit zeros are retained. `at` must be finite and non-negative;
4094
+ `for`, `bpm`, `beats` must be finite and positive, and `turns` finite.
4095
+ See [3D Scenes](scene-3d.md#characters) for script options and result tracks.
4096
+ `capabilities().character.dances` lists native human dance names;
4097
+ `capabilities().stickFigure.dances` continues to map stick-figure styles to
4098
+ their move names.
4099
+
4009
4100
  ### Beats
4010
4101
 
4011
4102
  In the engine (`@algorisys/tinyfly`), pure:
@@ -5576,6 +5667,11 @@ its box; resize the box to change its height. In the property panel:
5576
5667
  Poses that rest on a knee, the hands or the back are set down on the ground.
5577
5668
  - **Face**: an expression (happy, sad, surprised, angry, embarrassed with a
5578
5669
  blush, crying with tears, afraid with a bead of sweat…), or the pose's own.
5670
+ **Face style** switches between Simple and Colour anime. Anime faces have an
5671
+ **Iris colour** and **Eyelashes** toggle; **Age creases** adds subtle facial
5672
+ lines. The Cast picker includes eight colour anime presets for boys, girls,
5673
+ young adults, adults and older adults. The 3D Scene character's Cast picker
5674
+ uses the same presets.
5579
5675
 
5580
5676
  To animate a character, pick a view, a pose and a face, and click
5581
5677
  **◆ Keyframe pose at playhead**. Move the playhead, pick the next pose, and
@@ -5589,11 +5685,16 @@ tempo, then click **🕺 Dance from playhead**. Or pick a flip (front, back,
5589
5685
  layout, scissor, side flip, cartwheel, back handspring, split leap, toe touch)
5590
5686
  and click **🤸 Flip at playhead**. Both write ordinary keyframes from the
5591
5687
  playhead, a few a beat, keeping the character's keys before and after, so
5592
- every step can be edited afterwards. With cartoon gloves, dances key the hand
5688
+ every step can be edited afterwards. Native **Garba · two clap**, **Garba ·
5689
+ three clap** and **Dandiya · partner strikes** are also available as eight-beat
5690
+ whole routines. Their body-local steps keep the character's current view
5691
+ and existing turn/roll tracks, without mirroring the steps when facing left.
5692
+ Circle travel, planted-foot formations and paired stick contacts use the
5693
+ code APIs; the menu keys the dance on the spot. With cartoon gloves or natural hands, dances key the hand
5593
5694
  shapes too. When an audio element has a tempo, **Follow beat** (on by default)
5594
5695
  dances at the music's tempo and starts on the beat nearest the playhead. Popping's glides
5595
5696
  and moonwalk travel from where the character stands (an x track, the planted foot staying put); facing
5596
- 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
5697
+ 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
5698
  faces: pick the *Side* or *Side (left)* view first. Facing left, a front-on
5598
5699
  flip (a cartwheel, a side flip) is the mirror image: it steps off on the other
5599
5700
  foot and wheels left. See [Dance and Flips](dance.md).
@@ -5704,7 +5805,9 @@ red box. In the property panel:
5704
5805
  outline. **Lights**: colour and intensity.
5705
5806
  - **Characters**: a look (*Clean*, *Pencil*, *Silhouette* drawn by their pens
5706
5807
  in perspective, or *Solid*) and **🕺 Dance from playhead** with any dance
5707
- style.
5808
+ style, including native garba (two/three clap) and dandiya whole routines.
5809
+ The 3D Scene menu uses the style's default tempo and omits hand tracks;
5810
+ native styles keep the object's heading and pose turn/roll independent.
5708
5811
  - **Props**: which prop from the catalog (car, truck, bus, tractor, cart, train
5709
5812
  car, bike, motorbike, tree, house, helicopter, airplane, horse, dog, cat, cow,
5710
5813
  songbird, crow, chicken), its look (*Clean*, *Pencil*, *Silhouette*, or
@@ -6536,7 +6639,7 @@ The dialog shows the generated HTML/JavaScript code with a **Copy Code** button.
6536
6639
  **Steps to embed:**
6537
6640
  1. Build the player: `npm run build:player`
6538
6641
  2. Copy `lib/player/tinyfly-player.iife.js` to your project (or load
6539
- `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-player.iife.js`
6642
+ `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.104.0/cdn/tinyfly-player.iife.js`
6540
6643
  instead; see [Deployment](DEPLOYMENT.md))
6541
6644
  3. Copy the generated code into your HTML
6542
6645
  4. Adjust the script `src` path if needed
@@ -7707,7 +7810,7 @@ npx @algorisys/tinyfly capabilities --json # the same as data
7707
7810
  It lists the easings, track kinds, every property each canvas shape can
7708
7811
  animate (with units and ranges), the stick figure's joints, poses,
7709
7812
  expressions, gags, gaits, beat actions, dances, flips and hand shapes, the v2
7710
- character's poses, expressions, builds, hairstyles, facial hair, glasses,
7813
+ character's poses, native dances, expressions, builds, hairstyles, facial hair, glasses,
7711
7814
  hats and cast, the code panel's languages, every surface's anchors and
7712
7815
  edits (code panel, whiteboard, chart), camera shots and the teaching
7713
7816
  helpers. It is generated from the code, so it can't
@@ -7746,6 +7849,35 @@ tracks (`cameraMoveTracks`, `cameraHandheldTracks`), a mood from
7746
7849
  sound from `renderMix`; draw it with `depthBuffer: true` when shapes cross.
7747
7850
  See `docs/props.md` and `docs/scene-3d.md`.
7748
7851
 
7852
+ Native garba/dandiya use `humanDanceFrame(style, beat, base)` or
7853
+ `humanDanceTracks(target, { style, bpm, beats })`, keeping heading independent
7854
+ of local limb motion. `danceCircleAt` / `danceCircleTracks` coordinate a
7855
+ formation's x/z travel, facing and foot plants. Sparse clip fields use base,
7856
+ human/hand rest or zero defaults throughout the loop and JSON bakes.
7857
+ Contacts alternate left/right each integer beat, starting left, with stance
7858
+ through 0.6 of the beat; custom keys do not change this. For different
7859
+ footwork use `plantFeet: false` and your own `plantDanceFoot` contacts.
7860
+ Circle bakes require `beats` and default to 120 BPM (not the custom style's
7861
+ tempo); explicit `count` must match the targets. Render with the bake's base
7862
+ pose and build, since unchanged pose fields are omitted. Whole orbits and
7863
+ routines close only when the extra body spins also total whole revolutions.
7864
+ Zero-roll circle bakes use `rotateY`; with nonzero `pose.roll`, they use
7865
+ pose `turn` (quarter-turns), include roll, and set `rotateY: 0` to preserve
7866
+ yaw before roll and grounding. Supply roll when baking; apply all tracks
7867
+ together without adding heading twice. Apply both `pose` and
7868
+ `position` from `plantDanceFoot`; ankle/toe IK preserves authored `leg.*.rotate`
7869
+ hip turn-out. `meetDandiya` gives paired poses and 3D
7870
+ grip/tip segments with a `reached` flag. Build contact characters from the
7871
+ rendered dancers' options so body proportions, line width and hands match.
7872
+ Scripted dance entry and hand pose transitions use `HAND_REST` for missing
7873
+ hand fields, preserving relaxed hands during preceding holds and explicit zeros.
7874
+ Use `{ do: 'spin', turns: 2,
7875
+ for: 1500 }` for full rotations: `face` takes the shortest route, so facing
7876
+ 360° does not spin. A script dance stays in place; `for` alone derives its
7877
+ beat count at the BPM, and `beats` with `for` fits the beats into that duration.
7878
+ Stick geometry and paired IK are separate from native frames and circle
7879
+ bakes. See `docs/dance.md`.
7880
+
7749
7881
  ## Characters with a look
7750
7882
 
7751
7883
  A v2 character's appearance is plain options to `character()`, never drawing
@@ -7755,7 +7887,13 @@ code: `build` (`child`, `tall`, `short`…), `hair` (a style name, or
7755
7887
  `flat`, `pointed`, `big`) and `outfit: { shirt, trousers, over: 'hoodie' |
7756
7888
  'cardigan' | 'overalls' | 'sari' | 'apron' | 'labCoat', shoes: 'boots' }`.
7757
7889
  `castMember('grandpa', 300)` gives a whole ready-made character to start
7758
- from. Age is hair, glasses and clothes, never a stoop; a `cane` in a hand or
7890
+ from. The eight presets in `ANIME_CAST` (`animeBoy`, `animeGirl`,
7891
+ `animeYoungMan`, `animeYoungWoman`, `animeMan`, `animeWoman`,
7892
+ `animeOlderMan`, `animeOlderWoman`) work through `castMember` too.
7893
+ Use `face: { style: 'anime', iris: '#4b7fce', lashes: true, ageLines: 0.6 }`
7894
+ for coloured expressive eyes and optional creases; this is a face style,
7895
+ not a `look` value. It uses the same expressions, blink, gaze and turn fields.
7896
+ Age is proportions, hair, creases and clothes, never a stoop; a `cane` in a hand or
7759
7897
  a `wheelchair()` to ride (`RIDING_POSES.wheeling`) is an accessory any
7760
7898
  character can have. Expressions come from `HUMAN_EXPRESSIONS`
7761
7899
  and are pose fields, as are the face marks `blush`, `tears` and `sweat` (0–1)
@@ -7947,7 +8085,7 @@ path for all of that:
7947
8085
  </figure>
7948
8086
 
7949
8087
  <!-- once, anywhere on the page (a site-wide footer is fine) -->
7950
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
8088
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.104.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
7951
8089
  ```
7952
8090
 
7953
8091
  Every `[data-tinyfly-embed]` mounts when the page is ready, with no per-post
@@ -9219,8 +9357,8 @@ On a page with no build step, load the maps add-on after the browser bundle; it
9219
9357
  adds to the same `tinyfly` global:
9220
9358
 
9221
9359
  ```html
9222
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly.iife.js"></script>
9223
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-maps.iife.js"></script>
9360
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.104.0/cdn/tinyfly.iife.js"></script>
9361
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.104.0/cdn/tinyfly-maps.iife.js"></script>
9224
9362
  ```
9225
9363
 
9226
9364
  It is a separate script because the offline world map it carries adds about
@@ -9677,12 +9815,49 @@ cast member at an adult `height` (each stands at their own scale of it). The
9677
9815
  family: `boy`, `girl`, `youngMan`, `youngWoman`, `man`, `woman`, `grandpa`,
9678
9816
  `grandma`; at work (from the occupations sheet): `doctor`, `cook`, `builder`,
9679
9817
  `courier`, `teacher`, `farmer`. `CHARACTER_CAST` has each one's `label`,
9680
- `group` (`family` or `work`), `scale` and `options`.
9818
+ `group` (`family`, `work` or `anime`), `scale` and `options`.
9681
9819
 
9682
9820
  ```js
9683
9821
  const family = ['man', 'woman', 'girl', 'grandma'].map((name) => character(castMember(name, 280)))
9684
9822
  ```
9685
9823
 
9824
+ ### Colour anime cast
9825
+
9826
+ `ANIME_CAST` contains eight editable presets, also included in `CHARACTER_CAST`:
9827
+ `animeBoy`, `animeGirl`, `animeYoungMan`, `animeYoungWoman`, `animeMan`,
9828
+ `animeWoman`, `animeOlderMan`, and `animeOlderWoman`. Children use shorter
9829
+ limbs and a larger head; older adults use grey hair and subtle face creases.
9830
+ All presets use the same human rig, so existing expressions, acting,
9831
+ hand gestures, gaits, dance, and full head/body turns work with them.
9832
+ The looks are starting points: any hair, outfit, iris colour or build can be changed.
9833
+
9834
+ ```js
9835
+ const young = character(castMember('animeYoungWoman', 300))
9836
+ drawCharacter(ctx, young, humanPose({ ...HUMAN_EXPRESSIONS.surprised, turn: 0.5 }))
9837
+ const older = character(castMember('animeOlderMan', 300, {
9838
+ face: { style: 'anime', iris: '#94713e', lashes: false, ageLines: 0.6 }
9839
+ }))
9840
+ ```
9841
+
9842
+ For any character, `face: { style: 'anime' }` draws almond-shaped eyes with
9843
+ coloured irises and highlights. `iris` sets their colour (default `#4b7fce`),
9844
+ `lashes` enables outer lashes (default true), and `ageLines` sets subtle eye
9845
+ and smile creases from 0 to 1 (default 0). `style: 'simple'` is the original
9846
+ face and remains the default. Face style is separate from the pen's `look`
9847
+ (`clean`, `pencil`, or `silhouette`); `look: 'anime'` is not a pen style.
9848
+
9849
+ The existing `eye.left`, `eye.right`, `blink`, `lookX`, `lookY`, `pupil`, `lid`,
9850
+ `bulge`, brows and mouth fields animate both styles. The coloured eye opening
9851
+ narrows with the lids; blink or a fully lowered lid closes it. Far-side eyes
9852
+ hide in profile and all face features hide from behind. The style and colours
9853
+ are plain JSON; `face.inPupil` remains an optional drawing hook for custom content.
9854
+ `castMember` changes replace option objects such as `face` or `outfit` as a whole.
9855
+
9856
+ The **Colour Anime Cast** example shows all eight presets, expressions,
9857
+ face close-ups and a complete turnaround. Both the Character and 3D Scene
9858
+ editors offer these presets in their Cast picker. The Character editor also
9859
+ has Face style, Iris colour, Eyelashes and Age creases controls, saved in project JSON.
9860
+
9686
9861
  ## Hugs, help-ups and everyday cycles
9687
9862
 
9688
9863
  Two people, more than hands: `embrace(a, b)` is a hug. Both turn toward each
@@ -10607,6 +10782,154 @@ renders to video and syncs to music exactly.
10607
10782
 
10608
10783
  Try it on the Examples page: **Dance Floor (Characters)**.
10609
10784
 
10785
+ ## Native character dances, circles and spins
10786
+
10787
+ For v2 characters use `humanDanceFrame(style, beat, basePose)`, with
10788
+ `style` set to `garba`, `garbaThreeClap` or `dandiya`, or a custom `HumanDanceStyle`.
10789
+ These stylised eight-beat routines author limbs in the body's own 3D space,
10790
+ including weight shifts, knee lifts, clap preparation and recovery. `turn`
10791
+ and `roll` stay with the caller, so the same steps work from the front, back
10792
+ or either side. `HUMAN_DANCES` is plain JSON: copy a routine's `keys`,
10793
+ `strikes`, `beats`, `bpm` and `label` to customise it. Keys are ordered by beat,
10794
+ within `[0, beats)`, and loop back to the first key. Sparse keys use the full
10795
+ clip's field union at every beat: a missing value uses the caller's base pose,
10796
+ then the human or hand rest value, then zero for other fields. Both bakers
10797
+ preserve these numeric fields even when first authored at a later key.
10798
+ The frame also contains `contact: { side, start, weight }`: the support side,
10799
+ the absolute integer planting beat, and a weight that is 1 through stance
10800
+ and fades smoothly to 0 before the next beat. `strike` is 1 at a clap or
10801
+ stick-strike beat and fades linearly to 0 a quarter beat either side. Foot plants
10802
+ assume left/right alternation at each integer beat, starting with the left
10803
+ foot, and stance through 0.6 of each beat. Custom keys do not change this
10804
+ contact pattern. For hops, longer stances or reversed support, set
10805
+ `plantFeet: false` and supply your own contacts with `plantDanceFoot`.
10806
+
10807
+ ```js
10808
+ import { character, drawCharacter, humanDanceFrame, humanDanceTracks, danceCircleAt, danceCircleTracks } from '@algorisys/tinyfly/characters'
10809
+
10810
+ const who = character({ height: 220, hands: 'cartoon', handStyle: 'natural' })
10811
+ const frame = humanDanceFrame('garba', time * 120 / 60000, { turn: 2 })
10812
+ drawCharacter(ctx, who, frame.pose) // back view, without mirroring the step
10813
+
10814
+ const tracks = humanDanceTracks('dancer', { style: 'garba', bpm: 120, beats: 8 })
10815
+ // Ordinary JSON keyframes; turn/roll tracks can animate independently.
10816
+
10817
+ const members = danceCircleAt(time * 120 / 60000, {
10818
+ radius: 1.8, count: 8, beatsPerTurn: 32, facing: 'inward', style: 'garba',
10819
+ })
10820
+ // Each member: character, pose, position [x,y,z], heading (degrees), strike,
10821
+ // planted. Heading is already included in pose.turn for direct drawing.
10822
+
10823
+ const circleTracks = danceCircleTracks(['stage/a', 'stage/b'], {
10824
+ radius: 1.8, beatsPerTurn: 32, beats: 32, bpm: 120,
10825
+ })
10826
+ // Scene tracks: x/y/z, rotateY, and local pose fields; no doubled pose.turn.
10827
+ ```
10828
+
10829
+ `humanDanceTracks(target, { style, bpm?, beats?, start?, pose?, samplesPerBeat? })`
10830
+ defaults to the style's tempo and beat count, `start: 0` ms, `HUMAN_REST`
10831
+ and 16 samples per beat. It samples from beat 0 through `beats`, with
10832
+ linear JSON keys at `start + beat * 60000 / bpm`; between samples playback
10833
+ approximates the smoothly interpolated frame. It omits `turn`, `roll` and
10834
+ fields that stay at the supplied base/rest value. Give the target the same
10835
+ base pose, since omitted fields are not reset. Hand fields are included;
10836
+ use a hand rig to display them or filter `hand.*` tracks for dot hands.
10837
+
10838
+ Circle positions use `center: [x,z]`, `radius`, initial `angle` (degrees),
10839
+ `direction: 1 | -1`, and equal spacing. Facing can be `inward`, `outward`,
10840
+ `tangent`, or a fixed numeric heading. `spins` adds independent body turns
10841
+ per orbit, including negative or fractional turns. Defaults are
10842
+ `center: [0,0]`, `count: 8`, `beatsPerTurn: 32`, `angle: 0`, `direction: 1`
10843
+ (clockwise viewed from above), `facing: 'inward'`, `spins: 0`, `style: 'garba'`
10844
+ and `plantFeet: true`; `radius` must be positive. At angle 0 the first
10845
+ dancer stands along +z; heading 0 faces +z, 90 faces +x.
10846
+ Height and placement use the same units (default 1.7 metres).
10847
+ `danceCircleTracks(targets, options)` requires `beats`, takes its member
10848
+ count from `targets.length`, and defaults to 120 BPM, `start: 0` ms and
10849
+ 16 samples per beat, even when a custom style has a different tempo.
10850
+ Its linear keys omit unchanged base/rest pose fields but always include
10851
+ world placement; give the rendered characters the same base pose and build.
10852
+ With zero roll, circle bakes put heading in object `rotateY` (degrees) and
10853
+ omit pose `turn`; start with neutral object rotation and pose `turn: 0`.
10854
+ With a nonzero `pose.roll`, they instead bake heading into pose `turn`
10855
+ (quarter-turns), include the supplied `roll`, and write `rotateY: 0`. This
10856
+ keeps native yaw before roll, including its grounding and foot contacts.
10857
+ Apply these tracks together and do not add the same heading as object yaw.
10858
+ Set roll in the bake options so the contact solver uses that roll too.
10859
+ Use `character: who` for a custom build. Support toes are held at their
10860
+ planting point through the first 0.6 beat, then released smoothly;
10861
+ `plantFeet: false` disables this. `planted: false` also reports an unreachable
10862
+ plant, a releasing stance, or disabled planting. Keep travel per step within
10863
+ leg reach. To close a loop, use complete orbits and routines, an even number
10864
+ of beats for the alternating contacts, and a whole number of extra body
10865
+ revolutions (`spins * orbits`). Fractional spins can require multiple orbits
10866
+ to close. Run the video loop check for the whole scene.
10867
+
10868
+ For a custom path or pivot, `plantDanceFoot({ character, pose, position },
10869
+ side, worldPoint, 'toe' | 'ankle')` returns the adjusted **pose and position**
10870
+ and a `reached` flag. Apply both outputs: the vertical position correction
10871
+ transfers weight to the supporting leg. It does not translate sideways to
10872
+ hide an unreachable target. The default point is `toe`; `reached` means
10873
+ the joint is within 0.002 times the character height of the target.
10874
+ `danceJoint(partner, chain, joint)` reads a world-space joint with pose yaw,
10875
+ roll, grounding and position applied: arm index 2 is the wrist, leg index 2
10876
+ the ankle, and leg index 3 the toe. Include heading in `pose.turn`
10877
+ (quarter-turns); these contact helpers do not read scene object rotations.
10878
+ Foot IK preserves authored `leg.left.rotate` and
10879
+ `leg.right.rotate` hip turn-out when placing either ankle or toe, including
10880
+ straight-leg contacts at full reach.
10881
+
10882
+ For partner dandiya use `meetDandiya(a, b, { sideA, sideB, point, length })`,
10883
+ where each partner has `{ character, pose, position: [x,y,z] }`. Both grips
10884
+ and stick tips are solved in world space. It returns `a`/`b` poses, two
10885
+ `sticks` (`grip` → `tip` segments), the shared `point`, and `reached`. Defaults:
10886
+ right hands, chest-height contact, stick length 0.22 of the shorter height.
10887
+ The default point is halfway between the partners in x/z and at the higher
10888
+ position y plus 0.62 times the shorter height. `reached` means both tips
10889
+ are within 0.002 times that height of the point; inspect it before applying
10890
+ an unreachable solve. Neither partner's position changes. The returned
10891
+ poses set the selected hands to the `hold` shape. Dandiya frames and circle
10892
+ bakes supply choreography, not stick geometry or automatic partner IK;
10893
+ call `meetDandiya` and draw its segments yourself.
10894
+ Blend strike poses with `humanDanceFrame('dandiya', beat).pose` between hits,
10895
+ using its `strike` envelope; draw the returned sticks at each arm's depth.
10896
+ Construct the contact character from the same options as the rendered dancers,
10897
+ including height, head size, figure, limb proportions, line width and hands.
10898
+ The festive live and headless examples use `character(people[0])` so their
10899
+ solver and displayed bodies share the same geometry.
10900
+
10901
+ In a 3D beat script, use `{ do: 'dance', dance: 'garba', bpm: 120, beats: 8 }`
10902
+ and `{ do: 'spin', turns: 2, for: 1500 }`. Spin preserves the full signed
10903
+ rotation, unlike `face`, which deliberately chooses the shortest route.
10904
+ `spin` starts from the current heading, defaults to one positive revolution
10905
+ over 1000 ms, and turns at constant angular speed; negative and fractional
10906
+ `turns` are allowed. `dance` defaults to the style's BPM and one routine.
10907
+ With only `for`, its beat count is `for * bpm / 60000`; with both `beats`
10908
+ and `for`, that many beats are fitted into `for` ms, overriding the tempo.
10909
+ The script dances in place: use circle helpers for travel and foot plants.
10910
+ `at` must be finite and non-negative; `for`, `bpm` and `beats` must be
10911
+ finite and positive, and `turns` must be finite. Invalid beats are reported
10912
+ by `checkCharacterBeats3D` and rejected by `characterScript3D`.
10913
+ `face` honors an explicit `for` duration even when already facing the target.
10914
+ Scripted dances blend in for up to 150 ms within their duration, preserving
10915
+ a preceding hold, including relaxed hands. Missing hand fields use `HAND_REST`
10916
+ for both the start anchor and entry blend; explicit values, including zero,
10917
+ are preserved. Hand pose transitions use the same rest fallback.
10918
+ Unchanged action-start anchors preserve the preceding
10919
+ transition's endpoint easing; the next action keeps its own easing.
10920
+ Circle track `count`, when given, must match the target count.
10921
+ Garba, three-clap garba and dandiya are also in the editor's Character and
10922
+ 3D Scene dance menus. The Character menu follows the audio's beat grid.
10923
+ Native styles offer a whole routine, without individual moves; their tracks
10924
+ do not replace existing view or spin tracks. The Character menu keys hands
10925
+ only with Cartoon gloves or Natural hands. The 3D Scene menu uses the style's
10926
+ default tempo and omits hand tracks.
10927
+
10928
+ See `examples/headless-video/garba-circle.mjs` for a complete looping scene.
10929
+ The Examples page also includes **Navratri: Festive Garba & Dandiya**, with
10930
+ festive clothing, larger decorated sticks, partner strikes and half/full
10931
+ spins. Render `examples/headless-video/festive-dandiya.mjs` for its video.
10932
+
10610
10933
  ![Every dance style's moves and every flip](model-sheet/dance-and-flips.png)
10611
10934
 
10612
10935
  The sheet is `examples/headless-video/dance-sheet.mjs`.
@@ -10842,7 +11165,8 @@ move (or the whole routine) and a tempo, then **🕺 Dance from playhead**. Or
10842
11165
  pick a flip and **🤸 Flip at playhead**. Both write ordinary keyframes, a few
10843
11166
  a beat, and keep the character's keys before and after. Glides and the
10844
11167
  moonwalk also write an `x` track from where the character stands. A character
10845
- facing left (the *Side (left)* view) dances the mirror image (`mirrorHumanPose()`:
11168
+ using a converted stick-figure style and facing left (the *Side (left)* view)
11169
+ dances the mirror image (`mirrorHumanPose()`:
10846
11170
  sides swap, it turns, tips and rolls the other way) and glides the other way;
10847
11171
  it turns between 3 (side-on, facing left) and 4 (front-on), never round the
10848
11172
  back. With **Hands:
@@ -11242,7 +11566,8 @@ A character faces +z before any turn and stands on its object's ground: its
11242
11566
  lowest point at the object's y, so at y 0 it stands on a floor at y 0. Its
11243
11567
  pose fields are tracks on its object, next to `x`, `rotateY` and the rest:
11244
11568
  `stage/tum` `arm.right.spread`, `stage/tum` `turn`. Every dance and flip
11245
- plays in 3D: `stickToHuman(danceFrame(style, beat))` gives the pose, and
11569
+ plays in 3D: `const frame = danceFrame(style, beat)` followed by
11570
+ `stickToHuman(frame.pose, frame.hands)` gives the pose, and
11246
11571
  `mirrorHumanPose()` its mirror image for a partner. Its `turn`, `roll`,
11247
11572
  `lift` and ground contact behave as they do front-on; seen front-on through a
11248
11573
  flat camera, a character is exactly the 2D figure.
@@ -11250,6 +11575,25 @@ flat camera, a character is exactly the 2D figure.
11250
11575
  **Walking in metres.** `characterScript3D(id, beats, { scene, position, heading, height })`
11251
11576
  scripts a character in world metres, as `propScript3D` does props:
11252
11577
 
11578
+ It also accepts `{ do: 'spin', turns: 2, for: 1500 }` (signed full turns,
11579
+ linear angular motion) and `{ do: 'dance', dance: 'garba', bpm: 120, beats: 8 }`.
11580
+ `face` still takes the shortest turn and can use `for` to set its duration.
11581
+ An explicit duration is consumed even when no turn is needed. `spin`
11582
+ defaults to one revolution over 1000 ms; negative or fractional `turns`
11583
+ are allowed. A native `dance` stays in place, using the style's tempo and
11584
+ beat count by default. With only `for`, beats follow the BPM; with both
11585
+ `beats` and `for`, those beats are fitted into that duration.
11586
+ For circle formations with planted toes and independent facing/spins use
11587
+ `danceCircleTracks(['stage/a', 'stage/b'], { radius: 1.8, beatsPerTurn: 32,
11588
+ beats: 32, bpm: 120 })`. These write ordinary world-position, `rotateY` and
11589
+ native pose tracks. For nonzero `pose.roll`, heading uses pose `turn`
11590
+ (quarter-turns) with `rotateY: 0`, preserving native yaw before roll and
11591
+ grounding. Supply roll when baking and apply all returned tracks together.
11592
+ Use the same character build and base pose for baking and rendering; omitted
11593
+ base/rest fields are not reset. Partner stick contacts require `meetDandiya`
11594
+ and drawing its returned segments separately.
11595
+ See [Native character dances](dance.md#native-character-dances-circles-and-spins).
11596
+
11253
11597
  ```js
11254
11598
  import { characterScript3D } from '@algorisys/tinyfly/characters'
11255
11599
 
@@ -11881,6 +12225,8 @@ The project uses a separate OSS (Open Source Software) repository for public rel
11881
12225
  Files listed in `.ossignore` are excluded from OSS publishing:
11882
12226
  - `scripts/` - Internal publishing scripts
11883
12227
  - `CLAUDE.md` - Internal AI instructions
12228
+ - `.no-mistakes.yaml` - Internal release validation configuration (Codex reviewer,
12229
+ tests with two workers, and the TypeScript check)
11884
12230
 
11885
12231
  ### Publishing Process
11886
12232
 
@@ -13926,7 +14272,7 @@ magnet.addEventListener('pointerleave', () => {
13926
14272
 
13927
14273
  <!-- capabilities: generated from the library -->
13928
14274
 
13929
- # tinyfly capabilities (v0.102.0)
14275
+ # tinyfly capabilities (v0.104.0)
13930
14276
 
13931
14277
  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).
13932
14278
 
@@ -14149,7 +14495,7 @@ A prop is a 3D rig of simple parts drawn with the characters’ pens (clean, pen
14149
14495
  - `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
14150
14496
  - `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
14151
14497
  - `{ 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
14152
- - `characterScript3D(id, beats, { scene, position?, heading?, height?, pose? })`: a v2 character in a 3D scene in world metres: gaits to [x, z] or through points (its walk phase keyed with the distance), face, hold, pose, gag; checkCharacterBeats3D checks the beats
14498
+ - `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
14153
14499
  - `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)
14154
14500
  - `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
14155
14501
  - `propPreset(name, options?)`: a prop preset by name (did-you-mean on a wrong one)
@@ -14203,6 +14549,7 @@ Scenery: `scenery({ x, y, width, height, kind: sky | room, hour, clouds, wind, r
14203
14549
  ## Character (v2 human)
14204
14550
 
14205
14551
  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`.
14552
+ 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.
14206
14553
 
14207
14554
  Appearance options of `character({ … })`, all plain data that turns with the head (see docs/character-appearance.md):
14208
14555
 
@@ -14211,8 +14558,9 @@ Appearance options of `character({ … })`, all plain data that turns with the h
14211
14558
  - `facialHair`: `cleanShaven`, `stubble`, `pencilMoustache`, `shortMoustache`, `chevron`, `handlebar`, `walrus`, `goatee`, `vanDyke`, `circleBeard`, `shortBoxed`, `fullBeard`, `longBeard`, `roundedBeard`, `pointedBeard`, `chinStrap`, `soulPatch`, `sideburns`, `muttonChops`, `moustacheStubble`
14212
14559
  - `glasses`: `round`, `square`, `sunglasses`; `hat`: `cap`, `beanie`, `hardHat`, `sunHat`, `bowler`; `ears: true`; `face: { teeth, tongue }` (shown when the mouth opens); `feet`: `round`, `flat`, `pointed`, `big`
14213
14560
  - `outfit`: `{ shirt, trousers, sleeves: short | long | none, bottom: trousers | shorts | skirt, collar, tie: colour, over: apron | labCoat | hoodie | cardigan | overalls | sari, overColor, shoes: boots, shoeColor }`
14214
- - `castMember(name, height)`: `boy`, `girl`, `youngMan`, `youngWoman`, `man`, `woman`, `grandpa`, `grandma`, `doctor`, `cook`, `builder`, `courier`, `teacher`, `farmer`
14561
+ - `castMember(name, height)`: `boy`, `girl`, `youngMan`, `youngWoman`, `man`, `woman`, `grandpa`, `grandma`, `doctor`, `cook`, `builder`, `courier`, `teacher`, `farmer`, `animeBoy`, `animeGirl`, `animeYoungMan`, `animeYoungWoman`, `animeMan`, `animeWoman`, `animeOlderMan`, `animeOlderWoman`
14215
14562
  - Face marks (pose fields, 0–1): `blush`, `tears`, `sweat`; close-up fields `pupil` (size, 1 usual), `lid` (upper lids lowered, 0–1), `bulge` (eyes out of the head, 0–1); `face: { nose: true, inPupil(ctx, pupil) }`; `drawCharacterHead(ctx, who, pose, { x, y, radius })` draws just the head big
14563
+ - Face styles: `simple`, `anime`; `face: { style: 'anime', iris: '#4b7fce', lashes: true, ageLines: 0.8 }` uses coloured eyes and the same expressions, blinks and gaze. `ANIME_CAST` contains eight age presets, also available through `castMember`.
14216
14564
  - Hair in motion (pose fields): `hair.swing` (degrees round the head, + toward its left), `hair.trail` (head radii back), `hair.lift` (head radii up); key them with `hairFollowTracks(target, tracks, who)` after the character's tracks, or `hairFollow` + `hairMotionAt` when posing per frame
14217
14565
  - `holding`: `mug` (left or right), `phone` (left or right), `book` (one hand or both), `bag` (left or right), `briefcase` (left or right), `umbrella` (left or right), `broom` (left or right), `cane` (left or right), `parcel` (both); pose fields `held.left`, `held.right`, `held.both` (below 0.5 lets go); `handGrip(joints, side)`
14218
14566
  - `meetHands(kind, a, b)` (stand them `meetingSpacing(kind, a, b)` apart): `handshake`, `highFive`, `fistBump`, `handOver`; `embrace(a, b)` (a hug, `embraceSpacing` apart); `helpUp(helper, sitter, progress)` (0 on the floor, hand taken; 1 standing; `helpUpSpacing` apart)