@algorisys/tinyfly 0.92.0 → 0.93.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 +7 -6
- package/bin/tinyfly.mjs +34 -1
- package/docs/2d-animation-roadmap.md +191 -0
- package/docs/3d-rotations.md +164 -0
- package/docs/3d-support-plan.md +628 -0
- package/docs/DEPLOYMENT.md +414 -0
- package/docs/acting.md +466 -0
- package/docs/api-reference.md +2353 -0
- package/docs/camera.md +94 -0
- package/docs/cartoon-hands.md +96 -0
- package/docs/character-system-m1.md +218 -0
- package/docs/character-system-plan.md +384 -0
- package/docs/dance.md +315 -0
- package/docs/editor-guide.md +1249 -0
- package/docs/examples.md +765 -0
- package/docs/extending.md +168 -0
- package/docs/file-format.md +690 -0
- package/docs/getting-started.md +314 -0
- package/docs/grid-and-snapping.md +64 -0
- package/docs/gsap-compat.md +1241 -0
- package/docs/llm-guide.md +123 -0
- package/docs/maps.md +116 -0
- package/docs/onion-skinning.md +41 -0
- package/docs/pen-tool.md +65 -0
- package/docs/polygon-star.md +44 -0
- package/docs/scene-3d.md +299 -0
- package/docs/scroll-animation.md +314 -0
- package/docs/shape-morph.md +61 -0
- package/docs/sprite-sheet-export.md +54 -0
- package/docs/symbols-and-library.md +137 -0
- package/docs/teaching.md +348 -0
- package/docs/video-rendering.md +728 -0
- package/lib/addons/adapters.js +22 -18
- package/lib/addons/characters.js +2694 -1809
- package/lib/addons/target-properties-BtN9skb-.js +142 -0
- package/lib/browser/tinyfly.iife.js +9 -4
- package/lib/browser/tinyfly.js +6498 -5483
- package/lib/browser/tinyfly.umd.js +9 -4
- package/lib/engine/tinyfly-engine.js +286 -258
- package/lib/engine/tinyfly-engine.umd.cjs +2 -2
- package/lib/types/adapters/canvas/canvas-adapter.d.ts +6 -0
- package/lib/types/adapters/canvas/index.d.ts +1 -0
- package/lib/types/adapters/canvas/target-properties.d.ts +68 -0
- package/lib/types/characters/acting/beat-check.d.ts +95 -0
- package/lib/types/characters/acting/hand-path.d.ts +32 -0
- package/lib/types/characters/acting/index.d.ts +2 -0
- package/lib/types/characters/acting/script.d.ts +66 -7
- package/lib/types/characters/capabilities.d.ts +50 -0
- package/lib/types/characters/code-panel.d.ts +201 -0
- package/lib/types/characters/figure-actions.d.ts +11 -0
- package/lib/types/characters/figure-props.d.ts +87 -0
- package/lib/types/characters/gaits.d.ts +8 -0
- package/lib/types/characters/index.d.ts +3 -0
- package/lib/types/characters/stick-figure.d.ts +2 -0
- package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
- package/lib/types/engine/authoring/index.d.ts +1 -0
- package/llms-full.txt +12548 -0
- package/llms.txt +57 -0
- package/package.json +6 -2
- package/skills/tinyfly/SKILL.md +64 -0
- package/lib/addons/camera-C7bZOWMB.js +0 -33
package/docs/acting.md
ADDED
|
@@ -0,0 +1,466 @@
|
|
|
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
|
+
## Acting on code
|
|
257
|
+
|
|
258
|
+
`codePanel()` makes a code listing a scene object. Its layout is plain
|
|
259
|
+
arithmetic (each character `charWidth` em wide, lines `lineHeight` em apart),
|
|
260
|
+
never measured from a font, so every line and word is a known place in the
|
|
261
|
+
scene in a browser, a worker or a build script. Beats aim at those places, and
|
|
262
|
+
the beats that touch something report when: `contact` (when a leap lands, a
|
|
263
|
+
pointing arm arrives or a swipe's hand reaches the target) and `release`
|
|
264
|
+
(when the swipe's hand has crossed it). The code reacts on those frames.
|
|
265
|
+
|
|
266
|
+
```js
|
|
267
|
+
const code = codePanel({ code: source, language: 'go', x: 30, y: 70, fontSize: 17 })
|
|
268
|
+
const dead = code.line(7) // { x, y, left, right, top, bottom, width, height }
|
|
269
|
+
const script = scriptTracks('hero', [
|
|
270
|
+
{ do: 'walk', to: dead.right + 60 },
|
|
271
|
+
{ do: 'point', target: dead, say: 'Unreachable!', mood: 'angry' },
|
|
272
|
+
{ do: 'swipe', target: dead, mood: 'furious' },
|
|
273
|
+
{ do: 'leap', to: code.token(6, 'return').x, onto: code.line(6).top },
|
|
274
|
+
{ do: 'lie', for: 1800 },
|
|
275
|
+
], { from: 720, ground: code.box.bottom, height: 100, facing: -1 })
|
|
276
|
+
|
|
277
|
+
const [, point, swipe] = script.beats
|
|
278
|
+
code.highlight(7, { at: point.contact })
|
|
279
|
+
code.remove(7, { at: swipe.contact, duration: swipe.release - swipe.contact, from: 'right' })
|
|
280
|
+
const tracks = [...script.tracks, ...code.tracks('code')] // `code.target` is the canvas target
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
| Anchor | What it is |
|
|
284
|
+
|---|---|
|
|
285
|
+
| `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. |
|
|
286
|
+
| `code.token(n, text, occurrence?, time?)` | A word on a line. |
|
|
287
|
+
| `code.box` | The whole panel. |
|
|
288
|
+
|
|
289
|
+
| Edit | What it does |
|
|
290
|
+
|---|---|
|
|
291
|
+
| `highlight(n, { at, on? })` | Tints a line (`on: false` clears it). |
|
|
292
|
+
| `strike(n, { at })` | Strikes it through, left to right. |
|
|
293
|
+
| `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. |
|
|
294
|
+
| `type(n, { at })` | Types in a line given in `hidden`, character by character. |
|
|
295
|
+
|
|
296
|
+
### Words that come loose
|
|
297
|
+
|
|
298
|
+
`code.piece(n, text)` makes a word a piece that can leave its line. A grabbed
|
|
299
|
+
word follows the figure's hand: `handPath()` samples where the hand is from
|
|
300
|
+
the script's tracks, and `follow()` carries the piece along it. `fling()`
|
|
301
|
+
throws or kicks it away on a spinning arc (by default at the speed it was
|
|
302
|
+
moving along its path), and `write()` types new text into the gap it left,
|
|
303
|
+
the rest of the line making room.
|
|
304
|
+
|
|
305
|
+
```js
|
|
306
|
+
const word = code.piece(3, 'var')
|
|
307
|
+
const script = scriptTracks('hero', [
|
|
308
|
+
{ do: 'grab', target: word.home },
|
|
309
|
+
{ do: 'throw', to: 680 },
|
|
310
|
+
], { from: 560, ground: code.line(5).top, height: 100 })
|
|
311
|
+
const [grab, toss] = script.beats
|
|
312
|
+
code.follow(word, handPath('hero', script.tracks, { x: 560, y: code.line(5).top, style: { height: 100 }, start: grab.contact, end: toss.release }))
|
|
313
|
+
code.fling(word, { at: toss.release })
|
|
314
|
+
code.write(word, 'let', { at: toss.release + 500 })
|
|
315
|
+
// A kick: code.fling(other, { at: kick.contact, velocity: { x: 0.7, y: -0.8 } })
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
| Piece edit | What it does |
|
|
319
|
+
|---|---|
|
|
320
|
+
| `follow(piece, path)` | Its centre follows timed scene points (a `handPath()`). |
|
|
321
|
+
| `fling(piece, { at, velocity?, spin?, gravity?, duration? })` | Flies off on a ballistic arc, spinning, and fades. |
|
|
322
|
+
| `move(piece, { at, to })` | Moves its centre to a scene point (home is `piece.home`). |
|
|
323
|
+
| `write(piece, text, { at })` | Types new text into its place in the line. |
|
|
324
|
+
| `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. |
|
|
325
|
+
|
|
326
|
+
New text goes into a line with `insert(n, column, text, { at, duration })`:
|
|
327
|
+
the line opens room and the text is typed in. `spot(n, column, width?)` is
|
|
328
|
+
where a place in a line is (after the room earlier inserts opened), for a
|
|
329
|
+
`put` or a `write` to aim at:
|
|
330
|
+
|
|
331
|
+
```js
|
|
332
|
+
const semicolon = code.piece(5, ';')
|
|
333
|
+
const end = code.spot(4, code.lines[3].length) // just past the end of line 4
|
|
334
|
+
const mutSpot = code.spot(2, 8, 4) // four characters before column 8 of line 2
|
|
335
|
+
// beats: { do: 'grab', target: semicolon.home }, { do: 'put', target: end }, { do: 'write', target: mutSpot }
|
|
336
|
+
code.follow(semicolon, handPath('hero', script.tracks, { …, start: grab.contact, end: put.contact }))
|
|
337
|
+
code.drop(semicolon, 4, code.lines[3].length, { at: put.contact })
|
|
338
|
+
code.insert(2, 8, 'mut ', { at: write.contact, duration: write.release - write.contact })
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
To slide a word along its own line, `push` it to where `landing()` says it
|
|
342
|
+
will end up, and `drop()` it into its own line over the push: it slides at the
|
|
343
|
+
push's pace, and the text it passes closes up behind it.
|
|
344
|
+
|
|
345
|
+
```js
|
|
346
|
+
const not = code.piece(3, 'not ') // "if not user is None:"
|
|
347
|
+
const beforeNone = code.lines[2].indexOf('None')
|
|
348
|
+
// beat: { do: 'push', target: not.home, to: code.landing(not, 3, beforeNone).x }
|
|
349
|
+
code.drop(not, 3, beforeNone, { at: push.contact, duration: push.release - push.contact }) // "if user is not None:"
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
### Riding a line
|
|
353
|
+
|
|
354
|
+
Beats are written against the code as laid out. When a gap closes above the
|
|
355
|
+
line a figure stands on, `ride()` carries it up with that line (and a hop
|
|
356
|
+
off a line that has moved lands back on it):
|
|
357
|
+
|
|
358
|
+
```js
|
|
359
|
+
code.remove(2, { at: swipe.contact, duration: 600, style: 'blur' })
|
|
360
|
+
const tracks = [...code.ride(script.tracks, 'hero', { ground }), ...code.tracks('code')]
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
Record the panel's edits first: `ride()` reads the moves they make. On the
|
|
364
|
+
script's own `ground` (not a line), nothing carries the figure.
|
|
365
|
+
|
|
366
|
+
Edits take a line or a list of lines, and are recorded on the panel; `tracks(id)`
|
|
367
|
+
writes them out as one track per prop (`line.N.highlight`, `line.N.strike`,
|
|
368
|
+
`line.N.wipe`, `line.N.reveal`, `line.N.shift`). Syntax colours come from small
|
|
369
|
+
keyword lists for Go, Rust, C#, JavaScript, TypeScript and Python (strings,
|
|
370
|
+
numbers and line comments too); `plain` leaves the text uncoloured.
|
|
371
|
+
|
|
372
|
+
## Camera
|
|
373
|
+
|
|
374
|
+
Video scenes can be seen through a camera: `camera: true` reads the tracks of
|
|
375
|
+
the `Camera` target (the editor's camera uses the same name). `x` and `y`
|
|
376
|
+
pan, `scale` zooms and `rotate` rolls about the stage centre, and `shakeX`,
|
|
377
|
+
`shakeY` and `shakeRotate` add on top, so a shake never disturbs a pan. A new
|
|
378
|
+
`overlay` step draws in screen space after everything else, for captions and
|
|
379
|
+
titles that should not move with the camera.
|
|
380
|
+
|
|
381
|
+
`cameraTracks()` (in `@algorisys/tinyfly`) compiles shots into those tracks:
|
|
382
|
+
|
|
383
|
+
```js
|
|
384
|
+
cameraTracks([
|
|
385
|
+
{ at: 2000, duration: 500, frame: { focus: { x: 760, y: 470 }, scale: 1.25 } }, // push in
|
|
386
|
+
{ at: 3300, duration: 0, frame: { focus: { x: 640, y: 440 }, scale: 1.6 } }, // a cut (crash zoom)
|
|
387
|
+
{ at: 3900, duration: 450, shake: { strength: 14 } }, // an impact
|
|
388
|
+
{ at: 7000, until: 9000, follow: { x: heroX.keyframes, y: 470, lag: 220 } }, // follow a runner
|
|
389
|
+
{ at: 9200, duration: 600, frame: {} }, // back to the full frame
|
|
390
|
+
], { stage: { width: 1280, height: 720 } })
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
A `frame` shot moves so `focus` sits at the centre at `scale` (and `rotate`);
|
|
394
|
+
a duration of 0 cuts. A `shake` dies away over its duration and is seeded, so
|
|
395
|
+
renders repeat exactly. A `follow` keeps a subject's x (its x track's
|
|
396
|
+
keyframes) centred, `lag` ms behind it, with an optional `lead`. Shots play in
|
|
397
|
+
time order, and a later one takes over from an earlier one.
|
|
398
|
+
|
|
399
|
+
In the browser or your own canvas code, `applyCamera(ctx, cameraFromValues(values), stage)`
|
|
400
|
+
(from `@algorisys/tinyfly/characters`, `@algorisys/tinyfly/adapters` or the
|
|
401
|
+
browser bundle) applies a view to any canvas, and `cameraPoint(view, stage, point)` says where a scene
|
|
402
|
+
point lands on screen (the pencil story maps the drawing hand's strokes this
|
|
403
|
+
way, so the hand stays on the page while the camera moves).
|
|
404
|
+
|
|
405
|
+
## Examples
|
|
406
|
+
|
|
407
|
+
- `examples/headless-video/cartoon-acting.mjs`: the same keys through
|
|
408
|
+
`poseTracks()` and `actTracks()`, side by side, with a take, speed lines
|
|
409
|
+
and a dust puff, drawn on twos.
|
|
410
|
+
- `examples/headless-video/beat-script.mjs`: a beat script with gaits, a
|
|
411
|
+
take, dialogue, a sneak and a run, filmed by camera shots (a push-in, a
|
|
412
|
+
crash zoom, a shake and a follow).
|
|
413
|
+
- `examples/pencil-story-hindi/`: the thirsty-traveller story, acted. It has a
|
|
414
|
+
take and a double take, a tired walk and a bouncy one, a lip-synced line in
|
|
415
|
+
Hindi, and camera pushes, with the animator's hand drawing through the
|
|
416
|
+
camera.
|
|
417
|
+
- The **Cartoon Acting** card in the website gallery: the script live in the
|
|
418
|
+
browser, with pickers for the acting style and the walk, and toggles for
|
|
419
|
+
drawing on twos, speed lines and the camera.
|
|
420
|
+
|
|
421
|
+
```bash
|
|
422
|
+
npx tinyfly video examples/headless-video/beat-script.mjs
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
## In the editor
|
|
426
|
+
|
|
427
|
+
The Character element has an **Acting** section: a style, **🎭 Act the keyed
|
|
428
|
+
poses**, gags, gaits with a distance, lines to say, and the drawing rate (see
|
|
429
|
+
the [editor guide](editor-guide.md#characters)). With acting on, the element
|
|
430
|
+
keeps its plain key poses (`acting.keys`) and its tracks are generated from
|
|
431
|
+
them, so keying a pose, adding a gag or a walk, or saying a line re-acts the
|
|
432
|
+
whole performance.
|
|
433
|
+
|
|
434
|
+
## Characters (v2): native motion
|
|
435
|
+
|
|
436
|
+
The v2 human has its own line of action, gaits and gags, posed in the
|
|
437
|
+
character's frame (forward is the way it faces, in 3D), so they read from
|
|
438
|
+
every view (front, side, back, the other side) with no mirroring:
|
|
439
|
+
|
|
440
|
+
- **`bend`**: the back curved forward (+) or arched (−). It grows up the spine
|
|
441
|
+
and carries on into the neck, unlike `lean`, which tips a straight back.
|
|
442
|
+
- **`humanGaitPose(gait, phase, base)`** and **`humanGaitStrideLength(gait, height)`**:
|
|
443
|
+
the same `GAITS` data as the stick figure's, driving the human's legs, arms,
|
|
444
|
+
back and bounce. One spec, two rigs.
|
|
445
|
+
- **`humanGag(name, { at, from })`** and **`HUMAN_GAGS`**: take, double take,
|
|
446
|
+
wind-up, land, tremble and deflate, written for this body.
|
|
447
|
+
|
|
448
|
+
```js
|
|
449
|
+
import { humanGag, humanGaitPose, actCharacterTracks } from '@algorisys/tinyfly/characters'
|
|
450
|
+
|
|
451
|
+
const keys = [{ time: 0, pose: { turn: 1 } }, ...humanGag('take', { at: 600, from: { turn: 1 } })]
|
|
452
|
+
const tracks = actCharacterTracks('hero', keys, { style: 'snappy' })
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
The editor's gags and walks use these. Builds (`proportions`, `headSize`,
|
|
456
|
+
`shoulderWidth`, `hipWidth`) change the body, and the same motion fits each.
|
|
457
|
+
|
|
458
|
+
The timeline's `drawingRate` (`TimelineConfig.drawingRate`, set with
|
|
459
|
+
`timeline.drawingRate = 12`) holds every value on its drawing, wherever the
|
|
460
|
+
timeline plays: editor previews, players, embeds and exports.
|
|
461
|
+
|
|
462
|
+
## Not yet
|
|
463
|
+
|
|
464
|
+
- A code panel in the editor (a Code element whose lines and words snap beats)
|
|
465
|
+
- Beat scripts for v2 characters (`scriptTracks` drives the stick figure)
|
|
466
|
+
- Follow-through on hair, tails and ears (character-system milestones 3 and 5)
|