@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
|
@@ -0,0 +1,2353 @@
|
|
|
1
|
+
# API Reference
|
|
2
|
+
|
|
3
|
+
Complete reference for the tinyfly animation engine, player, and adapters.
|
|
4
|
+
|
|
5
|
+
## Table of Contents
|
|
6
|
+
|
|
7
|
+
- [Core Types](#core-types)
|
|
8
|
+
- [Timeline](#timeline)
|
|
9
|
+
- [Track](#track)
|
|
10
|
+
- [Clock](#clock)
|
|
11
|
+
- [Easing](#easing)
|
|
12
|
+
- [Interpolators](#interpolators)
|
|
13
|
+
- [3D Math](#3d-math)
|
|
14
|
+
- [3D Scenes](#3d-scenes)
|
|
15
|
+
- [Motion Path](#motion-path)
|
|
16
|
+
- [Text Tracks](#text-tracks)
|
|
17
|
+
- [Serialization](#serialization)
|
|
18
|
+
- [TinyflyPlayer](#tinyflyplayer)
|
|
19
|
+
- [TinyflySequencer](#tinyflysequencer)
|
|
20
|
+
- [Media Sync](#media-sync)
|
|
21
|
+
- [DOMAdapter](#domadapter)
|
|
22
|
+
- [CanvasAdapter](#canvasadapter)
|
|
23
|
+
- [SVGAdapter](#svgadapter)
|
|
24
|
+
- [Export Formats](#export-formats)
|
|
25
|
+
- [Headless Video](#headless-video)
|
|
26
|
+
- [WebGLAdapter](#webgladapter)
|
|
27
|
+
- [Inertia Tracks](#inertia-tracks)
|
|
28
|
+
- [Spring Tracks](#spring-tracks)
|
|
29
|
+
- [Stagger](#stagger)
|
|
30
|
+
- [Baking](#baking)
|
|
31
|
+
- [Authoring Values](#authoring-values)
|
|
32
|
+
- [Drivers](#drivers)
|
|
33
|
+
- [Interaction](#interaction)
|
|
34
|
+
- [Flip](#flip)
|
|
35
|
+
- [GSAP Compat](#gsap-compat)
|
|
36
|
+
|
|
37
|
+
Entry points: `tinyfly` (engine), `@algorisys/tinyfly/export` (CSS, Lottie, GIF, WebP,
|
|
38
|
+
video and sprite-sheet exporters), `@algorisys/tinyfly/player`, `@algorisys/tinyfly/adapters` (DOM,
|
|
39
|
+
Canvas, SVG and WebGL adapters, Flip helpers), `@algorisys/tinyfly/drivers`,
|
|
40
|
+
`@algorisys/tinyfly/interaction`, `@algorisys/tinyfly/gsap-compat`, `@algorisys/tinyfly/scene-3d` (3D scenes), `@algorisys/tinyfly/browser` (the live
|
|
41
|
+
runtime and everything except the exporters, for `<script>` tags), and `@algorisys/tinyfly/headless`
|
|
42
|
+
(video and stills rendering in Node).
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Core Types
|
|
47
|
+
|
|
48
|
+
### AnimatableValue
|
|
49
|
+
|
|
50
|
+
```typescript
|
|
51
|
+
type AnimatableValue = number | string | number[]
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
All values that can be animated. Numbers for position/opacity, strings for colors, arrays for multi-dimensional values.
|
|
55
|
+
|
|
56
|
+
### EasingType
|
|
57
|
+
|
|
58
|
+
```typescript
|
|
59
|
+
type BuiltInEasingType =
|
|
60
|
+
| 'linear'
|
|
61
|
+
| 'ease-in' | 'ease-out' | 'ease-in-out'
|
|
62
|
+
| 'ease-in-quad' | 'ease-out-quad' | 'ease-in-out-quad'
|
|
63
|
+
| 'ease-in-cubic' | 'ease-out-cubic' | 'ease-in-out-cubic'
|
|
64
|
+
|
|
65
|
+
interface CubicBezierEasing {
|
|
66
|
+
type: 'cubic-bezier'
|
|
67
|
+
points: [number, number, number, number] // [cp1x, cp1y, cp2x, cp2y]
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
type EaseMode = 'in' | 'out' | 'in-out'
|
|
71
|
+
|
|
72
|
+
type ParametricEasing =
|
|
73
|
+
| { type: 'steps'; count: number; position?: 'start' | 'end' | 'none' | 'both' }
|
|
74
|
+
| { type: 'elastic'; mode?: EaseMode; amplitude?: number; period?: number }
|
|
75
|
+
| { type: 'bounce'; mode?: EaseMode }
|
|
76
|
+
| { type: 'back'; mode?: EaseMode; overshoot?: number }
|
|
77
|
+
|
|
78
|
+
type EasingType = BuiltInEasingType | CubicBezierEasing | ParametricEasing
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Parametric eases are evaluated when played, so they stay one keyframe in JSON.
|
|
82
|
+
`isParametricEasing(easing)` tells them apart; `expandParametricEasings(track)`
|
|
83
|
+
samples them into linear keyframes for keyframe-only formats.
|
|
84
|
+
|
|
85
|
+
### Keyframe
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
interface Keyframe<T extends AnimatableValue = AnimatableValue> {
|
|
89
|
+
time: number // Time in milliseconds from timeline start
|
|
90
|
+
value: T // Value at this keyframe
|
|
91
|
+
easing?: EasingType // Easing function to use when interpolating TO this keyframe
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Track
|
|
96
|
+
|
|
97
|
+
```typescript
|
|
98
|
+
interface Track<T extends AnimatableValue = AnimatableValue> {
|
|
99
|
+
id: string // Unique identifier
|
|
100
|
+
target: string // Target element name
|
|
101
|
+
property: string // Property to animate (e.g., 'opacity', 'x')
|
|
102
|
+
keyframes: Keyframe<T>[] // Must be sorted by time
|
|
103
|
+
delay?: number // Shift every keyframe by this many ms at evaluation time
|
|
104
|
+
endDelay?: number // Extra ms held after the last keyframe (extends duration)
|
|
105
|
+
targets?: string[] // Drive several targets; `target` is then ignored
|
|
106
|
+
stagger?: StaggerConfig // Per-target time offsets for `targets`
|
|
107
|
+
interpolation?: 'slerp' // Values are [x, y, z, w] quaternions: turn the short way (format version 2)
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
interface StaggerConfig {
|
|
111
|
+
each?: number // ms between consecutive targets
|
|
112
|
+
amount?: number // Total spread in ms (wins over `each`)
|
|
113
|
+
from?: 'start' | 'end' | 'center' | 'edges' | number // default 'start'
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Every track kind accepts `delay`, `targets` and `stagger`. `endDelay` takes
|
|
118
|
+
effect on keyframe and text tracks; spring and inertia tracks decide their own
|
|
119
|
+
duration. See [Stagger](#stagger).
|
|
120
|
+
|
|
121
|
+
### MotionPathTrack
|
|
122
|
+
|
|
123
|
+
```typescript
|
|
124
|
+
interface MotionPathConfig {
|
|
125
|
+
pathData: string // SVG path data (d attribute)
|
|
126
|
+
autoRotate?: boolean // Auto-rotate to follow path tangent
|
|
127
|
+
rotateOffset?: number // Rotation offset in degrees
|
|
128
|
+
matrix?: [a, b, c, d, e, f] // Affine transform applied to points and tangent
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
interface MotionPathTrack {
|
|
132
|
+
id: string
|
|
133
|
+
target: string
|
|
134
|
+
property: 'motionPath'
|
|
135
|
+
motionPathConfig: MotionPathConfig
|
|
136
|
+
keyframes: Keyframe<number>[] // Progress values 0-1
|
|
137
|
+
delay?: number; endDelay?: number; targets?: string[]; stagger?: StaggerConfig
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### AnyTrack / KeyframedTrack
|
|
142
|
+
|
|
143
|
+
```typescript
|
|
144
|
+
type AnyTrack = Track | MotionPathTrack | TextTrack | SpringTrack | InertiaTrack
|
|
145
|
+
type KeyframedTrack = Track | MotionPathTrack | TextTrack
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`AnyTrack` is what a timeline holds. `KeyframedTrack` is the subset with
|
|
149
|
+
`keyframes`; spring and inertia tracks compute values from parameters instead.
|
|
150
|
+
See [Text Tracks](#text-tracks), [Spring Tracks](#spring-tracks) and
|
|
151
|
+
[Inertia Tracks](#inertia-tracks).
|
|
152
|
+
|
|
153
|
+
### TimelineConfig
|
|
154
|
+
|
|
155
|
+
```typescript
|
|
156
|
+
interface TimelineConfig {
|
|
157
|
+
duration?: number // Total duration in ms (auto-calculated if not set)
|
|
158
|
+
loop?: number // 0 = no loop, -1 = infinite, n = n times
|
|
159
|
+
speed?: number // Playback speed multiplier (default: 1)
|
|
160
|
+
alternate?: boolean // Ping-pong effect on each loop
|
|
161
|
+
repeatDelay?: number // ms to wait between loop iterations
|
|
162
|
+
drawingRate?: number // drawings per second: 12 holds each for two frames of 24 fps ("on twos")
|
|
163
|
+
}
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
`drawingRate` steps every value: `getStateAtTime(t)` evaluates at the start of
|
|
167
|
+
the drawing showing at `t` (`heldTime(t, rate)`), as hand-drawn animation is
|
|
168
|
+
timed. The clock still runs smoothly; only the values hold. Set it with
|
|
169
|
+
`timeline.drawingRate = 12` (0 turns it off).
|
|
170
|
+
|
|
171
|
+
`repeatDelay` applies at each loop boundary. Going forward, the playhead holds
|
|
172
|
+
the last frame for the delay, then wraps to the start; with `alternate` it holds
|
|
173
|
+
at the end it reached before turning round. The delay is consumed at `speed`,
|
|
174
|
+
and `seek()` or `stop()` cancels a pending one.
|
|
175
|
+
|
|
176
|
+
### TimelineDefinition
|
|
177
|
+
|
|
178
|
+
```typescript
|
|
179
|
+
interface TimelineDefinition {
|
|
180
|
+
formatVersion?: number // 1, or 2 when a track uses `interpolation`; readers refuse newer
|
|
181
|
+
id: string
|
|
182
|
+
name?: string
|
|
183
|
+
config: TimelineConfig
|
|
184
|
+
tracks: AnyTrack[]
|
|
185
|
+
}
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
The JSON-serializable format used for saving, loading, and embedding animations.
|
|
189
|
+
|
|
190
|
+
### AnimationState
|
|
191
|
+
|
|
192
|
+
```typescript
|
|
193
|
+
interface AnimationState {
|
|
194
|
+
values: Map<string, Map<string, AnimatableValue>> // target -> property -> value
|
|
195
|
+
currentTime: number
|
|
196
|
+
playbackState: 'idle' | 'playing' | 'paused'
|
|
197
|
+
direction: 'forward' | 'reverse'
|
|
198
|
+
loopIteration: number
|
|
199
|
+
}
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Returned by `timeline.getStateAtTime()`. Contains the computed value for every target and property at the given time.
|
|
203
|
+
|
|
204
|
+
### Type Guards
|
|
205
|
+
|
|
206
|
+
```typescript
|
|
207
|
+
function isCubicBezierEasing(easing: EasingType | undefined): easing is CubicBezierEasing
|
|
208
|
+
function isMotionPathTrack(track: AnyTrack): track is MotionPathTrack
|
|
209
|
+
function isTextTrack(track: AnyTrack): track is TextTrack
|
|
210
|
+
function isSpringTrack(track: AnyTrack): track is SpringTrack
|
|
211
|
+
function isInertiaTrack(track: AnyTrack): track is InertiaTrack
|
|
212
|
+
function hasKeyframes(track: AnyTrack): track is KeyframedTrack
|
|
213
|
+
function isMotionPathPoint(value: unknown): value is MotionPathPoint
|
|
214
|
+
function isPathData(value: string): boolean // starts with a moveto
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## Timeline
|
|
220
|
+
|
|
221
|
+
The central class that orchestrates animation playback across multiple tracks.
|
|
222
|
+
|
|
223
|
+
### Constructor
|
|
224
|
+
|
|
225
|
+
```typescript
|
|
226
|
+
new Timeline(options: TimelineOptions)
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
```typescript
|
|
230
|
+
interface TimelineOptions {
|
|
231
|
+
id: string
|
|
232
|
+
name?: string
|
|
233
|
+
tracks?: AnyTrack[]
|
|
234
|
+
config?: TimelineConfig
|
|
235
|
+
}
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
**Example:**
|
|
239
|
+
```typescript
|
|
240
|
+
const timeline = new Timeline({
|
|
241
|
+
id: 'my-animation',
|
|
242
|
+
name: 'Fade Pulse',
|
|
243
|
+
config: { duration: 2000, loop: -1, speed: 1 },
|
|
244
|
+
tracks: [myTrack1, myTrack2]
|
|
245
|
+
})
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
### Properties
|
|
249
|
+
|
|
250
|
+
| Property | Type | Description |
|
|
251
|
+
|----------|------|-------------|
|
|
252
|
+
| `id` | `string` | Unique identifier (readonly) |
|
|
253
|
+
| `name` | `string \| undefined` | Human-readable name (readonly) |
|
|
254
|
+
| `tracks` | `AnyTrack[]` | Copy of all tracks (readonly) |
|
|
255
|
+
| `duration` | `number` | Total duration in ms (readonly, auto-calculated if not explicit) |
|
|
256
|
+
| `currentTime` | `number` | Current playback position in ms (readonly) |
|
|
257
|
+
| `playbackState` | `PlaybackState` | `'idle'`, `'playing'`, or `'paused'` (readonly) |
|
|
258
|
+
| `direction` | `PlaybackDirection` | `'forward'` or `'reverse'` (readonly) |
|
|
259
|
+
| `loopIteration` | `number` | Current loop iteration, 0-indexed (readonly) |
|
|
260
|
+
| `speed` | `number` | Playback speed multiplier (get/set) |
|
|
261
|
+
|
|
262
|
+
### Methods
|
|
263
|
+
|
|
264
|
+
#### `play(): void`
|
|
265
|
+
|
|
266
|
+
Start or resume playback. If at the end (forward) or beginning (reverse), resets to the opposite end.
|
|
267
|
+
|
|
268
|
+
#### `pause(): void`
|
|
269
|
+
|
|
270
|
+
Pause playback at the current position.
|
|
271
|
+
|
|
272
|
+
#### `stop(): void`
|
|
273
|
+
|
|
274
|
+
Stop playback and reset to the beginning (time = 0, direction = forward).
|
|
275
|
+
|
|
276
|
+
#### `seek(time: number): void`
|
|
277
|
+
|
|
278
|
+
Jump to a specific time in milliseconds. Clamped to `[0, duration]`.
|
|
279
|
+
|
|
280
|
+
#### `reverse(): void`
|
|
281
|
+
|
|
282
|
+
Toggle playback direction between forward and reverse.
|
|
283
|
+
|
|
284
|
+
#### `tick(delta: number): void`
|
|
285
|
+
|
|
286
|
+
Advance the timeline by `delta` milliseconds. Call this from your animation loop (e.g., `requestAnimationFrame`). The delta is scaled by the `speed` multiplier. Handles looping, alternate direction, `repeatDelay`, and completion automatically. Does nothing unless the timeline is playing.
|
|
287
|
+
|
|
288
|
+
#### `getStateAtTime(time: number): AnimationState`
|
|
289
|
+
|
|
290
|
+
Compute the animation state at a specific time. Returns a map of all target/property values at that time. For motion path tracks, expands the progress value into `motionPathX`, `motionPathY`, and optionally `motionPathRotate`.
|
|
291
|
+
|
|
292
|
+
When several tracks drive the same target and property, the value comes from the track that **started most recently** (its first keyframe plus delay and stagger, at or before `time`). Before any of them has started, the one that **starts first** supplies its starting value. Ties on start time go to the track added last. This is what lets a sequence of tweens on one property play in order. `findConflicts()` names winners by the same rule.
|
|
293
|
+
|
|
294
|
+
#### `addTrack(track: AnyTrack): void`
|
|
295
|
+
|
|
296
|
+
Add a track to the timeline. Accepts every track kind.
|
|
297
|
+
|
|
298
|
+
#### `replaceTrack(trackId: string, track: AnyTrack): void`
|
|
299
|
+
|
|
300
|
+
Swap a track for a new version, keeping its position in the track order (which
|
|
301
|
+
decides ties between overlapping tracks). The new track may have a different id.
|
|
302
|
+
Does nothing if no track has `trackId`.
|
|
303
|
+
|
|
304
|
+
#### `removeTrack(trackId: string): void`
|
|
305
|
+
|
|
306
|
+
Remove a track by its ID.
|
|
307
|
+
|
|
308
|
+
#### `getTracks(filter?: TrackFilter): AnyTrack[]`
|
|
309
|
+
|
|
310
|
+
Tracks matching every field of the filter. An empty filter returns all tracks.
|
|
311
|
+
|
|
312
|
+
#### `removeTracks(filter?: TrackFilter): string[]`
|
|
313
|
+
|
|
314
|
+
Remove every track matching the filter and return their ids.
|
|
315
|
+
`timeline.removeTracks({ target: 'box' })` is the equivalent of killing all
|
|
316
|
+
tweens on an element.
|
|
317
|
+
|
|
318
|
+
```typescript
|
|
319
|
+
interface TrackFilter {
|
|
320
|
+
target?: string // includes one of a multi-target track's `targets`
|
|
321
|
+
property?: string
|
|
322
|
+
timeRange?: { from: number; to: number } // active span overlaps this range (ms)
|
|
323
|
+
id?: string
|
|
324
|
+
}
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
#### `getTrackSpan(trackId: string): { from: number; to: number } | undefined`
|
|
328
|
+
|
|
329
|
+
The span a track is active over, in ms: from its first keyframe plus `delay`
|
|
330
|
+
(or from `delay`, for springs and inertia) to its end, including stagger and
|
|
331
|
+
`endDelay`. `undefined` for an unknown id or a track with no keyframes.
|
|
332
|
+
|
|
333
|
+
#### `findConflicts(): TrackConflict[]`
|
|
334
|
+
|
|
335
|
+
Pairs of tracks that write the same property of the same target over
|
|
336
|
+
overlapping spans, with the winner decided by the rule above. The engine
|
|
337
|
+
resolves these silently, so authoring tools should call this and warn.
|
|
338
|
+
|
|
339
|
+
```typescript
|
|
340
|
+
interface TrackConflict {
|
|
341
|
+
target: string
|
|
342
|
+
property: string
|
|
343
|
+
losingTrackId: string // values discarded where the spans overlap
|
|
344
|
+
winningTrackId: string // values applied
|
|
345
|
+
}
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
#### `setDuration(duration: number | undefined): void`
|
|
349
|
+
|
|
350
|
+
Set an explicit duration in ms. Pass `undefined` to go back to the duration
|
|
351
|
+
calculated from the tracks.
|
|
352
|
+
|
|
353
|
+
#### `toDefinition(): TimelineDefinition`
|
|
354
|
+
|
|
355
|
+
Return the timeline as a `TimelineDefinition`. Not a copy: `tracks` are the
|
|
356
|
+
timeline's own track objects. Use [`serializeTimeline`](#serialization) for a
|
|
357
|
+
detached copy.
|
|
358
|
+
|
|
359
|
+
### Callbacks
|
|
360
|
+
|
|
361
|
+
| Callback | Signature | Description |
|
|
362
|
+
|----------|-----------|-------------|
|
|
363
|
+
| `onUpdate` | `(state: AnimationState) => void` | Called on each `tick()` with the current state |
|
|
364
|
+
| `onComplete` | `() => void` | Called when the animation finishes (end of last loop) |
|
|
365
|
+
|
|
366
|
+
**Example:**
|
|
367
|
+
```typescript
|
|
368
|
+
timeline.onUpdate = (state) => {
|
|
369
|
+
adapter.applyState(state)
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
timeline.onComplete = () => {
|
|
373
|
+
console.log('Animation finished!')
|
|
374
|
+
}
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
---
|
|
378
|
+
|
|
379
|
+
## Track
|
|
380
|
+
|
|
381
|
+
### createTrack
|
|
382
|
+
|
|
383
|
+
```typescript
|
|
384
|
+
function createTrack<T extends AnimatableValue>(options: Track<T>): Track<T>
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
Creates a track with keyframes sorted by time.
|
|
388
|
+
|
|
389
|
+
**Example:**
|
|
390
|
+
```typescript
|
|
391
|
+
const track = createTrack({
|
|
392
|
+
id: 'box-opacity',
|
|
393
|
+
target: 'box',
|
|
394
|
+
property: 'opacity',
|
|
395
|
+
keyframes: [
|
|
396
|
+
{ time: 0, value: 0 },
|
|
397
|
+
{ time: 500, value: 1, easing: 'ease-out' },
|
|
398
|
+
{ time: 1000, value: 0, easing: 'ease-in' }
|
|
399
|
+
]
|
|
400
|
+
})
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
### Animatable Properties
|
|
404
|
+
|
|
405
|
+
Common properties you can animate:
|
|
406
|
+
|
|
407
|
+
| Property | Value Type | Description |
|
|
408
|
+
|----------|-----------|-------------|
|
|
409
|
+
| `opacity` | number (0-1) | Transparency |
|
|
410
|
+
| `x` | number | Horizontal position |
|
|
411
|
+
| `y` | number | Vertical position |
|
|
412
|
+
| `width` | number | Width |
|
|
413
|
+
| `height` | number | Height |
|
|
414
|
+
| `rotation` | number | Rotation in degrees |
|
|
415
|
+
| `scaleX` | number | Horizontal scale |
|
|
416
|
+
| `scaleY` | number | Vertical scale |
|
|
417
|
+
| `fill` | string | Fill color (hex/rgb/rgba) |
|
|
418
|
+
| `stroke` | string | Stroke color |
|
|
419
|
+
| `strokeWidth` | number | Stroke thickness |
|
|
420
|
+
| `borderRadius` | number | Corner radius |
|
|
421
|
+
| `fontSize` | number | Text font size |
|
|
422
|
+
| `motionPath` | number (0-1) | Progress along a motion path |
|
|
423
|
+
|
|
424
|
+
---
|
|
425
|
+
|
|
426
|
+
## Clock
|
|
427
|
+
|
|
428
|
+
### Clock (Browser/RAF)
|
|
429
|
+
|
|
430
|
+
RAF-based clock for browser environments. Automatically advances time using `requestAnimationFrame`.
|
|
431
|
+
|
|
432
|
+
```typescript
|
|
433
|
+
const clock = new Clock({ speed: 1 })
|
|
434
|
+
|
|
435
|
+
clock.onTick = (delta, currentTime) => {
|
|
436
|
+
timeline.tick(delta)
|
|
437
|
+
}
|
|
438
|
+
|
|
439
|
+
clock.start()
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
| Property/Method | Type | Description |
|
|
443
|
+
|----------------|------|-------------|
|
|
444
|
+
| `currentTime` | `number` | Current time in ms (readonly) |
|
|
445
|
+
| `isRunning` | `boolean` | Whether the clock is ticking (readonly) |
|
|
446
|
+
| `speed` | `number` | Speed multiplier (get/set) |
|
|
447
|
+
| `onTick` | `TickCallback \| null` | Called each frame with `(delta, currentTime)` |
|
|
448
|
+
| `start()` | `void` | Start the RAF loop |
|
|
449
|
+
| `stop()` | `void` | Stop the RAF loop |
|
|
450
|
+
| `reset()` | `void` | Reset time to 0 |
|
|
451
|
+
| `seek(time)` | `void` | Set current time |
|
|
452
|
+
|
|
453
|
+
### ManualClock (Testing/Non-Browser)
|
|
454
|
+
|
|
455
|
+
For testing or environments without `requestAnimationFrame`. Time only advances when `tick()` is called explicitly.
|
|
456
|
+
|
|
457
|
+
```typescript
|
|
458
|
+
const clock = new ManualClock()
|
|
459
|
+
clock.onTick = (delta, currentTime) => {
|
|
460
|
+
timeline.tick(delta)
|
|
461
|
+
}
|
|
462
|
+
|
|
463
|
+
clock.start()
|
|
464
|
+
clock.tick(16.67) // Advance 16.67ms
|
|
465
|
+
clock.tick(16.67) // Advance another 16.67ms
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
| Property/Method | Type | Description |
|
|
469
|
+
|----------------|------|-------------|
|
|
470
|
+
| `currentTime` | `number` | Current time (readonly) |
|
|
471
|
+
| `isRunning` | `boolean` | Running state (readonly) |
|
|
472
|
+
| `onTick` | `TickCallback \| null` | Tick callback |
|
|
473
|
+
| `start()` | `void` | Set running to true |
|
|
474
|
+
| `stop()` | `void` | Set running to false |
|
|
475
|
+
| `tick(delta)` | `void` | Advance time by delta ms |
|
|
476
|
+
| `reset()` | `void` | Reset time to 0 |
|
|
477
|
+
| `seek(time)` | `void` | Set current time |
|
|
478
|
+
|
|
479
|
+
---
|
|
480
|
+
|
|
481
|
+
## Easing
|
|
482
|
+
|
|
483
|
+
### Built-in Functions
|
|
484
|
+
|
|
485
|
+
| Function | Description |
|
|
486
|
+
|----------|-------------|
|
|
487
|
+
| `linear` | Constant speed, no acceleration |
|
|
488
|
+
| `easeIn` | Cubic ease in (starts slow, accelerates) |
|
|
489
|
+
| `easeOut` | Cubic ease out (starts fast, decelerates) |
|
|
490
|
+
| `easeInOut` | Cubic ease in-out |
|
|
491
|
+
| `easeInQuad` | Quadratic ease in (gentler curve) |
|
|
492
|
+
| `easeOutQuad` | Quadratic ease out |
|
|
493
|
+
| `easeInOutQuad` | Quadratic ease in-out |
|
|
494
|
+
| `easeInCubic` | Cubic ease in (same as `easeIn`) |
|
|
495
|
+
| `easeOutCubic` | Cubic ease out (same as `easeOut`) |
|
|
496
|
+
| `easeInOutCubic` | Cubic ease in-out (same as `easeInOut`) |
|
|
497
|
+
|
|
498
|
+
Each function takes a normalized time value (0-1) and returns an eased value (0-1).
|
|
499
|
+
|
|
500
|
+
### createCubicBezier
|
|
501
|
+
|
|
502
|
+
```typescript
|
|
503
|
+
function createCubicBezier(points: [number, number, number, number]): EasingFunction
|
|
504
|
+
```
|
|
505
|
+
|
|
506
|
+
Creates a custom cubic bezier easing function from 4 control points `[cp1x, cp1y, cp2x, cp2y]`. Uses Newton-Raphson iteration for accurate x-to-t mapping.
|
|
507
|
+
|
|
508
|
+
**Example:**
|
|
509
|
+
```typescript
|
|
510
|
+
const customEase = createCubicBezier([0.25, 0.1, 0.25, 1.0])
|
|
511
|
+
const easedValue = customEase(0.5) // Returns ~0.8
|
|
512
|
+
```
|
|
513
|
+
|
|
514
|
+
### getEasingFunction
|
|
515
|
+
|
|
516
|
+
```typescript
|
|
517
|
+
function getEasingFunction(type: EasingType | undefined): EasingFunction
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
Resolves an easing type identifier to its function. Returns `linear` if type is undefined. Supports both built-in string types and `CubicBezierEasing` objects.
|
|
521
|
+
|
|
522
|
+
---
|
|
523
|
+
|
|
524
|
+
## Interpolators
|
|
525
|
+
|
|
526
|
+
Functions that compute intermediate values between two endpoints.
|
|
527
|
+
|
|
528
|
+
### interpolateNumber
|
|
529
|
+
|
|
530
|
+
```typescript
|
|
531
|
+
function interpolateNumber(from: number, to: number, progress: number): number
|
|
532
|
+
```
|
|
533
|
+
|
|
534
|
+
Linear interpolation between two numbers.
|
|
535
|
+
|
|
536
|
+
### interpolateColor
|
|
537
|
+
|
|
538
|
+
```typescript
|
|
539
|
+
function interpolateColor(from: string, to: string, progress: number): string
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
Smooth interpolation between two color values. Supports:
|
|
543
|
+
- Hex colors: `#ff0000`, `#00ff00`
|
|
544
|
+
- RGB: `rgb(255, 0, 0)`
|
|
545
|
+
- RGBA: `rgba(255, 0, 0, 0.5)`
|
|
546
|
+
|
|
547
|
+
Returns a color string in the same format as the inputs.
|
|
548
|
+
|
|
549
|
+
### interpolateArray
|
|
550
|
+
|
|
551
|
+
```typescript
|
|
552
|
+
function interpolateArray(from: number[], to: number[], progress: number): number[]
|
|
553
|
+
```
|
|
554
|
+
|
|
555
|
+
Element-wise interpolation of number arrays.
|
|
556
|
+
|
|
557
|
+
### interpolateQuaternion
|
|
558
|
+
|
|
559
|
+
```typescript
|
|
560
|
+
function interpolateQuaternion(from: number[], to: number[], progress: number): number[]
|
|
561
|
+
```
|
|
562
|
+
|
|
563
|
+
Spherical interpolation of `[x, y, z, w]` rotations: the short way round, at a
|
|
564
|
+
steady angular speed, always a unit quaternion. Used by tracks with
|
|
565
|
+
`interpolation: 'slerp'`.
|
|
566
|
+
|
|
567
|
+
### interpolateString
|
|
568
|
+
|
|
569
|
+
```typescript
|
|
570
|
+
function interpolateString(from: string, to: string, progress: number): string
|
|
571
|
+
```
|
|
572
|
+
|
|
573
|
+
Discrete interpolation — returns `from` when `progress < 1`, `to` when `progress >= 1`.
|
|
574
|
+
|
|
575
|
+
### morphPath (shape tween)
|
|
576
|
+
|
|
577
|
+
```typescript
|
|
578
|
+
function morphPath(from: string, to: string, progress: number, options?: MorphOptions): string
|
|
579
|
+
function isPathData(value: string): boolean
|
|
580
|
+
|
|
581
|
+
interface MorphOptions {
|
|
582
|
+
shapeIndex?: number // force the start-point alignment; negative reverses direction
|
|
583
|
+
}
|
|
584
|
+
```
|
|
585
|
+
|
|
586
|
+
Interpolate between two SVG path `d` strings. Both paths are sampled along their
|
|
587
|
+
length (keeping every corner) and the points are blended by `progress`, so **any**
|
|
588
|
+
two shapes morph smoothly and deterministically (no DOM required). `isPathData` recognises a
|
|
589
|
+
string that starts with a moveto. A `d` track animates a path's shape — see
|
|
590
|
+
[shape-morph.md](shape-morph.md).
|
|
591
|
+
|
|
592
|
+
### getInterpolator
|
|
593
|
+
|
|
594
|
+
```typescript
|
|
595
|
+
function getInterpolator<T extends AnimatableValue>(sampleValue: T, interpolation?: 'slerp'): Interpolator<T>
|
|
596
|
+
```
|
|
597
|
+
|
|
598
|
+
With `interpolation: 'slerp'`, `interpolateQuaternion`. Otherwise auto-detect
|
|
599
|
+
from a sample value:
|
|
600
|
+
- Numbers → `interpolateNumber`
|
|
601
|
+
- Strings starting with `#` or `rgb` → `interpolateColor`
|
|
602
|
+
- **SVG path data** (a moveto) → `morphPath` (shape morph)
|
|
603
|
+
- Other strings → `interpolateString`
|
|
604
|
+
- Arrays → `interpolateArray`
|
|
605
|
+
|
|
606
|
+
---
|
|
607
|
+
|
|
608
|
+
## 3D Math
|
|
609
|
+
|
|
610
|
+
Small, pure helpers for rotations and transforms, exported from the engine as
|
|
611
|
+
three namespaces. Values are plain arrays (JSON as they are): `Vec3` is
|
|
612
|
+
`[x, y, z]`, `Quat` is `[x, y, z, w]`, `Mat4` is 16 numbers, **column-major**
|
|
613
|
+
(as WebGL, glTF and CSS `matrix3d()`). Euler angles are degrees in **YXZ**
|
|
614
|
+
order: `quat.fromEuler(x, y, z)` turns as CSS `rotateY(y) rotateX(x) rotateZ(z)`.
|
|
615
|
+
|
|
616
|
+
```typescript
|
|
617
|
+
import { vec3, quat, mat4 } from '@algorisys/tinyfly'
|
|
618
|
+
|
|
619
|
+
vec3.add / subtract / scale / dot / cross / length / distance / normalize / lerp
|
|
620
|
+
quat.identity() / fromAxisAngle(axis, degrees) / fromEuler(x, y, z) / toEuler(q)
|
|
621
|
+
quat.multiply(a, b) // b first, then a
|
|
622
|
+
quat.slerp(a, b, t) / dot / length / normalize / conjugate / rotateVec3(q, v)
|
|
623
|
+
mat4.identity() / multiply(a, b) / translation(v) / scaling(v) / fromQuat(q)
|
|
624
|
+
mat4.compose(position, rotation, scale) // scale, then rotate, then move
|
|
625
|
+
mat4.invert(m) /* null when singular */ / transpose(m)
|
|
626
|
+
mat4.perspective(fovY, aspect, near, far) / orthographic(l, r, b, t, near, far)
|
|
627
|
+
mat4.lookAt(eye, target, up?) / transformPoint(m, p)
|
|
628
|
+
```
|
|
629
|
+
|
|
630
|
+
See [3D rotations](3d-rotations.md).
|
|
631
|
+
|
|
632
|
+
---
|
|
633
|
+
|
|
634
|
+
## 3D Scenes
|
|
635
|
+
|
|
636
|
+
`@algorisys/tinyfly/scene-3d` (and `tinyfly-scene-3d.iife.js` for script tags):
|
|
637
|
+
|
|
638
|
+
```typescript
|
|
639
|
+
loadScene3D(scene: Scene3D): LoadedScene3D
|
|
640
|
+
validateScene3D(scene: Scene3D, tracks?: { target, property }[]): string[]
|
|
641
|
+
resolveScene3D(loaded, values: SceneValues, { width, height, time?, valuesAt? }): ResolvedScene3D
|
|
642
|
+
drawScene3D(ctx, loaded, values | undefined, { width, height, time?, valuesAt? | stateAt? }): void
|
|
643
|
+
new Scene3DAdapter(renderer: Renderer3D, { width, height, valuesAt? }) // registerScene, unregisterScene, resize, applyState, render
|
|
644
|
+
new Canvas2DRenderer(ctx) // render(frame); drawResolvedScene(ctx, frame)
|
|
645
|
+
orbitPosition(target, yaw, pitch, distance) / dollyPosition(eye, target, amount) / lookAtView(eye, target) / projectionMatrix(camera, aspect)
|
|
646
|
+
shadeTriangle(triangle, lights, camera, fog?) / lightAt(point, normal, lights) / fogAmount(fog, distance) / parseColor(color)
|
|
647
|
+
boxMesh / planeMesh / sphereMesh / cylinderMesh / coneMesh / torusMesh / extrudeMesh(path, { depth, width?, curveSegments? }) / geometryMesh / meshEdges / MeshBuilder
|
|
648
|
+
triangulate(outline, holes?) / signedArea / pointInPolygon
|
|
649
|
+
```
|
|
650
|
+
|
|
651
|
+
Objects: `group`, `mesh`, `camera`, `light`, and `line` (`points`, `closed?`)
|
|
652
|
+
and `trail` (`follow`, `length` ms, `samples?`, `period?`), both with
|
|
653
|
+
`color`, `width` (metres), `taper`, `fade`, `opacity`, `blend: 'normal' | 'add'`.
|
|
654
|
+
A trail needs `valuesAt` (a video frame's `stateAt` does it). See
|
|
655
|
+
[3D Scenes](scene-3d.md#lines-and-trails).
|
|
656
|
+
|
|
657
|
+
new WebGL2Renderer(gl, { overlay? }) // @algorisys/tinyfly/scene-3d/webgl: render(frame), destroy()
|
|
658
|
+
loadScene3D(scene, { kinds: [characterObjects] }) // object kinds beyond the built-ins: ObjectKind { kind, validate?, prepare?, resolve }
|
|
659
|
+
// from @algorisys/tinyfly/characters:
|
|
660
|
+
characterObjects // the `character` object kind (pen or solid look)
|
|
661
|
+
drawCharacterInView(ctx, character, pose, projection, { height, time? }) / characterJointsInView(…)
|
|
662
|
+
skeletonInView(plan, pose, { height }, projection) / stagePlanSpace(plan, pose, { height }) / solvePlanSpace(plan, pose, height)
|
|
663
|
+
```
|
|
664
|
+
|
|
665
|
+
Types: `Scene3D`, `Object3D` (`group`, `mesh`, `camera`, `light`, `character`), `Geometry3D`,
|
|
666
|
+
`Material3D`, `ResolvedScene3D`, `DrawTriangle`. Tracks address objects as
|
|
667
|
+
`<sceneId>/<objectId>`; see [3D Scenes](scene-3d.md) for the properties.
|
|
668
|
+
|
|
669
|
+
---
|
|
670
|
+
|
|
671
|
+
## Motion Path
|
|
672
|
+
|
|
673
|
+
Animate elements along SVG paths.
|
|
674
|
+
|
|
675
|
+
### getMotionPathPoint
|
|
676
|
+
|
|
677
|
+
```typescript
|
|
678
|
+
function getMotionPathPoint(config: MotionPathConfig, progress: number): MotionPathPoint
|
|
679
|
+
```
|
|
680
|
+
|
|
681
|
+
Get the position and tangent angle at a given progress (0-1) along the path.
|
|
682
|
+
|
|
683
|
+
```typescript
|
|
684
|
+
interface MotionPathPoint {
|
|
685
|
+
x: number // X coordinate on the path
|
|
686
|
+
y: number // Y coordinate on the path
|
|
687
|
+
angle: number // Tangent angle in degrees
|
|
688
|
+
}
|
|
689
|
+
```
|
|
690
|
+
|
|
691
|
+
### interpolateMotionPath
|
|
692
|
+
|
|
693
|
+
```typescript
|
|
694
|
+
function interpolateMotionPath(
|
|
695
|
+
config: MotionPathConfig,
|
|
696
|
+
fromProgress: number,
|
|
697
|
+
toProgress: number,
|
|
698
|
+
t: number
|
|
699
|
+
): MotionPathPoint
|
|
700
|
+
```
|
|
701
|
+
|
|
702
|
+
Interpolate between two progress values on a path. The `t` parameter is the eased interpolation factor (0-1).
|
|
703
|
+
|
|
704
|
+
### Usage with Timeline
|
|
705
|
+
|
|
706
|
+
Motion paths are used through `MotionPathTrack`:
|
|
707
|
+
|
|
708
|
+
```typescript
|
|
709
|
+
const motionTrack: MotionPathTrack = {
|
|
710
|
+
id: 'path-track',
|
|
711
|
+
target: 'ball',
|
|
712
|
+
property: 'motionPath',
|
|
713
|
+
motionPathConfig: {
|
|
714
|
+
pathData: 'M 0 100 Q 150 0 300 100',
|
|
715
|
+
autoRotate: true,
|
|
716
|
+
rotateOffset: 0
|
|
717
|
+
},
|
|
718
|
+
keyframes: [
|
|
719
|
+
{ time: 0, value: 0 },
|
|
720
|
+
{ time: 2000, value: 1, easing: 'ease-in-out' }
|
|
721
|
+
]
|
|
722
|
+
}
|
|
723
|
+
|
|
724
|
+
timeline.addTrack(motionTrack)
|
|
725
|
+
```
|
|
726
|
+
|
|
727
|
+
The timeline automatically expands the motion path progress into `motionPathX`, `motionPathY`, and `motionPathRotate` properties in the animation state.
|
|
728
|
+
|
|
729
|
+
Progress is by arc length, including within curves, so followers move at an even
|
|
730
|
+
speed. `matrix` places the path into another coordinate space (x' = a·x + c·y + e,
|
|
731
|
+
y' = b·x + d·y + f); the tangent is transformed too, so `autoRotate` still faces
|
|
732
|
+
along the path.
|
|
733
|
+
|
|
734
|
+
### Path utilities
|
|
735
|
+
|
|
736
|
+
```typescript
|
|
737
|
+
import { parsePath, getPointAtProgress, getPathLength, pointsToPath, shapeToPathData, morphPath } from '@algorisys/tinyfly'
|
|
738
|
+
|
|
739
|
+
getPathLength('M0 0 L30 40') // 50
|
|
740
|
+
getPointAtProgress('M0 0 Q50 100 100 0', 0.5) // { x: 50, y: 50, angle: 0 }
|
|
741
|
+
pointsToPath([{ x: 0, y: 0 }, { x: 50, y: 50 }, { x: 100, y: 0 }], { curviness: 1, closed: false })
|
|
742
|
+
shapeToPathData({ tag: 'circle', attributes: { cx: '50', cy: '50', r: '40' } }) // 'M90 50 A40 40 …'
|
|
743
|
+
|
|
744
|
+
// Trails: where something was, as a pure function of time
|
|
745
|
+
trailSamples(positionAt: (t) => P, time, { length, samples = 32, period?, since? }): { at: P; time; age }[] // oldest first, age 1 → 0
|
|
746
|
+
ribbon(points: { x, y, width }[]): { left, right } // a band's mitred edges
|
|
747
|
+
ribbonHeadCap(points): { x, y, radius, start } | null // its round end
|
|
748
|
+
// @algorisys/tinyfly/adapters (and the browser bundle): draw one
|
|
749
|
+
drawTrail(ctx, samples, { color, width = 6, taper = 1, fade = 1, opacity = 1, blend: 'normal' | 'add', head?: { radius, color? } })
|
|
750
|
+
```
|
|
751
|
+
|
|
752
|
+
`morphPath(from, to, progress, { shapeIndex? })` blends two paths: subpaths are
|
|
753
|
+
paired, the start point and winding are chosen automatically (or forced with
|
|
754
|
+
`shapeIndex`), and corners of both shapes are kept. `pointAtDistance(segments,
|
|
755
|
+
distance, start?, end?)` samples a run of parsed segments; `parsePath(d).subpaths`
|
|
756
|
+
lists each subpath's segment range, length and whether it is closed.
|
|
757
|
+
|
|
758
|
+
`parsePath` reads every SVG path command, absolute or relative, including compact
|
|
759
|
+
notation (`10-20`, `.5.5`, exponents, unseparated arc flags). It normalises to
|
|
760
|
+
absolute lines and cubic beziers (`Q`/`T` exactly, `S`/`T` with reflected
|
|
761
|
+
controls, arcs split into ≤90° cubics). Results are cached (bounded).
|
|
762
|
+
|
|
763
|
+
### GSAP-style: `motionPath`
|
|
764
|
+
|
|
765
|
+
`tf`, `timeline()` and `live` accept `motionPath: { path, curviness, autoRotate, start, end }`
|
|
766
|
+
(or shorthand path data / points). `live` also accepts a selector or element for
|
|
767
|
+
`path`, plus `align` and `alignOrigin`. See [gsap-compat.md](gsap-compat.md#motion-paths).
|
|
768
|
+
|
|
769
|
+
---
|
|
770
|
+
|
|
771
|
+
## Text Tracks
|
|
772
|
+
|
|
773
|
+
Animate text by typing or scrambling from one string to another.
|
|
774
|
+
|
|
775
|
+
```typescript
|
|
776
|
+
interface TextConfig {
|
|
777
|
+
from?: string // text at progress 0 (default '')
|
|
778
|
+
to: string // text at progress 1
|
|
779
|
+
mode: 'type' | 'scramble'
|
|
780
|
+
chars?: 'upperCase' | 'lowerCase' | 'upperAndLowerCase' | 'numbers' | string
|
|
781
|
+
refreshRate?: number // scramble: random-character changes per second (default 20)
|
|
782
|
+
revealDelay?: number // scramble: fraction of the tween before characters settle
|
|
783
|
+
tweenLength?: boolean // scramble: grow/shrink length over the tween (default true)
|
|
784
|
+
rightToLeft?: boolean // reveal / type from the end
|
|
785
|
+
seed?: number // scramble: fixes the random characters
|
|
786
|
+
}
|
|
787
|
+
|
|
788
|
+
interface TextTrack {
|
|
789
|
+
id: string
|
|
790
|
+
target: string
|
|
791
|
+
property: 'text'
|
|
792
|
+
textConfig: TextConfig
|
|
793
|
+
keyframes: Keyframe<number>[] // progress 0-1, with easing
|
|
794
|
+
delay?: number; endDelay?: number; targets?: string[]; stagger?: StaggerConfig
|
|
795
|
+
}
|
|
796
|
+
```
|
|
797
|
+
|
|
798
|
+
The timeline expands progress into a `text` value in the animation state; the DOM
|
|
799
|
+
and SVG adapters set it as `textContent`, and the Canvas adapter as a text
|
|
800
|
+
target's `text`. `textAt(config, progress, elapsedMs)` computes the string
|
|
801
|
+
directly. It is pure: scramble characters come from a hash of the seed, position
|
|
802
|
+
and refresh step, so the same inputs always give the same string.
|
|
803
|
+
|
|
804
|
+
In `type` mode, the new text overwrites the old one character at a time over the
|
|
805
|
+
longer of the two strings, so typing towards shorter text deletes as it goes.
|
|
806
|
+
|
|
807
|
+
---
|
|
808
|
+
|
|
809
|
+
## Serialization
|
|
810
|
+
|
|
811
|
+
### serializeTimeline / deserializeTimeline
|
|
812
|
+
|
|
813
|
+
```typescript
|
|
814
|
+
function serializeTimeline(timeline: Timeline): TimelineDefinition
|
|
815
|
+
function deserializeTimeline(definition: TimelineDefinition): Timeline
|
|
816
|
+
```
|
|
817
|
+
|
|
818
|
+
Convert between `Timeline` instances and JSON-serializable `TimelineDefinition` objects.
|
|
819
|
+
|
|
820
|
+
### toJSON / fromJSON
|
|
821
|
+
|
|
822
|
+
```typescript
|
|
823
|
+
function toJSON(timeline: Timeline): string
|
|
824
|
+
function fromJSON(json: string): Timeline
|
|
825
|
+
```
|
|
826
|
+
|
|
827
|
+
Convert between `Timeline` instances and JSON strings.
|
|
828
|
+
|
|
829
|
+
### serializeTrack / deserializeTrack
|
|
830
|
+
|
|
831
|
+
```typescript
|
|
832
|
+
function serializeTrack(track: AnyTrack): AnyTrack
|
|
833
|
+
function deserializeTrack(data: AnyTrack): AnyTrack
|
|
834
|
+
```
|
|
835
|
+
|
|
836
|
+
Serialize/deserialize individual tracks of every kind. Scheduling fields are
|
|
837
|
+
kept when set and omitted otherwise; `deserializeTrack` sorts keyframes by time.
|
|
838
|
+
|
|
839
|
+
**Example:**
|
|
840
|
+
```typescript
|
|
841
|
+
// Save
|
|
842
|
+
const json = toJSON(timeline)
|
|
843
|
+
localStorage.setItem('animation', json)
|
|
844
|
+
|
|
845
|
+
// Load
|
|
846
|
+
const restored = fromJSON(localStorage.getItem('animation'))
|
|
847
|
+
restored.play()
|
|
848
|
+
```
|
|
849
|
+
|
|
850
|
+
---
|
|
851
|
+
|
|
852
|
+
## TinyflyPlayer
|
|
853
|
+
|
|
854
|
+
Lightweight player for embedding animations in web pages.
|
|
855
|
+
|
|
856
|
+
### Constructor
|
|
857
|
+
|
|
858
|
+
```typescript
|
|
859
|
+
new TinyflyPlayer(container: HTMLElement | string, options?: PlayerOptions)
|
|
860
|
+
```
|
|
861
|
+
|
|
862
|
+
```typescript
|
|
863
|
+
interface PlayerOptions {
|
|
864
|
+
speed?: number // Playback speed (default: 1)
|
|
865
|
+
loop?: number // -1 = infinite, 0 = no loop, n = n times
|
|
866
|
+
alternate?: boolean // Ping-pong effect
|
|
867
|
+
autoplay?: boolean // Auto-play on load (default: false)
|
|
868
|
+
onComplete?: () => void // Called when animation finishes
|
|
869
|
+
onUpdate?: (state: AnimationState) => void // Called each frame
|
|
870
|
+
}
|
|
871
|
+
```
|
|
872
|
+
|
|
873
|
+
The container can be an `HTMLElement` or a CSS selector string (e.g., `'#my-animation'`).
|
|
874
|
+
|
|
875
|
+
### Methods
|
|
876
|
+
|
|
877
|
+
#### `load(source: string | TimelineDefinition): Promise<void>`
|
|
878
|
+
|
|
879
|
+
Load an animation from a URL (fetches JSON) or an inline `TimelineDefinition` object. Automatically discovers target elements in the container.
|
|
880
|
+
|
|
881
|
+
#### `loadFromString(json: string): void`
|
|
882
|
+
|
|
883
|
+
Load an animation from a JSON string.
|
|
884
|
+
|
|
885
|
+
#### `registerTarget(name: string, element: HTMLElement | string): void`
|
|
886
|
+
|
|
887
|
+
Manually register a target element by name. The element can be an `HTMLElement` or a CSS selector (searched within the container).
|
|
888
|
+
|
|
889
|
+
#### `play(): void`
|
|
890
|
+
|
|
891
|
+
Start or resume playback.
|
|
892
|
+
|
|
893
|
+
#### `pause(): void`
|
|
894
|
+
|
|
895
|
+
Pause at the current position.
|
|
896
|
+
|
|
897
|
+
#### `stop(): void`
|
|
898
|
+
|
|
899
|
+
Stop and reset to the beginning.
|
|
900
|
+
|
|
901
|
+
#### `seek(time: number): void`
|
|
902
|
+
|
|
903
|
+
Jump to a specific time in milliseconds.
|
|
904
|
+
|
|
905
|
+
#### `setSpeed(speed: number): void`
|
|
906
|
+
|
|
907
|
+
Change the playback speed.
|
|
908
|
+
|
|
909
|
+
#### `reverse(): void`
|
|
910
|
+
|
|
911
|
+
Toggle playback direction.
|
|
912
|
+
|
|
913
|
+
#### `attachMedia(media: SyncableMedia, options?: MediaSyncOptions): void`
|
|
914
|
+
|
|
915
|
+
Keep an `<audio>` / `<video>` element (or anything shaped like one) in sync with
|
|
916
|
+
the timeline. The timeline stays the clock; the media follows play, pause, seek
|
|
917
|
+
and speed. Replaces any media attached before. See [Media Sync](#media-sync).
|
|
918
|
+
|
|
919
|
+
#### `detachMedia(): void`
|
|
920
|
+
|
|
921
|
+
Pause and release the attached media, if any.
|
|
922
|
+
|
|
923
|
+
#### `destroy(): void`
|
|
924
|
+
|
|
925
|
+
Clean up all resources, stop the animation loop, and clear registered targets.
|
|
926
|
+
|
|
927
|
+
### Properties
|
|
928
|
+
|
|
929
|
+
| Property | Type | Description |
|
|
930
|
+
|----------|------|-------------|
|
|
931
|
+
| `currentTime` | `number` | Current playback time in ms |
|
|
932
|
+
| `duration` | `number` | Total animation duration in ms |
|
|
933
|
+
| `isPlaying` | `boolean` | Whether currently playing |
|
|
934
|
+
|
|
935
|
+
### Target Auto-Discovery
|
|
936
|
+
|
|
937
|
+
When `load()` is called, the player automatically finds target elements by searching the container for:
|
|
938
|
+
|
|
939
|
+
1. `data-tinyfly="name"` attribute (highest priority)
|
|
940
|
+
2. Class name `.name`
|
|
941
|
+
3. ID `#name`
|
|
942
|
+
|
|
943
|
+
```html
|
|
944
|
+
<!-- All three are valid ways to mark a target named "box" -->
|
|
945
|
+
<div data-tinyfly="box"></div>
|
|
946
|
+
<div class="box"></div>
|
|
947
|
+
<div id="box"></div>
|
|
948
|
+
```
|
|
949
|
+
|
|
950
|
+
On `load()` the player also binds any `[data-tinyfly-media]` audio/video
|
|
951
|
+
elements in the container, starting each at its `data-tinyfly-start` time (ms).
|
|
952
|
+
The editor's embed export writes these attributes.
|
|
953
|
+
|
|
954
|
+
### Helper Functions
|
|
955
|
+
|
|
956
|
+
#### play()
|
|
957
|
+
|
|
958
|
+
```typescript
|
|
959
|
+
async function play(
|
|
960
|
+
container: HTMLElement | string,
|
|
961
|
+
source: string | TimelineDefinition,
|
|
962
|
+
options?: PlayerOptions
|
|
963
|
+
): Promise<TinyflyPlayer>
|
|
964
|
+
```
|
|
965
|
+
|
|
966
|
+
Create a player and immediately start playback. Shorthand for creating a player with `autoplay: true`.
|
|
967
|
+
|
|
968
|
+
```typescript
|
|
969
|
+
const player = await tinyfly.play('#animation', './animation.json', {
|
|
970
|
+
loop: -1
|
|
971
|
+
})
|
|
972
|
+
```
|
|
973
|
+
|
|
974
|
+
#### create()
|
|
975
|
+
|
|
976
|
+
```typescript
|
|
977
|
+
function create(
|
|
978
|
+
container: HTMLElement | string,
|
|
979
|
+
options?: PlayerOptions
|
|
980
|
+
): TinyflyPlayer
|
|
981
|
+
```
|
|
982
|
+
|
|
983
|
+
Create a player without auto-playing. Use this when you need to register targets or configure the player before loading.
|
|
984
|
+
|
|
985
|
+
```typescript
|
|
986
|
+
const player = tinyfly.create('#animation', { loop: -1 })
|
|
987
|
+
player.registerTarget('box', document.getElementById('my-box'))
|
|
988
|
+
await player.load('./animation.json')
|
|
989
|
+
player.play()
|
|
990
|
+
```
|
|
991
|
+
|
|
992
|
+
---
|
|
993
|
+
|
|
994
|
+
## TinyflySequencer
|
|
995
|
+
|
|
996
|
+
Multi-scene player that plays scenes in order with transitions between them.
|
|
997
|
+
|
|
998
|
+
### Constructor
|
|
999
|
+
|
|
1000
|
+
```typescript
|
|
1001
|
+
new TinyflySequencer(container: HTMLElement | string, options?: SequencerOptions)
|
|
1002
|
+
```
|
|
1003
|
+
|
|
1004
|
+
```typescript
|
|
1005
|
+
interface SequencerOptions {
|
|
1006
|
+
loop?: number // -1 = infinite, 0 = no loop
|
|
1007
|
+
autoplay?: boolean // Auto-play on load
|
|
1008
|
+
onComplete?: () => void // Called when sequence finishes
|
|
1009
|
+
onSceneChange?: (sceneIndex: number) => void // Called when scene starts
|
|
1010
|
+
}
|
|
1011
|
+
```
|
|
1012
|
+
|
|
1013
|
+
### Methods
|
|
1014
|
+
|
|
1015
|
+
#### `load(source: string | SequenceDefinition): Promise<void>`
|
|
1016
|
+
|
|
1017
|
+
Load a sequence from a URL or inline definition. Renders the first scene's elements and sets up the canvas dimensions.
|
|
1018
|
+
|
|
1019
|
+
#### `play(): void`
|
|
1020
|
+
|
|
1021
|
+
Start playing from the current scene. Does nothing if no sequence is loaded or if the sequence is empty.
|
|
1022
|
+
|
|
1023
|
+
#### `pause(): void`
|
|
1024
|
+
|
|
1025
|
+
Pause playback.
|
|
1026
|
+
|
|
1027
|
+
#### `stop(): void`
|
|
1028
|
+
|
|
1029
|
+
Stop and reset to the first scene.
|
|
1030
|
+
|
|
1031
|
+
#### `goToScene(index: number): void`
|
|
1032
|
+
|
|
1033
|
+
Jump directly to a specific scene by index. If the sequencer was playing, playback continues at the new scene. Invalid indices are ignored.
|
|
1034
|
+
|
|
1035
|
+
#### `destroy(): void`
|
|
1036
|
+
|
|
1037
|
+
Clean up all resources, remove scene containers, stop playback.
|
|
1038
|
+
|
|
1039
|
+
### Properties
|
|
1040
|
+
|
|
1041
|
+
| Property | Type | Description |
|
|
1042
|
+
|----------|------|-------------|
|
|
1043
|
+
| `currentSceneIndex` | `number` | Index of the current scene |
|
|
1044
|
+
| `sceneCount` | `number` | Total number of scenes |
|
|
1045
|
+
| `isPlaying` | `boolean` | Whether currently playing |
|
|
1046
|
+
| `state` | `string` | `'idle'`, `'playing-scene'`, or `'transitioning'` |
|
|
1047
|
+
|
|
1048
|
+
### Sequence Types
|
|
1049
|
+
|
|
1050
|
+
```typescript
|
|
1051
|
+
interface SequenceDefinition {
|
|
1052
|
+
id: string
|
|
1053
|
+
name: string
|
|
1054
|
+
canvas: { width: number; height: number }
|
|
1055
|
+
scenes: SequenceScene[]
|
|
1056
|
+
loop?: number
|
|
1057
|
+
}
|
|
1058
|
+
|
|
1059
|
+
interface SequenceScene {
|
|
1060
|
+
id: string
|
|
1061
|
+
name: string
|
|
1062
|
+
elements: SerializedElement[]
|
|
1063
|
+
timeline: TimelineDefinition | null
|
|
1064
|
+
transition: SceneTransition // Ignored for first scene
|
|
1065
|
+
}
|
|
1066
|
+
|
|
1067
|
+
interface SceneTransition {
|
|
1068
|
+
type: TransitionType
|
|
1069
|
+
duration: number // In milliseconds
|
|
1070
|
+
}
|
|
1071
|
+
|
|
1072
|
+
type TransitionType = 'none' | 'fade' | 'slide-left' | 'slide-right' | 'slide-up' | 'slide-down'
|
|
1073
|
+
```
|
|
1074
|
+
|
|
1075
|
+
### playSequence()
|
|
1076
|
+
|
|
1077
|
+
```typescript
|
|
1078
|
+
async function playSequence(
|
|
1079
|
+
container: HTMLElement | string,
|
|
1080
|
+
source: string | SequenceDefinition,
|
|
1081
|
+
options?: SequencerOptions
|
|
1082
|
+
): Promise<TinyflySequencer>
|
|
1083
|
+
```
|
|
1084
|
+
|
|
1085
|
+
Create a sequencer and immediately start playback.
|
|
1086
|
+
|
|
1087
|
+
```typescript
|
|
1088
|
+
const sequencer = await tinyfly.playSequence('#container', './sequence.json', {
|
|
1089
|
+
loop: -1,
|
|
1090
|
+
onSceneChange: (index) => console.log(`Now playing scene ${index}`)
|
|
1091
|
+
})
|
|
1092
|
+
```
|
|
1093
|
+
|
|
1094
|
+
---
|
|
1095
|
+
|
|
1096
|
+
## Media Sync
|
|
1097
|
+
|
|
1098
|
+
Locks media to a timeline. Depends only on a small structural subset of
|
|
1099
|
+
`HTMLMediaElement`, so it can drive any media source and is testable without a
|
|
1100
|
+
browser.
|
|
1101
|
+
|
|
1102
|
+
```typescript
|
|
1103
|
+
import { MediaSync, syncMediaElement } from '@algorisys/tinyfly/player'
|
|
1104
|
+
|
|
1105
|
+
interface SyncableMedia {
|
|
1106
|
+
currentTime: number // seconds
|
|
1107
|
+
readonly paused: boolean
|
|
1108
|
+
playbackRate: number
|
|
1109
|
+
play(): Promise<void> | void
|
|
1110
|
+
pause(): void
|
|
1111
|
+
}
|
|
1112
|
+
|
|
1113
|
+
interface MediaSyncOptions {
|
|
1114
|
+
offset?: number // seconds added to timeline time (default 0)
|
|
1115
|
+
driftTolerance?: number // seconds of drift allowed while playing (default 0.15)
|
|
1116
|
+
}
|
|
1117
|
+
```
|
|
1118
|
+
|
|
1119
|
+
| `MediaSync` method | Description |
|
|
1120
|
+
|--------|-------------|
|
|
1121
|
+
| `new MediaSync(media, options?)` | Wrap a media element |
|
|
1122
|
+
| `update(timelineTimeMs, isPlaying)` | Call each frame. Plays or pauses the media to match; re-seeks while playing only when drift exceeds the tolerance, and exactly while paused |
|
|
1123
|
+
| `seek(timelineTimeMs)` | Hard-align on an explicit seek |
|
|
1124
|
+
| `setRate(rate)` | Mirror the timeline speed onto `playbackRate` |
|
|
1125
|
+
| `dispose()` | Pause the media |
|
|
1126
|
+
|
|
1127
|
+
`syncMediaElement(sync, media, timelineMs, isPlaying, startMs)` handles media
|
|
1128
|
+
that starts partway through: before `startMs` it keeps the media paused at 0,
|
|
1129
|
+
after it syncs to the elapsed time. A `play()` rejected by autoplay policy is
|
|
1130
|
+
ignored, so blocked audio never stops the animation.
|
|
1131
|
+
|
|
1132
|
+
---
|
|
1133
|
+
|
|
1134
|
+
## DOMAdapter
|
|
1135
|
+
|
|
1136
|
+
Applies animation state to HTML elements using CSS transforms and styles.
|
|
1137
|
+
|
|
1138
|
+
### Usage
|
|
1139
|
+
|
|
1140
|
+
```typescript
|
|
1141
|
+
import { DOMAdapter } from '@algorisys/tinyfly/adapters'
|
|
1142
|
+
|
|
1143
|
+
const adapter = new DOMAdapter()
|
|
1144
|
+
adapter.registerTarget('box', document.getElementById('my-box'))
|
|
1145
|
+
|
|
1146
|
+
// In animation loop:
|
|
1147
|
+
const state = timeline.getStateAtTime(timeline.currentTime)
|
|
1148
|
+
adapter.applyState(state)
|
|
1149
|
+
```
|
|
1150
|
+
|
|
1151
|
+
### Methods
|
|
1152
|
+
|
|
1153
|
+
| Method | Description |
|
|
1154
|
+
|--------|-------------|
|
|
1155
|
+
| `registerTarget(id, element)` | Register an HTML element as a target |
|
|
1156
|
+
| `unregisterTarget(id)` | Remove a target |
|
|
1157
|
+
| `getTarget(id)` | Get a registered element |
|
|
1158
|
+
| `clearTargets()` | Remove all targets |
|
|
1159
|
+
| `applyState(state)` | Apply animation state to all registered targets |
|
|
1160
|
+
|
|
1161
|
+
### Property Mappings
|
|
1162
|
+
|
|
1163
|
+
The DOM adapter maps animation properties to CSS:
|
|
1164
|
+
|
|
1165
|
+
**Transform properties** (applied via `style.transform`):
|
|
1166
|
+
- `x` → `translateX`
|
|
1167
|
+
- `y` → `translateY`
|
|
1168
|
+
- `rotation` / `rotate` → `rotate`
|
|
1169
|
+
- `scale` → `scale`
|
|
1170
|
+
- `scaleX` → `scaleX`
|
|
1171
|
+
- `scaleY` → `scaleY`
|
|
1172
|
+
- `skewX` → `skewX`
|
|
1173
|
+
- `skewY` → `skewY`
|
|
1174
|
+
- `z`, `rotateX`, `rotateY`, `rotateZ`, `scaleZ` → `translateZ`, `rotateX`, … (3D)
|
|
1175
|
+
- `perspective` → `perspective()`, first in the list
|
|
1176
|
+
- `quaternion` (`[x, y, z, w]`, a track with `interpolation: 'slerp'`) → `matrix3d()`
|
|
1177
|
+
- Written in one order whatever the track order: perspective, translate, rotate, rotateX, rotateY, quaternion, scale, skew (as the SVG, Canvas and WebGL adapters compose them)
|
|
1178
|
+
|
|
1179
|
+
**3D layout:** `childPerspective` (px) and `perspectiveOriginX` / `perspectiveOriginY` (%) set CSS `perspective` / `perspective-origin` on a parent for its children; `transformStyle` and `backfaceVisibility` pass through as CSS. The Canvas and WebGL adapters take `z`, `rotateX`, `rotateY`, `quaternion`, `perspective` and `backfaceVisibility` too, in true perspective (see [3D transforms](3d-rotations.md)).
|
|
1180
|
+
|
|
1181
|
+
**Style properties:**
|
|
1182
|
+
- `opacity` → `style.opacity`
|
|
1183
|
+
- `fill` → `style.backgroundColor` (or `style.color` for text)
|
|
1184
|
+
- `stroke` → `style.borderColor`
|
|
1185
|
+
- `strokeWidth` → `style.borderWidth`
|
|
1186
|
+
- `width` → `style.width`
|
|
1187
|
+
- `height` → `style.height`
|
|
1188
|
+
- `borderRadius` → `style.borderRadius`
|
|
1189
|
+
- `fontSize` → `style.fontSize`
|
|
1190
|
+
|
|
1191
|
+
**Motion path properties:**
|
|
1192
|
+
- `motionPathX` → adds `translateX` override
|
|
1193
|
+
- `motionPathY` → adds `translateY` override
|
|
1194
|
+
- `motionPathRotate` → adds `rotate` override
|
|
1195
|
+
|
|
1196
|
+
---
|
|
1197
|
+
|
|
1198
|
+
## CanvasAdapter
|
|
1199
|
+
|
|
1200
|
+
Draws animated shapes on a Canvas 2D context.
|
|
1201
|
+
|
|
1202
|
+
### Usage
|
|
1203
|
+
|
|
1204
|
+
```typescript
|
|
1205
|
+
import { CanvasAdapter } from '@algorisys/tinyfly/adapters'
|
|
1206
|
+
|
|
1207
|
+
const canvas = document.getElementById('my-canvas') as HTMLCanvasElement
|
|
1208
|
+
const ctx = canvas.getContext('2d')
|
|
1209
|
+
const adapter = new CanvasAdapter()
|
|
1210
|
+
|
|
1211
|
+
// Register targets
|
|
1212
|
+
adapter.registerTarget('box', {
|
|
1213
|
+
type: 'rect',
|
|
1214
|
+
x: 50, y: 50, width: 100, height: 100,
|
|
1215
|
+
fillStyle: '#4a9eff'
|
|
1216
|
+
})
|
|
1217
|
+
|
|
1218
|
+
// Animation loop
|
|
1219
|
+
function animate() {
|
|
1220
|
+
const state = timeline.getStateAtTime(timeline.currentTime)
|
|
1221
|
+
adapter.applyState(state)
|
|
1222
|
+
|
|
1223
|
+
ctx.clearRect(0, 0, canvas.width, canvas.height)
|
|
1224
|
+
adapter.render(ctx)
|
|
1225
|
+
requestAnimationFrame(animate)
|
|
1226
|
+
}
|
|
1227
|
+
```
|
|
1228
|
+
|
|
1229
|
+
### Methods
|
|
1230
|
+
|
|
1231
|
+
| Method | Description |
|
|
1232
|
+
|--------|-------------|
|
|
1233
|
+
| `registerTarget(id, target, aliasFor?)` | Register a canvas target |
|
|
1234
|
+
| `unregisterTarget(id)` | Remove a target |
|
|
1235
|
+
| `getTarget(id)` | Get a registered target |
|
|
1236
|
+
| `clearTargets()` | Remove all targets |
|
|
1237
|
+
| `applyState(state)` | Update target properties from animation state |
|
|
1238
|
+
| `render(ctx)` | Draw all targets to a canvas context |
|
|
1239
|
+
| `static loadImage(src)` | Load an image for use as ImageTarget |
|
|
1240
|
+
|
|
1241
|
+
### Sketched and drawn-on shapes
|
|
1242
|
+
|
|
1243
|
+
Rect, circle, line and path targets take two more properties:
|
|
1244
|
+
|
|
1245
|
+
| Property | |
|
|
1246
|
+
|---|---|
|
|
1247
|
+
| `sketch` | A `SketchStyle` (`roughness`, `passes`, `boil`, `seed`): the outline is drawn in hand-drawn pencil strokes that boil; the fill stays clean |
|
|
1248
|
+
| `drawOn` | 0..1, how much of the outline is drawn (default 1). Animate it to draw a shape on; the fill appears once the outline is complete. Circles start at the top and go clockwise |
|
|
1249
|
+
|
|
1250
|
+
```typescript
|
|
1251
|
+
adapter.registerTarget('box', {
|
|
1252
|
+
type: 'rect', x: 50, y: 50, width: 100, height: 100,
|
|
1253
|
+
fillStyle: '#fde68a', strokeStyle: '#2f2f33', lineWidth: 4,
|
|
1254
|
+
sketch: { roughness: 3, boil: 8 },
|
|
1255
|
+
})
|
|
1256
|
+
// …and a track: { target: 'box', property: 'drawOn', keyframes: [{ time: 0, value: 0 }, { time: 800, value: 1 }] }
|
|
1257
|
+
```
|
|
1258
|
+
|
|
1259
|
+
Without `sketch`, and with `drawOn` at 1, shapes draw exactly as before. The
|
|
1260
|
+
pen and the outline helpers are exported too: `sketchPen()`, `boilFrame()`,
|
|
1261
|
+
`pathOutline()`, `rectOutline()`, `drawOutline()`, `partialPath()`,
|
|
1262
|
+
`pointAlong()`, `pathLength()`.
|
|
1263
|
+
|
|
1264
|
+
### Target Types
|
|
1265
|
+
|
|
1266
|
+
#### RectTarget
|
|
1267
|
+
|
|
1268
|
+
```typescript
|
|
1269
|
+
{
|
|
1270
|
+
type: 'rect'
|
|
1271
|
+
x: number, y: number, width: number, height: number
|
|
1272
|
+
opacity?: number, rotate?: number, scale?: number
|
|
1273
|
+
fillStyle?: string | LinearGradient | RadialGradient
|
|
1274
|
+
strokeStyle?: string, lineWidth?: number
|
|
1275
|
+
borderRadius?: number
|
|
1276
|
+
}
|
|
1277
|
+
```
|
|
1278
|
+
|
|
1279
|
+
#### CircleTarget
|
|
1280
|
+
|
|
1281
|
+
```typescript
|
|
1282
|
+
{
|
|
1283
|
+
type: 'circle'
|
|
1284
|
+
x: number, y: number, radius: number
|
|
1285
|
+
opacity?: number, rotate?: number, scale?: number
|
|
1286
|
+
fillStyle?: string | LinearGradient | RadialGradient
|
|
1287
|
+
strokeStyle?: string, lineWidth?: number
|
|
1288
|
+
}
|
|
1289
|
+
```
|
|
1290
|
+
|
|
1291
|
+
#### TextTarget
|
|
1292
|
+
|
|
1293
|
+
```typescript
|
|
1294
|
+
{
|
|
1295
|
+
type: 'text'
|
|
1296
|
+
x: number, y: number, text: string
|
|
1297
|
+
fontSize?: number, fontFamily?: string, fontWeight?: number
|
|
1298
|
+
textAlign?: 'left' | 'center' | 'right'
|
|
1299
|
+
textBaseline?: CanvasTextBaseline
|
|
1300
|
+
fillStyle?: string | LinearGradient | RadialGradient
|
|
1301
|
+
strokeStyle?: string
|
|
1302
|
+
}
|
|
1303
|
+
```
|
|
1304
|
+
|
|
1305
|
+
#### LineTarget
|
|
1306
|
+
|
|
1307
|
+
```typescript
|
|
1308
|
+
{
|
|
1309
|
+
type: 'line'
|
|
1310
|
+
x: number, y: number, x2: number, y2: number
|
|
1311
|
+
strokeStyle?: string, lineWidth?: number
|
|
1312
|
+
lineCap?: CanvasLineCap
|
|
1313
|
+
}
|
|
1314
|
+
```
|
|
1315
|
+
|
|
1316
|
+
#### PathTarget
|
|
1317
|
+
|
|
1318
|
+
```typescript
|
|
1319
|
+
{
|
|
1320
|
+
type: 'path'
|
|
1321
|
+
x: number, y: number, d: string // SVG path data
|
|
1322
|
+
fillStyle?: string | LinearGradient | RadialGradient
|
|
1323
|
+
strokeStyle?: string, lineWidth?: number
|
|
1324
|
+
lineCap?: CanvasLineCap, lineJoin?: CanvasLineJoin
|
|
1325
|
+
}
|
|
1326
|
+
```
|
|
1327
|
+
|
|
1328
|
+
#### ImageTarget
|
|
1329
|
+
|
|
1330
|
+
```typescript
|
|
1331
|
+
{
|
|
1332
|
+
type: 'image'
|
|
1333
|
+
x: number, y: number, width: number, height: number
|
|
1334
|
+
image: CanvasImageSource | null
|
|
1335
|
+
opacity?: number
|
|
1336
|
+
}
|
|
1337
|
+
```
|
|
1338
|
+
|
|
1339
|
+
#### CustomTarget
|
|
1340
|
+
|
|
1341
|
+
Drawn by code, animated by the timeline. The context is translated to `x`/`y`
|
|
1342
|
+
with opacity, transforms, fill, stroke and filters applied, so `draw` works in
|
|
1343
|
+
local coordinates. A track whose property is a key of `props` writes into
|
|
1344
|
+
`props`; base properties (`x`, `opacity`, `rotate`, …) behave as usual.
|
|
1345
|
+
|
|
1346
|
+
```typescript
|
|
1347
|
+
{
|
|
1348
|
+
type: 'custom'
|
|
1349
|
+
x: number, y: number, width: number, height: number // box = transform pivot
|
|
1350
|
+
draw: (ctx: CanvasRenderingContext2D, target: CustomTarget, time: number) => void
|
|
1351
|
+
props?: Record<string, AnimatableValue> // values tracks may animate
|
|
1352
|
+
opacity?: number, rotate?: number, scale?: number
|
|
1353
|
+
}
|
|
1354
|
+
```
|
|
1355
|
+
|
|
1356
|
+
### Gradient Support
|
|
1357
|
+
|
|
1358
|
+
```typescript
|
|
1359
|
+
interface LinearGradient {
|
|
1360
|
+
type: 'linear'
|
|
1361
|
+
angle: number // Degrees
|
|
1362
|
+
stops: GradientStop[]
|
|
1363
|
+
}
|
|
1364
|
+
|
|
1365
|
+
interface RadialGradient {
|
|
1366
|
+
type: 'radial'
|
|
1367
|
+
centerX: number // 0-1, relative to target
|
|
1368
|
+
centerY: number // 0-1, relative to target
|
|
1369
|
+
radius: number // 0-1, relative to target
|
|
1370
|
+
stops: GradientStop[]
|
|
1371
|
+
}
|
|
1372
|
+
|
|
1373
|
+
interface GradientStop {
|
|
1374
|
+
offset: number // 0-1
|
|
1375
|
+
color: string
|
|
1376
|
+
}
|
|
1377
|
+
```
|
|
1378
|
+
|
|
1379
|
+
---
|
|
1380
|
+
|
|
1381
|
+
## SVGAdapter
|
|
1382
|
+
|
|
1383
|
+
Applies animation state to SVG elements.
|
|
1384
|
+
|
|
1385
|
+
### Usage
|
|
1386
|
+
|
|
1387
|
+
```typescript
|
|
1388
|
+
import { SVGAdapter } from '@algorisys/tinyfly/adapters'
|
|
1389
|
+
|
|
1390
|
+
const adapter = new SVGAdapter()
|
|
1391
|
+
const circle = document.querySelector('circle') as SVGElement
|
|
1392
|
+
adapter.registerTarget('ball', circle)
|
|
1393
|
+
|
|
1394
|
+
// In animation loop:
|
|
1395
|
+
adapter.applyState(state)
|
|
1396
|
+
```
|
|
1397
|
+
|
|
1398
|
+
### Methods
|
|
1399
|
+
|
|
1400
|
+
Same interface as DOMAdapter:
|
|
1401
|
+
|
|
1402
|
+
| Method | Description |
|
|
1403
|
+
|--------|-------------|
|
|
1404
|
+
| `registerTarget(id, element)` | Register an SVG element |
|
|
1405
|
+
| `unregisterTarget(id)` | Remove a target |
|
|
1406
|
+
| `getTarget(id)` | Get a registered element |
|
|
1407
|
+
| `clearTargets()` | Remove all targets |
|
|
1408
|
+
| `applyState(state)` | Apply state to SVG elements |
|
|
1409
|
+
|
|
1410
|
+
### Property Mappings
|
|
1411
|
+
|
|
1412
|
+
**SVG attributes** (set via `setAttribute`):
|
|
1413
|
+
- `fill`, `stroke`, `d`, `points`
|
|
1414
|
+
- `x`, `y`, `cx`, `cy`, `r`, `rx`, `ry`
|
|
1415
|
+
- `width`, `height`
|
|
1416
|
+
- `strokeWidth` → `stroke-width`
|
|
1417
|
+
- `borderRadius` → `rx`
|
|
1418
|
+
|
|
1419
|
+
**Transform properties** (set via `style.transform`):
|
|
1420
|
+
- `x`, `y` → `translateX`/`translateY` (for non-positioning elements)
|
|
1421
|
+
- `rotation` → `rotate`
|
|
1422
|
+
- `scale`, `scaleX`, `scaleY` → `scale`
|
|
1423
|
+
|
|
1424
|
+
**Style properties:**
|
|
1425
|
+
- `opacity` → `style.opacity`
|
|
1426
|
+
- `fontSize` → `style.fontSize`
|
|
1427
|
+
|
|
1428
|
+
---
|
|
1429
|
+
|
|
1430
|
+
## Export Formats
|
|
1431
|
+
|
|
1432
|
+
The exporters are their own entry point, `@algorisys/tinyfly/export`, so the engine stays
|
|
1433
|
+
small for pages that only play animations (the exporters are about half its size).
|
|
1434
|
+
|
|
1435
|
+
### CSS Export
|
|
1436
|
+
|
|
1437
|
+
```typescript
|
|
1438
|
+
import { exportToCSS } from '@algorisys/tinyfly/export'
|
|
1439
|
+
|
|
1440
|
+
interface CSSExportOptions {
|
|
1441
|
+
classPrefix?: string // CSS class prefix (default: 'tinyfly')
|
|
1442
|
+
includeKeyframes?: boolean // Include @keyframes (default: true)
|
|
1443
|
+
includeAnimation?: boolean // Include animation properties (default: true)
|
|
1444
|
+
minify?: boolean // Minify output (default: false)
|
|
1445
|
+
propertyMap?: Record<string, string> // Custom property name mapping
|
|
1446
|
+
}
|
|
1447
|
+
|
|
1448
|
+
interface CSSExportResult {
|
|
1449
|
+
css: string // Full CSS output
|
|
1450
|
+
keyframes: Map<string, string> // Individual @keyframes blocks
|
|
1451
|
+
selectors: Map<string, string> // Individual animation properties
|
|
1452
|
+
}
|
|
1453
|
+
|
|
1454
|
+
const result = exportToCSS(timeline, {
|
|
1455
|
+
classPrefix: 'my-anim',
|
|
1456
|
+
minify: true
|
|
1457
|
+
})
|
|
1458
|
+
|
|
1459
|
+
// result.css contains the full CSS output
|
|
1460
|
+
```
|
|
1461
|
+
|
|
1462
|
+
Generates standard CSS `@keyframes` animations. Combines transform properties automatically and maps easing to CSS timing functions.
|
|
1463
|
+
|
|
1464
|
+
### Lottie Export
|
|
1465
|
+
|
|
1466
|
+
```typescript
|
|
1467
|
+
import { exportToLottie } from '@algorisys/tinyfly/export'
|
|
1468
|
+
|
|
1469
|
+
interface LottieExportOptions {
|
|
1470
|
+
name?: string // Animation name
|
|
1471
|
+
frameRate?: number // Frame rate (default: 60)
|
|
1472
|
+
width?: number // Canvas width (default: 512)
|
|
1473
|
+
height?: number // Canvas height (default: 512)
|
|
1474
|
+
backgroundColor?: string // Background color
|
|
1475
|
+
}
|
|
1476
|
+
|
|
1477
|
+
const lottie = exportToLottie(timeline, {
|
|
1478
|
+
name: 'My Animation',
|
|
1479
|
+
frameRate: 30,
|
|
1480
|
+
width: 800,
|
|
1481
|
+
height: 600
|
|
1482
|
+
})
|
|
1483
|
+
|
|
1484
|
+
// lottie is a bodymovin-compatible JSON object
|
|
1485
|
+
```
|
|
1486
|
+
|
|
1487
|
+
Exports animations in the Lottie/bodymovin format. Supports position, rotation, scale, and opacity properties.
|
|
1488
|
+
|
|
1489
|
+
### GIF Export
|
|
1490
|
+
|
|
1491
|
+
```typescript
|
|
1492
|
+
import { extractFrames } from '@algorisys/tinyfly/export'
|
|
1493
|
+
|
|
1494
|
+
interface GIFExportOptions {
|
|
1495
|
+
width: number
|
|
1496
|
+
height: number
|
|
1497
|
+
frameRate?: number // Default: 30
|
|
1498
|
+
quality?: number // 1-20, lower = better quality
|
|
1499
|
+
backgroundColor?: string
|
|
1500
|
+
loops?: number // 0 = infinite loop
|
|
1501
|
+
renderFrame?: (
|
|
1502
|
+
ctx: CanvasRenderingContext2D,
|
|
1503
|
+
values: Map<string, Map<string, AnimatableValue>>,
|
|
1504
|
+
time: number
|
|
1505
|
+
) => void
|
|
1506
|
+
}
|
|
1507
|
+
|
|
1508
|
+
interface GIFExportResult {
|
|
1509
|
+
frames: GIFFrame[]
|
|
1510
|
+
duration: number
|
|
1511
|
+
frameCount: number
|
|
1512
|
+
}
|
|
1513
|
+
|
|
1514
|
+
const result = extractFrames(timeline, {
|
|
1515
|
+
width: 400,
|
|
1516
|
+
height: 300,
|
|
1517
|
+
frameRate: 15
|
|
1518
|
+
})
|
|
1519
|
+
```
|
|
1520
|
+
|
|
1521
|
+
Extracts individual frames from the animation. Use with a GIF encoder library (like gif.js or gifenc) to create the actual GIF file. The `renderFrame` callback lets you customize how each frame is drawn.
|
|
1522
|
+
|
|
1523
|
+
The engine also ships real encoders used by the editor, each taking a
|
|
1524
|
+
`renderFrame` callback:
|
|
1525
|
+
|
|
1526
|
+
```typescript
|
|
1527
|
+
exportToGIF(timeline: Timeline, options: GIFExportOptions): Promise<Blob>
|
|
1528
|
+
exportToWebP(timeline: Timeline, options: WebPExportOptions): Promise<Blob>
|
|
1529
|
+
```
|
|
1530
|
+
|
|
1531
|
+
### Video Export
|
|
1532
|
+
|
|
1533
|
+
```typescript
|
|
1534
|
+
import { exportVideo, exportToMP4, exportToVideo, getVideoExportFormats, isVideoExportSupported } from '@algorisys/tinyfly/export'
|
|
1535
|
+
|
|
1536
|
+
isVideoExportSupported(): boolean
|
|
1537
|
+
getVideoExportFormats(): VideoExportFormat[] // { id, label, extension, deterministic }, best first
|
|
1538
|
+
exportVideo(options: VideoExportOptions & { format?: string }): Promise<{ blob: Blob; extension: string }>
|
|
1539
|
+
exportToMP4(options: MP4ExportOptions): Promise<Blob>
|
|
1540
|
+
exportToVideo(options: VideoExportOptions): Promise<Blob>
|
|
1541
|
+
```
|
|
1542
|
+
|
|
1543
|
+
| Function | Description |
|
|
1544
|
+
|----------|-------------|
|
|
1545
|
+
| `isVideoExportSupported` | Whether this environment can export video at all (needs a DOM, and WebCodecs or MediaRecorder) |
|
|
1546
|
+
| `getVideoExportFormats` | Formats this browser can produce: MP4 (H.264) via WebCodecs first (`id: 'mp4-webcodecs'`, deterministic), then MediaRecorder codecs such as WebM VP9/VP8 (real-time) |
|
|
1547
|
+
| `exportVideo` | Export with the format whose `id` you pass, or the best one |
|
|
1548
|
+
| `exportToMP4` | Encode H.264 MP4 with WebCodecs. Not real-time: frames are encoded as fast as possible at exact timestamps. Throws without WebCodecs |
|
|
1549
|
+
| `exportToVideo` | Record with MediaRecorder in real time (a 6s animation takes ~6s). `mimeType` defaults to the best supported codec |
|
|
1550
|
+
|
|
1551
|
+
Shared options: `width`, `height`, `durationMs`, `fps` (default 30), `bitrate`,
|
|
1552
|
+
`background` (default white; `null` keeps transparency),
|
|
1553
|
+
`renderFrame(ctx, timeMs)` (may be async), `onProgress(fraction)` and `signal`
|
|
1554
|
+
(an `AbortSignal`). `exportToMP4` also takes `bitsPerPixel` (default 0.25) and
|
|
1555
|
+
`keyFrameInterval`, and rounds the size up to even numbers. `downloadVideo(blob,
|
|
1556
|
+
filename?)` saves the result.
|
|
1557
|
+
|
|
1558
|
+
`exportToLottieJSON(timeline, options?)` returns `exportToLottie`'s result as a
|
|
1559
|
+
JSON string.
|
|
1560
|
+
|
|
1561
|
+
### Sprite-sheet layout
|
|
1562
|
+
|
|
1563
|
+
```typescript
|
|
1564
|
+
import {
|
|
1565
|
+
spriteSheetLayout, frameCell, spriteFrameTimes, spriteSheetMeta
|
|
1566
|
+
} from '@algorisys/tinyfly'
|
|
1567
|
+
|
|
1568
|
+
const layout = spriteSheetLayout(frames, frameWidth, frameHeight, maxColumns) // grid + sheet size
|
|
1569
|
+
const cell = frameCell(index, layout) // { index, col, row, x, y }
|
|
1570
|
+
const times = spriteFrameTimes(frames, durationMs) // even sample times (loop-safe)
|
|
1571
|
+
const meta = spriteSheetMeta(layout, fps, durationMs) // portable JSON metadata
|
|
1572
|
+
```
|
|
1573
|
+
|
|
1574
|
+
Pure helpers for packing animation frames into a grid PNG and writing matching
|
|
1575
|
+
metadata (frame size, columns/rows, count, fps). The editor's **Sprite** export
|
|
1576
|
+
uses them to render each frame into its cell and download `…-spritesheet.png` +
|
|
1577
|
+
`…-spritesheet.json`. See [sprite-sheet-export.md](sprite-sheet-export.md).
|
|
1578
|
+
|
|
1579
|
+
---
|
|
1580
|
+
|
|
1581
|
+
### Captions (SRT / WebVTT)
|
|
1582
|
+
|
|
1583
|
+
```typescript
|
|
1584
|
+
import { toSRT, toWebVTT, captionCuesFromTimeline } from '@algorisys/tinyfly/export'
|
|
1585
|
+
|
|
1586
|
+
interface CaptionCue { start: number; end: number; text: string } // ms
|
|
1587
|
+
|
|
1588
|
+
toSRT(cues) // "1\n00:00:00,350 --> 00:00:01,750\nMeet the figure.\n…"
|
|
1589
|
+
toWebVTT(cues) // "WEBVTT\n\n00:00:00.350 --> …"
|
|
1590
|
+
captionCuesFromTimeline(definition, { language: 'es' }) // marker → next marker
|
|
1591
|
+
```
|
|
1592
|
+
|
|
1593
|
+
---
|
|
1594
|
+
|
|
1595
|
+
## Headless Video
|
|
1596
|
+
|
|
1597
|
+
Render a scene to MP4 or PNG stills in Node (needs `@napi-rs/canvas` and
|
|
1598
|
+
`ffmpeg`). The guide is [Rendering Video from Code](video-rendering.md).
|
|
1599
|
+
|
|
1600
|
+
```typescript
|
|
1601
|
+
import { renderVideo, renderStills, FrameRenderer, sceneCaptions } from '@algorisys/tinyfly/headless'
|
|
1602
|
+
|
|
1603
|
+
await renderVideo(scene, { output: 'out.mp4', baseDir, scale, fps, crf, preset, audio, ffmpeg, onProgress })
|
|
1604
|
+
await renderStills(scene, { dir: 'stills', times?: [{ id, time }] }) // default: mid-caption, else mid-marker-step
|
|
1605
|
+
|
|
1606
|
+
const renderer = new FrameRenderer(scene, { scale: 1 }) // no Node API: any 2D context
|
|
1607
|
+
renderer.render(ctx, timeMs)
|
|
1608
|
+
renderer.frameCount; renderer.frameTime(i); renderer.stillTimes()
|
|
1609
|
+
```
|
|
1610
|
+
|
|
1611
|
+
| `VideoScene` field | Meaning |
|
|
1612
|
+
|---|---|
|
|
1613
|
+
| `width`, `height`, `fps` | Frame size and rate (fps default 30) |
|
|
1614
|
+
| `duration` | ms; defaults to the timeline's duration |
|
|
1615
|
+
| `timeline`, `targets` | A `TimelineDefinition` and the canvas targets it animates |
|
|
1616
|
+
| `background` | Colour, `'transparent'`, or `(ctx, frame) => void` drawn under the targets |
|
|
1617
|
+
| `draw` | `(ctx, frame) => void` drawn over the targets |
|
|
1618
|
+
| `audio`, `fonts` | Soundtrack and font files, relative to `baseDir` |
|
|
1619
|
+
| `captions` | Cues for `--srt` / `--vtt`; default from the timeline's markers |
|
|
1620
|
+
| `bloom` | `true` or `{ threshold, strength, radius, halo, downsample }`: a glow around bright things |
|
|
1621
|
+
|
|
1622
|
+
Loops and glow:
|
|
1623
|
+
|
|
1624
|
+
```typescript
|
|
1625
|
+
checkLoop(scene, { scale?, fps?, baseDir? }): Promise<LoopReport> // { closure, seam, steps, loops, verdict }
|
|
1626
|
+
psnr(a, b): number; loopReport(frames): LoopReport // pure, on RGBA frames
|
|
1627
|
+
|
|
1628
|
+
// @algorisys/tinyfly/adapters (and the browser bundle): any 2D canvas
|
|
1629
|
+
applyBloom(ctx, { threshold = 0.55, strength = 0.9, radius, halo = 0.6, downsample = 4 })
|
|
1630
|
+
brightPass(rgba, threshold): Float32Array; boxBlur(rgb, width, height, radius): Float32Array
|
|
1631
|
+
```
|
|
1632
|
+
|
|
1633
|
+
### Narration audio
|
|
1634
|
+
|
|
1635
|
+
```typescript
|
|
1636
|
+
voiceNarration(scenes: VoicedScene[], { output, baseDir, sampleRate = 48000, ffmpeg, lead, gap, tail })
|
|
1637
|
+
: Promise<{ plan: NarrationPlan; audio: string }> // lines carry `audio` instead of `duration`
|
|
1638
|
+
decodeAudio(file, { sampleRate, ffmpeg }): Promise<Float32Array> // mono float samples
|
|
1639
|
+
assembleNarration(plan, clips: Float32Array[], sampleRate): Float32Array // pure
|
|
1640
|
+
encodeWav(samples, sampleRate): Uint8Array // pure, 16-bit mono
|
|
1641
|
+
```
|
|
1642
|
+
|
|
1643
|
+
### Characters
|
|
1644
|
+
|
|
1645
|
+
`@algorisys/tinyfly/characters` (browser-safe): `StickPose`, `REST_POSE`, `POSES`,
|
|
1646
|
+
`EXPRESSIONS`, `Expression`, `withExpression()`, `pose()`, `blendPose()`, `walkPose()`, `strideLength()`, `talkingMouth()`, `drawStickFigure()`, `rubberLimb()`,
|
|
1647
|
+
`stickFigureTarget()`, `poseTracks()`, joints and costume layers: `stickFigureJoints()`, `resolveStickPose()`, `stickFigureAt()`, `jointsToScene()`, `headPoint()`, `StickStyle.layers`, `StickStyle.shoulderWidth`, the `turn` and `sit` pose fields, `seatHeight()`, `taperedLine()`, `StickStyle.classic` and `StickStyle.headSize`, and the pencil sketch style: `SketchStyle`, `sketchPen()`, `boilFrame()`, erasing: `erasable()`, `withErased()`, `clipErased()`, `scrubPath()`, `drawEraser()`, `partialPath()`, `pointAlong()`, `pathLength()`, and the drawing hand: `drawnPathTarget()`, `drawHand()`, `drawPencil()`, `circlePath()`. See
|
|
1648
|
+
[Rendering Video from Code](video-rendering.md#characters).
|
|
1649
|
+
|
|
1650
|
+
Dance and flips (see [Dance and Flips](dance.md)): the pose fields `leftWrist`/`rightWrist`, `leftAnkle`/`rightAnkle`, `leftFootOut`/`rightFootOut`, `spin`, `rise`; `StickStyle.hands` (cartoon hands), `StickJoints.fingertips`;
|
|
1651
|
+
`DANCE_STYLES`, `DanceStyle`, `DanceMove`, `DanceKey`, `Groove`, `RoutineStep`, `MUDRAS`, `danceFrame()`, `dancePose()`, `danceTaps()`, `danceTravel()`, `danceTravelTrack()`, `stickToHuman()`, `mirrorHumanPose()`, `handProp()`, `DanceTap`, `TapName`, `routineBeats()`, `beatAt()`, `mirrorPose()`, `applyGroove()`, `danceStance()`, `dancer()`, `danceTracks()`, `bakeDanceTracks()`, `stickFigureTarget({ dance })` with the `beat` and `dancing` props, `resolveStickFrame()`;
|
|
1652
|
+
`FLIPS`, `Flip`, `FlipKey`, `flipPose()`, `flipTravel()`, `flipTracks()`; `POSES.sideSplit` and `POSES.frontSplit`.
|
|
1653
|
+
|
|
1654
|
+
### Beats
|
|
1655
|
+
|
|
1656
|
+
In the engine (`@algorisys/tinyfly`), pure:
|
|
1657
|
+
|
|
1658
|
+
```typescript
|
|
1659
|
+
interface BeatGrid { bpm: number; offset: number /* ms of a beat */; beatsPerBar?: number }
|
|
1660
|
+
beatLength(grid): number // ms between beats
|
|
1661
|
+
beatTime(grid, n): number // ms of beat n
|
|
1662
|
+
beatAtTime(grid, time): number // which beat (fractional)
|
|
1663
|
+
nearestBeat(grid, time): number
|
|
1664
|
+
nextBeat(grid, time): number
|
|
1665
|
+
beatsBetween(grid, from, to): { time, bar, n }[]
|
|
1666
|
+
detectTempo(samples: Float32Array, sampleRate, { minBpm = 70, maxBpm = 180, maxSeconds = 60 }):
|
|
1667
|
+
{ bpm, offset /* ms into the audio */, confidence /* 0..1 */ }
|
|
1668
|
+
```
|
|
1669
|
+
|
|
1670
|
+
`detectTempo` is deterministic: onset strength from 10 ms loudness frames,
|
|
1671
|
+
autocorrelation for the tempo (gently preferring tempos near 120 to settle
|
|
1672
|
+
half- and double-time), then tempo and phase fitted together over the clip.
|
|
1673
|
+
In Node, feed it `decodeAudio()` samples; the editor decodes clips in the
|
|
1674
|
+
browser.
|
|
1675
|
+
|
|
1676
|
+
### Narration timing
|
|
1677
|
+
|
|
1678
|
+
In the engine (`@algorisys/tinyfly`):
|
|
1679
|
+
|
|
1680
|
+
```typescript
|
|
1681
|
+
planNarration(scenes: NarrationScene[], { lead = 350, gap = 300, tail = 550 }): NarrationPlan
|
|
1682
|
+
narrationMarkers(plan): TimelineMarker[] // one per line, labelled with its text
|
|
1683
|
+
narrationSceneAt(plan, time): NarrationSceneTiming | undefined
|
|
1684
|
+
```
|
|
1685
|
+
|
|
1686
|
+
---
|
|
1687
|
+
|
|
1688
|
+
## WebGLAdapter
|
|
1689
|
+
|
|
1690
|
+
A minimal GPU render target: every element is a textured or solid-coloured quad
|
|
1691
|
+
with a transform, opacity and tint. Covers the same ground as the Canvas adapter
|
|
1692
|
+
for moving, scaling, rotating and fading rectangles and images. Paths, text and
|
|
1693
|
+
gradients are out of scope — use the Canvas or SVG adapter for those.
|
|
1694
|
+
|
|
1695
|
+
```typescript
|
|
1696
|
+
import { WebGLAdapter } from '@algorisys/tinyfly/adapters'
|
|
1697
|
+
|
|
1698
|
+
const gl = canvas.getContext('webgl')!
|
|
1699
|
+
const adapter = new WebGLAdapter(gl)
|
|
1700
|
+
|
|
1701
|
+
adapter.registerTarget('box', { x: 200, y: 100, width: 80, height: 80, fill: '#4f9' })
|
|
1702
|
+
|
|
1703
|
+
timeline.onUpdate = (state) => {
|
|
1704
|
+
adapter.applyState(state)
|
|
1705
|
+
adapter.render()
|
|
1706
|
+
}
|
|
1707
|
+
```
|
|
1708
|
+
|
|
1709
|
+
Pure helpers `quadMatrix(target, canvasWidth, canvasHeight)` and
|
|
1710
|
+
`parseColor(hex)` are exported for testing and for building your own renderer.
|
|
1711
|
+
|
|
1712
|
+
---
|
|
1713
|
+
|
|
1714
|
+
## Inertia Tracks
|
|
1715
|
+
|
|
1716
|
+
A throw: a value released with a velocity that slows under friction and comes to rest.
|
|
1717
|
+
|
|
1718
|
+
```typescript
|
|
1719
|
+
interface InertiaConfig {
|
|
1720
|
+
from: number
|
|
1721
|
+
velocity: number // units per second at release
|
|
1722
|
+
friction?: number // decay rate per second (default 4)
|
|
1723
|
+
min?: number
|
|
1724
|
+
max?: number
|
|
1725
|
+
end?: number | number[] // snap to multiples of a number, or the nearest listed value
|
|
1726
|
+
restDelta?: number // settle threshold (default: scales with distance)
|
|
1727
|
+
}
|
|
1728
|
+
|
|
1729
|
+
interface InertiaTrack {
|
|
1730
|
+
id: string
|
|
1731
|
+
target: string
|
|
1732
|
+
property: string
|
|
1733
|
+
kind: 'inertia'
|
|
1734
|
+
inertia: InertiaConfig
|
|
1735
|
+
delay?: number; targets?: string[]; stagger?: StaggerConfig
|
|
1736
|
+
}
|
|
1737
|
+
```
|
|
1738
|
+
|
|
1739
|
+
`x(t) = from + (rest − from)(1 − e^(−friction·t))`, where `rest` is the free
|
|
1740
|
+
throw's stopping point (`from + velocity / friction`), snapped, then clamped to
|
|
1741
|
+
bounds. Settling takes the same time for any distance, like springs.
|
|
1742
|
+
|
|
1743
|
+
```typescript
|
|
1744
|
+
inertiaValueAt(config, timeMs): number
|
|
1745
|
+
inertiaVelocityAt(config, timeMs): number
|
|
1746
|
+
inertiaRest(config): number // where it comes to rest
|
|
1747
|
+
naturalRest(config): number // where a free throw would stop
|
|
1748
|
+
inertiaDuration(config): number // ms until settled
|
|
1749
|
+
bakeInertiaTrack(track, options?): Track<number>
|
|
1750
|
+
```
|
|
1751
|
+
|
|
1752
|
+
`Timeline.replaceTrack(id, track)` swaps a track in place — see
|
|
1753
|
+
[Timeline methods](#methods).
|
|
1754
|
+
|
|
1755
|
+
---
|
|
1756
|
+
|
|
1757
|
+
## Spring Tracks
|
|
1758
|
+
|
|
1759
|
+
A track whose values come from a physical simulation rather than keyframes.
|
|
1760
|
+
|
|
1761
|
+
```typescript
|
|
1762
|
+
timeline.addTrack({
|
|
1763
|
+
id: 'pop',
|
|
1764
|
+
target: 'box',
|
|
1765
|
+
property: 'scale',
|
|
1766
|
+
kind: 'spring',
|
|
1767
|
+
spring: { from: 0, to: 1, stiffness: 200, damping: 12, mass: 1, velocity: 0 },
|
|
1768
|
+
})
|
|
1769
|
+
```
|
|
1770
|
+
|
|
1771
|
+
| Field | Default | Meaning |
|
|
1772
|
+
|---|---|---|
|
|
1773
|
+
| `from` / `to` | — | Start and resting values |
|
|
1774
|
+
| `stiffness` | 180 | Higher is snappier |
|
|
1775
|
+
| `damping` | 12 | Higher settles sooner; 0 oscillates forever |
|
|
1776
|
+
| `mass` | 1 | Higher is more sluggish |
|
|
1777
|
+
| `velocity` | 0 | Initial velocity, units/second |
|
|
1778
|
+
| `restDelta` | 0.01 | Distance from `to` that counts as settled, as a fraction of the travel distance |
|
|
1779
|
+
| `restSpeed` | 0.1 | Speed that counts as settled, as a fraction of the travel distance per second |
|
|
1780
|
+
|
|
1781
|
+
Springs are integrated at a **fixed 1ms timestep from t=0** on every query, so
|
|
1782
|
+
`getValueAtTime` stays a pure function of time: seeking backwards gives the same
|
|
1783
|
+
values as playing forwards, and two runs are byte-identical. The simulation is
|
|
1784
|
+
memoised, so scrubbing is cheap after the first pass. An undamped spring is
|
|
1785
|
+
capped at 60s so its duration stays finite.
|
|
1786
|
+
|
|
1787
|
+
Because the animation is the *parameters*, a spring track serializes like any
|
|
1788
|
+
other track.
|
|
1789
|
+
|
|
1790
|
+
```typescript
|
|
1791
|
+
import {
|
|
1792
|
+
SpringSampler, springValueAt, springDuration, isUnderdamped, criticalDamping,
|
|
1793
|
+
} from '@algorisys/tinyfly'
|
|
1794
|
+
|
|
1795
|
+
springDuration({ from: 0, to: 100 }) // natural settle time in ms
|
|
1796
|
+
springValueAt({ from: 0, to: 100 }, 120) // value at 120ms
|
|
1797
|
+
isUnderdamped({ from: 0, to: 100, damping: 4 }) // true — it overshoots
|
|
1798
|
+
criticalDamping({ from: 0, to: 100, stiffness: 100, mass: 1 }) // 20
|
|
1799
|
+
```
|
|
1800
|
+
|
|
1801
|
+
`isUnderdamped` is the closed-form test for whether a spring passes its target
|
|
1802
|
+
before settling (`damping < 2 * sqrt(stiffness * mass)`), so it costs nothing —
|
|
1803
|
+
no simulation needed. Overshoot is usually the point of reaching for a spring,
|
|
1804
|
+
and its absence is the most common reason a "bouncy" one looks flat.
|
|
1805
|
+
|
|
1806
|
+
### Authoring in the editor
|
|
1807
|
+
|
|
1808
|
+
Add a spring from the **Tracks** panel (**+** → **Add Spring**), then tune it in
|
|
1809
|
+
**Properties**: named feel presets (Gentle, Snappy, Bouncy, Wobbly…), from/to,
|
|
1810
|
+
delay, and sliders for stiffness, damping and mass. The panel shows the settle
|
|
1811
|
+
time and flags whether the spring overshoots.
|
|
1812
|
+
|
|
1813
|
+
The scene extends automatically to fit the settle time — a spring decides its
|
|
1814
|
+
own duration, so a looser one simply takes longer, and without that the tail
|
|
1815
|
+
would be silently cut off.
|
|
1816
|
+
|
|
1817
|
+
---
|
|
1818
|
+
|
|
1819
|
+
## Stagger
|
|
1820
|
+
|
|
1821
|
+
One track can drive many targets, each offset in time.
|
|
1822
|
+
|
|
1823
|
+
```typescript
|
|
1824
|
+
timeline.addTrack(createTrack({
|
|
1825
|
+
id: 'letters',
|
|
1826
|
+
target: 'unused', // ignored when `targets` is present
|
|
1827
|
+
targets: ['l1', 'l2', 'l3'],
|
|
1828
|
+
stagger: { each: 100, from: 'center' },
|
|
1829
|
+
property: 'opacity',
|
|
1830
|
+
keyframes: [{ time: 0, value: 0 }, { time: 500, value: 1 }],
|
|
1831
|
+
}))
|
|
1832
|
+
```
|
|
1833
|
+
|
|
1834
|
+
| Field | Meaning |
|
|
1835
|
+
|---|---|
|
|
1836
|
+
| `each` | Milliseconds between consecutive targets |
|
|
1837
|
+
| `amount` | Total spread, divided across the targets (wins over `each`) |
|
|
1838
|
+
| `from` | `'start'` (default), `'end'`, `'center'`, `'edges'`, or an index |
|
|
1839
|
+
|
|
1840
|
+
This produces exactly what baking the stagger into N separate tracks would, so
|
|
1841
|
+
either form is valid. **Which to use is a file-size and editability trade-off,
|
|
1842
|
+
not a speed one** — the two evaluate at the same rate (measured; see
|
|
1843
|
+
`stagger-forms.test.ts`), but serialize very differently:
|
|
1844
|
+
|
|
1845
|
+
| Targets | Baked JSON | Runtime JSON |
|
|
1846
|
+
|---|---|---|
|
|
1847
|
+
| 100 | 11,676 bytes | 792 bytes |
|
|
1848
|
+
| 500 | 59,626 bytes | 3,593 bytes |
|
|
1849
|
+
|
|
1850
|
+
Use the **runtime** form when the stagger is uniform and you ship the JSON — a
|
|
1851
|
+
500-letter split is 59 KB baked and 3.5 KB as one track. Use the **baked** form
|
|
1852
|
+
when each target needs to be tuned individually, which is why the editor's
|
|
1853
|
+
per-letter stagger bakes: it keeps every letter's keyframes draggable.
|
|
1854
|
+
|
|
1855
|
+
Pure helpers, shared by the editor, the engine and the compat facade:
|
|
1856
|
+
|
|
1857
|
+
```typescript
|
|
1858
|
+
import { staggerOffset, staggerOffsets, staggerSpan, staggerDistance } from '@algorisys/tinyfly'
|
|
1859
|
+
|
|
1860
|
+
staggerOffsets(3, { each: 100 }) // [0, 100, 200]
|
|
1861
|
+
staggerSpan(4, { each: 100 }) // 300 — how far it extends a timeline
|
|
1862
|
+
```
|
|
1863
|
+
|
|
1864
|
+
### Track scheduling
|
|
1865
|
+
|
|
1866
|
+
Every track kind also accepts:
|
|
1867
|
+
|
|
1868
|
+
| Field | Meaning |
|
|
1869
|
+
|---|---|
|
|
1870
|
+
| `delay` | Shift every keyframe by this many ms at evaluation time |
|
|
1871
|
+
| `endDelay` | Extra ms held after the last keyframe (extends duration). Keyframe and text tracks |
|
|
1872
|
+
|
|
1873
|
+
---
|
|
1874
|
+
|
|
1875
|
+
## Baking
|
|
1876
|
+
|
|
1877
|
+
Turning a computed animation into plain keyframes, for export formats that only
|
|
1878
|
+
understand keyframes (CSS, Lottie) and for eases with no closed form.
|
|
1879
|
+
|
|
1880
|
+
```typescript
|
|
1881
|
+
import { bakeSpringTrack, bakeEasing, toKeyframedTracks, simplifyKeyframes } from '@algorisys/tinyfly'
|
|
1882
|
+
|
|
1883
|
+
bakeSpringTrack(springTrack, { intervalMs: 1000 / 60, tolerance: 0.01 })
|
|
1884
|
+
bakeEasing(fromKeyframe, toKeyframe, elasticFn, { intervalMs: 16 })
|
|
1885
|
+
toKeyframedTracks(timeline.tracks) // springs baked, everything else untouched
|
|
1886
|
+
```
|
|
1887
|
+
|
|
1888
|
+
Baking is lossy in file size, not fidelity: sampling a deterministic simulation
|
|
1889
|
+
always produces the same keyframes. `simplifyKeyframes` drops points that lie on
|
|
1890
|
+
a straight line between their neighbours.
|
|
1891
|
+
|
|
1892
|
+
---
|
|
1893
|
+
|
|
1894
|
+
## Authoring Values
|
|
1895
|
+
|
|
1896
|
+
Relative and random values are resolved when the timeline is **built**, not when
|
|
1897
|
+
it runs, so what lands in the JSON is a plain number.
|
|
1898
|
+
|
|
1899
|
+
```typescript
|
|
1900
|
+
import { ValueResolver, resolveValue, resolveSequence, createRandom } from '@algorisys/tinyfly'
|
|
1901
|
+
|
|
1902
|
+
resolveValue('+=100', { base: 50 }) // 150
|
|
1903
|
+
resolveSequence(['+=100', '+=100'], 0) // [100, 200]
|
|
1904
|
+
|
|
1905
|
+
const resolver = new ValueResolver(2024) // the seed
|
|
1906
|
+
resolver.resolve('random(-50, 50)') // same seed → same number, always
|
|
1907
|
+
resolver.seed // store alongside the timeline
|
|
1908
|
+
```
|
|
1909
|
+
|
|
1910
|
+
Operators: `+=`, `-=`, `*=`, `/=`. Random: `random(min, max)` and
|
|
1911
|
+
`random(min, max, step)`. Non-expression values (numbers, colours, path data)
|
|
1912
|
+
pass through untouched.
|
|
1913
|
+
|
|
1914
|
+
---
|
|
1915
|
+
|
|
1916
|
+
## Drivers
|
|
1917
|
+
|
|
1918
|
+
Modules that decide *when* a timeline advances and *to what time*. They may
|
|
1919
|
+
touch the DOM; the engine never imports them. See
|
|
1920
|
+
[scroll-animation.md](scroll-animation.md).
|
|
1921
|
+
|
|
1922
|
+
```typescript
|
|
1923
|
+
import { VisibilityDriver, ScrollDriver, scrollProgress } from '@algorisys/tinyfly/drivers'
|
|
1924
|
+
|
|
1925
|
+
new VisibilityDriver({ timeline, trigger, behaviour: 'once' }).start()
|
|
1926
|
+
new ScrollDriver({ timeline, trigger, start: 'top bottom', end: 'bottom top', scrub: true }).start()
|
|
1927
|
+
```
|
|
1928
|
+
|
|
1929
|
+
Both implement `Driver` (`start()`, `stop()`, `destroy()`, each safe to call
|
|
1930
|
+
twice). Drivers only move the playhead: `VisibilityDriver` calls `play()`, so
|
|
1931
|
+
something must still tick the timeline; `ScrollDriver` calls `seek()`, so render
|
|
1932
|
+
in its `onUpdate`.
|
|
1933
|
+
|
|
1934
|
+
```typescript
|
|
1935
|
+
interface ScrollDriverOptions {
|
|
1936
|
+
timeline?: Timeline // optional: without it, only progress and callbacks
|
|
1937
|
+
trigger: Element
|
|
1938
|
+
start?: TriggerPosition // 'top bottom'
|
|
1939
|
+
end?: TriggerPosition // 'bottom top'; '+=600' / '+=150%' from the start
|
|
1940
|
+
scrub?: boolean | number // true exact; seconds of smoothing
|
|
1941
|
+
pin?: boolean | Element // hold the trigger (or an element) through the range
|
|
1942
|
+
snap?: SnapOption // number | number[] | (p) => number | { snapTo, duration, delay, ease }
|
|
1943
|
+
markers?: boolean | MarkerOptions
|
|
1944
|
+
container?: ContainerAxis // { range(), progress(), shiftAt(progress) } for horizontal triggers
|
|
1945
|
+
scroller?: HTMLElement | null // default: the window
|
|
1946
|
+
onUpdate?: (progress: number, velocity: number) => void // velocity px/s, 0 after scrolling stops
|
|
1947
|
+
onEnter?, onLeave?, onEnterBack?, onLeaveBack?: () => void
|
|
1948
|
+
}
|
|
1949
|
+
```
|
|
1950
|
+
|
|
1951
|
+
| `ScrollDriver` member | |
|
|
1952
|
+
|---|---|
|
|
1953
|
+
| `progress` / `velocity` | 0..1 through the range / scroll speed in px/s |
|
|
1954
|
+
| `refresh()` | Re-measure (automatic on resize); `sample()` is the same |
|
|
1955
|
+
| `update(scrollPosition?)` | Update from the scroll offset — no layout reads; pass a value to drive it from a virtual scroller |
|
|
1956
|
+
| `ScrollDriver.refreshAll()` | Re-measure every started driver, in start order |
|
|
1957
|
+
| `startOffset` / `endOffset` | The range as scroll offsets |
|
|
1958
|
+
| `destroy()` | Stop and remove any pin spacer |
|
|
1959
|
+
|
|
1960
|
+
`ScrollPin` (also exported) is the sticky-spacer pin the driver uses.
|
|
1961
|
+
|
|
1962
|
+
```typescript
|
|
1963
|
+
playWhenVisible(options: VisibilityDriverOptions): VisibilityDriver // new VisibilityDriver(options), started
|
|
1964
|
+
scrubOnScroll(options: ScrollDriverOptions): ScrollDriver // new ScrollDriver(options), started
|
|
1965
|
+
```
|
|
1966
|
+
|
|
1967
|
+
Pure helpers, so trigger geometry can be tested without a browser (`rect` is
|
|
1968
|
+
`{ top, bottom, height }` in viewport coordinates):
|
|
1969
|
+
|
|
1970
|
+
| Function | Returns |
|
|
1971
|
+
|----------|---------|
|
|
1972
|
+
| `parseTrigger(position)` | `{ elementFraction, viewportFraction, offsetPx, absolutePx? }` for a `"<element edge> <viewport edge>"` string or a pixel number |
|
|
1973
|
+
| `triggerDistance(rect, viewportHeight, position)` | Scroll distance in px until the trigger fires; positive means it is still ahead |
|
|
1974
|
+
| `scrollProgress(rect, viewportHeight, start, end)` | Progress between the two triggers, clamped to 0..1 |
|
|
1975
|
+
| `smoothToward(current, target, smoothingSeconds, deltaMs)` | `current` moved toward `target` by exponential smoothing (what `scrub: <seconds>` uses); returns `target` when `smoothingSeconds <= 0` |
|
|
1976
|
+
| `clamp01(value)` | `value` clamped to 0..1 |
|
|
1977
|
+
|
|
1978
|
+
The editor's **⇅ Scroll** preview attaches the same `ScrollDriver` to a real
|
|
1979
|
+
scroll strip, so triggers tuned there behave identically on a page.
|
|
1980
|
+
|
|
1981
|
+
---
|
|
1982
|
+
|
|
1983
|
+
## Interaction
|
|
1984
|
+
|
|
1985
|
+
Live input. **Has no serializable representation** — a dragged position is not
|
|
1986
|
+
part of an animation document.
|
|
1987
|
+
|
|
1988
|
+
```typescript
|
|
1989
|
+
import { Observer, Draggable } from '@algorisys/tinyfly/interaction'
|
|
1990
|
+
|
|
1991
|
+
// Drag to scrub a timeline
|
|
1992
|
+
new Draggable({ target: el, mode: 'scrub', timeline, scrubDistance: 500 }).start()
|
|
1993
|
+
|
|
1994
|
+
// Drag to move, with bounds and snapping
|
|
1995
|
+
new Draggable({ target: el, axis: 'x', bounds: { minX: 0, maxX: 300 }, snap: 25 }).start()
|
|
1996
|
+
```
|
|
1997
|
+
|
|
1998
|
+
`Observer` normalises pointer, touch and wheel into one `{ deltaX, deltaY,
|
|
1999
|
+
velocityX, velocityY, totalX, totalY, isDragging }` shape.
|
|
2000
|
+
|
|
2001
|
+
Snapping shares the editor stage's math (`snapAxis` / `gridLinesFor`, also
|
|
2002
|
+
exported from this entry point). Pass `snapLinesX` / `snapLinesY` to snap to
|
|
2003
|
+
other elements' edges or guides, and read `draggable.snapLines` — or the
|
|
2004
|
+
`onSnap` callback — to draw a guide for whichever line caught. `snapThreshold`
|
|
2005
|
+
defaults to half the grid size, so a plain `snap: n` behaves like rounding.
|
|
2006
|
+
|
|
2007
|
+
---
|
|
2008
|
+
|
|
2009
|
+
## Flip
|
|
2010
|
+
|
|
2011
|
+
FLIP layout transitions, compiled to ordinary keyframes at authoring time.
|
|
2012
|
+
|
|
2013
|
+
```typescript
|
|
2014
|
+
import { flip, recordFlipState, buildFlipTracks } from '@algorisys/tinyfly/adapters'
|
|
2015
|
+
|
|
2016
|
+
const tracks = flip(
|
|
2017
|
+
[{ name: 'card', element: cardEl }],
|
|
2018
|
+
() => container.classList.add('grid-layout'), // your layout change
|
|
2019
|
+
{ duration: 600, easing: 'ease-out' }
|
|
2020
|
+
)
|
|
2021
|
+
tracks.forEach((t) => timeline.addTrack(t))
|
|
2022
|
+
```
|
|
2023
|
+
|
|
2024
|
+
Measurement happens in the DOM layer, so the engine stays free of live layout
|
|
2025
|
+
reads. The trade-off: the resulting JSON is a snapshot of one specific layout
|
|
2026
|
+
change — recompute it when the layout it was measured against changes.
|
|
2027
|
+
|
|
2028
|
+
---
|
|
2029
|
+
|
|
2030
|
+
## GSAP Compat
|
|
2031
|
+
|
|
2032
|
+
A GSAP-flavoured authoring surface that desugars to ordinary tracks. See
|
|
2033
|
+
[gsap-compat.md](gsap-compat.md) for the full mapping table.
|
|
2034
|
+
|
|
2035
|
+
```typescript
|
|
2036
|
+
import { timeline, quickPlay } from '@algorisys/tinyfly/gsap-compat'
|
|
2037
|
+
|
|
2038
|
+
const tl = timeline()
|
|
2039
|
+
tl.fromTo('box', { x: 0 }, { x: 200, duration: 1, ease: 'power2.out' })
|
|
2040
|
+
tl.to('box', { rotate: 180, duration: 0.5 }, '-=0.25')
|
|
2041
|
+
|
|
2042
|
+
quickPlay({ timeline: tl.timeline, targets: { box: '#box' } })
|
|
2043
|
+
```
|
|
2044
|
+
|
|
2045
|
+
`quickPlay` also stands alone: it wires a timeline to the DOM and runs the rAF
|
|
2046
|
+
loop, replacing the usual boilerplate.
|
|
2047
|
+
|
|
2048
|
+
### `live` — play on real elements
|
|
2049
|
+
|
|
2050
|
+
```typescript
|
|
2051
|
+
import { live, createLive, Stage } from '@algorisys/tinyfly/gsap-compat'
|
|
2052
|
+
|
|
2053
|
+
live.to('.box', { x: 200, duration: 1 }) // → LiveTimeline, already playing
|
|
2054
|
+
live.from(target, vars)
|
|
2055
|
+
live.fromTo(target, fromVars, toVars)
|
|
2056
|
+
live.set(target, vars) // applied on the next microtask
|
|
2057
|
+
live.timeline(options?: LiveTimelineOptions) // chainable .to/.from/.fromTo/.set/.addLabel/.add
|
|
2058
|
+
```
|
|
2059
|
+
|
|
2060
|
+
`target` is a CSS selector, an `Element`, a plain object, a `NodeList`, or an
|
|
2061
|
+
array of those. A plain object's properties are tweened from its current values
|
|
2062
|
+
and assigned back onto it each frame (for canvas, WebGL or any custom renderer).
|
|
2063
|
+
|
|
2064
|
+
```typescript
|
|
2065
|
+
live.ticker.add(callback: TickerCallback): void
|
|
2066
|
+
live.ticker.remove(callback: TickerCallback): void
|
|
2067
|
+
|
|
2068
|
+
type TickerCallback = (time: number, deltaTime: number, frame: number) => void
|
|
2069
|
+
```
|
|
2070
|
+
|
|
2071
|
+
Ticker callbacks run every frame after animations are applied: `time` is seconds
|
|
2072
|
+
since the ticker started, `deltaTime` milliseconds since the last frame. The loop
|
|
2073
|
+
runs while any callback is registered.
|
|
2074
|
+
|
|
2075
|
+
| `LiveTimelineOptions` | |
|
|
2076
|
+
|---|---|
|
|
2077
|
+
| `repeat`, `yoyo`, `repeatDelay`, `timeScale`, `defaults`, `bakeEases`, `onWarning` | As on `timeline()` |
|
|
2078
|
+
| `paused` | Do not autoplay |
|
|
2079
|
+
| `onStart`, `onUpdate`, `onComplete` | Lifecycle callbacks |
|
|
2080
|
+
|
|
2081
|
+
`LiveTimeline` methods: `play()`, `pause()`, `resume()`, `restart()`,
|
|
2082
|
+
`reverse()`, `seek(secondsOrLabel)`, `progress(value?)`, `timeScale(value?)`,
|
|
2083
|
+
`duration()`, `isActive()`, `kill()`, `toDefinition()`. The engine timeline is
|
|
2084
|
+
`.timeline`, the compiled compat timeline `.compat`.
|
|
2085
|
+
|
|
2086
|
+
`createLive(stage?)` binds the same API to a separate `Stage`; `live.stage` is
|
|
2087
|
+
the one the default `live` uses.
|
|
2088
|
+
|
|
2089
|
+
```typescript
|
|
2090
|
+
live.convertToPath(targets: string | Element | ArrayLike<Element>): Element[]
|
|
2091
|
+
live.draggable(target: TargetInput, options?: LiveDraggableOptions): LiveDraggable
|
|
2092
|
+
|
|
2093
|
+
interface LiveDraggable {
|
|
2094
|
+
readonly draggable: Draggable // the underlying tinyfly/interaction Draggable
|
|
2095
|
+
readonly position: { x: number; y: number } // where the element is now
|
|
2096
|
+
destroy(): void // stop listening and stop any throw in progress
|
|
2097
|
+
}
|
|
2098
|
+
```
|
|
2099
|
+
|
|
2100
|
+
`convertToPath` replaces basic SVG shapes with equivalent `<path>` elements
|
|
2101
|
+
(selectors resolve within the stage's root) and returns the resulting elements
|
|
2102
|
+
in order. It changes the document. `draggable` options are listed in
|
|
2103
|
+
[gsap-compat.md](gsap-compat.md#inertia-and-dragging); it throws if the target
|
|
2104
|
+
matches nothing.
|
|
2105
|
+
|
|
2106
|
+
### Springs on `live`
|
|
2107
|
+
|
|
2108
|
+
```typescript
|
|
2109
|
+
live.to(target, { x: 0, spring: true | SpringPresetName | SpringOptions })
|
|
2110
|
+
|
|
2111
|
+
type SpringPresetName = 'gentle' | 'default' | 'snappy' | 'bouncy' | 'wobbly' | 'stiff'
|
|
2112
|
+
interface SpringOptions {
|
|
2113
|
+
preset?: SpringPresetName
|
|
2114
|
+
stiffness?: number
|
|
2115
|
+
damping?: number
|
|
2116
|
+
mass?: number
|
|
2117
|
+
velocity?: number | Record<string, number> // units/s; unset → the property's current velocity
|
|
2118
|
+
restDelta?: number
|
|
2119
|
+
}
|
|
2120
|
+
|
|
2121
|
+
SPRING_PRESETS: Record<SpringPresetName, { stiffness: number; damping: number; mass: number }> // from tinyfly
|
|
2122
|
+
stage.velocityOf(name, property): number | undefined // units/s from the playing timeline that animates it
|
|
2123
|
+
```
|
|
2124
|
+
|
|
2125
|
+
Numeric properties compile to spring tracks; the tween lasts until the slowest
|
|
2126
|
+
settles. `CompatTimelineOptions.startVelocity(target, property)` is the hook `live`
|
|
2127
|
+
uses to carry momentum. See [gsap-compat.md](gsap-compat.md#springs).
|
|
2128
|
+
|
|
2129
|
+
### Line drawing
|
|
2130
|
+
|
|
2131
|
+
```typescript
|
|
2132
|
+
live.to(shape, { drawSVG: true | false | number | string }) // '60%', '20% 80%', '10 50%'
|
|
2133
|
+
|
|
2134
|
+
drawSegment(value: DrawSvgValue, length: number): [start: number, end: number]
|
|
2135
|
+
drawSvgProperties(value: DrawSvgValue, length: number): { strokeDasharray: [number, number]; strokeDashoffset: number }
|
|
2136
|
+
```
|
|
2137
|
+
|
|
2138
|
+
`live` measures `getTotalLength()` once per element and compiles to
|
|
2139
|
+
`strokeDasharray` / `strokeDashoffset` tracks. See [gsap-compat.md](gsap-compat.md#line-drawing).
|
|
2140
|
+
|
|
2141
|
+
### Scroll triggers
|
|
2142
|
+
|
|
2143
|
+
```typescript
|
|
2144
|
+
live.timeline({ scrollTrigger: ScrollTriggerVars, ...options })
|
|
2145
|
+
live.to(target, { ...vars, scrollTrigger: ScrollTriggerVars })
|
|
2146
|
+
live.scrollTrigger(vars: ScrollTriggerVars & { trigger }): ScrollDriver | undefined
|
|
2147
|
+
live.refreshScroll(): void
|
|
2148
|
+
tl.scrollTrigger: ScrollDriver | undefined // after the next microtask
|
|
2149
|
+
tl.reversed(): boolean
|
|
2150
|
+
tl.invalidate(): LiveTimeline // rebuild from the same calls (function values re-run)
|
|
2151
|
+
|
|
2152
|
+
interface ScrollTriggerVars {
|
|
2153
|
+
trigger?: string | Element
|
|
2154
|
+
start?: TriggerPosition | (() => TriggerPosition) // functions re-run on refresh
|
|
2155
|
+
end?: TriggerPosition | (() => TriggerPosition)
|
|
2156
|
+
invalidateOnRefresh?: boolean // rebuild the animation on every refresh
|
|
2157
|
+
scrub?: boolean | number
|
|
2158
|
+
pin?: boolean | string | Element
|
|
2159
|
+
scroller?: string | HTMLElement
|
|
2160
|
+
toggleActions?: string // 'play none none none'
|
|
2161
|
+
once?: boolean
|
|
2162
|
+
snap?: number | number[] | 'labels' | ((progress: number) => number)
|
|
2163
|
+
| { snapTo, duration?: number | { min, max }, delay?: number, ease?: string }
|
|
2164
|
+
markers?: boolean | { startColor?, endColor?, fontSize?, indent?, id? }
|
|
2165
|
+
containerAnimation?: LiveTimeline // triggers inside a horizontally sliding row
|
|
2166
|
+
onUpdate?: (self: { progress: number; velocity: number; direction: 1 | -1 }) => void
|
|
2167
|
+
onEnter?, onLeave?, onEnterBack?, onLeaveBack?: () => void
|
|
2168
|
+
}
|
|
2169
|
+
```
|
|
2170
|
+
|
|
2171
|
+
See [gsap-compat.md](gsap-compat.md#scroll-triggers).
|
|
2172
|
+
|
|
2173
|
+
### Split text
|
|
2174
|
+
|
|
2175
|
+
```typescript
|
|
2176
|
+
live.splitText(targets: string | Element | ArrayLike<Element>, options?: SplitTextOptions): SplitTextResult
|
|
2177
|
+
splitText(elements: Element[], options?: SplitTextOptions): SplitTextResult // from tinyfly/gsap-compat
|
|
2178
|
+
|
|
2179
|
+
interface SplitTextOptions {
|
|
2180
|
+
type?: string // 'chars,words,lines' (default), any subset
|
|
2181
|
+
mask?: 'chars' | 'words' | 'lines'
|
|
2182
|
+
charsClass?: string // 'char'
|
|
2183
|
+
wordsClass?: string // 'word'
|
|
2184
|
+
linesClass?: string // 'line'
|
|
2185
|
+
aria?: boolean // true: aria-label on the element, aria-hidden on the pieces
|
|
2186
|
+
autoSplit?: boolean // re-split when width changes or fonts load
|
|
2187
|
+
onSplit?: (self: SplitTextResult) => { kill?(): unknown; revert?(): unknown } | void
|
|
2188
|
+
}
|
|
2189
|
+
|
|
2190
|
+
interface SplitTextResult {
|
|
2191
|
+
elements: Element[]
|
|
2192
|
+
chars: HTMLElement[]
|
|
2193
|
+
words: HTMLElement[]
|
|
2194
|
+
lines: HTMLElement[]
|
|
2195
|
+
masks: HTMLElement[]
|
|
2196
|
+
split(): void // re-split now
|
|
2197
|
+
revert(): void
|
|
2198
|
+
}
|
|
2199
|
+
```
|
|
2200
|
+
|
|
2201
|
+
Lines are measured from layout once, at split time. See
|
|
2202
|
+
[gsap-compat.md](gsap-compat.md#split-text) for what the markup looks like.
|
|
2203
|
+
|
|
2204
|
+
### Custom eases
|
|
2205
|
+
|
|
2206
|
+
```typescript
|
|
2207
|
+
// tinyfly (engine): pure generators
|
|
2208
|
+
customEase(definition: string | CubicBezierPoints): { fn: EasingFunction; bezier?: CubicBezierPoints }
|
|
2209
|
+
customBounce(options?: { strength?: number }): EasingFunction
|
|
2210
|
+
customWiggle(options?: { wiggles?: number; type?: 'easeOut' | 'easeInOut' | 'uniform' }): EasingFunction
|
|
2211
|
+
|
|
2212
|
+
// tinyfly/gsap-compat: register by name
|
|
2213
|
+
CustomEase.create(name, definition): string // also live.customEase(name, definition)
|
|
2214
|
+
CustomBounce.create(name, options?): string // live.customBounce
|
|
2215
|
+
CustomWiggle.create(name, options?): string // live.customWiggle
|
|
2216
|
+
registerEase(name, { fn, bezier? }): string
|
|
2217
|
+
```
|
|
2218
|
+
|
|
2219
|
+
`bakeEasing` ends on the ease's own final value, so an ease that does not end at 1
|
|
2220
|
+
(a wiggle) bakes correctly.
|
|
2221
|
+
|
|
2222
|
+
### Page transitions
|
|
2223
|
+
|
|
2224
|
+
```typescript
|
|
2225
|
+
live.pageTransition(options: PageTransitionOptions): Promise<void>
|
|
2226
|
+
|
|
2227
|
+
interface PageTransitionOptions {
|
|
2228
|
+
update: () => void | Promise<void>
|
|
2229
|
+
from?: TargetInput
|
|
2230
|
+
to?: TargetInput | (() => TargetInput)
|
|
2231
|
+
shared?: string // selector; matched by data-flip-id
|
|
2232
|
+
leave?: TweenVars | false // { opacity: 0, y: -16 }
|
|
2233
|
+
enter?: TweenVars | false // { opacity: 0, y: 16 }
|
|
2234
|
+
duration?: number // 0.35 per phase
|
|
2235
|
+
ease?: string // 'power2.inOut'
|
|
2236
|
+
native?: boolean // View Transitions API when available
|
|
2237
|
+
}
|
|
2238
|
+
```
|
|
2239
|
+
|
|
2240
|
+
### Image sequences
|
|
2241
|
+
|
|
2242
|
+
```typescript
|
|
2243
|
+
live.imageSequence(canvas: string | HTMLCanvasElement, options: ImageSequenceOptions): ImageSequence
|
|
2244
|
+
|
|
2245
|
+
interface ImageSequenceOptions {
|
|
2246
|
+
frames: number
|
|
2247
|
+
url: (index: number) => string
|
|
2248
|
+
fit?: 'cover' | 'contain' // 'cover'
|
|
2249
|
+
concurrency?: number // 6
|
|
2250
|
+
onProgress?: (loaded: number, total: number) => void
|
|
2251
|
+
}
|
|
2252
|
+
|
|
2253
|
+
class ImageSequence {
|
|
2254
|
+
frame: number // set it (or tween it) to draw the nearest frame
|
|
2255
|
+
readonly frames: number
|
|
2256
|
+
readonly loaded: number
|
|
2257
|
+
resize(): void
|
|
2258
|
+
destroy(): void
|
|
2259
|
+
}
|
|
2260
|
+
```
|
|
2261
|
+
|
|
2262
|
+
### quickTo
|
|
2263
|
+
|
|
2264
|
+
```typescript
|
|
2265
|
+
live.quickTo(target: TargetInput, property: string, vars?: { duration?: number; ease?: string; spring?: SpringVars }): QuickTo
|
|
2266
|
+
|
|
2267
|
+
interface QuickTo {
|
|
2268
|
+
(value: number): void // animate toward value from the current one; applied next frame
|
|
2269
|
+
readonly tween: LiveTimeline
|
|
2270
|
+
kill(): void
|
|
2271
|
+
}
|
|
2272
|
+
```
|
|
2273
|
+
|
|
2274
|
+
Defaults: `duration` 0.4, `ease` `'power3.out'`. See [gsap-compat.md](gsap-compat.md#values-that-change-every-event-quickto).
|
|
2275
|
+
|
|
2276
|
+
### Contexts and media queries
|
|
2277
|
+
|
|
2278
|
+
```typescript
|
|
2279
|
+
live.context(fn?: (ctx: LiveContext) => unknown, scope?: ParentNode): LiveContext
|
|
2280
|
+
live.matchMedia(scope?: ParentNode): LiveMatchMedia
|
|
2281
|
+
|
|
2282
|
+
class LiveContext {
|
|
2283
|
+
conditions: Record<string, boolean> // set by matchMedia
|
|
2284
|
+
add<T>(fn: () => T): T // run fn collecting; a returned function is cleanup
|
|
2285
|
+
revert(): void // undo everything, restore elements' inline style and SVG d
|
|
2286
|
+
}
|
|
2287
|
+
|
|
2288
|
+
class LiveMatchMedia {
|
|
2289
|
+
add(conditions: string | Record<string, string>, setup: (ctx: LiveContext) => unknown): this
|
|
2290
|
+
revert(): void
|
|
2291
|
+
}
|
|
2292
|
+
```
|
|
2293
|
+
|
|
2294
|
+
Function values: any non-configuration tween var may be `(index, target) => value`.
|
|
2295
|
+
See [gsap-compat.md](gsap-compat.md#surviving-resizes) and
|
|
2296
|
+
[responsive setups](gsap-compat.md#responsive-setups-reduced-motion-and-cleanup).
|
|
2297
|
+
|
|
2298
|
+
### Stage
|
|
2299
|
+
|
|
2300
|
+
The shared runtime behind `live`: one frame loop, one DOM adapter, and the
|
|
2301
|
+
values last applied to each element, merged per element so concurrent
|
|
2302
|
+
animations compose.
|
|
2303
|
+
|
|
2304
|
+
```typescript
|
|
2305
|
+
new Stage(options?: StageOptions)
|
|
2306
|
+
|
|
2307
|
+
interface StageOptions {
|
|
2308
|
+
scheduler?: FrameScheduler // { request(cb): number; cancel(id): void } — default requestAnimationFrame
|
|
2309
|
+
root?: ParentNode // where selectors resolve (default: document)
|
|
2310
|
+
onWarning?: (message: string) => void // warnings from every live timeline on this stage
|
|
2311
|
+
}
|
|
2312
|
+
|
|
2313
|
+
type ObjectTarget = Record<string, unknown>
|
|
2314
|
+
type TargetInput = string | Element | ObjectTarget | ArrayLike<Element> | ReadonlyArray<string | Element | ObjectTarget>
|
|
2315
|
+
```
|
|
2316
|
+
|
|
2317
|
+
| Member | Description |
|
|
2318
|
+
|--------|-------------|
|
|
2319
|
+
| `root` | The `ParentNode` selectors resolve in (read lazily, so a stage can exist without a document) |
|
|
2320
|
+
| `resolveTargets(input)` | Engine target names for a selector, element, object or list, registering new ones (an element with an `id` is named `#id`, objects `obj-N`) |
|
|
2321
|
+
| `query(selector)` | First matching element within `root` |
|
|
2322
|
+
| `elementFor(name)` | The element registered under a target name |
|
|
2323
|
+
| `objectFor(name)` | The plain object registered under a target name |
|
|
2324
|
+
| `ticker` | `add(callback)` / `remove(callback)`: run after each frame's values are applied; keeps the loop running |
|
|
2325
|
+
| `appliedValue(name, property)` | The last value applied to that property |
|
|
2326
|
+
| `apply(name, values)` | Write values for one target immediately, without a timeline (e.g. while dragging); later tweens start from them |
|
|
2327
|
+
| `render(timeline)` | Apply a timeline's state at its current time, immediately |
|
|
2328
|
+
| `activate(timeline)` / `deactivate(timeline)` | Add a playing timeline to the loop (moving it last, so it wins merges) / remove it, keeping its applied values |
|
|
2329
|
+
| `tick(deltaMs)` | Advance every active timeline and apply the merged result. The loop calls it; call it yourself when you own the loop |
|
|
2330
|
+
| `destroy()` | Stop everything, release elements, and ignore later playback |
|
|
2331
|
+
|
|
2332
|
+
### Flip
|
|
2333
|
+
|
|
2334
|
+
```typescript
|
|
2335
|
+
live.getFlipState(targets): LiveFlipState
|
|
2336
|
+
live.flipFrom(state, { duration?, ease?, stagger?, scale?, targets?, enter?, fade?, onComplete? }): LiveTimeline
|
|
2337
|
+
live.flip(targets, change: () => void, vars?): LiveTimeline
|
|
2338
|
+
```
|
|
2339
|
+
|
|
2340
|
+
Measures where elements appear before a layout change (transforms included) and
|
|
2341
|
+
where they are laid out after (transforms ignored), then animates each from the
|
|
2342
|
+
difference back to rest using centre offsets, plus scale for size changes.
|
|
2343
|
+
Newly visible elements get the `enter` animation — unless they share a
|
|
2344
|
+
`data-flip-id` with a recorded element, in which case they flip from that
|
|
2345
|
+
element's box (`fade: true` cross-fades the two). A flip that starts while
|
|
2346
|
+
another is running takes over each element from where it appears.
|
|
2347
|
+
|
|
2348
|
+
### Browser bundle
|
|
2349
|
+
|
|
2350
|
+
`@algorisys/tinyfly/browser` (and `lib/browser/tinyfly.iife.js` for `<script>` tags, global
|
|
2351
|
+
`tinyfly`) re-exports the engine, player, drivers, interaction, `tf`, `live`,
|
|
2352
|
+
`Stage` and `quickPlay`, with `to`, `from`, `fromTo`, `set`, `timeline`,
|
|
2353
|
+
`ticker` and `splitText` at the top level bound to `live`.
|