@algorisys/tinyfly 0.98.0 → 0.100.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 +81 -14
  3. package/docs/character-appearance.md +96 -10
  4. package/docs/editor-guide.md +76 -4
  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 -9
  9. package/docs/maps.md +2 -2
  10. package/docs/props.md +61 -1
  11. package/docs/scene-3d.md +3 -1
  12. package/docs/teaching.md +1 -1
  13. package/lib/addons/characters.js +6709 -5248
  14. package/lib/browser/tinyfly.iife.js +15 -15
  15. package/lib/browser/tinyfly.js +7532 -6071
  16. package/lib/browser/tinyfly.umd.js +15 -15
  17. package/lib/types/characters/acting/character-script.d.ts +56 -0
  18. package/lib/types/characters/acting/index.d.ts +1 -0
  19. package/lib/types/characters/acting/script.d.ts +9 -0
  20. package/lib/types/characters/capabilities.d.ts +2 -0
  21. package/lib/types/characters/character.d.ts +21 -2
  22. package/lib/types/characters/chart.d.ts +52 -14
  23. package/lib/types/characters/hair-follow.d.ts +82 -0
  24. package/lib/types/characters/hands/held-items.d.ts +6 -2
  25. package/lib/types/characters/head/face.d.ts +6 -1
  26. package/lib/types/characters/head/hair.d.ts +27 -1
  27. package/lib/types/characters/head/head-look.d.ts +5 -2
  28. package/lib/types/characters/head/index.d.ts +1 -1
  29. package/lib/types/characters/index.d.ts +4 -2
  30. package/lib/types/characters/interactions.d.ts +60 -0
  31. package/lib/types/characters/props/draw.d.ts +9 -0
  32. package/lib/types/characters/props/families/animals.d.ts +6 -0
  33. package/lib/types/characters/props/families/birds.d.ts +16 -0
  34. package/lib/types/characters/props/families/furniture.d.ts +102 -0
  35. package/lib/types/characters/props/index.d.ts +1 -0
  36. package/lib/types/characters/props/presets.d.ts +15 -2
  37. package/lib/types/characters/props/prop-surface.d.ts +14 -3
  38. package/lib/types/characters/props/ride-3d.d.ts +34 -2
  39. package/lib/types/characters/props/target.d.ts +5 -1
  40. package/lib/types/characters/scenery.d.ts +126 -0
  41. package/lib/types/characters/species/human-motion.d.ts +17 -0
  42. package/lib/types/characters/species/human.d.ts +8 -0
  43. package/lib/types/characters/wardrobe/basic-outfit.d.ts +16 -5
  44. package/lib/types/characters/whiteboard.d.ts +13 -1
  45. package/llms-full.txt +400 -70
  46. package/llms.txt +29 -29
  47. package/package.json +2 -2
  48. package/skills/tinyfly/SKILL.md +22 -10
package/docs/llm-guide.md CHANGED
@@ -30,10 +30,16 @@ in `@algorisys/tinyfly/characters`.
30
30
 
31
31
  ## Props
32
32
 
33
- For objects in a story (vehicles, trees, houses, aircraft, animals, birds),
34
- use the presets (`car()`, `tree()`, `helicopter()`, `dog()`, `crow()`…) with
33
+ For objects in a story (vehicles, trees, houses, furniture, aircraft,
34
+ animals, birds), use the presets (`car()`, `tree()`, `chair()`, `door()`,
35
+ `wheelchair()`, `helicopter()`, `dog()`, `goat()`, `owl()`…) with
35
36
  `propTarget` and `propScript`; the catalog lists each preset's actions,
36
- controls and anchors, and `checkPropBeats` checks prop beats. `style: 'stick'`
37
+ controls and anchors, and `checkPropBeats` checks prop beats. Furniture has
38
+ the places a figure uses it at as anchors (`seat`, `top`, `mattress`,
39
+ `handle`, `doorway`): aim beats at them rather than guessing a spot. For a
40
+ sky or a room behind everything use `scenery()` (or `scenePreset('park')`),
41
+ whose `hour`, `clouds`, `wind`, `rain` and `snow` are tracks, not a drawing
42
+ of your own. `style: 'stick'`
37
43
  draws any prop as line art to go with stick figures. A bird's `lift` is in
