@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,690 @@
|
|
|
1
|
+
# tinyfly File Format
|
|
2
|
+
|
|
3
|
+
tinyfly animations are **plain JSON** — no binary blobs, no framework-specific
|
|
4
|
+
wrappers. This document is the reference for anyone generating, consuming, or
|
|
5
|
+
integrating tinyfly animations (tooling, AI generation, importers/exporters,
|
|
6
|
+
custom players).
|
|
7
|
+
|
|
8
|
+
Everything here is stable, serializable data. The same JSON plays in the
|
|
9
|
+
browser, a Web Worker, or any headless JS runtime, and always produces the same
|
|
10
|
+
output for the same input (see [Determinism](#determinism)).
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## The formats at a glance
|
|
15
|
+
|
|
16
|
+
tinyfly has a few related JSON shapes. Pick the one that matches your task:
|
|
17
|
+
|
|
18
|
+
| Format | Shape | Use it for |
|
|
19
|
+
|--------|-------|------------|
|
|
20
|
+
| **Animation Document** | `{ duration, canvas?, elements[], tracks[] }` | **The integration format.** Author or generate animations by hand/AI. Loaded the same way samples are. |
|
|
21
|
+
| **Timeline Definition** | `{ id, name?, config, tracks[] }` | The engine's serialized timeline (`serializeTimeline()` / `toJSON()`, and the `.json` files the editor exports & imports). What a custom player consumes. |
|
|
22
|
+
| **Project** | `{ id, name, canvas, scenes[], symbols[], ... }` | The editor's saved document — one or more scenes, each with its own elements + timeline, plus a symbol library. |
|
|
23
|
+
| **Sequence** | `{ id, name, canvas, scenes[], symbols? }` | A multi-scene bundle for the embeddable player/sequencer. |
|
|
24
|
+
|
|
25
|
+
If you're integrating with tinyfly, start with the **Animation Document** — it's
|
|
26
|
+
the highest-level, most stable shape and describes *what to draw* as well as
|
|
27
|
+
*how to animate it*.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## 1. Animation Document
|
|
32
|
+
|
|
33
|
+
The document a sample, an AI generation, or a hand-authored animation uses. It
|
|
34
|
+
describes a set of **elements** (the things on the artboard) and **tracks** (how
|
|
35
|
+
their properties change over time).
|
|
36
|
+
|
|
37
|
+
```jsonc
|
|
38
|
+
{
|
|
39
|
+
"duration": 2000, // total length in ms (required, > 0)
|
|
40
|
+
"canvas": { "width": 300, "height": 200 }, // optional artboard size
|
|
41
|
+
"elements": [ /* Element[] */ ], // what to draw
|
|
42
|
+
"tracks": [ /* Track[] */ ] // how to animate it
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
- `duration` — **required**, milliseconds, must be `> 0`. The timeline can
|
|
47
|
+
auto-extend to fit tracks, but always declare the intended length.
|
|
48
|
+
- `canvas` — optional `{ width, height }` in px. When present, loading the
|
|
49
|
+
document resizes the artboard (e.g. a vertical `360×640` promo). Defaults to
|
|
50
|
+
the current/host canvas.
|
|
51
|
+
- `elements` — array of [Elements](#elements).
|
|
52
|
+
- `tracks` — array of [Tracks](#tracks-and-keyframes). A track's `target` matches
|
|
53
|
+
an **element `name`** (see below).
|
|
54
|
+
|
|
55
|
+
The editor writes one with **More → Export Animation Document** (`*.animation.json`).
|
|
56
|
+
Besides the fields above it adds `name`, playback options other than duration
|
|
57
|
+
under `config` (`loop`, `speed`, `markers`…), `captions` when present, and keeps
|
|
58
|
+
each element's `id` (groups refer to their children by id). Its tracks are the
|
|
59
|
+
editor's tracks unchanged, so springs, staggers and scheduling fields survive for
|
|
60
|
+
a reader that runs the engine; the editor's own loader reads the subset in
|
|
61
|
+
[Track kinds](#track-kinds-in-an-animation-document).
|
|
62
|
+
|
|
63
|
+
> **Key rule:** in the Animation Document, tracks bind to elements by **`name`**,
|
|
64
|
+
> not `id`. Element `id`s are assigned by the editor on load; names are what you
|
|
65
|
+
> author against. Every `track.target` must equal some `element.name`.
|
|
66
|
+
|
|
67
|
+
### Minimal example
|
|
68
|
+
|
|
69
|
+
```json
|
|
70
|
+
{
|
|
71
|
+
"duration": 2000,
|
|
72
|
+
"canvas": { "width": 300, "height": 200 },
|
|
73
|
+
"elements": [
|
|
74
|
+
{ "type": "rect", "name": "Box", "x": 120, "y": 70, "width": 60, "height": 60, "fill": "#4a9eff", "borderRadius": 8 }
|
|
75
|
+
],
|
|
76
|
+
"tracks": [
|
|
77
|
+
{
|
|
78
|
+
"target": "Box",
|
|
79
|
+
"property": "opacity",
|
|
80
|
+
"keyframes": [
|
|
81
|
+
{ "time": 0, "value": 0 },
|
|
82
|
+
{ "time": 500, "value": 1, "easing": "ease-out" },
|
|
83
|
+
{ "time": 1500, "value": 1 },
|
|
84
|
+
{ "time": 2000, "value": 0, "easing": "ease-in" }
|
|
85
|
+
]
|
|
86
|
+
}
|
|
87
|
+
]
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Elements
|
|
94
|
+
|
|
95
|
+
Every element shares a **base** shape and adds a few fields per `type`. When
|
|
96
|
+
authoring a document, most base fields are optional and are filled with sensible
|
|
97
|
+
defaults — but `type` and `name` should always be set (`name` is how tracks find
|
|
98
|
+
it). Coordinates are in artboard pixels; the origin is the top-left.
|
|
99
|
+
|
|
100
|
+
### Base fields (all element types)
|
|
101
|
+
|
|
102
|
+
| Field | Type | Notes |
|
|
103
|
+
|-------|------|-------|
|
|
104
|
+
| `type` | string | One of the element types below. **Required.** |
|
|
105
|
+
| `name` | string | Human-readable id used as a track `target`. **Required for animation.** |
|
|
106
|
+
| `x`, `y` | number | Top-left position in px. |
|
|
107
|
+
| `width`, `height` | number | Size in px. |
|
|
108
|
+
| `rotation` | number | Degrees. |
|
|
109
|
+
| `opacity` | number | `0`–`1`. |
|
|
110
|
+
| `visible` | boolean | Hidden elements are skipped in render/export. |
|
|
111
|
+
| `locked` | boolean | Editor-only (not selectable); no runtime effect. |
|
|
112
|
+
| `id` | string | Assigned by the editor. Omit when authoring. |
|
|
113
|
+
|
|
114
|
+
### Element types & their extra fields
|
|
115
|
+
|
|
116
|
+
| `type` | Extra fields |
|
|
117
|
+
|--------|--------------|
|
|
118
|
+
| `rect` | `fill` (color or [gradient](#fills--gradients)), `stroke`, `strokeWidth`, `borderRadius` |
|
|
119
|
+
| `circle` | `fill`, `stroke`, `strokeWidth` |
|
|
120
|
+
| `text` | `text` (string), `fontSize`, `fontFamily`, `fontWeight`, `fill`, `textAlign` (`left`\|`center`\|`right`) |
|
|
121
|
+
| `image` | `src` (URL or data URI), `objectFit` (`contain`\|`cover`\|`fill`) |
|
|
122
|
+
| `video` | `src`, `objectFit`, `borderRadius`, `volume` (0–1), `muted`, `loop`, `startTime` (ms) |
|
|
123
|
+
| `audio` | `src`, `volume` (0–1), `muted`, `loop`, `startTime` (ms) |
|
|
124
|
+
| `line` | `x2`, `y2`, `stroke`, `strokeWidth`, `lineCap` (`butt`\|`round`\|`square`) |
|
|
125
|
+
| `arrow` | `x2`, `y2`, `stroke`, `strokeWidth`, `headSize`, `startHead` (bool), `endHead` (bool) |
|
|
126
|
+
| `path` | `d` (SVG path data), `fill`, `stroke`, `strokeWidth`, `lineCap`, `lineJoin` (`miter`\|`round`\|`bevel`), `closed` (bool), `shape` (optional `{ kind: 'polygon'\|'star', points, innerRatio? }` — a parametric polygon/star whose `d` is regenerated from the spec and the element's size; see [polygon-star.md](polygon-star.md)) |
|
|
127
|
+
| `group` | `childIds` (string[]) — ids of grouped elements |
|
|
128
|
+
| `symbol` | `symbolId` (id of a symbol in the Project's `symbols` library), `swapSet` (optional string[] of symbol ids; a `swapIndex` track picks `swapSet[floor(swapIndex)]`), `overrides` (reserved). Only meaningful inside a [Project](#3-project-format), which carries the library — see [symbols-and-library.md](symbols-and-library.md) |
|
|
129
|
+
|
|
130
|
+
### Fills & gradients
|
|
131
|
+
|
|
132
|
+
`fill` (on `rect`, `circle`, `path`) is either a CSS color string
|
|
133
|
+
(`"#4a9eff"`, `"rgba(...)"`) **or** a gradient object:
|
|
134
|
+
|
|
135
|
+
```jsonc
|
|
136
|
+
// Linear gradient — angle in degrees (0 = left→right, 90 = top→bottom)
|
|
137
|
+
{
|
|
138
|
+
"type": "linear",
|
|
139
|
+
"angle": 90,
|
|
140
|
+
"stops": [ { "offset": 0, "color": "#4a9eff" }, { "offset": 1, "color": "#9b59b6" } ]
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
// Radial gradient — center/radius are 0–1, relative to the element box
|
|
144
|
+
{
|
|
145
|
+
"type": "radial",
|
|
146
|
+
"centerX": 0.5,
|
|
147
|
+
"centerY": 0.5,
|
|
148
|
+
"radius": 0.5,
|
|
149
|
+
"stops": [ { "offset": 0, "color": "#fff" }, { "offset": 1, "color": "#000" } ]
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
`stops[].offset` is `0`–`1`; `angle` is in degrees; `centerX`/`centerY`/`radius`
|
|
154
|
+
are fractions of the element box (`0`–`1`).
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## Tracks and keyframes
|
|
159
|
+
|
|
160
|
+
A **track** animates one property of one target over time.
|
|
161
|
+
|
|
162
|
+
```jsonc
|
|
163
|
+
{
|
|
164
|
+
"id": "opacity-1", // optional in a document; the editor assigns one
|
|
165
|
+
"target": "Box", // MUST match an element `name`
|
|
166
|
+
"property": "opacity", // see the animatable-properties table
|
|
167
|
+
"keyframes": [
|
|
168
|
+
{ "time": 0, "value": 0 },
|
|
169
|
+
{ "time": 500, "value": 1, "easing": "ease-out" }
|
|
170
|
+
]
|
|
171
|
+
}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
- `target` — the element `name` to animate (in the engine Timeline format this
|
|
175
|
+
is the element **id** instead — see [Timeline Definition](#2-timeline-definition)).
|
|
176
|
+
- `property` — the property to animate (below).
|
|
177
|
+
- `keyframes` — **sorted by `time`** (ascending), each:
|
|
178
|
+
- `time` — milliseconds from the timeline start.
|
|
179
|
+
- `value` — a number, a string (colour or path data), or a number array,
|
|
180
|
+
depending on the property (an [AnimatableValue](#value-types)).
|
|
181
|
+
- `easing` — optional; the curve used interpolating **into** this keyframe.
|
|
182
|
+
Defaults to `linear`.
|
|
183
|
+
|
|
184
|
+
### Value types
|
|
185
|
+
|
|
186
|
+
`value` is one of:
|
|
187
|
+
|
|
188
|
+
- **number** — e.g. `x`, `opacity`, `scale`, `rotate`, `width`.
|
|
189
|
+
- **color string** — e.g. `fill`, `stroke` (`"#ff0000"`, `"rgb(...)"`).
|
|
190
|
+
Interpolated channel-by-channel.
|
|
191
|
+
- **path string** — SVG path data starting with a moveto (`"M0 0 L10 10"`),
|
|
192
|
+
e.g. on a `d` track. Morphed point-by-point between keyframes, so any two
|
|
193
|
+
shapes blend — see [shape-morph.md](shape-morph.md).
|
|
194
|
+
- **other strings** — not interpolated: the value jumps to the next keyframe's
|
|
195
|
+
string when that keyframe is reached. To animate text, use a
|
|
196
|
+
[text track](#text-tracks).
|
|
197
|
+
- **number[]** — for array-valued properties.
|
|
198
|
+
|
|
199
|
+
Between two keyframes, the earlier keyframe's value decides the interpolator: a
|
|
200
|
+
number, an array, a string starting with `#` or `rgb` (colour), a path string,
|
|
201
|
+
or any other string (discrete).
|
|
202
|
+
|
|
203
|
+
### Animatable properties
|
|
204
|
+
|
|
205
|
+
| Category | Properties |
|
|
206
|
+
|----------|-----------|
|
|
207
|
+
| Position | `x`, `y`, `z` |
|
|
208
|
+
| Transform | `rotate`, `rotateX`, `rotateY`, `rotateZ`, `scale`, `scaleX`, `scaleY`, `scaleZ`, `skewX`, `skewY` |
|
|
209
|
+
| Appearance | `opacity`, `fill`, `stroke`, `strokeWidth`, `width`, `height`, `borderRadius`, `fontSize` |
|
|
210
|
+
| Shape | `d` (path string — morphs the path's shape) |
|
|
211
|
+
| Text | `text` (via a [text track](#text-tracks)) |
|
|
212
|
+
| Clip / reveal | `clipTop`, `clipRight`, `clipBottom`, `clipLeft` (inset %, `0` = fully shown, `100` = fully clipped from that edge) |
|
|
213
|
+
| Filters | `blur`, `glow`, `dropShadow` |
|
|
214
|
+
| Stroke draw-on | `strokeDasharray`, `strokeDashoffset` |
|
|
215
|
+
| Shine | `shine` (0–1 sweep position) |
|
|
216
|
+
| Motion path | `motionPathX`, `motionPathY`, `motionPathRotate` (usually via a motion-path track — below) |
|
|
217
|
+
|
|
218
|
+
Adapters ignore properties that don't apply to a given render target, so an
|
|
219
|
+
unknown/unsupported property is a no-op, never an error.
|
|
220
|
+
|
|
221
|
+
### Easing values
|
|
222
|
+
|
|
223
|
+
`easing` is either a **built-in name**:
|
|
224
|
+
|
|
225
|
+
```
|
|
226
|
+
linear
|
|
227
|
+
ease-in ease-out ease-in-out
|
|
228
|
+
ease-in-quad ease-out-quad ease-in-out-quad
|
|
229
|
+
ease-in-cubic ease-out-cubic ease-in-out-cubic
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
…or a **custom cubic-bezier**:
|
|
233
|
+
|
|
234
|
+
```json
|
|
235
|
+
{ "type": "cubic-bezier", "points": [0.68, -0.55, 0.27, 1.55] }
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
`points` are `[cp1x, cp1y, cp2x, cp2y]` (CSS `cubic-bezier` order).
|
|
239
|
+
|
|
240
|
+
…or a **parametric ease**, evaluated exactly when played:
|
|
241
|
+
|
|
242
|
+
```jsonc
|
|
243
|
+
{ "type": "elastic", "mode": "out", "amplitude": 1, "period": 0.3 } // overshoots and oscillates
|
|
244
|
+
{ "type": "bounce", "mode": "out" } // rebounds off the end
|
|
245
|
+
{ "type": "back", "mode": "out", "overshoot": 1.70158 } // goes past, then settles
|
|
246
|
+
{ "type": "steps", "count": 5, "position": "end" } // holds, then jumps
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
`mode` is `"in"`, `"out"` (default) or `"in-out"`. `position` follows CSS
|
|
250
|
+
`steps()`: `"end"` (default), `"start"`, `"none"` (hold both ends) or `"both"`.
|
|
251
|
+
CSS and Lottie exports sample these into keyframes.
|
|
252
|
+
|
|
253
|
+
### Motion-path tracks
|
|
254
|
+
|
|
255
|
+
A track can animate an element **along an SVG path** instead of listing X/Y
|
|
256
|
+
keyframes. Its `property` is the literal `"motionPath"` and it carries a
|
|
257
|
+
`motionPathConfig`:
|
|
258
|
+
|
|
259
|
+
```jsonc
|
|
260
|
+
{
|
|
261
|
+
"target": "Ball",
|
|
262
|
+
"property": "motionPath",
|
|
263
|
+
"motionPathConfig": {
|
|
264
|
+
"pathData": "M0,0 C50,-80 150,-80 200,0", // SVG `d`
|
|
265
|
+
"autoRotate": true, // face the path tangent
|
|
266
|
+
"rotateOffset": 0, // degrees added when autoRotate
|
|
267
|
+
"matrix": [1, 0, 0, 1, 40, 20] // optional affine transform
|
|
268
|
+
},
|
|
269
|
+
"keyframes": [
|
|
270
|
+
{ "time": 0, "value": 0 }, // progress 0..1 along the path
|
|
271
|
+
{ "time": 2000, "value": 1, "easing": "ease-in-out" }
|
|
272
|
+
]
|
|
273
|
+
}
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
Keyframe `value`s are **progress** along the path (`0`–`1`), measured by arc
|
|
277
|
+
length. The timeline expands progress into `motionPathX`, `motionPathY` and
|
|
278
|
+
(with `autoRotate`) `motionPathRotate`.
|
|
279
|
+
|
|
280
|
+
`matrix` is an optional affine transform `[a, b, c, d, e, f]` applied to every
|
|
281
|
+
point on the path and to its tangent: `x' = a·x + c·y + e`, `y' = b·x + d·y + f`.
|
|
282
|
+
It places a path drawn in one coordinate space (an SVG's user units) into the
|
|
283
|
+
follower's space. Omit it for identity. `live`'s `motionPath` `align` option
|
|
284
|
+
writes it — see [gsap-compat.md](gsap-compat.md#motion-paths).
|
|
285
|
+
|
|
286
|
+
### Text tracks
|
|
287
|
+
|
|
288
|
+
A track whose `property` is the literal `"text"` types or scrambles from one
|
|
289
|
+
string to another. Like a motion path, its keyframes carry **progress**
|
|
290
|
+
(`0`–`1`) with easing, and `textConfig` says what the progress means:
|
|
291
|
+
|
|
292
|
+
```jsonc
|
|
293
|
+
{
|
|
294
|
+
"id": "title-text",
|
|
295
|
+
"target": "Title",
|
|
296
|
+
"property": "text",
|
|
297
|
+
"textConfig": {
|
|
298
|
+
"from": "LOADING", // text at progress 0 (default "")
|
|
299
|
+
"to": "TINYFLY", // text at progress 1 (required)
|
|
300
|
+
"mode": "scramble", // "type" | "scramble" (required)
|
|
301
|
+
"chars": "upperCase", // scramble: upperCase | lowerCase | upperAndLowerCase | numbers | your own characters
|
|
302
|
+
"revealDelay": 0.3, // scramble: fraction of the tween before characters settle
|
|
303
|
+
"seed": 7 // scramble: fixes the random characters
|
|
304
|
+
},
|
|
305
|
+
"keyframes": [
|
|
306
|
+
{ "time": 0, "value": 0 },
|
|
307
|
+
{ "time": 1200, "value": 1, "easing": "ease-out" }
|
|
308
|
+
]
|
|
309
|
+
}
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
Other `textConfig` fields: `refreshRate` (scramble: random-character changes
|
|
313
|
+
per second, default `20`), `tweenLength` (scramble: grow or shrink the length
|
|
314
|
+
over the tween, default `true`), `rightToLeft` (reveal from the end). The
|
|
315
|
+
timeline turns progress into a `text` value; adapters set it as the element's
|
|
316
|
+
text. Scramble characters come from a hash of the seed, position and refresh
|
|
317
|
+
step, so the string at any time is always the same.
|
|
318
|
+
|
|
319
|
+
### Spring tracks
|
|
320
|
+
|
|
321
|
+
A track with `"kind": "spring"` has no keyframes. Its values come from a
|
|
322
|
+
spring simulation, integrated at a fixed step from `t = 0`, so it is still a pure
|
|
323
|
+
function of time. The track stores the parameters, not a baked curve:
|
|
324
|
+
|
|
325
|
+
```jsonc
|
|
326
|
+
{
|
|
327
|
+
"id": "pop",
|
|
328
|
+
"target": "Box",
|
|
329
|
+
"property": "scale",
|
|
330
|
+
"kind": "spring",
|
|
331
|
+
"spring": {
|
|
332
|
+
"from": 0, // required
|
|
333
|
+
"to": 1, // required: resting value
|
|
334
|
+
"stiffness": 180, // default 180 — higher is snappier
|
|
335
|
+
"damping": 12, // default 12 — higher settles sooner, 0 oscillates forever
|
|
336
|
+
"mass": 1, // default 1
|
|
337
|
+
"velocity": 0, // default 0, units per second
|
|
338
|
+
"restDelta": 0.01, // default 0.01, fraction of the travel distance
|
|
339
|
+
"restSpeed": 0.1 // default 0.1, fraction of the travel distance per second
|
|
340
|
+
},
|
|
341
|
+
"delay": 200
|
|
342
|
+
}
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
A spring decides its own duration: the time until it settles, plus `delay`.
|
|
346
|
+
|
|
347
|
+
### Inertia tracks
|
|
348
|
+
|
|
349
|
+
A track with `"kind": "inertia"` is a throw: a value released with a velocity
|
|
350
|
+
that slows under friction and comes to rest. It has no keyframes; the motion is
|
|
351
|
+
a closed-form function of time.
|
|
352
|
+
|
|
353
|
+
```jsonc
|
|
354
|
+
{
|
|
355
|
+
"id": "puck-x",
|
|
356
|
+
"target": "Puck",
|
|
357
|
+
"property": "x",
|
|
358
|
+
"kind": "inertia",
|
|
359
|
+
"inertia": {
|
|
360
|
+
"from": 0, // required: value at release
|
|
361
|
+
"velocity": 900, // required: units per second (negative moves down)
|
|
362
|
+
"friction": 4, // default 4 — exponential decay rate per second
|
|
363
|
+
"min": 0, // optional lowest resting value
|
|
364
|
+
"max": 240, // optional highest resting value
|
|
365
|
+
"end": 120 // optional: a number snaps to multiples of it; an array snaps to the nearest listed value
|
|
366
|
+
},
|
|
367
|
+
"delay": 200
|
|
368
|
+
}
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
`restDelta` (optional) sets how close to the resting value counts as settled;
|
|
372
|
+
by default it scales with the distance travelled. Like a spring, an inertia
|
|
373
|
+
track decides its own duration.
|
|
374
|
+
|
|
375
|
+
### Rotation tracks (`interpolation: "slerp"`)
|
|
376
|
+
|
|
377
|
+
A keyframe track may say how its values blend. Its one mode today, `"slerp"`,
|
|
378
|
+
marks the values as rotations: `[x, y, z, w]` quaternions, turned the short way
|
|
379
|
+
round at a steady speed (spherical interpolation). Easing shapes the turn as it
|
|
380
|
+
shapes any other value.
|
|
381
|
+
|
|
382
|
+
```json
|
|
383
|
+
{
|
|
384
|
+
"id": "turn",
|
|
385
|
+
"target": "cube",
|
|
386
|
+
"property": "quaternion",
|
|
387
|
+
"interpolation": "slerp",
|
|
388
|
+
"keyframes": [
|
|
389
|
+
{ "time": 0, "value": [0, 0, 0, 1] },
|
|
390
|
+
{ "time": 2000, "value": [0, 1, 0, 0], "easing": "ease-in-out" }
|
|
391
|
+
]
|
|
392
|
+
}
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
It is data, not guessed: a 4-number array without it blends element-wise, as
|
|
396
|
+
arrays always have. A file that uses it is written as `formatVersion: 2`, so
|
|
397
|
+
older readers refuse it instead of playing the rotation wrongly; files that do
|
|
398
|
+
not stay at version 1. The DOM adapter draws a `quaternion` value as a CSS
|
|
399
|
+
`matrix3d()`. See [3D rotations](3d-rotations.md).
|
|
400
|
+
|
|
401
|
+
### Track scheduling
|
|
402
|
+
|
|
403
|
+
Every track kind accepts these optional fields. They are omitted from the JSON
|
|
404
|
+
when unset.
|
|
405
|
+
|
|
406
|
+
| Field | Type | Meaning |
|
|
407
|
+
|-------|------|---------|
|
|
408
|
+
| `delay` | number (ms) | Shift the whole track later. `"delay": 200` is the same as adding 200 to every keyframe's `time`. |
|
|
409
|
+
| `endDelay` | number (ms) | Extra time held after the last keyframe. Extends the track's (and so the timeline's) duration without changing its final value. Keyframe and text tracks only. |
|
|
410
|
+
| `targets` | string[] | Drive several targets from this one track. When present, `target` is ignored. |
|
|
411
|
+
| `stagger` | `{ each?, amount?, from?, offsets? }` | Offsets each of `targets` in time. Ignored without `targets`. |
|
|
412
|
+
|
|
413
|
+
`stagger` fields:
|
|
414
|
+
|
|
415
|
+
- `each` — ms between consecutive targets.
|
|
416
|
+
- `amount` — total spread in ms, divided across the targets. Wins over `each`.
|
|
417
|
+
- `from` — which target starts first: `"start"` (default), `"end"`,
|
|
418
|
+
`"center"`, `"edges"`, or a target index.
|
|
419
|
+
- `offsets` — explicit ms per target, in order, for layouts no 1D fan describes
|
|
420
|
+
(grids, random order). Wins over the other fields.
|
|
421
|
+
|
|
422
|
+
With neither `each` nor `amount`, every offset is `0`.
|
|
423
|
+
|
|
424
|
+
```jsonc
|
|
425
|
+
{
|
|
426
|
+
"id": "letters-in",
|
|
427
|
+
"target": "l1",
|
|
428
|
+
"targets": ["l1", "l2", "l3", "l4"],
|
|
429
|
+
"stagger": { "each": 80, "from": "center" },
|
|
430
|
+
"property": "opacity",
|
|
431
|
+
"keyframes": [
|
|
432
|
+
{ "time": 0, "value": 0 },
|
|
433
|
+
{ "time": 400, "value": 1, "easing": "ease-out" }
|
|
434
|
+
],
|
|
435
|
+
"delay": 100
|
|
436
|
+
}
|
|
437
|
+
```
|
|
438
|
+
|
|
439
|
+
When several tracks drive the same target and property, the value comes from
|
|
440
|
+
the one that started most recently (its first keyframe plus delay and stagger).
|
|
441
|
+
Ties go to the track listed later.
|
|
442
|
+
|
|
443
|
+
### Track kinds in an Animation Document
|
|
444
|
+
|
|
445
|
+
The editor loads an Animation Document's tracks through its own authoring
|
|
446
|
+
actions, so it reads only part of each track kind:
|
|
447
|
+
|
|
448
|
+
| Track | What the loader keeps |
|
|
449
|
+
|-------|-----------------------|
|
|
450
|
+
| Keyframe | `target`, `property`, `keyframes`. Scheduling fields are dropped. |
|
|
451
|
+
| Motion path | `pathData`, `autoRotate`, `rotateOffset`. Start and end time come from the first and last keyframes, easing from the last. `matrix` and middle keyframes are dropped. |
|
|
452
|
+
| Text | `textConfig`. Start and end time come from the first and last keyframes, easing from the last. |
|
|
453
|
+
| Inertia | `inertia` and `delay` |
|
|
454
|
+
| Spring | Not supported. Add springs in the editor, or use a [Timeline Definition](#2-timeline-definition). |
|
|
455
|
+
|
|
456
|
+
The engine itself reads every field above. Put springs, `matrix`, `targets` and
|
|
457
|
+
`stagger` in a Timeline Definition.
|
|
458
|
+
|
|
459
|
+
---
|
|
460
|
+
|
|
461
|
+
## 2. Timeline Definition
|
|
462
|
+
|
|
463
|
+
The engine's serialized timeline — what `serializeTimeline(timeline)` (or
|
|
464
|
+
`toJSON(timeline)` for a string) produces, what `deserializeTimeline()` /
|
|
465
|
+
`fromJSON()` / the standalone player consume, and the shape of the `.json` files
|
|
466
|
+
the editor's JSON export and import write and read.
|
|
467
|
+
|
|
468
|
+
```ts
|
|
469
|
+
import { serializeTimeline, toJSON, fromJSON } from '@algorisys/tinyfly'
|
|
470
|
+
|
|
471
|
+
const definition = serializeTimeline(timeline) // TimelineDefinition object
|
|
472
|
+
const json = toJSON(timeline) // the same, as a string
|
|
473
|
+
const restored = fromJSON(json) // back to a Timeline
|
|
474
|
+
```
|
|
475
|
+
|
|
476
|
+
`timeline.toDefinition()` returns the same shape without copying: its `config`
|
|
477
|
+
is exactly what the timeline was built with and its `tracks` are the live track
|
|
478
|
+
objects. Use `serializeTimeline` when you need a detached copy.
|
|
479
|
+
|
|
480
|
+
```jsonc
|
|
481
|
+
{
|
|
482
|
+
"formatVersion": 1, // optional; absent means 1 (2 when a track uses slerp)
|
|
483
|
+
"id": "scene-1",
|
|
484
|
+
"name": "My Animation", // optional
|
|
485
|
+
"config": {
|
|
486
|
+
"duration": 2000, // ms; omit to auto-derive from tracks
|
|
487
|
+
"loop": 0, // 0 = play once, -1 = infinite, N = repeat N more times
|
|
488
|
+
"speed": 1, // playback multiplier
|
|
489
|
+
"alternate": false, // ping-pong direction each loop
|
|
490
|
+
"repeatDelay": 500, // ms to wait between loop iterations
|
|
491
|
+
"drawingRate": 12, // optional: drawings per second (12 = on twos); values hold between drawings
|
|
492
|
+
"markers": [ // optional named steps, in time order
|
|
493
|
+
{ "id": "full", "time": 1400, "label": "cap is full", "pause": true, "question": "What happens next?" }
|
|
494
|
+
]
|
|
495
|
+
},
|
|
496
|
+
"captions": { // optional: per language, per marker id
|
|
497
|
+
"es": { "full": "la capacidad está llena" }
|
|
498
|
+
},
|
|
499
|
+
"tracks": [
|
|
500
|
+
{
|
|
501
|
+
"id": "track-1",
|
|
502
|
+
"target": "box", // element id (see note)
|
|
503
|
+
"property": "opacity",
|
|
504
|
+
"keyframes": [
|
|
505
|
+
{ "time": 0, "value": 0 },
|
|
506
|
+
{ "time": 1000, "value": 1, "easing": "ease-out" }
|
|
507
|
+
]
|
|
508
|
+
}
|
|
509
|
+
]
|
|
510
|
+
}
|
|
511
|
+
```
|
|
512
|
+
|
|
513
|
+
Differences from the Animation Document:
|
|
514
|
+
|
|
515
|
+
- It is **timeline-only** — no `elements`. The engine animates *targets*;
|
|
516
|
+
something else (a DOM/Canvas/SVG adapter) owns the actual objects and maps
|
|
517
|
+
`target` → real element.
|
|
518
|
+
- `target` here is whatever key you registered with the adapter — in editor
|
|
519
|
+
exports that's the element **id**; in a hand-wired integration it's your own
|
|
520
|
+
key (e.g. `adapter.registerTarget("box", el)`).
|
|
521
|
+
- Playback options live under `config`.
|
|
522
|
+
- `tracks` may mix every track kind: keyframe, [motion-path](#motion-path-tracks),
|
|
523
|
+
[text](#text-tracks), [spring](#spring-tracks) and [inertia](#inertia-tracks),
|
|
524
|
+
each with the [scheduling fields](#track-scheduling).
|
|
525
|
+
|
|
526
|
+
**Markers** name steps: players step between them, stop at `pause` markers and
|
|
527
|
+
show `question`s. **Captions** translate marker labels without touching the tracks.
|
|
528
|
+
See [Teaching animations](teaching.md).
|
|
529
|
+
|
|
530
|
+
**`formatVersion`** is the format a file was written for. Readers refuse a newer
|
|
531
|
+
version with a clear error. Optional additions keep the version; a change an older
|
|
532
|
+
reader would misread bumps it. Writers use the lowest version a file needs:
|
|
533
|
+
|
|
534
|
+
| Version | Adds |
|
|
535
|
+
|---|---|
|
|
536
|
+
| 1 | the original format |
|
|
537
|
+
| 2 | [`interpolation: "slerp"`](#rotation-tracks-interpolation-slerp) on keyframe tracks |
|
|
538
|
+
|
|
539
|
+
`repeatDelay` applies when the timeline loops (`loop` is not `0`). Going
|
|
540
|
+
forward, the playhead **holds the last frame** for the delay, then wraps to the
|
|
541
|
+
start. With `alternate`, it holds at whichever end it reached before turning
|
|
542
|
+
round. The delay is consumed at the timeline's `speed`, and a `seek()` cancels a
|
|
543
|
+
pending delay.
|
|
544
|
+
|
|
545
|
+
### Consuming a Timeline (custom integration)
|
|
546
|
+
|
|
547
|
+
```ts
|
|
548
|
+
import { deserializeTimeline } from '@algorisys/tinyfly'
|
|
549
|
+
import { DOMAdapter } from '@algorisys/tinyfly/adapters'
|
|
550
|
+
|
|
551
|
+
const timeline = deserializeTimeline(json) // json = Timeline Definition
|
|
552
|
+
const adapter = new DOMAdapter()
|
|
553
|
+
adapter.registerTarget('box', document.querySelector('#box'))
|
|
554
|
+
|
|
555
|
+
function frame(dt) {
|
|
556
|
+
timeline.tick(dt) // advance by dt ms
|
|
557
|
+
adapter.applyState(timeline.getStateAtTime(timeline.currentTime))
|
|
558
|
+
requestAnimationFrame(() => frame(16.67))
|
|
559
|
+
}
|
|
560
|
+
timeline.play()
|
|
561
|
+
frame(16.67)
|
|
562
|
+
```
|
|
563
|
+
|
|
564
|
+
Or skip the wiring entirely with the bundled player (`TinyflyPlayer`) — see the
|
|
565
|
+
[API reference](api-reference.md) and [Getting Started](getting-started.md).
|
|
566
|
+
|
|
567
|
+
---
|
|
568
|
+
|
|
569
|
+
## 3. Project format
|
|
570
|
+
|
|
571
|
+
The editor's saved document (in IndexedDB, and what you'd export to move a whole
|
|
572
|
+
project). One project holds one or more **scenes**, each with its own elements
|
|
573
|
+
and timeline.
|
|
574
|
+
|
|
575
|
+
```jsonc
|
|
576
|
+
{
|
|
577
|
+
"id": "project-…",
|
|
578
|
+
"name": "Untitled Animation",
|
|
579
|
+
"created": 1750000000000, // epoch ms
|
|
580
|
+
"modified": 1750000000000,
|
|
581
|
+
"canvas": { "width": 300, "height": 200, "background": "#252525" },
|
|
582
|
+
"activeSceneId": "scene-…",
|
|
583
|
+
"scenes": [
|
|
584
|
+
{
|
|
585
|
+
"id": "scene-…",
|
|
586
|
+
"name": "Scene 1",
|
|
587
|
+
"order": 0,
|
|
588
|
+
"elements": [ /* Element[] (with ids) */ ],
|
|
589
|
+
"timeline": { /* Timeline Definition | null */ },
|
|
590
|
+
"transition": { "type": "fade", "duration": 400 } // optional
|
|
591
|
+
}
|
|
592
|
+
],
|
|
593
|
+
"symbols": [ // the Library, shared across scenes
|
|
594
|
+
{
|
|
595
|
+
"id": "symbol-…",
|
|
596
|
+
"name": "Mouth",
|
|
597
|
+
"width": 120, "height": 80, // intrinsic size; instances scale from it
|
|
598
|
+
"elements": [ /* Element[] */ ],
|
|
599
|
+
"timeline": { /* Timeline Definition | null */ },
|
|
600
|
+
"created": 1750000000000,
|
|
601
|
+
"modified": 1750000000000
|
|
602
|
+
}
|
|
603
|
+
]
|
|
604
|
+
}
|
|
605
|
+
```
|
|
606
|
+
|
|
607
|
+
- `canvas.background` is a CSS color; also the default background for raster
|
|
608
|
+
exports.
|
|
609
|
+
- `scene.timeline` is a full [Timeline Definition](#2-timeline-definition) (or
|
|
610
|
+
`null` for an empty scene). Here the timeline `target`s are element **ids**.
|
|
611
|
+
- `scene.transition.type` is one of `none`, `fade`, `slide-left`,
|
|
612
|
+
`slide-right`, `slide-up`, `slide-down`.
|
|
613
|
+
- `symbols` holds reusable symbol definitions. A `symbol` element points at one
|
|
614
|
+
by `symbolId`; the symbol's own `timeline` plays inside each instance. Projects
|
|
615
|
+
saved before symbols existed load with an empty list.
|
|
616
|
+
|
|
617
|
+
---
|
|
618
|
+
|
|
619
|
+
## 4. Sequence format
|
|
620
|
+
|
|
621
|
+
A flattened, self-contained bundle for the embeddable multi-scene player
|
|
622
|
+
(`TinyflySequencer`). Each scene carries pre-rendered element HTML so the player
|
|
623
|
+
needs no editor code.
|
|
624
|
+
|
|
625
|
+
```jsonc
|
|
626
|
+
{
|
|
627
|
+
"id": "project-…",
|
|
628
|
+
"name": "My Promo",
|
|
629
|
+
"canvas": { "width": 360, "height": 640, "background": "#111" },
|
|
630
|
+
"scenes": [
|
|
631
|
+
{
|
|
632
|
+
"id": "scene-…",
|
|
633
|
+
"name": "Scene 1",
|
|
634
|
+
"elements": [
|
|
635
|
+
{ "type": "rect", "name": "Box", "x": 0, "y": 0, "width": 60, "height": 60,
|
|
636
|
+
"rotation": 0, "opacity": 1, "html": "<div …></div>" }
|
|
637
|
+
],
|
|
638
|
+
"timeline": { /* Timeline Definition */ },
|
|
639
|
+
"transition": { "type": "fade", "duration": 400 }
|
|
640
|
+
}
|
|
641
|
+
],
|
|
642
|
+
"loop": 0, // optional: -1 = infinite, 0 = no loop, N = N times
|
|
643
|
+
"symbols": [ // optional: nested timelines for symbol instances
|
|
644
|
+
{ "id": "symbol-…", "timeline": { /* Timeline Definition */ } }
|
|
645
|
+
]
|
|
646
|
+
}
|
|
647
|
+
```
|
|
648
|
+
|
|
649
|
+
`symbols` lists only symbols that are used in a scene and have a non-empty
|
|
650
|
+
timeline. The sequencer animates each instance's inner elements (tagged
|
|
651
|
+
`data-tinyfly-symbol`) from the matching timeline.
|
|
652
|
+
|
|
653
|
+
This is what the editor's **Embed → All Scenes** option emits. For a single
|
|
654
|
+
scene, embedding emits a plain [Timeline Definition](#2-timeline-definition)
|
|
655
|
+
plus its element HTML.
|
|
656
|
+
|
|
657
|
+
---
|
|
658
|
+
|
|
659
|
+
## Determinism
|
|
660
|
+
|
|
661
|
+
tinyfly guarantees **same input → same output**:
|
|
662
|
+
|
|
663
|
+
- All timing is explicit and in **milliseconds**. The engine advances by the
|
|
664
|
+
`dt` you feed `tick(dt)`; it never reads wall-clock time itself.
|
|
665
|
+
- Interpolation and easing are pure functions of `(from, to, progress)`.
|
|
666
|
+
- No implicit browser or global state affects the produced values.
|
|
667
|
+
|
|
668
|
+
So a document rendered at 30fps, 60fps, or frame-stepped for export yields the
|
|
669
|
+
same values at the same timeline times — which is why GIF/WebP/MP4 export is
|
|
670
|
+
reproducible.
|
|
671
|
+
|
|
672
|
+
---
|
|
673
|
+
|
|
674
|
+
## Versioning & forward-compatibility
|
|
675
|
+
|
|
676
|
+
- Unknown **element fields** and unknown **animatable properties** are ignored by
|
|
677
|
+
adapters, not rejected — older players tolerate newer documents' extras.
|
|
678
|
+
- Older documents are migrated on load (e.g. a pre-scenes project is wrapped into
|
|
679
|
+
a single scene; a missing `canvas.background` picks up the default).
|
|
680
|
+
- There is no explicit format-version field today; the shapes above are additive.
|
|
681
|
+
Treat missing optional fields as their documented defaults.
|
|
682
|
+
|
|
683
|
+
---
|
|
684
|
+
|
|
685
|
+
## See also
|
|
686
|
+
|
|
687
|
+
- [Getting Started](getting-started.md) — install and play your first animation.
|
|
688
|
+
- [API Reference](api-reference.md) — `Timeline`, adapters, `TinyflyPlayer`.
|
|
689
|
+
- [Editor Guide](editor-guide.md) — how these documents are produced in the UI.
|
|
690
|
+
- [Examples](examples.md) — complete, annotated animations.
|