@algorisys/tinyfly 0.101.0 → 0.103.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +17 -6
- package/bin/tinyfly.mjs +9 -3
- package/docs/DEPLOYMENT.md +2 -0
- package/docs/api-reference.md +61 -0
- package/docs/dance.md +150 -1
- package/docs/editor-guide.md +11 -4
- package/docs/examples.md +22 -1
- package/docs/getting-started.md +1 -1
- package/docs/gsap-compat.md +1 -1
- package/docs/llm-guide.md +38 -3
- package/docs/maps.md +2 -2
- package/docs/scene-3d.md +138 -6
- package/docs/teaching.md +1 -1
- package/docs/video-rendering.md +44 -1
- package/lib/addons/adapters.js +168 -123
- package/lib/addons/characters.js +5802 -5506
- package/lib/addons/scene-3d-webgl.js +30 -30
- package/lib/addons/scene-3d.js +650 -341
- package/lib/browser/tinyfly-scene-3d-webgl.iife.js +2 -2
- package/lib/browser/tinyfly-scene-3d.iife.js +2 -2
- package/lib/browser/tinyfly.iife.js +14 -14
- package/lib/browser/tinyfly.js +5798 -5467
- package/lib/browser/tinyfly.umd.js +14 -14
- package/lib/engine/tinyfly-engine.js +1207 -1172
- package/lib/engine/tinyfly-engine.umd.cjs +2 -2
- package/lib/headless/headless.js +150 -6
- package/lib/types/adapters/canvas/framing.d.ts +27 -0
- package/lib/types/adapters/canvas/index.d.ts +1 -0
- package/lib/types/characters/capabilities.d.ts +1 -0
- package/lib/types/characters/character-script-3d.d.ts +34 -4
- package/lib/types/characters/dance-circle.d.ts +59 -0
- package/lib/types/characters/dance-contact.d.ts +52 -0
- package/lib/types/characters/human-dance.d.ts +86 -0
- package/lib/types/characters/index.d.ts +5 -1
- package/lib/types/characters/rig/reach.d.ts +6 -3
- package/lib/types/characters/staging-3d.d.ts +56 -0
- package/lib/types/engine/authoring/framing.d.ts +48 -0
- package/lib/types/engine/authoring/index.d.ts +1 -0
- package/lib/types/headless/audio-mix.d.ts +40 -0
- package/lib/types/headless/ffmpeg-args.d.ts +2 -0
- package/lib/types/headless/frame-renderer.d.ts +7 -1
- package/lib/types/headless/index.d.ts +1 -0
- package/lib/types/headless/node-audio.d.ts +19 -0
- package/lib/types/headless/node-video.d.ts +2 -0
- package/lib/types/headless/video-scene.d.ts +12 -0
- package/lib/types/scene-3d/index.d.ts +3 -0
- package/lib/types/scene-3d/lighting.d.ts +58 -0
- package/lib/types/scene-3d/resolve-scene.d.ts +5 -1
- package/lib/types/scene-3d/scene-3d-adapter.d.ts +2 -0
- package/lib/types/scene-3d/scene-types.d.ts +14 -2
- package/lib/types/scene-3d/shots.d.ts +162 -0
- package/lib/types/scene-3d/software-renderer.d.ts +40 -0
- package/llms-full.txt +474 -23
- package/llms.txt +29 -29
- package/package.json +1 -1
- package/skills/tinyfly/SKILL.md +32 -1
- package/lib/types/characters/polyline.d.ts +0 -12
- package/lib/types/characters/sketch.d.ts +0 -54
- package/lib/types/compat/gsap/playhead-crossings.d.ts +0 -47
package/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.
|
|
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.
|
|
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.
|
|
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.
|
|
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))}
|
|
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
|
package/docs/DEPLOYMENT.md
CHANGED
|
@@ -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
|
|
package/docs/api-reference.md
CHANGED
|
@@ -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
|

|
|
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)
|
|
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:
|
package/docs/editor-guide.md
CHANGED
|
@@ -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.
|
|
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,
|
|
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.
|
|
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.
|
|
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
|
|
package/docs/getting-started.md
CHANGED
|
@@ -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.
|
|
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>
|
package/docs/gsap-compat.md
CHANGED
|
@@ -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.
|
|
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`
|
|
52
|
-
|
|
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.
|
|
18
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
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
|