38
44
  metres: to perch it on a branch or a roof, work the height out from that
39
45
  prop's anchor (`propAt(tree, frame, 'tree').anchor('branch')`). In a 3D
@@ -49,15 +55,25 @@ seated with `propRide3D` and spliced into its script with `spliceTracks`. See `d
49
55
 
50
56
  A v2 character's appearance is plain options to `character()`, never drawing
51
57
  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`
58
+ `{ style, color, length, … }`), `facialHair`, `glasses`, `hat`, `ears: true`,
59
+ `face: { teeth, tongue }` (shown when the mouth opens), `feet` (`round`,
60
+ `flat`, `pointed`, `big`) and `outfit: { shirt, trousers, over: 'hoodie' |
61
+ 'cardigan' | 'overalls' | 'sari' | 'apron' | 'labCoat', shoes: 'boots' }`.
62
+ `castMember('grandpa', 300)` gives a whole ready-made character to start
63
+ from. Age is hair, glasses and clothes, never a stoop; a `cane` in a hand or
64
+ a `wheelchair()` to ride (`RIDING_POSES.wheeling`) is an accessory any
65
+ character can have. Expressions come from `HUMAN_EXPRESSIONS`
55
66
  and are pose fields, as are the face marks `blush`, `tears` and `sweat` (0–1),
56
67
  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. Put things in hands with `holding`
68
+ don't draw a different hairstyle per view. Hanging hair swings on its own:
69
+ after the character's tracks add `hairFollowTracks(target, tracks, who)` (or,
70
+ posing per frame, `hairFollow` once and `hairMotionAt(keys, t)` each frame)
71
+ rather than keying `hair.swing` by hand. Put things in hands with `holding`
58
72
  (`{ right: 'mug' }`, `{ both: 'parcel' }`; the pose field `held.both` lets go),
59
73
  and for two characters touching use `meetHands('handshake', a, b)` with the
60
- two standing `meetingSpacing(…)` apart, never two separate clips. See
74
+ two standing `meetingSpacing(…)` apart, `embrace(a, b)` for a hug at
75
+ `embraceSpacing` and `helpUp(helper, sitter, progress)` for a help-up at
76
+ `helpUpSpacing`, never two separate clips. See
61
77
  `docs/character-appearance.md`.
62
78
 
63
79
  ## Surfaces
@@ -110,7 +126,11 @@ scriptTracks: 2 problem(s) in the beats:
110
126
 
111
127
  - **Beat scripts**: `scriptTracks()` throws on errors. `checkBeats(beats)`
112
128
  returns errors and warnings without throwing, and from the command line:
113
- `npx @algorisys/tinyfly check beats.json`.
129
+ `npx @algorisys/tinyfly check beats.json`. For a v2 `character()` use
130
+ `characterScript(target, who, beats, options)`: the same beats and checks,
131
+ compiled for the human body and a `characterTarget` (its `walk`, `walking`
132
+ and `gait` tracks step the gait as it draws); add
133
+ `hairFollowTracks(target, tracks, who)` after it.
114
134
  - **Tracks**: `checkTracks(tracks, targets)` finds tracks aimed at targets
115
135
  that aren't there, properties a target can't animate (`rotation` → `rotate`),
116
136
  keys out of time order, values of the wrong kind and values out of range.
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.98.0/cdn/tinyfly.iife.js"></script>
18
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.98.0/cdn/tinyfly-maps.iife.js"></script>
17
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.100.0/cdn/tinyfly.iife.js"></script>
18
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.100.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
@@ -107,14 +107,22 @@ one probably meant, and `propScript` throws on them.
107
107
  | `car()`, `truck()`, `bus()`, `tractor()`, `cart()`, `trainCar()`, `bike()`, `motorbike()` | `drive` (`to`), `brake` (`to`, a skid with locked wheels), `bump`, `honk`, `door` (`open`), `lights` (`on`) — doors and lights where it has them |
