@algorisys/tinyfly 0.92.0 → 0.94.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 (64) hide show
  1. package/README.md +7 -6
  2. package/bin/tinyfly.mjs +34 -1
  3. package/docs/2d-animation-roadmap.md +191 -0
  4. package/docs/3d-rotations.md +164 -0
  5. package/docs/3d-support-plan.md +628 -0
  6. package/docs/DEPLOYMENT.md +414 -0
  7. package/docs/acting.md +529 -0
  8. package/docs/api-reference.md +2353 -0
  9. package/docs/camera.md +94 -0
  10. package/docs/cartoon-hands.md +96 -0
  11. package/docs/character-system-m1.md +218 -0
  12. package/docs/character-system-plan.md +384 -0
  13. package/docs/dance.md +315 -0
  14. package/docs/editor-guide.md +1249 -0
  15. package/docs/examples.md +765 -0
  16. package/docs/extending.md +168 -0
  17. package/docs/file-format.md +690 -0
  18. package/docs/getting-started.md +314 -0
  19. package/docs/grid-and-snapping.md +64 -0
  20. package/docs/gsap-compat.md +1241 -0
  21. package/docs/llm-guide.md +131 -0
  22. package/docs/maps.md +116 -0
  23. package/docs/onion-skinning.md +41 -0
  24. package/docs/pen-tool.md +65 -0
  25. package/docs/polygon-star.md +44 -0
  26. package/docs/scene-3d.md +299 -0
  27. package/docs/scroll-animation.md +314 -0
  28. package/docs/shape-morph.md +61 -0
  29. package/docs/sprite-sheet-export.md +54 -0
  30. package/docs/symbols-and-library.md +137 -0
  31. package/docs/teaching.md +348 -0
  32. package/docs/video-rendering.md +728 -0
  33. package/lib/addons/adapters.js +22 -18
  34. package/lib/addons/characters.js +3045 -2024
  35. package/lib/addons/target-properties-BtN9skb-.js +142 -0
  36. package/lib/browser/tinyfly.iife.js +9 -4
  37. package/lib/browser/tinyfly.js +6968 -5817
  38. package/lib/browser/tinyfly.umd.js +9 -4
  39. package/lib/engine/tinyfly-engine.js +286 -258
  40. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  41. package/lib/types/adapters/canvas/canvas-adapter.d.ts +6 -0
  42. package/lib/types/adapters/canvas/index.d.ts +1 -0
  43. package/lib/types/adapters/canvas/target-properties.d.ts +68 -0
  44. package/lib/types/characters/acting/beat-check.d.ts +102 -0
  45. package/lib/types/characters/acting/custom.d.ts +66 -0
  46. package/lib/types/characters/acting/gags.d.ts +10 -0
  47. package/lib/types/characters/acting/hand-path.d.ts +35 -0
  48. package/lib/types/characters/acting/index.d.ts +4 -0
  49. package/lib/types/characters/acting/persona.d.ts +93 -0
  50. package/lib/types/characters/acting/script.d.ts +75 -11
  51. package/lib/types/characters/capabilities.d.ts +61 -0
  52. package/lib/types/characters/code-panel.d.ts +201 -0
  53. package/lib/types/characters/figure-actions.d.ts +12 -0
  54. package/lib/types/characters/figure-props.d.ts +87 -0
  55. package/lib/types/characters/gaits.d.ts +8 -0
  56. package/lib/types/characters/index.d.ts +3 -0
  57. package/lib/types/characters/stick-figure.d.ts +9 -2
  58. package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
  59. package/lib/types/engine/authoring/index.d.ts +1 -0
  60. package/llms-full.txt +12631 -0
  61. package/llms.txt +57 -0
  62. package/package.json +6 -2
  63. package/skills/tinyfly/SKILL.md +67 -0
  64. package/lib/addons/camera-C7bZOWMB.js +0 -33
