@algorisys/tinyfly 0.107.1 → 0.109.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 (50) hide show
  1. package/README.md +22 -12
  2. package/docs/character-appearance.md +148 -0
  3. package/docs/cricket.md +127 -0
  4. package/docs/editor-guide.md +1 -1
  5. package/docs/examples.md +1 -1
  6. package/docs/getting-started.md +1 -1
  7. package/docs/gsap-compat.md +1 -1
  8. package/docs/llm-guide.md +58 -0
  9. package/docs/maps.md +2 -2
  10. package/docs/teaching.md +1 -1
  11. package/lib/addons/characters.js +4674 -8156
  12. package/lib/addons/cricket-camera-BWByoNgz.js +4205 -0
  13. package/lib/addons/scene-3d.js +436 -540
  14. package/lib/addons/shots-DR_ViiAC.js +125 -0
  15. package/lib/addons/sports.js +390 -0
  16. package/lib/browser/tinyfly.iife.js +14 -14
  17. package/lib/browser/tinyfly.js +9334 -8322
  18. package/lib/browser/tinyfly.umd.js +14 -14
  19. package/lib/types/browser/index.d.ts +1 -0
  20. package/lib/types/characters/body/organic-body.d.ts +56 -0
  21. package/lib/types/characters/body/organic-draw.d.ts +5 -0
  22. package/lib/types/characters/body/organic-geometry.d.ts +25 -0
  23. package/lib/types/characters/capabilities.d.ts +14 -0
  24. package/lib/types/characters/character.d.ts +15 -2
  25. package/lib/types/characters/hands/draw-cartoon-hand.d.ts +4 -0
  26. package/lib/types/characters/head/face.d.ts +6 -4
  27. package/lib/types/characters/head/facial-hair.d.ts +2 -0
  28. package/lib/types/characters/head/glasses.d.ts +2 -0
  29. package/lib/types/characters/head/head-look.d.ts +4 -2
  30. package/lib/types/characters/head/head-shape.d.ts +4 -0
  31. package/lib/types/characters/index.d.ts +5 -0
  32. package/lib/types/characters/look/pen.d.ts +1 -0
  33. package/lib/types/characters/look/skin-shading.d.ts +4 -0
  34. package/lib/types/characters/rig/skeleton.d.ts +2 -0
  35. package/lib/types/characters/soft-cartoon-cast.d.ts +166 -0
  36. package/lib/types/characters/wardrobe/basic-outfit.d.ts +5 -1
  37. package/lib/types/characters/wardrobe/leaf-outfit.d.ts +18 -0
  38. package/lib/types/characters/wardrobe/outfit-preset.d.ts +6 -0
  39. package/lib/types/sports/ball-flight.d.ts +22 -0
  40. package/lib/types/sports/cricket/cricket-action.d.ts +7 -0
  41. package/lib/types/sports/cricket/cricket-camera.d.ts +13 -0
  42. package/lib/types/sports/cricket/cricket-field.d.ts +13 -0
  43. package/lib/types/sports/cricket/cricket-motion.d.ts +36 -0
  44. package/lib/types/sports/cricket/cricket-types.d.ts +84 -0
  45. package/lib/types/sports/cricket/index.d.ts +5 -0
  46. package/lib/types/sports/index.d.ts +3 -0
  47. package/llms-full.txt +377 -9
  48. package/llms.txt +30 -29
  49. package/package.json +5 -1
  50. package/skills/tinyfly/SKILL.md +49 -0