108
108
  | `tree()` | `sway` (`wind`, `for`), `shake`, `shedLeaves` |
109
109
  | `house()` | `door` (`open`), `lights` (`on`), `smoke` (`for`, runs in the background), `shake` |
110
+ | `chair()` | `tip` (`for`: back on its rear legs, then settles), `fall` |
111
+ | `desk()` | `drawer` (`open`) |
112
+ | `bed()` | `bounce` (`for`: the mattress gives and springs back) |
113
+ | `door()` | `open` (`open`, `for`), `slam`, `knock` (`for`) |
114
+ | `wheelchair()` | `roll` (`to`; the wheels turn the distance), `brake` (`to`, wheels locked), `wheelie` (`for`) |
110
115
  | `helicopter()` | `takeOff` (`height`), `fly` (`to`, `height`), `hover`, `land` |
111
116
  | `airplane()` | `takeOff` (`to`, `height`), `fly` (`to`, `height`), `loop`, `land` (`to`) |
112
117
  | `horse()` | `walk`, `trot`, `canter`, `gallop` (`to`), `rear`, `buck`, `neigh`, `graze`, `sit`, `lie`, `jump`, `nod`, `swish` |
113
118
  | `dog()` | `walk`, `trot`, `run` (`to`), `bark`, `wag`, `sniff`, `sit`, `lie`, `jump`, `nod`, `swish` |
114
119
  | `cat()` | `walk`, `trot`, `run` (`to`), `meow`, `arch`, `pounce` (`to`), `sit`, `lie`, `jump`, `nod`, `swish` |
115
120
  | `cow()` | `walk`, `trot` (`to`), `moo`, `graze`, `sit`, `lie`, `jump`, `nod`, `swish` |
121
+ | `goat()` | `walk`, `trot`, `gallop` (`to`), `bleat`, `graze`, `sit`, `lie`, `jump`, `nod`, `swish` |
122
+ | `rabbit()`, `squirrel()` | `walk`, `gallop` (`to`: a hop, a scamper), `squeak` / `chatter`, `graze` (nibble), `sit`, `lie`, `jump`, `nod`, `swish` |
116
123
  | `songbird()`, `crow()` | `hop`, `walk` (`to`), `peck` (`for`), `flap` (`for`), `fly` (`to`, `height`), `glide` (`to`, `height`), `land` (`height`, `to`), `tweet` / `caw` |
117
124
  | `chicken()` | `walk` (`to`), `peck`, `flap`, `flutter`, `cluck` (it cannot fly) |
125
+ | `pigeon()`, `duck()`, `owl()`, `parrot()` | As the songbird: `hop`, `walk`, `peck`, `flap`, `fly`, `glide`, `land`, and `coo` / `quack` / `hoot` / `squawk` |
118
126
 
119
127
  **Line art.** `propTarget({ …, style: 'stick' })` (or `drawSolvedProp(…, { style: 'stick' })`)
120
128
  draws a prop as line art to go with stick figures: tubes (legs, necks, tails,
@@ -141,7 +149,8 @@ neck stretches down to reach), and it walks with its head bobbing or hops.
141
149
  air) and flies to `height` metres; `glide` holds the wings out still and sinks
142
150
  gently toward `height` on the way to `to` (from the ground it flies the first
143
151
  stretch); `land` comes down to the ground or to a
144
- perch (`height`). Perch it with anchors:
152
+ perch (`height`), and landing above the ground its toes curl round the perch
153
+ (`grip`, cleared as it takes off). Perch it with anchors:
145
154
 
