@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/acting.md ADDED
@@ -0,0 +1,529 @@
1
+ # Cartoon Acting
2
+
3
+ Key poses say *what* a character does. Acting is *how* it gets there, and it is
4
+ most of the difference between a stiff procedural figure and one that feels
5
+ drawn. `poseTracks()` moves every joint at once, start to stop. `actTracks()`
6
+ takes the same keys and applies the timing habits of hand-drawn animation:
7
+
8
+ | Habit | What happens |
9
+ |---|---|
10
+ | **Anticipation** | Before a joint moves, it winds up a little the other way (an arm dips before it rises). |
11
+ | **Overshoot and settle** | It passes its target, then eases back (or wobbles, in the `snappy` style). |
12
+ | **Overlap** | The body leads and each joint further out trails: hips, then shoulders and knees, then elbows and ankles, then wrists. |
13
+ | **Eyes lead** | The eyes dart to a new look before the head and body follow, and the figure blinks as its head turns. |
14
+ | **Moving holds** | A long hold drifts slightly instead of freezing dead; the figure still ends on its last pose. |
15
+ | **Idle blinks** | Now and then during long holds. |
16
+ | **Jump squash** | When `rise` leaves the ground: squash, stretch in the air, squash on landing. |
17
+
18
+ The output is ordinary keyframe tracks, so seeking, exporting, loops and the
19
+ editor all see plain JSON. Nothing is random at play time: the small variations
20
+ (which way a hold drifts, when an idle blink falls) come from a hash of the
21
+ field and the `seed`.
22
+
23
+ ```js
24
+ import { actTracks } from '@algorisys/tinyfly/characters'
25
+
26
+ const tracks = actTracks('hero', [
27
+ { time: 0, pose: 'rest', expression: 'happy' },
28
+ { time: 900, pose: { turn: 0.6, lookX: 1 }, expression: 'confused' },
29
+ { time: 1800, pose: 'point' },
30
+ { time: 3200, pose: 'wave' },
31
+ ], { style: 'snappy' })
32
+ ```
33
+
34
+ Keys are the same as `poseTracks()` keys: a named pose or the joints that change,
35
+ an optional expression and an optional easing (which replaces the style's action
36
+ ease for that move). Track ids are the same too (`hero-rightShoulder`), so
37
+ switching between them is a one-word change.
38
+
39
+ For the v2 characters, `actCharacterTracks(target, keys, options)` takes
40
+ `characterPoseTracks()` keys.
41
+
42
+ ## Styles
43
+
44
+ | Style | Feel |
45
+ |---|---|
46
+ | `full` (default) | Classic feature animation: soft wind-ups, overshoot that settles smoothly, generous overlap. |
47
+ | `snappy` | Theatrical cartoon timing: bigger wind-ups held a beat, a fast action that overshoots and wobbles to a stop. |
48
+ | `limited` | TV and Pencilmation-style: little anticipation, no overshoot, crisp holds. Pairs well with drawing on twos. |
49
+ | `none` | The keys as written: the same tracks as `poseTracks()`. |
50
+
51
+ Tune any of them by changing values on a preset:
52
+
53
+ ```js
54
+ actTracks('hero', keys, { style: { base: 'snappy', overlap: 60, overshoot: 0.2 } })
55
+ ```
56
+
57
+ The values are in `ActingStyle`: `anticipation` (share of a move's size),
58
+ `anticipationTime` and `hold` (shares of its time), `overshoot`, `settle` (ms),
59
+ `settleEase`, `actionEase`, `overlap` (ms per step out a chain), `eyeLead` and
60
+ `eyeDart` (ms), `drift`, `blinks` and `jumpSquash`.
61
+
62
+ What leads, what drags and how far each joint may wind up is an `ActingRig`:
63
+ `STICK_ACTING_RIG` for the stick figure, `HUMAN_ACTING_RIG` for the v2 human.
64
+ Pass `rig` to act a body of your own. The core, `actKeyframes(keys, rig, options)`,
65
+ works on any record of numbers.
66
+
67
+ A few rules keep the result predictable:
68
+
69
+ - Moves shorter than 160 ms are not wound up, and moves shorter than 120 ms land without an overshoot. There is no time for either to read.
70
+ - A move's delay is at most half the time between its two keys, so a quick move still lands near its key.
71
+ - A settle takes at most half the time to the next key.
72
+ - If the keys animate `blink` themselves, the pass leaves blinking alone; if they animate `stretch`, it adds no jump squash.
73
+
74
+ ## Gags
75
+
76
+ Some cartoon moments are their own timing: the take, the double take, the
77
+ wind-up before a zip-off. They come as data, built on the pose they start from.
78
+ You splice them into a key list:
79
+
80
+ ```js
81
+ import { actTracks, gag, gagDuration, resolvePoseKeys } from '@algorisys/tinyfly/characters'
82
+
83
+ const opening = [{ time: 0, pose: 'rest' }, { time: 1800, pose: 'point' }]
84
+ const from = resolvePoseKeys(opening).at(-1)
85
+ const keys = [
86
+ ...opening,
87
+ ...gag('take', { at: 2600, from }),
88
+ { time: 2600 + gagDuration('take') + 900, pose: 'shrug' },
89
+ ]
90
+ actTracks('hero', keys, { style: 'snappy' })
91
+ ```
92
+
93
+ | Gag | What happens |
94
+ |---|---|
95
+ | `take` | Squash down in a squint, shoot up stretched with eyes popping, hang, land squashed, end surprised. |
96
+ | `doubleTake` | Glance, look away unbothered, snap back in shock with a little hop. |
97
+ | `windUp` | Rear back with a knee up and arms cocked, hold, pitch forward ready to run. |
98
+ | `land` | Squash on contact with the ground and spring back up. |
99
+ | `tremble` | A frightened shiver: fast small shakes with wide eyes. |
100
+ | `deflate` | A sigh: the body sags, shoulders and head drop. |
101
+
102
+ The gag's keys are marked `act: false`, so the acting pass leaves its timing as
103
+ written (only the move onto its first pose is acted). Mark any key of your own
104
+ the same way to keep it exact. `speed` stretches a gag in time (`2` is twice as
105
+ long).
106
+
107
+ ## Speed lines, dust and stars
108
+
109
+ ```js
110
+ import { drawStickSmear, drawDustPuff, drawImpactStars } from '@algorisys/tinyfly/characters'
111
+
112
+ const hero = stickFigureTarget({ x: 640, y: 600, style })
113
+ export default {
114
+ // ...
115
+ targets: { hero },
116
+ background(ctx, frame) {
117
+ // Under the figure: streaks behind its fast hands, feet and head.
118
+ drawStickSmear(ctx, hero, frame, 'hero', { color: '#333', length: 110 })
119
+ },
120
+ draw(ctx, frame) {
121
+ drawDustPuff(ctx, { x: 640, y: 600 }, (frame.time - 3500) / 500, { size: 120 })
122
+ },
123
+ }
124
+ ```
125
+
126
+ `drawStickSmear()` asks where the figure was over the last `length` ms
127
+ (`frame.stateAt`, as trails do), and streaks only the parts moving faster than
128
+ `threshold` figure heights a second. The streaks fade in above the threshold, so
129
+ they never pop. Frames are drawn the same in any order. `parts` chooses among
130
+ `hands`, `toes`, `head` and `body`. `drawSpeedLines(ctx, points, style)` streaks
131
+ any path.
132
+
133
+ `drawDustPuff()` and `drawImpactStars()` take a `progress` from 0 to 1 and draw
134
+ nothing outside that range, so passing `(time - start) / length` is enough.
135
+
136
+ ## Drawing on twos
137
+
138
+ Hand-drawn animation is usually drawn "on twos": 12 drawings a second, each
139
+ shown for two frames of 24 fps film. Animating on every frame looks smooth but
140
+ digital, especially against a pencil line that boils at 8 drawings a second.
141
+
142
+ A video scene's `drawingRate` holds the timeline to that many drawings a second.
143
+ The frame rate stays as set, and so does the time passed to `draw` and
144
+ `background`, so a camera move drawn there can stay smooth:
145
+
146
+ ```js
147
+ export default { width: 1280, height: 720, fps: 24, drawingRate: 12, timeline, targets }
148
+ ```
149
+
150
+ In the browser, `heldTime(time, 12)` (from `@algorisys/tinyfly`) gives the
151
+ same held time to evaluate a timeline at.
152
+
153
+ ## Line of action
154
+
155
+ `bend` curves the stick figure's spine, in degrees from hips to neck: positive
156
+ curls forward (the way `lean` tips), negative arches back. Unlike `lean`, which
157
+ tips a straight back, the curve spreads along the spine, and the chest, arms
158
+ and head ride on its end. A slump, a recoil and a cheer each read from the
159
+ curve before anything else.
160
+
161
+ ```js
162
+ pose({ bend: 18, headTilt: 10 }) // a slump
163
+ pose({ bend: -14, leftShoulder: 150, rightShoulder: 150 }) // arched back, arms up
164
+ ```
165
+
166
+ It is a pose field like any other, so it blends, keys and acts (it leads with
167
+ the hips, winds up and overshoots). The gags use it: a take arches back as it
168
+ shoots up and curls on landing. At 0 the figure is drawn exactly as before.
169
+
170
+ ## Gaits
171
+
172
+ How a figure walks is data: `GAITS` has `walk` (the plain walk, the same as
173
+ `walkPose()`), `bouncy`, `doubleBounce` (two bobs a step), `sneak` (tiptoe in
174
+ a crouch, paws up), `strut` (chest out), `tired` (slumped and dragging) and
175
+ `run` (knees high, arms pumping, off the ground between steps).
176
+
177
+ ```js
178
+ gaitPose('sneak', phase, base) // a pose at a phase of the cycle
179
+ gaitStrideLength('sneak', height) // ground per cycle, so feet stay planted
180
+ ```
181
+
182
+ A gait is a handful of numbers (`swing`, `knee`, `arm`, `elbow`, `forearm`,
183
+ `shoulder`, `lean`, `bend`, `headTilt`, `bounce`, `bounces`, `squash`,
184
+ `crouch`, `tiptoe`, `sway`), so you can write your own and pass it in place of
185
+ a name. On a `stickFigureTarget` the `gait` prop picks one, and a string track
186
+ switches it: `{ property: 'gait', keyframes: [{ time: 0, value: 'walk' }, { time: 3000, value: 'run' }] }`.
187
+
188
+ ## Lip-sync
189
+
190
+ `lipSyncKeyframes({ text, start, end })` reads a line as mouth shapes:
191
+ vowels open the mouth in their shape, m/b/p close it, f/v bite the lip, and
192
+ pauses rest it. The shapes share the line's time by how long each sound tends
193
+ to take. It reads Latin script and Devanagari: inherent vowels, matras and
194
+ virama, with lip consonants (प फ ब भ म) closing the mouth. It writes the
195
+ `mouth` and `mouthWidth` fields, which both figure systems have.
196
+
197
+ ```js
198
+ lipSyncTracks('hero', [{ text: 'Where did my pot go?', start: 4000, end: 5400 }])
199
+ // Over acted tracks: the face carries on around the line (a gape, a grin).
200
+ lipSyncOver('hero', actTracks('hero', keys), lines)
201
+ ```
202
+
203
+ `VISEMES` holds the shapes and `soundsOf(text)` the sounds, for drawing your
204
+ own mouths.
205
+
206
+ ## Beat scripts
207
+
208
+ `scriptTracks()` takes a story written as beats (what the figure does, not
209
+ when its joints move) and compiles it into tracks:
210
+
211
+ ```js
212
+ const { tracks, duration, lines, beats } = scriptTracks('hero', [
213
+ { do: 'walk', to: 640, mood: 'happy' },
214
+ { do: 'look', toward: 900, mood: 'confused' },
215
+ { do: 'take' },
216
+ { do: 'say', say: 'Is that box ticking?', mood: 'worried' },
217
+ { do: 'sneak', to: 820, mood: 'scared' },
218
+ { do: 'face', toward: 0 },
219
+ { do: 'run', to: 120, say: 'Nope!' },
220
+ ], { from: 180, height: 220, style: 'snappy' })
221
+ ```
222
+
223
+ Each beat starts when the one before ends (or at `at`) and lasts its action's
224
+ own length (or `for`).
225
+
226
+ | `do` | What happens |
227
+ |---|---|
228
+ | a gait name, with `to` | Walks to a scene x at the gait's pace, feet planted. It turns round first if the place is behind it. Writes `x` (an offset from `from`), `walk`, `walking`, `gait` and `facing`. |
229
+ | a pose name (`wave`, `point`, `cheer`, `sit`…) or `stand` | Moves into the pose and holds it. The figure keeps the way it is turned unless the pose sets its own. |
230
+ | a gag name (`take`, `doubleTake`…) | Splices the gag in, built on the current pose. |
231
+ | `look`, with `toward` | Turns the head and eyes toward a scene x, `viewer`, `ahead` or `back`. |
232
+ | `face`, with `toward` | Turns the whole figure, turning round if needed. |
233
+ | `zip`, with `to` | The cartoon exit: winds up, wheels its legs in place, then shoots off to `to`. The script's `effects` say where to draw the dust it leaves hanging. |
234
+ | `say`, with `say` | Lip-syncs the line, with small head nods and brow lifts, for as long as the line takes. |
235
+ | `hold` | Holds (the acting pass drifts long holds). |
236
+ | `leap`, with `to` and `onto` | Crouches, springs, arcs over the higher floor and lands squashed on a new floor (`onto`, a scene y). Writes a `y` track (an offset from `ground`). Dust where it lands. |
237
+ | `point`, with `target` | Turns toward the target if it is behind, then aims a straight arm and the eyes at it. Without `target` it is the plain `point` pose. |
238
+ | `swipe`, with `target` | Steps in and winds the arm up behind the head, then slides along the target with the arm out, so the hand crosses it edge to edge (`left` to `right`, or back), follows through and settles. |
239
+ | `grab`, with `target` | Steps to where its straight arm just reaches the target (crouching over something low), closes its hand on it, and lifts it overhead. |
240
+ | `throw`, with `to` or `target` | Winds the arm back over the shoulder and throws forward and up; `release` is when it lets go. |
241
+ | `kick`, with `target` | Steps to a leg's length from it, draws the leg back and kicks through it, arms out for balance. |
242
+ | `put`, with `target` | Steps to where the straight arm reaches the spot, sets the thing down there, and brings the arm back. |
243
+ | `write`, with `target` | Reaches a pen to the spot and scribbles along it left to right (the arm bends to follow the line); when the spot is wider than it reaches, it moves along with the pen. `release` is when it is done. |
244
+ | `push`, with `target` and `to` | Sets both hands on the near side and walks it along (the `shove` gait: short steps, steady arms) until its centre is at `to`. |
245
+ | `duck`, `lie` (poses) | Ducks low with arms over the head; lies on its back on the floor, hands behind the head. |
246
+
247
+ Any beat can take `say` (a line said while it happens), `mood` (an
248
+ expression) and `pose` (joints to change). The result carries the spoken lines
249
+ with their times (for captions), when each beat starts and ends (for camera
250
+ shots), and `effects`: dust cues for where a take lands and where a zip
251
+ leaves, with a time, a scene x and y and a length, ready for `drawDustPuff`.
252
+
253
+ Any beat can also take `onto` (a scene y): the figure is carried to that floor
254
+ over the beat, as when the line it stands on moves up.
255
+
256
+ ## Your own actions, gaits and personas
257
+
258
+ Behaviours of your own are plain values passed where they are used; nothing
259
+ is registered globally.
260
+
261
+ **Actions** come in two kinds. Built from other beats (a macro):
262
+
263
+ ```js
264
+ const nervousPoint = defineAction({
265
+ summary: 'Trembles, then points at the target.',
266
+ needs: ['target'],
267
+ beats: (beat) => [{ do: 'tremble' }, { do: 'point', target: beat.target }],
268
+ })
269
+ ```
270
+
271
+ Or written as timed pose steps from the pose it starts on, like a gag:
272
+
273
+ ```js
274
+ const facepalm = defineAction({
275
+ summary: 'Drops its face into its hand.',
276
+ steps: (from) => [
277
+ { after: 220, pose: { rightShoulder: 150, rightElbow: 155, headTilt: from.headTilt - 10 }, easing: 'ease-out' },
278
+ { after: 900, pose: { headTilt: from.headTilt - 16 } },
279
+ ],
280
+ })
281
+ ```
282
+
283
+ **Gaits** are data, like the built-in ones: `defineGait({ swing, knee, arm,
284
+ elbow, lean, cycle?, sway?, … })` (degrees; `cycle` is ms per two steps).
285
+
286
+ Pass them to `scriptTracks(id, beats, { actions, gaits })`, `checkBeats(beats,
287
+ { actions, gaits })` and the figure that draws them
288
+ (`stickFigureTarget({ …, cast: { actions, gaits } })`, which lists them in
289
+ `describeTarget`). A custom name may not reuse a built-in one. A beats action's
290
+ first beat keeps the original's `at`, and its `mood` and `say` go to the first
291
+ beat that has none; the expanded beats are checked too.
292
+
293
+ **Personas** bundle a character: its look, acting style, gait, usual face,
294
+ stance and own actions.
295
+
296
+ ```js
297
+ const junior = persona({
298
+ name: 'Junior', summary: 'A nervous junior developer',
299
+ look: { color: '#89b4fa', rubber: 0.7 }, height: 92,
300
+ acting: 'full', gait: 'sneak', mood: 'worried', stance: 'rest',
301
+ actions: { facepalm },
302
+ })
303
+ const hero = junior.figure({ x: 600, y: 300, facing: -1 })
304
+ const script = junior.script('hero', [
305
+ { do: 'go', to: 300 }, // walks in its own gait
306
+ { do: 'facepalm', say: 'Oh no.' },
307
+ { do: 'stand' }, // back to its stance and usual face
308
+ ], { from: 600, ground: 300, facing: -1 })
309
+ junior.check(beats) // its own actions count as known
310
+ junior.describe() // { name, summary, habits, actions, own }
311
+ junior.handPath('hero', script.tracks, { x: 600, y: 300, start, end })
312
+ ```
313
+
314
+ `go` is a built-in action: it walks in the persona's gait (in `walk` without
315
+ one). Scripts are deterministic, so two personas can be timed against each
316
+ other by reading one's `beats` before writing the other's (the **Code Review**
317
+ example does).
318
+
319
+ ## Acting on code
320
+
321
+ `codePanel()` makes a code listing a scene object. Its layout is plain
322
+ arithmetic (each character `charWidth` em wide, lines `lineHeight` em apart),
323
+ never measured from a font, so every line and word is a known place in the
324
+ scene in a browser, a worker or a build script. Beats aim at those places, and
325
+ the beats that touch something report when: `contact` (when a leap lands, a
326
+ pointing arm arrives or a swipe's hand reaches the target) and `release`
327
+ (when the swipe's hand has crossed it). The code reacts on those frames.
328
+
329
+ ```js
330
+ const code = codePanel({ code: source, language: 'go', x: 30, y: 70, fontSize: 17 })
331
+ const dead = code.line(7) // { x, y, left, right, top, bottom, width, height }
332
+ const script = scriptTracks('hero', [
333
+ { do: 'walk', to: dead.right + 60 },
334
+ { do: 'point', target: dead, say: 'Unreachable!', mood: 'angry' },
335
+ { do: 'swipe', target: dead, mood: 'furious' },
336
+ { do: 'leap', to: code.token(6, 'return').x, onto: code.line(6).top },
337
+ { do: 'lie', for: 1800 },
338
+ ], { from: 720, ground: code.box.bottom, height: 100, facing: -1 })
339
+
340
+ const [, point, swipe] = script.beats
341
+ code.highlight(7, { at: point.contact })
342
+ code.remove(7, { at: swipe.contact, duration: swipe.release - swipe.contact, from: 'right' })
343
+ const tracks = [...script.tracks, ...code.tracks('code')] // `code.target` is the canvas target
344
+ ```
345
+
346
+ | Anchor | What it is |
347
+ |---|---|
348
+ | `code.line(n, time?)` | Line `n`'s text (numbered from 1). Stand on `top`, point at `x`, `y`. With a `time`, after the gaps of removed lines above it have closed. |
349
+ | `code.token(n, text, occurrence?, time?)` | A word on a line. |
350
+ | `code.box` | The whole panel. |
351
+
352
+ | Edit | What it does |
353
+ |---|---|
354
+ | `highlight(n, { at, on? })` | Tints a line (`on: false` clears it). |
355
+ | `strike(n, { at })` | Strikes it through, left to right. |
356
+ | `remove(n, { at, duration, style?, from?, close? })` | Takes it away, then the lines below close the gap. `style`: `wipe` (default) erases it from `left` or `right`; `fly` knocks it off the panel (pushed from `from`), blurring and fading as it goes; `blur` takes it out of focus where it is. |
357
+ | `type(n, { at })` | Types in a line given in `hidden`, character by character. |
358
+
359
+ ### Words that come loose
360
+
361
+ `code.piece(n, text)` makes a word a piece that can leave its line. A grabbed
362
+ word follows the figure's hand: `handPath()` samples where the hand is from
363
+ the script's tracks, and `follow()` carries the piece along it. `fling()`
364
+ throws or kicks it away on a spinning arc (by default at the speed it was
365
+ moving along its path), and `write()` types new text into the gap it left,
366
+ the rest of the line making room.
367
+
368
+ ```js
369
+ const word = code.piece(3, 'var')
370
+ const script = scriptTracks('hero', [
371
+ { do: 'grab', target: word.home },
372
+ { do: 'throw', to: 680 },
373
+ ], { from: 560, ground: code.line(5).top, height: 100 })
374
+ const [grab, toss] = script.beats
375
+ code.follow(word, handPath('hero', script.tracks, { x: 560, y: code.line(5).top, style: { height: 100 }, start: grab.contact, end: toss.release }))
376
+ code.fling(word, { at: toss.release })
377
+ code.write(word, 'let', { at: toss.release + 500 })
378
+ // A kick: code.fling(other, { at: kick.contact, velocity: { x: 0.7, y: -0.8 } })
379
+ ```
380
+
381
+ | Piece edit | What it does |
382
+ |---|---|
383
+ | `follow(piece, path)` | Its centre follows timed scene points (a `handPath()`). |
384
+ | `fling(piece, { at, velocity?, spin?, gravity?, duration? })` | Flies off on a ballistic arc, spinning, and fades. |
385
+ | `move(piece, { at, to })` | Moves its centre to a scene point (home is `piece.home`). |
386
+ | `write(piece, text, { at })` | Types new text into its place in the line. |
387
+ | `drop(piece, n, column, { at })` | Puts it into line `n` before `column`: it moves there as the line opens room, and its old place closes. |
388
+
389
+ New text goes into a line with `insert(n, column, text, { at, duration })`:
390
+ the line opens room and the text is typed in. `spot(n, column, width?)` is
391
+ where a place in a line is (after the room earlier inserts opened), for a
392
+ `put` or a `write` to aim at:
393
+
394
+ ```js
395
+ const semicolon = code.piece(5, ';')
396
+ const end = code.spot(4, code.lines[3].length) // just past the end of line 4
397
+ const mutSpot = code.spot(2, 8, 4) // four characters before column 8 of line 2
398
+ // beats: { do: 'grab', target: semicolon.home }, { do: 'put', target: end }, { do: 'write', target: mutSpot }
399
+ code.follow(semicolon, handPath('hero', script.tracks, { …, start: grab.contact, end: put.contact }))
400
+ code.drop(semicolon, 4, code.lines[3].length, { at: put.contact })
401
+ code.insert(2, 8, 'mut ', { at: write.contact, duration: write.release - write.contact })
402
+ ```
403
+
404
+ To slide a word along its own line, `push` it to where `landing()` says it
405
+ will end up, and `drop()` it into its own line over the push: it slides at the
406
+ push's pace, and the text it passes closes up behind it.
407
+
408
+ ```js
409
+ const not = code.piece(3, 'not ') // "if not user is None:"
410
+ const beforeNone = code.lines[2].indexOf('None')
411
+ // beat: { do: 'push', target: not.home, to: code.landing(not, 3, beforeNone).x }
412
+ code.drop(not, 3, beforeNone, { at: push.contact, duration: push.release - push.contact }) // "if user is not None:"
413
+ ```
414
+
415
+ ### Riding a line
416
+
417
+ Beats are written against the code as laid out. When a gap closes above the
418
+ line a figure stands on, `ride()` carries it up with that line (and a hop
419
+ off a line that has moved lands back on it):
420
+
421
+ ```js
422
+ code.remove(2, { at: swipe.contact, duration: 600, style: 'blur' })
423
+ const tracks = [...code.ride(script.tracks, 'hero', { ground }), ...code.tracks('code')]
424
+ ```
425
+
426
+ Record the panel's edits first: `ride()` reads the moves they make. On the
427
+ script's own `ground` (not a line), nothing carries the figure.
428
+
429
+ Edits take a line or a list of lines, and are recorded on the panel; `tracks(id)`
430
+ writes them out as one track per prop (`line.N.highlight`, `line.N.strike`,
431
+ `line.N.wipe`, `line.N.reveal`, `line.N.shift`). Syntax colours come from small
432
+ keyword lists for Go, Rust, C#, JavaScript, TypeScript and Python (strings,
433
+ numbers and line comments too); `plain` leaves the text uncoloured.
434
+
435
+ ## Camera
436
+
437
+ Video scenes can be seen through a camera: `camera: true` reads the tracks of
438
+ the `Camera` target (the editor's camera uses the same name). `x` and `y`
439
+ pan, `scale` zooms and `rotate` rolls about the stage centre, and `shakeX`,
440
+ `shakeY` and `shakeRotate` add on top, so a shake never disturbs a pan. A new
441
+ `overlay` step draws in screen space after everything else, for captions and
442
+ titles that should not move with the camera.
443
+
444
+ `cameraTracks()` (in `@algorisys/tinyfly`) compiles shots into those tracks:
445
+
446
+ ```js
447
+ cameraTracks([
448
+ { at: 2000, duration: 500, frame: { focus: { x: 760, y: 470 }, scale: 1.25 } }, // push in
449
+ { at: 3300, duration: 0, frame: { focus: { x: 640, y: 440 }, scale: 1.6 } }, // a cut (crash zoom)
450
+ { at: 3900, duration: 450, shake: { strength: 14 } }, // an impact
451
+ { at: 7000, until: 9000, follow: { x: heroX.keyframes, y: 470, lag: 220 } }, // follow a runner
452
+ { at: 9200, duration: 600, frame: {} }, // back to the full frame
453
+ ], { stage: { width: 1280, height: 720 } })
454
+ ```
455
+
456
+ A `frame` shot moves so `focus` sits at the centre at `scale` (and `rotate`);
457
+ a duration of 0 cuts. A `shake` dies away over its duration and is seeded, so
458
+ renders repeat exactly. A `follow` keeps a subject's x (its x track's
459
+ keyframes) centred, `lag` ms behind it, with an optional `lead`. Shots play in
460
+ time order, and a later one takes over from an earlier one.
461
+
462
+ In the browser or your own canvas code, `applyCamera(ctx, cameraFromValues(values), stage)`
463
+ (from `@algorisys/tinyfly/characters`, `@algorisys/tinyfly/adapters` or the
464
+ browser bundle) applies a view to any canvas, and `cameraPoint(view, stage, point)` says where a scene
465
+ point lands on screen (the pencil story maps the drawing hand's strokes this
466
+ way, so the hand stays on the page while the camera moves).
467
+
468
+ ## Examples
469
+
470
+ - `examples/headless-video/cartoon-acting.mjs`: the same keys through
471
+ `poseTracks()` and `actTracks()`, side by side, with a take, speed lines
472
+ and a dust puff, drawn on twos.
473
+ - `examples/headless-video/beat-script.mjs`: a beat script with gaits, a
474
+ take, dialogue, a sneak and a run, filmed by camera shots (a push-in, a
475
+ crash zoom, a shake and a follow).
476
+ - `examples/pencil-story-hindi/`: the thirsty-traveller story, acted. It has a
477
+ take and a double take, a tired walk and a bouncy one, a lip-synced line in
478
+ Hindi, and camera pushes, with the animator's hand drawing through the
479
+ camera.
480
+ - The **Cartoon Acting** card in the website gallery: the script live in the
481
+ browser, with pickers for the acting style and the walk, and toggles for
482
+ drawing on twos, speed lines and the camera.
483
+
484
+ ```bash
485
+ npx tinyfly video examples/headless-video/beat-script.mjs
486
+ ```
487
+
488
+ ## In the editor
489
+
490
+ The Character element has an **Acting** section: a style, **🎭 Act the keyed
491
+ poses**, gags, gaits with a distance, lines to say, and the drawing rate (see
492
+ the [editor guide](editor-guide.md#characters)). With acting on, the element
493
+ keeps its plain key poses (`acting.keys`) and its tracks are generated from
494
+ them, so keying a pose, adding a gag or a walk, or saying a line re-acts the
495
+ whole performance.
496
+
497
+ ## Characters (v2): native motion
498
+
499
+ The v2 human has its own line of action, gaits and gags, posed in the
500
+ character's frame (forward is the way it faces, in 3D), so they read from
501
+ every view (front, side, back, the other side) with no mirroring:
502
+
503
+ - **`bend`**: the back curved forward (+) or arched (−). It grows up the spine
504
+ and carries on into the neck, unlike `lean`, which tips a straight back.
505
+ - **`humanGaitPose(gait, phase, base)`** and **`humanGaitStrideLength(gait, height)`**:
506
+ the same `GAITS` data as the stick figure's, driving the human's legs, arms,
507
+ back and bounce. One spec, two rigs.
508
+ - **`humanGag(name, { at, from })`** and **`HUMAN_GAGS`**: take, double take,
509
+ wind-up, land, tremble and deflate, written for this body.
510
+
511
+ ```js
512
+ import { humanGag, humanGaitPose, actCharacterTracks } from '@algorisys/tinyfly/characters'
513
+
514
+ const keys = [{ time: 0, pose: { turn: 1 } }, ...humanGag('take', { at: 600, from: { turn: 1 } })]
515
+ const tracks = actCharacterTracks('hero', keys, { style: 'snappy' })
516
+ ```
517
+
518
+ The editor's gags and walks use these. Builds (`proportions`, `headSize`,
519
+ `shoulderWidth`, `hipWidth`) change the body, and the same motion fits each.
520
+
521
+ The timeline's `drawingRate` (`TimelineConfig.drawingRate`, set with
522
+ `timeline.drawingRate = 12`) holds every value on its drawing, wherever the
523
+ timeline plays: editor previews, players, embeds and exports.
524
+
525
+ ## Not yet
526
+
527
+ - A code panel in the editor (a Code element whose lines and words snap beats)
528
+ - Beat scripts for v2 characters (`scriptTracks` drives the stick figure)
529
+ - Follow-through on hair, tails and ears (character-system milestones 3 and 5)