package/README.md CHANGED
@@ -54,6 +54,11 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
54
54
  - **Code-drawn targets** - A `custom` canvas target draws with code (characters, charts, props) while the timeline animates its position, opacity and its own `props`, so drawing stays code and timing stays JSON
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
+ - **Cricket stories** - Public `@algorisys/tinyfly/sports` builders create an organic adult/child cast, standard pitch, full fielding side, wickets and boundary. Sixteen authored plays cover deliveries, strokes, running, boundaries, catches, fielding, throws, dismissals, no-balls and wides for Test, ODI and T20. Exact contact keys, captions and results are JSON; eight camera views include a 360° ground orbit and ball follow. Try [Cricket Stories](https://tinyfly.app/examples/live-cricket-story), download its scene/action/camera JSON, or render the headless example. See [the cricket guide](docs/cricket.md).
58
+ Wide camera clipping scales for boundaries up to 250 m, and ball-follow generation reads only ball channels. Local full-page previews include add-ons before publication; copied pages keep their versioned CDN bundles.
59
+ Defensive blocks meet the blade with both hands on the bat. Keeper-bound deliveries pass outside the off stump with clearance for the displayed ball before collection.
60
+
61
+ - **Soft cartoon story characters** - Opt-in `figure: 'organic'` adds filled shoulders, chest/waist/hip contours, supple limbs, small posed hands and deterministic cel shading on the existing rig. JSON body profiles keep anatomy independent of outline width; one skin colour covers body, face and hands under scene lighting and fog, and cel shading respects inherited opacity. Foreground arms stay over waist garments in 2D and globally sorted 3D scenes, with only foreground arms promoted to garment depths so leaning head, neck, torso and legs retain world-object occlusion. Transparent organic skin keeps exposed body, head and both hand variants outline-only in every look. Editor Skin and Line controls resolve and edit imported body colour overrides. Leaf garment options are validated and copied at construction. Actor names are checked at runtime, and each head contour is reused for filling, shading and face clipping within a draw. Editable adult and child `softCartoonCharacter` presets, flowing hair, editable everyday/formal/casual/leaf clothing and the existing script, reach and lip-sync APIs support original stories. Try [**Soft Cartoon Characters**](https://tinyfly.app/examples/live-organic-characters): adults, children or an adult and child, with seven actions, face/hair controls and independent outfit editing. `outfitPreset()` supplies JSON wardrobe defaults; shirts, T-shirts, blouses, dresses, trousers, jeans, cargo, shorts, skirts, sleeves, collars, ties and colours remain editable. See [the appearance guide](docs/character-appearance.md).
57
62
  - **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**: 41 hairstyles, including soft sweeps, flowing bobs and cascading waves with scalp-attached curved locks and individual flexibility, 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
63
  - **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
64
  - **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
@@ -228,6 +233,7 @@ for what you import:
228
233
  | `@algorisys/tinyfly/maps` | Animated maps: OpenStreetMap tiles or an offline world outline, places, routes that draw on, a camera that flies (`mapTarget`, `mapFlyTracks`, `fitView`, `WORLD_CITIES`) | Anywhere with a Canvas 2D context (tiles need a network) |
229
234
  | `@algorisys/tinyfly/characters` | Poseable stick figure: `stickFigureTarget`, `poseTracks`, `POSES`, `blendPose`, `walkPose`, `drawStickFigure`; `stickFigureJoints` and `layers` for costumes, hair and props; `turn`, `sit` and ground contact; an organic look by default (`classic` keeps the old one); **characters v2**: `character()` / `characterTarget()`, turnarounds front to back, contact, reaching, clean / pencil / silhouette looks; `hair`, `facialHair`, `glasses`, `hat`, `ears`, `face`, `feet`, `build`, `outfit` as data, `castMember()`, `HUMAN_EXPRESSIONS` with face marks; `embrace`, `helpUp`, `scenery` | Anywhere with a Canvas 2D context |
230
235
  | `@algorisys/tinyfly/headless` | `renderVideo`, `renderStills`, `FrameRenderer`: render a scene to MP4 or PNGs (see [Rendering Video from Code](docs/video-rendering.md)) | Node (`@napi-rs/canvas` optional peer, ffmpeg) |
236
+ | `@algorisys/tinyfly/sports` | `cricketPlayer`, `cricketField`, `cricketAction`, `cricketClip`, `cricketCameraTracks`, `cricketEventAt`, shared `ballFlightTracks`; authored organic cricket stories and a 360° ground camera | Browser, Worker, Node; scene rendering through adapters |
231
237
  | `@algorisys/tinyfly/browser` | One script-tag bundle (`tinyfly.iife.js`): the engine, player, drivers, interaction, the GSAP-style `live` / `tf` facades, teaching-embed controls and mounting, and the `characters` stick figure. Not included: `export`, `adapters`, `teach`, the framework hooks, `headless` | Browser |
232
238
 
233
239
  ```js
@@ -274,7 +280,7 @@ GSAP-shaped functions at the top level. Teaching embeds are included: add
274
280
  itself.
275
281
 
276
282
  ```html
277
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.1/cdn/tinyfly.iife.js"></script>
283
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.109.0/cdn/tinyfly.iife.js"></script>
278
284
  <script>
279
285
  tinyfly.to('.box', { x: 200, rotate: 90, duration: 1, ease: 'power2.out' })
280
286
 
@@ -310,7 +316,7 @@ A teaching figure needs no code at all:
310
316
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON with markers… }</script>
311
317
  <figcaption>Appending to a full slice</figcaption>
312
318
  </figure>
313
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.1/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
319
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.109.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
314
320
  ```
315
321
 
316
322
  See [Teaching Animations](docs/teaching.md).
@@ -409,7 +415,7 @@ Without a build step, the player bundle puts the same functions on a `tinyfly` g
409
415
  <div data-tinyfly="box" style="width: 60px; height: 60px; background: #4a9eff;"></div>
410
416
  </div>
411
417
 
412
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.1/cdn/tinyfly-player.iife.js"></script>
418
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.109.0/cdn/tinyfly-player.iife.js"></script>
413
419
  <script>
414
420
  tinyfly.play('#animation', './animation.json', { loop: -1 })
415
421
  </script>
@@ -518,7 +524,7 @@ Or skip the code entirely with declarative embeds (see [Teaching Animations](doc
518
524
  <svg viewBox="0 0 720 200">…</svg>
519
525
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON… }</script>
520
526
  </figure>
521
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.1/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
527
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.109.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
522
528
  ```
523
529
 
524
530
  ### Audio / Video Sync
@@ -762,7 +768,7 @@ npm run build
762
768
  ```
763
769
 
764
770
  The private repository's `.no-mistakes.yaml` selects the Codex reviewer and
765
- uses `npm run test:run -- --maxWorkers 2` for tests and
771
+ builds the add-on bundles before `npm run test:run -- --maxWorkers 2` for tests and
766
772
  `npx tsc -p tsconfig.app.json --noEmit` for its lint/type check.
767
773
  It is excluded from the OSS mirror; the project needs no runtime configuration
768
774
  for this validation.
@@ -808,20 +814,24 @@ load.
808
814
 
809
815
  ### Test Coverage
810
816
 
811
- `npm test` runs 2,197 unit tests in 127 files, all passing:
817
+ `npm test` runs 3,610 unit tests in 234 files, all passing. The Organic
818
+ Characters browser suite checks 74 desktop/mobile scenarios per browser.
812
819
 
813
820
  | Area | Tests |
814
821
  |---|---|
815
- | Engine (`src/engine`: timeline, easing, paths, text, exports, serialization) | 521 |
816
- | Editor (`src/editor`: stores, utils, presets, AI, samples) | 409 |
817
- | GSAP-style API (`src/compat/gsap`) | 332 |
818
- | Examples page, GSAP-style demos and showcases (`src/examples`) | 302 |
819
- | Render adapters (`src/adapters`) | 134 |
822
+ | Engine (`src/engine`: timeline, easing, paths, text, exports, serialization) | 601 |
823
+ | Editor (`src/editor`: stores, utils, presets, AI, samples) | 600 |
824
+ | GSAP-style API (`src/compat/gsap`) | 335 |
825
+ | Examples page, GSAP-style demos and showcases (`src/examples`) | 436 |
826
+ | Render adapters (`src/adapters`) | 197 |
827
+ | Characters, maps and 3D scenes (`src/characters`, `src/maps`, `src/scene-3d`) | 865 |
820
828
  | Interactive course (`src/learn`) | 211 |
821
829
  | Drivers and interaction (`src/drivers`, `src/interaction`) | 136 |
822
830
  | Player, media sync, sequencer, teaching and scenarios (`src/player`) | 103 |
823
- | Docs viewer and `llms.txt` (`src/docs`) | 16 |
831
+ | Docs viewer and `llms.txt` (`src/docs`) | 18 |
824
832
  | Embeds, teaching kit, framework hooks, landing (`src/embed`, `src/teach`, `src/frameworks`, `src/landing`) | 33 |
833
+ | Headless rendering and audio (`src/headless`) | 63 |
834
+ | Entry boundaries | 2 |
825
835
 
826
836
  ## Contributing
827
837
 
@@ -35,6 +35,147 @@ drawCharacter(ctx, maya, humanPose({ ...HUMAN_EXPRESSIONS.embarrassed, turn: 0.5
35
35
  A plain figure (no `hair`, `facialHair`, `glasses`, `hat` or `ears`) draws
36
36
  exactly as it did before these options existed.
37
37
 
38
+ ## Organic cartoon bodies
39
+
40
+ Use `figure: 'organic'` for original, softly drawn story characters. The
41
+ existing human skeleton controls poses, reaching, ground contact and part
42
+ order. Filled contours supply shoulders, chest, waist, hips and shaped
43
+ limbs; dimensions are independent of the outline width.
44
+
45
+ ```js
46
+ import { character, softCartoonCharacter, characterScript, hairFollowTracks } from '@algorisys/tinyfly/characters'
47
+
48
+ const actor = character({
49
+ figure: 'organic', height: 320, skin: '#efbd96',
50
+ body: {
51
+ arm: [{ at: 0, width: 0.028 }, { at: 0.5, width: 0.018 },
52
+ { at: 0.7, width: 0.023 }, { at: 1, width: 0.012 }],
53
+ outline: { color: '#53372d', width: 1.5 },
54
+ shading: { mode: 'cel', light: [-0.8, -0.6], opacity: 0.17 },
55
+ },
56
+ face: { style: 'anime', shape: 'angular', jawRoundness: 1 },
57
+ hair: { style: 'flowingBob', color: '#38291f' },
58
+ outfit: { shirt: '#72958b', trousers: '#495a67' },
59
+ })
60
+ const friend = softCartoonCharacter('youngWoman', { height: 300 })
61
+ const story = characterScript('actor', actor, [
62
+ { do: 'walk', to: 240, for: 2200 },
63
+ { do: 'say', say: 'Let us explore!', for: 1800, mood: 'happy' },
64
+ ], { from: 60 })
65
+ story.tracks.push(...hairFollowTracks('actor', story.tracks, actor))
66
+ ```
67
+
68
+ `softCartoonCharacter` accepts only `youngMan`, `youngWoman`, `childBoy`
69
+ and `childGirl`; unknown actor names throw an error, including inherited
70
+ object keys such as `constructor`.
71
+
72
+ `body.torso`, `arm`, `leg` and `neck` are arrays of `{ at, width }`.
73
+ `at` increases from 0 to 1; `width` is a half-width fraction of character
74
+ height. Torso positions run hip to neck, arms shoulder to wrist, and legs
75
+ hip to ankle. Cubic centerlines pass through native elbow/knee joints with
76
+ interpolated width profiles. Options are copied at construction and can
77
+ travel as JSON. `body.depth` (0.2–1, default 0.55) sets torso side thickness.
78
+ `body.fill` overrides `skin` for all exposed body, face and palms; omit it
79
+ to keep one `skin` colour control. The editor's Skin and Line controls show
80
+ the resolved fill and outline colour; editing them also updates any existing
81
+ `body.fill` or `body.outline.color` override without changing other body options.
82
+
83
+ Default organic hands are small natural five-finger hands (`handSize: 0.073`).
84
+ Existing `hand.left.*` / `hand.right.*` tracks control palms, fists, pointing,
85
+ bends and wrist rolls. Foreground organic arms and hands draw together after
86
+ the torso and lower garments; rear arms remain behind them. Attached borders at shoulders, hips, wrists and ankles are hidden
87
+ where connected contours meet. This ordering also survives the 3D scene's
88
+ global depth sort, while separate world objects can still occlude the figure.
89
+ `characterPartsInView()` retains each part's physical `depth` and supplies
90
+ an organic `sortDepth` for painter ordering. Only foreground arms are promoted
91
+ to the nearest torso/leg garment depth; head, neck, torso, legs and rear arms
92
+ keep their physical depths. Scene integrations sort by `sortDepth ?? depth`, retaining array
93
+ order for ties. Fluid and stick parts retain their existing depth ordering.
94
+
95
+ Organic faces default to `face.projection: 'volume'`: feature centres follow
96
+ the head's 3D axes, both eyes stay readable in three-quarter views, the far
97
+ eye narrows toward profile, and opaque hair covers
98
+ eyes and brows. Features stay clipped inside the head through turns and nods.
99
+ The facial plane is flatter than the rounded rear cranium in profile.
100
+ With `face.nose: true`, a small nose projects from above the mouth and shapes
101
+ the turned silhouette without extending the chin.
102
+ `projection: 'cartoon'` retains the classic face slide used by fluid/stick.
103
+
104
+ Cel shading is clipped to moving skin in the clean look. `body.shading`
105
+ accepts `mode: 'cel' | 'none'`, screen-space `light: [x, y]`, `shadow`,
106
+ `opacity` and `highlight`. Seeking and headless rendering are deterministic.
107
+ Pencil and silhouette use their existing pens. Artist-authored painted
108
+ meshes remain a separate future capability.
109
+
110
+ Set `body.fill: 'none'` (or `skin: 'none'` without a body fill override) for
111
+ outline-only exposed body, head and hands in every look. Dot and articulated
112
+ hands omit skin fills and shading; clothing retains its own material.
113
+
114
+ Everyday shirts, sleeves, trousers, shorts and skirts follow organic anatomy.
115
+ `leafOutfit: { top: true, color: '#638c39', accent: '#87ae4e', length: 0.32 }`
116
+ selects attached leaf garments with curved shapes and veins; `top: false`
117
+ leaves the upper body uncovered. It requires organic mode.
118
+ `leafOutfitContours(joints, options)` exposes plain coverage geometry for
119
+ custom layers and exporters. Both wardrobes use native part depths.
120
+
121
+ `softCartoonCharacter('childBoy')` and `softCartoonCharacter('childGirl')`
122
+ provide original child presets with a larger head/body ratio, shorter arms
123
+ and legs, rounded torsos and smaller default heights (230 and 225 px).
124
+ All face, hair, clothes, skin and proportions remain editable; changing
125
+ `height` preserves the child anatomy. The same pose, script, hand, reaching
126
+ and lip-sync APIs work for adults and children.
127
+
128
+ The example at `/examples/live-organic-characters` includes adult, child and
129
+ adult/child pairs, face/hair
130
+ choices, independently editable everyday/formal/casual/leaf garments, seven actions, outline and skin controls,
131
+ shading, playback and scrubbing. Available in v0.108.0. See the
132
+ [contact sheet](model-sheet/organic-characters.png) and
133
+ [child character sheet](model-sheet/child-characters.png).
134
+ Close-up [head turns](model-sheet/organic-head-turns.png) exercise independent
135
+ `head.turn` at the story's body orientation.
136
+ `fluid` and `stick` keep their existing defaults and ink-based dimensions.
137
+
138
+ ## Everyday, Formal and Casual clothing
139
+
140
+ `outfitPreset(category, overrides)` returns fresh plain JSON options for
141
+ `character({ outfit })` or `softCartoonCharacter(name, { outfit })`.
142
+ The categories are `everyday`, `formal` and `casual`. Every garment works
143
+ with adult and child actors, regardless of gender.
144
+
145
+ ```js
146
+ import { softCartoonCharacter, outfitPreset } from '@algorisys/tinyfly/characters'
147
+
148
+ const formal = softCartoonCharacter('youngMan', {
149
+ outfit: outfitPreset('formal', { shirt: '#ece6db', trousers: '#354456', tie: '#7b3955' }),
150
+ })
151
+ const casual = softCartoonCharacter('youngWoman', {
152
+ outfit: outfitPreset('casual', { top: 'tshirt', bottom: 'shorts', trouserStyle: 'cargo' }),
153
+ })
154
+ const dress = softCartoonCharacter('childGirl', {
155
+ outfit: outfitPreset('formal', { top: 'dress', shirt: '#aa6b91', sleeves: 'none' }),
156
+ })
157
+ ```
158
+
159
+ - `top`: `tshirt`, `shirt` (button placket), `blouse` (V neckline) or `dress`.
160
+ Omit it to retain the original plain T-shirt. Shirts default to a collar;
161
+ an explicit `collar: false` removes it.
162
+ - `bottom`: `trousers`, `shorts` or `skirt`; `trouserStyle`: `plain`, `jeans`
163
+ (pockets and stitching) or `cargo` (thigh pockets). Details follow the
164
+ limbs and stay clipped inside the fabric.
165
+ - `shirt` and `trousers` remain top and bottom colours. A dress uses
166
+ `shirt` for both its bodice and skirt, overriding `bottom` and ignoring
167
+ the separate bottom colour. `sleeves` accepts `short`, `long` or `none`.
168
+ - `collar` is a boolean; `tie` is a colour or `null` to remove it. Changing a
169
+ formal preset to a different top removes its default collar and tie;
170
+ explicit accessory overrides take precedence.
171
+
172
+ The example's **Edit outfit** choice edits both characters or either actor
173
+ separately. Formal starts with a shirt/tie or blouse/skirt; Casual starts
174
+ with a T-shirt/jeans. All cuts remain selectable for either character.
175
+ The editor exposes the same presets and garment choices, saved with scene
176
+ JSON. [Clothing sheet](model-sheet/clothing-options.png), reproduced by
177
+ `examples/headless-video/clothing-options.mjs`.
178
+
38
179
  ## How it turns
39
180
 
40
181
  Hair, beards and hats are not flat drawings pasted on the face. Each is a
@@ -287,6 +428,13 @@ body part before it draws. Set the canvas clipping path in this hook; it is
287
428
  restored before the part's `over` layers and the next part. The built-in outfit
288
429
  uses this to hide thighs under tops. `joints.parts[id].order` is the resolved
289
430
  far-to-near drawing index; use it when a garment spans several parts.
431
+ Camera-projected joints also provide `bodyForward: [x,y,z]` in view space:
432
+ `z` is front visibility and `x` is the side offset for front details. This
433
+ axis follows the body and camera independently of head yaw. `joints.turn`
434
+ retains the authored body turn; flat drawing omits `bodyForward`, so use
435
+ `cos(turn * Math.PI / 2)` and `sin(turn * Math.PI / 2)` there.
436
+ The built-in wardrobe uses this direction for front buttons, necklines,
437
+ pockets, collars, ties and outer-garment details.
290
438
 
291
439
  ## The cast
292
440
 
@@ -0,0 +1,127 @@
1
+ # Cricket stories
2
+
3
+ Build a cricket scene and a play as JSON with `@algorisys/tinyfly/sports`.
4
+ The same data runs in a browser, Worker or Node. Players use tinyfly's
5
+ existing organic adult and child rig. Try the [interactive cricket example](https://tinyfly.app/examples/live-cricket-story)
6
+ or its [full-page view](https://tinyfly.app/examples/live-cricket-story/full).
7
+
8
+ ```ts
9
+ import { Timeline } from '@algorisys/tinyfly'
10
+ import { cricketClip, cricketCameraTracks, cricketEventAt } from '@algorisys/tinyfly/sports'
11
+ import { characterObjects } from '@algorisys/tinyfly/characters'
12
+ import { loadScene3D, drawScene3D } from '@algorisys/tinyfly/scene-3d'
13
+
14
+ const clip = cricketClip({ format: 't20', action: 'stumping', cast: 'mixed' })
15
+ const tracks = [...clip.timeline.tracks, ...cricketCameraTracks(clip, { view: 'keeper' })]
16
+ const timeline = new Timeline({ ...clip.timeline, tracks })
17
+ const scene = loadScene3D(clip.scene, { kinds: [characterObjects] })
18
+ // Your explicit clock supplies time in milliseconds.
19
+ function draw(ctx, time) {
20
+ drawScene3D(ctx, scene, timeline.getStateAtTime(time).values,
21
+ { width: 1280, height: 720, time })
22
+ const caption = cricketEventAt(clip.events, time)?.caption
23
+ return caption
24
+ }
25
+ const json = JSON.stringify({ ...clip, timeline: { ...clip.timeline, tracks } })
26
+ ```
27
+
28
+ With script tags, load `tinyfly.iife.js` and the scene-3d add-on. Sports builders
29
+ and characters are available on `tinyfly`; scene rendering uses the add-on.
30
+ See [getting started](getting-started.md) for the versioned CDN URLs.
31
+
32
+ ## Builders
33
+
34
+ | API | Result |
35
+ | --- | --- |
36
+ | `cricketPlayer({ id, role, preset?, format?, height?, position?, color?, headwear?, appearance? })` | An owned JSON `character` scene object. Roles: batter, bowler, keeper, fielder, umpire. Presets include youngMan, youngWoman, childBoy, childGirl. |
37
+ | `cricketField({ id?, format?, cast?, boundaryRadius?, battingColor?, fieldingColor? })` | `scene`, `format`, `boundaryRadius`, `landmarks`. A 20.12 × 3.05 metre pitch, standard creases, wickets/bails, two bats, ball, boundary, eleven fielding players, two batters and two umpires. |
38
+ | `cricketAction(field, { action?, duration?, every? })` | A JSON timeline, timed events/captions and declared example result. Does not modify the field. |
39
+ | `cricketClip(options)` | Combines field and action; default T20, adult cast, pace bowling, 6000 ms. |
40
+ | `cricketCameraTracks(clip, { view?, yaw?, every? })` | Ordinary scene camera tracks. Merge these with the action tracks. |
41
+ | `cricketEventAt(events, time)` | Most recent event at that time, including when seeking backward. |
42
+ | `ballFlightPoint(options, time)`, `ballFlightTracks(options)` | Shared sampled arcs for other sports too. `from`, `to`, `arc`, `curve`, `start`, `end`, `target`; exact endpoints. |
43
+
44
+ Units are metres, milliseconds and degrees. `cast` is `adults`, `children` or
45
+ `mixed`; `format` is `test`, `odi` or `t20`. `boundaryRadius` defaults to 64 m
46
+ and accepts 24–250 m. A boundary is venue dependent. Sampling defaults to 40 ms,
47
+ accepts 16–1000 ms and always includes play contact events. Durations accept
48
+ 4000–60000 ms; changing duration scales the whole play. Player height accepts
49
+ 0.5–3 m. Bare heads are the default; optional `headwear` is `none`, `cap` or
50
+ `sun-hat`. Appearance is JSON data, without canvas hooks or rig callbacks.
51
+
52
+ The standard action builder expects the named actors/equipment from
53
+ `cricketField`; required actors must be unparented with no object rotation or
54
+ scale. It owns poses and paths for that layout. Customize appearance and
55
+ uniforms before compiling; author your own scene tracks for a different layout.
56
+
57
+ ## Plays and cameras
58
+
59
+ `CRICKET_ACTIONS` contains sixteen plays:
60
+
61
+ - `bowling`, `spin`: run-up, delivery, bounce and keeper collection.
62
+ - `batting`, `defend`: drive or block with two hands gripping the bat.
63
+ - `running`: batters change ends for one illustrated run.
64
+ - `four`, `six`: grounded boundary or boundary crossed in the air, with signals.
65
+ - `catch`, `fielding`, `throw`: aerial catch, ground collection or return throw.
66
+ - `bowled`, `lbw`, `stumping`, `run-out`: distinct authored dismissal examples.
67
+ - `no-ball`, `wide`: extra, umpire signal and an uncounted delivery.
68
+
69
+ The ball releases from a rendered palm, meets the blade at contact, and follows
70
+ the collecting hand. Bails move after the relevant wicket break. Bats scale
71
+ with child proportions. Events carry `id`, `time`, `kind`, `label`, `caption`;
72
+ the timeline also contains matching markers and English captions.
73
+ Drive and ground-fielding plays use distinct collection positions, with the
74
+ ball and fielder keyed to the same palm contact.
75
+ Defensive blocks retain their downward two-hand bat pose and emit the `contact`
76
+ event with the “Bat contact” label. Pace, spin, no-ball and stumping deliveries
77
+ pass outside the off stump on the side away from the batter, allowing for the
78
+ displayed ball and stump radii before collection. Bowled keeps its intentional
79
+ wicket collision; stumping keeps the later hand-held wicket break.
80
+
81
+ `CRICKET_VIEWS` offers `pitch`, `batter`, `bowler`, `keeper`, `field`, `overhead`,
82
+ `orbit` and `follow-ball`. `yaw` chooses any azimuth; `orbit` adds a complete
83
+ 360° revolution over the play. `CRICKET_CAMERA_ANGLES` provides suggested
84
+ starting angles. Equivalent azimuths such as 0° and 360° use identical geometry.
85
+ The field camera's clipping range scales with the boundary radius so wide views
86
+ include the full supported ground. Following the ball samples only its three
87
+ position channels with forward keyframe cursors, using the requested camera
88
+ spacing without evaluating actor tracks.
89
+
90
+ Development full-page previews load the local browser API and scene add-ons;
91
+ production previews and copied HTML retain the versioned CDN bundles.
92
+
93
+ ## Teaching scope
94
+
95
+ These are authored visual demonstrations. Arcs, the enlarged ball, timings,
96
+ field placements and results are illustrative. The API does not infer a
97
+ cricket decision from collisions, enforce every law, simulate ball physics,
98
+ manage an innings or supply lesson navigation/quizzes. `result` declares
99
+ `runs`, `extras`, `wickets`, `legalBall`, `freeHitNext` and optional `dismissal`.
100
+ Use it with your own tutorial, narration, scoring or lesson system.
101
+
102
+ `CRICKET_FORMATS` records basic Test, ODI and T20 differences. Test has two
103
+ innings per side and no innings over limit; ODI/T20 have one innings per side
104
+ and maximum 50/20 overs respectively. See the [ICC format overview](https://www.icc-cricket.com/about/cricket/game-formats/the-three-formats).
105
+ No-balls and wides each add one extra and do not count as legal over balls.
106
+ The stumping example uses a legal delivery and a batter outside their ground,
107
+ without an attempted run. The LBW caption explicitly leaves a full decision's
108
+ pitching, impact and bat-contact checks to the author. Consult the
109
+ [MCC Laws, 2026 edition](https://www.lords.org/getmedia/a4ef9f77-2a25-4f5b-a286-4601f08e6334/Laws-of-Cricket-2017-Code-4th-Edition-(2026)_5.pdf).
110
+ ODI/T20 no-balls lead to a free hit on the next legitimate delivery; Test
111
+ does not add this automatically. Competition rules and effective dates matter:
112
+ see [ICC playing conditions](https://www.icc-cricket.com/about/cricket/rules-and-regulations/playing-conditions)
113
+ and the [October 2026 changes](https://www.icc-cricket.com/news/key-changes-across-formats-with-new-icc-playing-conditions).
114
+
115
+ ## Headless video
116
+
117
+ After `npm run build:libs`:
118
+
119
+ ```sh
120
+ node bin/tinyfly.mjs video examples/headless-video/cricket-story.mjs --stills /tmp/cricket-story
121
+ node bin/tinyfly.mjs video examples/headless-video/cricket-story.mjs -o /tmp/cricket-story.mp4
122
+ ```
123
+
124
+ The example consumes the same public clip, camera and scene APIs. JSON download
125
+ in the interactive example includes the selected camera tracks, ready to sample
126
+ again after parsing. Other sports can reuse `ballFlightTracks`, character rigs
127
+ and scene cameras; cricket-specific motion remains in the sports add-on.
@@ -1143,7 +1143,7 @@ The dialog shows the generated HTML/JavaScript code with a **Copy Code** button.
1143
1143
  **Steps to embed:**
1144
1144
  1. Build the player: `npm run build:player`
1145
1145
  2. Copy `lib/player/tinyfly-player.iife.js` to your project (or load
1146
- `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.1/cdn/tinyfly-player.iife.js`
1146
+ `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.109.0/cdn/tinyfly-player.iife.js`
1147
1147
  instead; see [Deployment](DEPLOYMENT.md))
1148
1148
  3. Copy the generated code into your HTML
1149
1149
  4. Adjust the script `src` path if needed
package/docs/examples.md CHANGED
@@ -743,7 +743,7 @@ For simple website embedding without a build system.
743
743
  </html>
744
744
  ```
745
745
 
746
- 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.107.1/cdn/tinyfly-player.iife.js`.
746
+ 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.109.0/cdn/tinyfly-player.iife.js`.
747
747
 
748
748
  ---
749
749
 
@@ -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.107.1/cdn/tinyfly.iife.js"></script>
188
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.109.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.107.1/cdn/tinyfly.iife.js"></script>
77
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.109.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
@@ -88,6 +88,58 @@ bakes. See `docs/dance.md`.
88
88
 
89
89
  ## Characters with a look
90
90
 
91
+ For cricket tutorials, import `cricketClip`, `cricketCameraTracks` and
92
+ `cricketEventAt` from `@algorisys/tinyfly/sports`. The clip is an owned scene,
93
+ JSON timeline, timed captions and declared result. Choose `test | odi | t20`,
94
+ `adults | children | mixed`, and a play from `CRICKET_ACTIONS`. Merge camera
95
+ tracks with action tracks; render with scene-3d plus `[characterObjects]`.
96
+ The UI is a consumer of these APIs. `orbit` covers the full ground in 360°;
97
+ `follow-ball` keys against the same ball tracks. Contacts are sampled exactly,
98
+ including two-hand bat grip, release, catch and wicket break. These are authored
99
+ demonstrations, not collision-based umpiring or an innings simulator. Do not
100
+ infer new outcomes from the illustrative arcs. See `docs/cricket.md` and
101
+ `examples/headless-video/cricket-story.mjs`; `/examples/live-cricket-story`
102
+ has event seeking and downloadable scene/action/camera JSON.
103
+ Wide cameras support the full 24–250 m boundary range; equivalent yaw angles
104
+ use identical geometry. Ball-follow cameras sample only ball position channels.
105
+ Render the headless example with `tinyfly video <scene.mjs> -o <output.mp4>`.
106
+ Preserve the defensive block's two-hand blade contact and `contact` event.
107
+ Keeper-bound pace/spin/no-ball/stumping paths clear the off stump with the
108
+ displayed ball radius included, before palm collection. Keep bowled contact
109
+ and the later stumping wicket break intentional when editing these paths.
110
+
111
+ For original soft cartoon story characters, opt into `figure: 'organic'`.
112
+ Its default `face.projection: 'volume'` moves eyes/mouth around the head and
113
+ lets hair occlude them, with a flatter profile facial plane and a nose above
114
+ the mouth; classic `cartoon` projection remains available. Foreground organic
115
+ arms/hands draw together over lower garments, preserving the wrist at the waist.
116
+ `body` owns JSON half-width profiles (`torso`, `arm`, `leg`, `neck`): increasing
117
+ arrays of `{ at: 0..1, width: fractionOfHeight }` spanning 0 to 1. Set `skin`
118
+ once for exposed body, head and hands; `body.fill` overrides it.
119
+ Use `body.fill: 'none'` for outline-only exposed skin, including both hand
120
+ variants in every look. In 3D, only foreground arms use garment depths for
121
+ painter ordering; other organic parts retain physical world-object occlusion.
122
+ `body.outline: { color, width }` is independent of anatomy. Optional
123
+ `body.shading: { mode: 'cel' | 'none', light: [x,y], shadow, opacity, highlight }`
124
+ is deterministic and clipped to skin. Defaults include small natural hands.
125
+ `softCartoonCharacter('youngMan' | 'youngWoman' | 'childBoy' | 'childGirl', options)`
126
+ provides editable original actors; `SOFT_CARTOON_CAST` contains their source
127
+ options. Children default to shorter heights, larger head proportions, shorter
128
+ limbs and rounded torsos. Override `height` to change size while preserving
129
+ their anatomy. Use `outfitPreset('everyday' | 'formal' | 'casual', overrides)`
130
+ for owned JSON wardrobe defaults. `outfit.top` is `tshirt | shirt | blouse |
131
+ dress`; `trouserStyle` is `plain | jeans | cargo`; `shirt` and `trousers`
132
+ remain colour fields. Bottoms are `trousers | shorts | skirt`; sleeves,
133
+ collar and tie colour are editable. Dresses force a skirt in the top colour.
134
+ All garments are available for every actor. `outfit` adapts to organic contours; organic-only `leafOutfit` accepts
135
+ `{ top?, color?, accent?, length? }`. Use the existing `characterScript`,
136
+ `characterPoseTracks`, `reachCharacter`, hand pose and `hairFollowTracks`
137
+ APIs for motion. Avoid a foreground whole-body overlay. An unrigged PNG
138
+ is not a posable character. The interactive example is
139
+ `/examples/live-organic-characters`; a headless study is
140
+ `examples/headless-video/organic-characters.mjs`. Child proportions and poses
141
+ are shown in `examples/headless-video/child-characters.mjs`.
142
+
91
143
  A v2 character's appearance is plain options to `character()`, never drawing
92
144
  code: `build` (`child`, `tall`, `short`…), `hair` (a style name, or
93
145
  `{ style, color, length, … }`), `facialHair`, `glasses`, `hat`, `ears: true`,
@@ -96,6 +148,9 @@ code: `build` (`child`, `tall`, `short`…), `hair` (a style name, or
96
148
  'cardigan' | 'overalls' | 'sari' | 'apron' | 'labCoat', shoes: 'boots' }`.
97
149
  Built-in tops hide thighs and trouser roots under their hem during turns;
98
150
  garments spanning both legs use the resolved body order in camera views too.
151
+ Custom camera-view garment details should use `joints.bodyForward` (view-space
152
+ body axis: `z` front visibility, `x` side offset), independent of head yaw.
153
+ `joints.turn` remains authored; flat joints omit `bodyForward`.
99
154
  For custom clothes, `layers.parts[id].clip` clips only the bare body before
100
155
  `over` draws, and `joints.parts[id].order` gives the drawing index.
101
156
  `castMember('grandpa', 300)` gives a whole ready-made character to start
@@ -294,3 +349,6 @@ new-tab player using the same standalone HTML as Copy code. Live demos,
294
349
  timeline examples and editable sample scenes play with their own controls
295
350
  and scrolling, without the gallery panels. Use these URLs when sharing an
296
351
  example for visual review.
352
+ Development live previews load the local browser API and required add-ons, so
353
+ unpublished APIs work before release. Production previews and copied pages
354
+ keep the versioned CDN URLs.
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.107.1/cdn/tinyfly.iife.js"></script>
18
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.1/cdn/tinyfly-maps.iife.js"></script>
17
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.109.0/cdn/tinyfly.iife.js"></script>
18
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.109.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
package/docs/teaching.md CHANGED
@@ -25,7 +25,7 @@ path for all of that:
25
25
  </figure>
26
26
 
27
27
  <!-- once, anywhere on the page (a site-wide footer is fine) -->
28
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.1/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
28
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.109.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
29
29
  ```
30
30
 
31
31
  Every `[data-tinyfly-embed]` mounts when the page is ready, with no per-post