146
155
  ```js
147
156
  const branch = propAt(treeTarget, { time: 0 }, 'tree').anchor('branch')
@@ -165,6 +174,26 @@ Make your own from the family generators: `vehicle(spec)` takes:
165
174
 
166
175
  `tree(spec)` and `house(spec)` take sizes and colours.
167
176
 
177
+ **Furniture.** `chair()`, `desk()`, `bed()` and `door()` stand on the ground
178
+ facing the viewer, and their places are anchors a figure uses them at: a
179
+ chair's `seat` (ride it with `propRide({ anchor: 'seat' })`, a `seated` pose
180
+ and `offset: { y: seatHeight(height) }`), `back` and `front`; a desk's `top`,
181
+ `edge`, `drawer` and the `chair` spot in front; a bed's `mattress`, `pillow`,
182
+ `foot` and `side`; a door's `handle`, `doorway`, `front` and `beyond` (a figure
183
+ goes through from `front` to `beyond`, and the door is drawn over it until it
184
+ opens). Each takes sizes and colours (`chair({ seatHeight: 0.5 })`, `door({
185
+ hinge: 'right' })`). As surfaces (`propSurface`), their controls are edits a
186
+ beat makes: `set` or `switch` `control:open`, `control:drawer`, `control:tip`.
187
+
188
+ A `wheelchair()` is furniture that moves: a seat and back on a frame, two big
189
+ rimmed wheels, castors and footrests. It `roll`s to a place with its wheels
190
+ turning exactly the distance (in 3D, its `roll` move does the same in
191
+ metres), `brake`s with them locked, and tips back for a `wheelie`. Any
192
+ character rides its `seat` in the `wheeling` pose (`RIDING_POSES.wheeling`:
193
+ sitting up, hands down at the rims), and a pusher stands at `handles` in the
194
+ `push` pose. It is an accessory, not an age or a build: who uses it is the
195
+ story's choice, like a `cane` in a hand.
196
+
168
197
  ## Figures with props
169
198
 
170
199
  - **Riding.** `propRide({ prop, propId, propTracks, anchor: 'seat', figure, figureId, start, end, offset })`
@@ -183,6 +212,37 @@ Make your own from the family generators: `vehicle(spec)` takes:
183
212
  See the gallery cards **Road Trip**, **Windy Day**, **Helicopter**,
184
213
  **Traffic**, **Horse & Cart**, **Farmyard**, **Birds** and **3D Scene: Village**.
185
214
 
215
+ ## Scenery
216
+
217
+ `scenery(options)` is the world behind the figures: a canvas target that draws
218
+ a sky (the sun and moon on their arcs, stars at night, clouds drifting on the
219
+ wind, rain that slants with it, snow that drifts, hills or a city on the
220
+ horizon, the ground) or a room (a wall, a floor and a window on that sky). Its
221
+ values are tracks, so a day passes and weather comes and goes as keyframes,
222
+ and every frame is drawn from its time alone:
223
+
224
+ ```js
225
+ const sky = scenery({ x: 0, y: 0, width: 720, height: 400, hour: 9, clouds: 0.4, horizon: 'hills' })
226
+ sky.set('hour', { at: 0, value: 20, duration: 12000 }) // dawn to night
227
+ sky.set('wind', { at: 3000, value: 0.8, duration: 1000 })
228
+ sky.set('rain', { at: 5000, value: 0.8, duration: 1500 })
229
+ const tracks = sky.tracks('sky') // hour, wind, rain keys on 'sky'
230
+ sky.anchor('sun', 4000) // where the sun is then
231
+ ```
232
+
233
+ `hour` runs 0–24, `clouds`, `rain` and `snow` 0–1, `wind` −1 (from the right)
234
+ to 1 (from the left). The same wind streams a character's hair:
235
+ `hairFollowTracks(target, tracks, who, { wind })`. `kind: 'room'` draws a wall
236
+ and a floor with a `window` on the sky; `horizon` is `hills`, `city` (lit
237
+ windows at night) or `flat`; `colors` recolour any of it.
238
+
239
+ `scenePreset(name, { width, height })` lays out a scene as plain data (the
240
+ scenery and where the props stand) and `buildScene` builds it into targets:
241
+ `park` (a late-morning sky over hills, two trees and a bench), `street` (the end
242
+ of the afternoon against the city: houses, a car, a tree), `office` (a room
243
+ with a desk, a chair and a door) and `home` (a room at night with a bed, a
244
+ chair and a door). The Park Day card plays a day over the park.
245
+
186
246
  ## In 3D scenes
187
247
 
188
248
  Props stand in `@algorisys/tinyfly/scene-3d` scenes too:
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.98.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
28
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.100.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