package/docs/dance.md ADDED
@@ -0,0 +1,315 @@
1
+ # Dance and Flips
2
+
3
+ The stick figure from `@algorisys/tinyfly/characters` can dance (disco, hip
4
+ hop, breaking toprock, jazz, K-pop, Bollywood, Bhangra, Bharatanatyam,
5
+ Charleston, tap, popping with its glides and the moonwalk) and do
6
+ flips (front, back, layout, scissor, side flip, cartwheel, back handspring),
7
+ leaps (split leap, toe touch) and full splits.
8
+ Like everything else in tinyfly, it is plain data played by pure functions:
9
+ the same style at the same beat always gives the same pose, so a dance scrubs,
10
+ renders to video and syncs to music exactly.
11
+
12
+ Try it on the Examples page: **Dance Floor (Characters)**.
13
+
14
+ ![Every dance style's moves and every flip](model-sheet/dance-and-flips.png)
15
+
16
+ The sheet is `examples/headless-video/dance-sheet.mjs`.
17
+
18
+ ```js
19
+ import { danceFrame, drawStickFigure } from '@algorisys/tinyfly/characters'
20
+
21
+ // Beats, not milliseconds: any tempo plays the same dance.
22
+ const beat = (time * 120) / 60000
23
+ const { pose, hands } = danceFrame('disco', beat)
24
+ drawStickFigure(ctx, pose, { height: 220, hands: { ...hands } })
25
+ ```
26
+
27
+ ## The joints that make it dance
28
+
29
+ Dancing needs more than shoulders, elbows, hips and knees. These pose fields
30
+ are numbers like every other, so they blend and can be timeline tracks:
31
+
32
+ | Field | Meaning |
33
+ |---|---|
34
+ | `leftWrist`, `rightWrist` | Wrist bend, degrees, added to the forearm like the elbow is to the upper arm. Turns `handAngle`, `fingertips` and the drawn hands |
35
+ | `leftAnkle`, `rightAnkle` | Positive points the toe down (onto tiptoe, which lifts the body); negative flexes it up onto the heel |
36
+ | `leftFootOut`, `rightFootOut` | Feet turned out (positive, 1 fully sideways) or in (negative) from their natural splay: Bharatanatyam's turn-out, a twist |
37
+ | `spin` | The whole body turned about the hips, degrees: positive rolls forward (a front flip), negative backward. Front-on (`turn` 0) it is a cartwheel |
38
+ | `rise` | Lift off the ground, as a fraction of the height. Once off the ground, the feet stop being planted, so a tuck keeps the hips' height |
39
+
40
+ The joints gain `fingertips` (where each hand reaches), and `handAngle` now
41
+ includes the wrist. All of these default to 0, which draws exactly as before.
42
+
43
+ ### Hands with fingers
44
+
45
+ `style.hands` replaces the dot hands with [cartoon hands](cartoon-hands.md),
46
+ posed per side and turned by the wrist:
47
+
48
+ ```js
49
+ drawStickFigure(ctx, pose, {
50
+ hands: { left: HAND_SHAPES.fist, right: HAND_SHAPES.point, size: 0.1 },
51
+ })
52
+ ```
53
+
54
+ Dance keys set hand shapes by name: any of `HAND_SHAPES` (`point`, `fist`,
55
+ `spread`, `peace`, `cupped`…) or the `MUDRAS` of Indian classical dance:
56
+ `pataka`, `tripataka`, `alapadma`, `mushti`, `shikhara`, `hamsasya`,
57
+ `katakamukha`.
58
+
59
+ ## Moves, styles and routines
60
+
61
+ A **move** is a short loop of keys counted in beats. Each key changes some
62
+ joints from the previous key (`reset: true` starts again from the stance), may
63
+ set hand shapes, and names the easing into it:
64
+
65
+ ```js
66
+ const point = {
67
+ label: 'The point',
68
+ beats: 2,
69
+ easing: 'ease-out-cubic',
70
+ keys: [
71
+ { beat: 0, pose: { rightShoulder: 150, leftShoulder: 40, leftElbow: -105, lean: -5 }, hands: { right: 'point', left: 'fist' } },
72
+ { beat: 1, pose: { rightShoulder: -30, lean: 5 } },
73
+ ],
74
+ }
75
+ ```
76
+
77
+ A **style** gathers a stance (the base every move builds on), a face, a
78
+ **groove** (a knee bounce on or off the beat and a sway over two beats, which
79
+ every move carries), its moves, and a **routine** that strings them together.
80
+ Steps can be mirrored (left and right swap), and one step blends into the next
81
+ over half a beat.
82
+
83
+ ```js
84
+ const twoStep = {
85
+ label: 'Two-step',
86
+ bpm: 100,
87
+ stance: { leftHip: 12, rightHip: 12 },
88
+ expression: 'happy',
89
+ groove: { bounce: 10, accent: 'down', sway: 3 },
90
+ moves: { point },
91
+ routine: [
92
+ { move: 'point', beats: 8 },
93
+ { move: 'point', beats: 8, mirror: true },
94
+ ],
95
+ }
96
+ ```
97
+
98
+ `DANCE_STYLES` has eleven ready-made styles. Each is plain data, so copy one and
99
+ change it:
100
+
101
+ | Style | Moves |
102
+ |---|---|
103
+ | `disco` | the point, rolling arms, bump and clap |
104
+ | `hipHop` | bounce (down on the beat), running man (side-on), arm wave |
105
+ | `breaking` | toprock (Indian step), kick out, b-boy stance |
106
+ | `jazz` | jazz hands, kick ball change (pointed toe), jazz square, drop into the splits |
107
+ | `kpop` | point combo, big heart and finger heart, isolations (sharp hits) |
108
+ | `bollywood` | thumka, screw the bulb and pat the dog, cross and flick |
109
+ | `bhangra` | the bhangra step (knee lifts, arms up), dhamaal jumps |
110
+ | `bharatanatyam` | tatta adavu (stamps in aramandi), natta adavu, alapadma to the sky |
111
+ | `charleston` | kick forward and back, swivel (heels in, heels out with `footOut`), crossing knees |
112
+ | `tap` | side-on: shuffle ball change, single time step (stamp, shuffle, hop, step, flap, step), heel toe, cramp roll; every strike is in `taps` |
113
+ | `popping` | side glide (front-on), moonwalk and forward glide (side-on), toe stand; the glides travel (see below) |
114
+
115
+ ### Travelling moves: glides and the moonwalk
116
+
117
+ Most moves dance on the spot. A move with `travel` carries the figure across
118
+ the floor at a steady speed: `travel` is the ground one loop covers, as a
119
+ fraction of the figure's height, positive toward +x (the way a side-on figure
120
+ faces). The moonwalk's is negative, so it slides backward while its feet look
121
+ like they step forward. A mirrored step travels the other way front-on (left
122
+ and right swap) and keeps its direction side-on (the figure still faces the
123
+ same way).
124
+
125
+ Popping's glides follow one rule. On each beat one foot is planted on its toe
126
+ and drops its heel while the other slides flat along the floor; then they
127
+ swap. Their keys are linear and their `travel` matches the planted foot, so
128
+ that foot stays put on the floor while the body glides over it. The tests
129
+ check this with `stickFigureJoints()`. The popping routine glides right, back
130
+ left, moonwalks away and glides forward home, so it loops on the spot.
131
+
132
+ ```js
133
+ import { danceFrame, danceTravel, danceTravelTrack, drawStickFigure } from '@algorisys/tinyfly/characters'
134
+
135
+ const { pose } = danceFrame('popping', beat, { move: 'moonwalk' })
136
+ const x = startX + danceTravel('popping', beat, { move: 'moonwalk' }) * 220 // heights → px
137
+ drawStickFigure(ctx, pose, { height: 220 })
138
+
139
+ // On a timeline: an x track with linear keys where the speed changes.
140
+ const xTrack = danceTravelTrack('tum', 'popping', { bpm: 100, height: 220, x: 340 })
141
+ ```
142
+
143
+ `bakeDanceTracks()` and the editor's **🕺 Dance from playhead** add that `x`
144
+ track themselves when given the figure's height (the editor uses the
145
+ character's, from where it is at the playhead). With `danceTracks()` add
146
+ `danceTravelTrack()` beside the two tracks. It eases in and out over the same
147
+ `fade` (default 1 beat), so the figure does not glide before it has danced in.
148
+ Pass `fade: 0` for full speed from the first beat to the last. A routine that does not come back
149
+ keeps going the same way each time it loops. The Dance Floor carries its
150
+ dancer off one side of the stage and brings it back in at the other.
151
+
152
+ ### Dancing to music
153
+
154
+ Beats are the tempo's: `beatAt(time, bpm, start)` turns time into beats, so
155
+ `danceFrame(style, beatAt(time, music.bpm, music.firstBeat))` keeps a dancer
156
+ on the music. To find a song's tempo and its first beat, use the engine's
157
+ `detectTempo(samples, sampleRate)` (see the API reference); in the editor, an
158
+ Audio element's **🎵 Detect tempo** does it, and a Character's dances then
159
+ follow the beat.
160
+
161
+ ### Taps: when the feet strike the floor
162
+
163
+ A key can name the parts of the feet that strike the floor on it:
164
+ `taps: ['rightToe']`, `['leftHeel']`, or both of a foot for a stamp. Tap is
165
+ built on them, and Bharatanatyam's stamps carry them too. `danceTaps(style,
166
+ from, to)` lists the strikes between two beats (the end not included), in
167
+ order, through the routine and its mirrored steps, so calling it each frame
168
+ with the last frame's beat and this one's gives exactly the taps that just
169
+ happened: play a sound, flash the foot, shake the floor.
170
+
171
+ ```js
172
+ for (const { beat, tap } of danceTaps('tap', lastBeat, beat)) {
173
+ playClick(tap.endsWith('Heel') ? 'heel' : 'toe')
174
+ }
175
+ ```
176
+
177
+ The Dance Floor example flashes the foot at `joints.toes[side]` and, with
178
+ "tap sounds" on, clicks through Web Audio.
179
+
180
+ ### The functions
181
+
182
+ ```ts
183
+ danceFrame(style, beat, { move?, mirror? }): { pose, hands } // the routine, or one move on a loop
184
+ stickToHuman(pose): CharacterPose // a stick pose on a v2 character
185
+ danceTaps(style, fromBeat, toBeat, options?): { beat, tap }[] // foot strikes, for sounds
186
+ danceTravel(style, beat, options?): number // ground covered, in heights
187
+ danceTravelTrack(target, style, { height, x?, bpm?, beats?, start?, fade?, move?, mirror? }): Track | undefined
188
+ mirrorHumanPose(pose): CharacterPose // a v2 pose's mirror image
189
+ dancePose(style, beat, options?): StickPose
190
+ routineBeats(style): number
191
+ beatAt(timeMs, bpm, startMs = 0): number
192
+ mirrorPose(pose): StickPose
193
+ applyGroove(pose, groove, beat): StickPose
194
+ danceStance(style): StickPose
195
+ ```
196
+
197
+ ### On a timeline
198
+
199
+ Give a stick-figure target a dancer, then two small tracks make it dance:
200
+ `beat` counts beats at the tempo, and `dancing` blends it in from standing and
201
+ back out.
202
+
203
+ ```js
204
+ import { stickFigureTarget, dancer, danceTracks } from '@algorisys/tinyfly/characters'
205
+
206
+ const tum = stickFigureTarget({ x: 340, y: 300, dance: dancer('bollywood'), style: { hands: {} } })
207
+ const tracks = danceTracks('tum', { bpm: 120, beats: 32, start: 1000 })
208
+ ```
209
+
210
+ For a timeline that must stand alone as JSON (no `dance` option), bake the
211
+ dance into pose keyframes, a few per beat:
212
+
213
+ ```js
214
+ bakeDanceTracks('tum', 'kpop', { bpm: 125, beats: 16, samplesPerBeat: 4 })
215
+ ```
216
+
217
+ Hand shapes bake too, as `hand.left.*` / `hand.right.*` tracks (one per hand
218
+ pose field that moves, such as `hand.right.index.curl`). A target drawn with
219
+ `style.hands` has a prop for every hand field, so those tracks pose its
220
+ fingers; pass `hands: false` to leave them out.
221
+
222
+ ### On a v2 character, and in the editor
223
+
224
+ `stickToHuman(pose)` turns a stick-figure pose into a v2 character pose, so
225
+ every dance and flip plays on `character()` figures too. Each stick limb angle
226
+ is split by the view into a sideways `spread` and a forward `swing`, and the
227
+ character turns the same way. Front-on, a stick leg lies in the picture: on
228
+ the character that is a leg turned out 90° at the hip (`leg.*.rotate`), so
229
+ knees bend out over the toes as they do on the stick figure (Bharatanatyam's
230
+ half-sit, a plié). Foot turn-out becomes `leg.*.toeOut`, and `rise` and `spin`
231
+ become `lift` and `roll`. Pass the frame's hands too, `stickToHuman(frame.pose,
232
+ frame.hands)`, and it adds the `hand.left.*` / `hand.right.*` fields a
233
+ character with `hands: 'cartoon'` draws: the shapes and mudras, with the wrist
234
+ bends as each hand's `roll`. `handStyle: 'natural'` gives five-fingered hands,
235
+ so mudras read finger by finger.
236
+
237
+ ```js
238
+ import { character, drawCharacter, danceFrame, stickToHuman } from '@algorisys/tinyfly/characters'
239
+
240
+ const frame = danceFrame('bharatanatyam', beat)
241
+ drawCharacter(ctx, character({ figure: 'fluid', hands: 'cartoon', handStyle: 'natural' }), stickToHuman(frame.pose, frame.hands), time)
242
+ ```
243
+
244
+ In the editor, a **🧍 Character** has a **Dance** section: pick a style, a
245
+ move (or the whole routine) and a tempo, then **🕺 Dance from playhead**. Or
246
+ pick a flip and **🤸 Flip at playhead**. Both write ordinary keyframes, a few
247
+ a beat, and keep the character's keys before and after. Glides and the
248
+ moonwalk also write an `x` track from where the character stands. A character
249
+ facing left (the *Side (left)* view) dances the mirror image (`mirrorHumanPose()`:
250
+ sides swap, it turns, tips and rolls the other way) and glides the other way;
251
+ it turns between 3 (side-on, facing left) and 4 (front-on), never round the
252
+ back. With **Hands:
253
+ Cartoon gloves** or **Natural**, dances key the hand shapes and mudras too. Flips travel from where
254
+ the character is, the way it faces: pick the *Side* or *Side (left)* view
255
+ first.
256
+
257
+ ### Side-on moves
258
+
259
+ Moves can be danced side-on (tap, the running man). Side-on, a limb's angle
260
+ swings it forward or back, and forward is a positive angle for the right limbs
261
+ and a negative one for the left. The groove follows: both knees bend forward.
262
+ Mirroring a side-on pose gives the move to the other arm and leg while the
263
+ figure keeps facing the same way; front-on it is a mirror image.
264
+
265
+ ## Flips
266
+
267
+ A flip is one continuous motion: wind up (crouch, arms back), take off (arms
268
+ swing up, toes push), the air, and land (absorb in a crouch, stand).
269
+ `progress` runs 0 → 1 through all of it. The body's pose is keyed; the turn
270
+ and the height are not. In the air the hips follow a parabola, and the turn
271
+ starts at take-off and is quickest at the top, where a tuck spins fastest.
272
+ After landing the turn is a whole number of turns, drawn as none, so the
273
+ figure blends on into any other pose.
274
+
275
+ ```js
276
+ import { flipPose, flipTravel, flipTracks, FLIPS } from '@algorisys/tinyfly/characters'
277
+
278
+ const figure = flipPose('backFlip', 0.5) // upside down, at the top
279
+ const x = startX + flipTravel('backFlip', 0.5, 220) // ground covered so far, px
280
+
281
+ // As keyframe tracks (every moving joint, spin, rise, and x when given a height):
282
+ const tracks = flipTracks('tum', 'frontFlip', { start: 2000, height: 220 })
283
+ ```
284
+
285
+ | Flip | Seen | Notes |
286
+ |---|---|---|
287
+ | `frontFlip` | profile | tuck, rolls forward |
288
+ | `backFlip` | profile | tuck, rolls backward |
289
+ | `layout` | profile | back flip with a straight, arched body |
290
+ | `scissorFlip` | profile | legs scissor through the turn |
291
+ | `sideFlip` | front-on | tucked side flip |
292
+ | `cartwheel` | front-on | arms overhead reach the ground half way round |
293
+ | `backHandspring` | profile | arms reach back to the ground, legs snap over |
294
+ | `splitLeap` | profile | grand jeté: a front split in the air, no turn |
295
+ | `toeTouch` | front-on | straddle jump, hands reaching for the toes |
296
+
297
+ Each `Flip` is data (`view`, `spin`, `height`, `travel`, `takeoff`, `landing`,
298
+ `duration`, `keys`), so new ones are a copy and a few numbers. To flip in the
299
+ middle of a dance, blend from the dance pose to `flipPose()` over the first and
300
+ last tenth of the flip, as the Dance Floor example does.
301
+
302
+ ## Full splits
303
+
304
+ `POSES.sideSplit` (front-on, legs straight out to each side) and
305
+ `POSES.frontSplit` (in profile, one leg forward, one back) put the legs flat
306
+ along the floor; the planted feet bring the hips right down to it, so a split
307
+ is just a pose to blend into. Jazz's `splitDrop` move slides down into one,
308
+ holds, and gathers back up through a crouch.
309
+
310
+ ## Limits
311
+
312
+ The stick figure is drawn in one plane, front-on or in profile. Floor work
313
+ (windmills, headspins, freezes on the hands) and body rolls need a bendable
314
+ spine and limbs that reach a point; those come with
315
+ [Characters v2](character-system-plan.md).