@algorisys/tinyfly 0.97.0 → 0.99.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 (48) hide show
  1. package/README.md +10 -10
  2. package/docs/acting.md +76 -13
  3. package/docs/character-appearance.md +329 -0
  4. package/docs/editor-guide.md +54 -9
  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 +29 -2
  9. package/docs/maps.md +2 -2
  10. package/docs/props.md +8 -6
  11. package/docs/scene-3d.md +3 -1
  12. package/docs/teaching.md +1 -1
  13. package/lib/addons/characters.js +5911 -4230
  14. package/lib/browser/tinyfly.iife.js +14 -14
  15. package/lib/browser/tinyfly.js +8545 -6864
  16. package/lib/browser/tinyfly.umd.js +14 -14
  17. package/lib/types/characters/acting/character-script.d.ts +44 -0
  18. package/lib/types/characters/acting/index.d.ts +1 -0
  19. package/lib/types/characters/capabilities.d.ts +15 -0
  20. package/lib/types/characters/cast.d.ts +284 -0
  21. package/lib/types/characters/character.d.ts +35 -5
  22. package/lib/types/characters/chart.d.ts +52 -14
  23. package/lib/types/characters/hair-follow.d.ts +76 -0
  24. package/lib/types/characters/hands/held-items.d.ts +88 -0
  25. package/lib/types/characters/hands/index.d.ts +1 -0
  26. package/lib/types/characters/head/ears.d.ts +10 -0
  27. package/lib/types/characters/head/facial-hair.d.ts +118 -0
  28. package/lib/types/characters/head/glasses.d.ts +24 -0
  29. package/lib/types/characters/head/hair.d.ts +586 -0
  30. package/lib/types/characters/head/hats.d.ts +58 -0
  31. package/lib/types/characters/head/head-look.d.ts +56 -0
  32. package/lib/types/characters/head/index.d.ts +5 -0
  33. package/lib/types/characters/head/shell.d.ts +64 -0
  34. package/lib/types/characters/index.d.ts +5 -1
  35. package/lib/types/characters/interactions.d.ts +69 -0
  36. package/lib/types/characters/props/draw.d.ts +9 -0
  37. package/lib/types/characters/props/families/animals.d.ts +6 -0
  38. package/lib/types/characters/props/prop-surface.d.ts +14 -3
  39. package/lib/types/characters/props/ride-3d.d.ts +31 -2
  40. package/lib/types/characters/props/target.d.ts +5 -1
  41. package/lib/types/characters/species/human-motion.d.ts +5 -2
  42. package/lib/types/characters/species/human.d.ts +113 -4
  43. package/lib/types/characters/wardrobe/basic-outfit.d.ts +19 -5
  44. package/lib/types/characters/whiteboard.d.ts +13 -1
  45. package/llms-full.txt +549 -56
  46. package/llms.txt +29 -28
  47. package/package.json +1 -1
  48. package/skills/tinyfly/SKILL.md +18 -4
@@ -43,7 +43,9 @@ left to right:
43
43
  is a reassuring, tap-friendly manual save (handy on tablets).
44
44
  - **New** — start a fresh project (prompts if you have unsaved changes).
45
45
  - **AI** — show or hide the AI prompt bar, where you describe an animation and
46
- click **Generate**.
46
+ click **Generate**. A brief with a story in it ("grandma walks up to a ticking
47
+ box, jumps, and runs off") gets a 🧍 Character from the cast with a beat
48
+ script, compiled into its tracks on load (the beats stay on the element).
47
49
  - **My Animations** — open the gallery of every project you've saved (thumbnails,
48
50
  open / duplicate / delete). See [Project Management](#project-management).
49
51
  - **Examples** — every ready-made animation on one page (`/examples`). Open one in
@@ -78,6 +80,8 @@ Shapes, text, images, video, lines, arrows and paths are added from the
78
80
  | **Group** | Container that groups multiple elements |
79
81
  | **🧍 Character** | A posable figure: pick a view, a pose and a face, and keyframe them to animate (see [Characters](#characters)) |
80
82
  | **🗺 Map** | An animated map: places, a route between them, and a camera (see [Maps](#maps)) |
83
+ | **🧊 3D Scene** | A real 3D scene seen through its camera: meshes, lights, characters and props (see [3D Scenes](#3d-scenes)) |
84
+ | **⌨ Code** | A code panel whose lines a Character's beats aim at and change (see [Code](#code)) |
81
85
 
82
86
  Polygon and star are **parametric** paths: change the sides/points/inner ratio in
83
87
  the Property Panel and the shape regenerates, and they rescale cleanly when you
@@ -137,12 +141,19 @@ its box; resize the box to change its height. In the property panel:
137
141
  traditional stick figure).
138
142
  - **Look**: *Clean*, *Pencil* (hand-drawn strokes that boil, with faint
139
143
  construction lines) or *Silhouette*.
140
- - **Build**: *Standard*, *Slim*, *Kid* (big head), *Broad*, *Curvy* or
141
- *Stocky*, or set **Head**, **Shoulders** and **Hips** with the sliders (the
142
- Stick figure has a head size only). Clothes, gags, walks and dances fit
143
- every build.
144
+ - **Build**: *Standard*, *Slim*, *Kid* (big head), *Child*, *Toddler*, *Tall*,
145
+ *Short*, *Broad*, *Curvy* or *Stocky*, or set **Head**, **Shoulders**,
146
+ **Hips**, **Legs** and **Arms** with the sliders (the Stick figure has no
147
+ shoulders or hips). Clothes, gags, walks and dances fit every build.
144
148
  - **Line**, **Skin**, and **Clothes** (a T-shirt and trousers, with their
145
149
  colours, or none).
150
+ - **Head**: **Cast** dresses the character as one of the ready-made cast
151
+ (boy, girl, young man, young woman, man, woman, grandpa, grandma: build,
152
+ hair, facial hair, glasses and clothes in one step); then **Hair** (34
153
+ styles, from buzz cut to twin braids) and its **Hair colour**, **Facial
154
+ hair** (20 styles), **Glasses**, **Hat** and **Ears** change one thing at a
155
+ time. Hair and hats turn with the head in every view (see
156
+ [Character Appearance](character-appearance.md)).
146
157
  - **Hands**: *Round*, *Cartoon gloves* (a thumb and three plump fingers), or
147
158
  *Natural* (five fingers, best for mudras). Gloves and natural hands take hand
148
159
  shapes: dances key them (jazz hands, mudras), and each finger is a track
@@ -154,7 +165,8 @@ its box; resize the box to change its height. In the property panel:
154
165
  - **Body**: a pose (standing, waving, pointing, cheering, hands on hips,
155
166
  thinking, shrugging, sitting, kneeling, crouching, crawling, lying down).
156
167
  Poses that rest on a knee, the hands or the back are set down on the ground.
157
- - **Face**: an expression (happy, sad, surprised, angry…), or the pose's own.
168
+ - **Face**: an expression (happy, sad, surprised, angry, embarrassed with a
169
+ blush, crying with tears, afraid with a bead of sweat…), or the pose's own.
158
170
 
159
171
  To animate a character, pick a view, a pose and a face, and click
160
172
  **◆ Keyframe pose at playhead**. Move the playhead, pick the next pose, and
@@ -205,12 +217,39 @@ Dances and flips are written as they are, and turn acting off.
205
217
  (`drawingRate` in the JSON), so previews, players and exports all hold the
206
218
  same way.
207
219
 
220
+ - **Beats**: a story written as beats, compiled in the chosen style into the
221
+ character's tracks and kept on the element (`beats` in the JSON). Write them
222
+ as JSON (`[{ "do": "walk", "to": 320, "mood": "happy" }, { "do": "say",
223
+ "say": "Hello!" }, { "do": "take" }]`) and click **🎬 Run beats**; the
224
+ timeline grows to fit. A beat can aim at a **⌨ Code** element's lines
225
+ (`"target": { "surface": "Code 1", "anchor": "line:2" }`, also for `to`,
226
+ `toward` and `onto`) and change them (`"then": { "surface": "Code 1",
227
+ "edit": "highlight", "anchor": "line:2", "at": "contact" }`): the edits
228
+ become tracks on that element. Problems are named by beat (an unknown
229
+ action, mood or place) before anything is written. The AI prompt bar writes
230
+ beats this way too.
231
+
208
232
  See [Cartoon Acting](acting.md).
209
233
 
210
234
  Characters show in the DOM and Canvas previews and in GIF / WebP / MP4
211
235
  export. They are not part of exported HTML or embeds yet, and the SVG preview
212
236
  does not draw them.
213
237
 
238
+ ### Code
239
+
240
+ A **⌨ Code** element is a code panel (`codePanel()` from code): a listing with
241
+ line numbers, drawn by code into its box, which grows to fit its lines. In the
242
+ property panel: the **Language** (JavaScript, TypeScript, Python, Go, Rust,
243
+ C#, plain), **Font size**, **Line numbers**, **Hidden lines** (typed in later)
244
+ and the **Listing** itself.
245
+
246
+ Its lines are places. A Character's **Beats** aim at them and change them
247
+ (highlight, strike, remove, type, fling a token…), and those edits are tracks
248
+ on the Code element named `line.N.highlight`, `line.N.strike`, `line.N.wipe`,
249
+ `line.N.reveal` and so on, which you can also key by hand. Code panels show in
250
+ the DOM and Canvas previews and in GIF / WebP / MP4 export. See [Acting on
251
+ code](acting.md#acting-on-code) for the same from code.
252
+
214
253
  ### Maps
215
254
 
216
255
  A **🗺 Map** fills the canvas with a map of the world. In the property panel:
@@ -245,8 +284,8 @@ camera: it starts with a camera at three-quarters, a key light, a floor and a
245
284
  red box. In the property panel:
246
285
 
247
286
  - **Objects**: pick one to edit. **Add** puts a box, sphere, cylinder, cone,
248
- ring, star (an extruded path), character or light on the next free spot;
249
- ✕ removes the picked one (not the scene's camera).
287
+ ring, star (an extruded path), character, prop or light on the next free
288
+ spot; ✕ removes the picked one (not the scene's camera).
250
289
  - **Transform**: X, Y, Z (metres, +y up), Tilt X, Turn Y, Roll Z and Scale.
251
290
  **◆ Key transform at playhead** keys all of them; once a value is animated
252
291
  (◆ by its name), changing it keys it at the playhead.
@@ -255,6 +294,12 @@ red box. In the property panel:
255
294
  - **Characters**: a look (*Clean*, *Pencil*, *Silhouette* drawn by their pens
256
295
  in perspective, or *Solid*) and **🕺 Dance from playhead** with any dance
257
296
  style.
297
+ - **Props**: which prop from the catalog (car, truck, bus, tractor, cart, train
298
+ car, bike, motorbike, tree, house, helicopter, airplane, horse, dog, cat, cow,
299
+ songbird, crow, chicken), its look (*Clean*, *Pencil*, *Silhouette*, or
300
+ *Mesh*, lit with the scene) and style (*Solid* or *Stick* line art). Its
301
+ controls (`car.door`, `car.wheelSpin`, `dog.tail`…) are tracks on the
302
+ element.
258
303
  - **Cameras**: field of view, **Look through this camera**, and **✂ Cut to
259
304
  this camera at playhead**, which keys the shot change.
260
305
  - **Camera** view presets (*Front*, *¾*, *Side*, *Top*) and the scene's
@@ -1058,7 +1103,7 @@ The dialog shows the generated HTML/JavaScript code with a **Copy Code** button.
1058
1103
  **Steps to embed:**
1059
1104
  1. Build the player: `npm run build:player`
1060
1105
  2. Copy `lib/player/tinyfly-player.iife.js` to your project (or load
1061
- `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.97.0/cdn/tinyfly-player.iife.js`
1106
+ `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.99.0/cdn/tinyfly-player.iife.js`
1062
1107
  instead; see [Deployment](DEPLOYMENT.md))
1063
1108
  3. Copy the generated code into your HTML
1064
1109
  4. Adjust the script `src` path if needed
package/docs/examples.md CHANGED
@@ -694,7 +694,7 @@ For simple website embedding without a build system.
694
694
  </html>
695
695
  ```
696
696
 
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.97.0/cdn/tinyfly-player.iife.js`.
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.99.0/cdn/tinyfly-player.iife.js`.
698
698
 
699
699
  ---
700
700
 
@@ -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.97.0/cdn/tinyfly.iife.js"></script>
188
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.99.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.97.0/cdn/tinyfly.iife.js"></script>
77
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.99.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,8 @@ 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, the code panel's languages, every surface's anchors and
21
+ character's poses, expressions, builds, hairstyles, facial hair, glasses,
22
+ hats and cast, the code panel's languages, every surface's anchors and
22
23
  edits (code panel, whiteboard, chart), camera shots and the teaching
23
24
  helpers. It is generated from the code, so it can't
24
25
  fall behind: **a name in it is accepted, and a name not in it is rejected.**
@@ -44,6 +45,24 @@ Characters in a 3D scene walk the same way with `characterScript3D`
44
45
  (`{ do: 'walk', to: [x, z] }`, `pose`, `gag`, `face`, `place`); a rider is
45
46
  seated with `propRide3D` and spliced into its script with `spliceTracks`. See `docs/props.md`.
46
47
 
48
+ ## Characters with a look
49
+
50
+ A v2 character's appearance is plain options to `character()`, never drawing
51
+ code: `build` (`child`, `tall`, `short`…), `hair` (a style name, or
52
+ `{ style, color, length, … }`), `facialHair`, `glasses`, `hat`, `ears: true`
53
+ and `outfit: { shirt, trousers }`. `castMember('grandpa', 300)` gives a whole
54
+ ready-made character to start from. Expressions come from `HUMAN_EXPRESSIONS`
55
+ and are pose fields, as are the face marks `blush`, `tears` and `sweat` (0–1),
56
+ so any face goes with any action or view. Hair and hats turn with the head:
57
+ don't draw a different hairstyle per view. Hanging hair swings on its own:
58
+ after the character's tracks add `hairFollowTracks(target, tracks, who)` (or,
59
+ posing per frame, `hairFollow` once and `hairMotionAt(keys, t)` each frame)
60
+ rather than keying `hair.swing` by hand. Put things in hands with `holding`
61
+ (`{ right: 'mug' }`, `{ both: 'parcel' }`; the pose field `held.both` lets go),
62
+ and for two characters touching use `meetHands('handshake', a, b)` with the
63
+ two standing `meetingSpacing(…)` apart, never two separate clips. See
64
+ `docs/character-appearance.md`.
65
+
47
66
  ## Surfaces
48
67
 
49
68
  Code panels (`codePanel()`), whiteboards (`whiteboard()`), charts
@@ -94,7 +113,11 @@ scriptTracks: 2 problem(s) in the beats:
94
113
 
95
114
  - **Beat scripts**: `scriptTracks()` throws on errors. `checkBeats(beats)`
96
115
  returns errors and warnings without throwing, and from the command line:
97
- `npx @algorisys/tinyfly check beats.json`.
116
+ `npx @algorisys/tinyfly check beats.json`. For a v2 `character()` use
117
+ `characterScript(target, who, beats, options)`: the same beats and checks,
118
+ compiled for the human body and a `characterTarget` (its `walk`, `walking`
119
+ and `gait` tracks step the gait as it draws); add
120
+ `hairFollowTracks(target, tracks, who)` after it.
98
121
  - **Tracks**: `checkTracks(tracks, targets)` finds tracks aimed at targets
99
122
  that aren't there, properties a target can't animate (`rotation` → `rotate`),
100
123
  keys out of time order, values of the wrong kind and values out of range.
@@ -128,6 +151,10 @@ Fix, render again.
128
151
  figure's `ground` (a house's `anchor:doorstep`).
129
152
  - **Angles are degrees.** Stick-figure arms: 0 hangs down, 90 straight out,
130
153
  180 straight up; in profile the left arm's forward is negative.
154
+ - **A character's look is data, and names are checked.** `hair: 'bob'`, not
155
+ a drawing in `layers`; a style name not in the catalog throws (`hair:
156
+ unknown style`). Side names (`at: 'left'`, `arm.left`) are the character's
157
+ own: from the front its left is on screen right.
131
158
  - **Aim beats at anchors, not guessed numbers**: `code.line(7)`,
132
159
  `code.token(3, 'var')`, `code.spot(2, 8, 4)`, `piece.home`.
133
160
  - **Key reactions to contact times.** Beats that touch something report
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.97.0/cdn/tinyfly.iife.js"></script>
18
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.97.0/cdn/tinyfly-maps.iife.js"></script>
17
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.99.0/cdn/tinyfly.iife.js"></script>
18
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.99.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/props.md CHANGED
@@ -109,11 +109,11 @@ one probably meant, and `propScript` throws on them.
109
109
  | `house()` | `door` (`open`), `lights` (`on`), `smoke` (`for`, runs in the background), `shake` |
110
110
  | `helicopter()` | `takeOff` (`height`), `fly` (`to`, `height`), `hover`, `land` |
111
111
  | `airplane()` | `takeOff` (`to`, `height`), `fly` (`to`, `height`), `loop`, `land` (`to`) |
112
- | `horse()` | `walk`, `trot`, `canter`, `gallop` (`to`), `rear`, `buck`, `neigh`, `graze`, `sit`, `jump`, `nod`, `swish` |
113
- | `dog()` | `walk`, `trot`, `run` (`to`), `bark`, `wag`, `sniff`, `sit`, `jump`, `nod`, `swish` |
114
- | `cat()` | `walk`, `trot`, `run` (`to`), `meow`, `arch`, `pounce` (`to`), `sit`, `jump`, `nod`, `swish` |
115
- | `cow()` | `walk`, `trot` (`to`), `moo`, `graze`, `sit`, `jump`, `nod`, `swish` |
116
- | `songbird()`, `crow()` | `hop`, `walk` (`to`), `peck` (`for`), `flap` (`for`), `fly` (`to`, `height`), `land` (`height`, `to`), `tweet` / `caw` |
112
+ | `horse()` | `walk`, `trot`, `canter`, `gallop` (`to`), `rear`, `buck`, `neigh`, `graze`, `sit`, `lie`, `jump`, `nod`, `swish` |
113
+ | `dog()` | `walk`, `trot`, `run` (`to`), `bark`, `wag`, `sniff`, `sit`, `lie`, `jump`, `nod`, `swish` |
114
+ | `cat()` | `walk`, `trot`, `run` (`to`), `meow`, `arch`, `pounce` (`to`), `sit`, `lie`, `jump`, `nod`, `swish` |
115
+ | `cow()` | `walk`, `trot` (`to`), `moo`, `graze`, `sit`, `lie`, `jump`, `nod`, `swish` |
116
+ | `songbird()`, `crow()` | `hop`, `walk` (`to`), `peck` (`for`), `flap` (`for`), `fly` (`to`, `height`), `glide` (`to`, `height`), `land` (`height`, `to`), `tweet` / `caw` |
117
117
  | `chicken()` | `walk` (`to`), `peck`, `flap`, `flutter`, `cluck` (it cannot fly) |
118
118
 
119
119
  **Line art.** `propTarget({ …, style: 'stick' })` (or `drawSolvedProp(…, { style: 'stick' })`)
@@ -138,7 +138,9 @@ and while `flapping` is on, the rig's `derive` beats them from a phase,
138
138
  a second, a crow four). Its head pecks from a neck joint (`peck`; a chicken's
139
139
  neck stretches down to reach), and it walks with its head bobbing or hops.
140
140
  `fly` takes off with a crouch and a leap (no crouch if it is already in the
141
- air) and flies to `height` metres; `land` comes down to the ground or to a
141
+ air) and flies to `height` metres; `glide` holds the wings out still and sinks
142
+ gently toward `height` on the way to `to` (from the ground it flies the first
143
+ stretch); `land` comes down to the ground or to a
142
144
  perch (`height`). Perch it with anchors:
143
145
 
144
146
  ```js
package/docs/scene-3d.md CHANGED
@@ -271,7 +271,9 @@ a cart's `seat`) as the prop moves, turns, bobs with its stride and pitches,
271
271
  writing the rider's `x`, `y`, `z` and `rotateY`; `mount: { from: [x, z] }` and
272
272
  `dismount: { to: [x, z] }` hop it on and off. `spliceTracks(riderTracks, ride, { from, to })`
273
273
  puts the ride into the rider's script, which holds the riding pose
274
- (`RIDING_POSES.astride` or `.seated`) meanwhile and `place`s it where it got
274
+ (`RIDING_POSES.astride`, `.seated`, `.driving` with the hands on a wheel, or
275
+ `.cycling`; `pedallingKeys({ start, end, cadence })` keys the legs round the
276
+ pedals on the cycling pose) meanwhile and `place`s it where it got
275
277
  off. A character in a scene is drawn part by part, each part at its own depth
276
278
  (`characterPartsInView`), so a leg astride a horse shows on each side of it.
277
279
  A seat inside a closed cabin (a car's) is not handled yet: its glass is opaque
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.97.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
28
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.99.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