@algorisys/tinyfly 0.92.0 → 0.94.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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 +529 -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 +131 -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 +3045 -2024
- package/lib/addons/target-properties-BtN9skb-.js +142 -0
- package/lib/browser/tinyfly.iife.js +9 -4
- package/lib/browser/tinyfly.js +6968 -5817
- 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 +102 -0
- package/lib/types/characters/acting/custom.d.ts +66 -0
- package/lib/types/characters/acting/gags.d.ts +10 -0
- package/lib/types/characters/acting/hand-path.d.ts +35 -0
- package/lib/types/characters/acting/index.d.ts +4 -0
- package/lib/types/characters/acting/persona.d.ts +93 -0
- package/lib/types/characters/acting/script.d.ts +75 -11
- package/lib/types/characters/capabilities.d.ts +61 -0
- package/lib/types/characters/code-panel.d.ts +201 -0
- package/lib/types/characters/figure-actions.d.ts +12 -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 +9 -2
- 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 +12631 -0
- package/llms.txt +57 -0
- package/package.json +6 -2
- package/skills/tinyfly/SKILL.md +67 -0
- package/lib/addons/camera-C7bZOWMB.js +0 -33
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
# Extending tinyfly
|
|
2
|
+
|
|
3
|
+
tinyfly has no plugin system, and that is deliberate. A plugin would put
|
|
4
|
+
arbitrary code inside the engine, which evaluates animations and must stay
|
|
5
|
+
deterministic and serializable. Instead there are four ways to extend it, from
|
|
6
|
+
the one that needs no engine change to the one that does:
|
|
7
|
+
|
|
8
|
+
1. **Render somewhere new:** write an adapter.
|
|
9
|
+
2. **Animate new kinds of things:** plain-object targets and the ticker.
|
|
10
|
+
3. **Shape motion:** eases, custom curves and stagger offsets.
|
|
11
|
+
4. **Add a track kind:** an engine change, with the contract below.
|
|
12
|
+
|
|
13
|
+
Examples and showcases are also contributions. The last section covers how to
|
|
14
|
+
add one to the gallery.
|
|
15
|
+
|
|
16
|
+
## 1. A render adapter
|
|
17
|
+
|
|
18
|
+
The engine never draws anything. A timeline answers one question: *what are the
|
|
19
|
+
values at this time?*
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
const state = timeline.getStateAtTime(1250)
|
|
23
|
+
// state.values: Map<targetName, Map<property, value>>
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
An adapter applies that state to something: DOM elements, a canvas, WebGL
|
|
27
|
+
uniforms, a terminal, a LED strip. Its whole contract is a method that takes an
|
|
28
|
+
`AnimationState`:
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
import { Timeline, type AnimationState } from '@algorisys/tinyfly'
|
|
32
|
+
|
|
33
|
+
class ConsoleAdapter {
|
|
34
|
+
private readonly targets = new Map<string, { label: string }>()
|
|
35
|
+
|
|
36
|
+
registerTarget(name: string, target: { label: string }) {
|
|
37
|
+
this.targets.set(name, target)
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
applyState(state: AnimationState) {
|
|
41
|
+
for (const [name, properties] of state.values) {
|
|
42
|
+
const target = this.targets.get(name)
|
|
43
|
+
if (!target) continue
|
|
44
|
+
console.log(target.label, Object.fromEntries(properties))
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Drive it with whatever clock you have:
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
let last = performance.now()
|
|
54
|
+
requestAnimationFrame(function frame(now) {
|
|
55
|
+
timeline.tick(now - last)
|
|
56
|
+
last = now
|
|
57
|
+
adapter.applyState(timeline.getStateAtTime(timeline.currentTime))
|
|
58
|
+
requestAnimationFrame(frame)
|
|
59
|
+
})
|
|
60
|
+
timeline.play()
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The built-in adapters show the patterns to copy:
|
|
64
|
+
|
|
65
|
+
| Adapter | Look at it for |
|
|
66
|
+
|---|---|
|
|
67
|
+
| `DOMAdapter` (`src/adapters/dom`) | Merging several properties into one `transform` per element; filters; text |
|
|
68
|
+
| `CanvasAdapter` (`src/adapters/canvas`) | Retained targets redrawn each frame; gradients; clip insets |
|
|
69
|
+
| `SVGAdapter` (`src/adapters/svg`) | Attributes vs. styles; path `d`; stroke drawing |
|
|
70
|
+
| `WebGLAdapter` (`src/adapters/webgl`) | Writing values into uniforms |
|
|
71
|
+
|
|
72
|
+
**Rules an adapter keeps:**
|
|
73
|
+
|
|
74
|
+
- **Read nothing back.** An adapter writes values; it never measures the thing it
|
|
75
|
+
renders to decide what to write. Values come from the timeline only, which is
|
|
76
|
+
what keeps playback deterministic.
|
|
77
|
+
- **Ignore what you don't understand.** An unknown property is skipped, not an
|
|
78
|
+
error, so one JSON file plays in several renderers.
|
|
79
|
+
- **Apply the whole state.** Don't cache "what changed" in the adapter; the engine
|
|
80
|
+
and stage already avoid redundant work.
|
|
81
|
+
|
|
82
|
+
**Before writing an adapter:** if you only need to draw something the built-in
|
|
83
|
+
canvas shapes can't (a character, a chart, a prop), a `custom` canvas target may
|
|
84
|
+
be enough. Its `draw(ctx, target, time)` function is your code, while the
|
|
85
|
+
`CanvasAdapter` still positions, transforms and fades it and the timeline animates
|
|
86
|
+
the values it declares in `props`. See
|
|
87
|
+
[Rendering Video from Code](video-rendering.md#custom-targets).
|
|
88
|
+
|
|
89
|
+
## 2. Animating anything with `live`
|
|
90
|
+
|
|
91
|
+
For most integrations you don't need an adapter at all. `live` tweens **plain
|
|
92
|
+
objects**, and `ticker.add` runs your drawing code after each frame's values are
|
|
93
|
+
applied:
|
|
94
|
+
|
|
95
|
+
```js
|
|
96
|
+
const uniforms = { time: 0, glow: 0 }
|
|
97
|
+
live.to(uniforms, { glow: 1, duration: 0.6, repeat: -1, yoyo: true })
|
|
98
|
+
live.ticker.add(() => {
|
|
99
|
+
material.uniforms.uGlow.value = uniforms.glow // Three.js, PixiJS, a game loop…
|
|
100
|
+
renderer.render(scene, camera)
|
|
101
|
+
})
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Plain objects work with everything else too: scroll triggers, stagger, springs,
|
|
105
|
+
keyframes, `quickTo` and `repeatRefresh`.
|
|
106
|
+
|
|
107
|
+
## 3. Shaping motion
|
|
108
|
+
|
|
109
|
+
- **Named eases:**
|
|
110
|
+
- `live.customEase(name, 'M0,0 C…')` takes a curve drawn in a design tool.
|
|
111
|
+
- `customBounce` and `customWiggle` generate physical curves.
|
|
112
|
+
- All of these register a name you can use as `ease`.
|
|
113
|
+
- **Parametric eases:** `{ type: 'elastic' | 'bounce' | 'back' | 'steps', … }` are
|
|
114
|
+
exact and serializable. Prefer them over sampled curves when one fits.
|
|
115
|
+
- **Explicit stagger offsets:** a track's `stagger.offsets` takes any per-target
|
|
116
|
+
timing you can compute, such as a hex grid, distance from the pointer or reading
|
|
117
|
+
order. They are stored as plain numbers in the JSON.
|
|
118
|
+
- **Function values:** `x: (index, target, targets) => …` run when the tween is built
|
|
119
|
+
(and on every repeat with `repeatRefresh`). Randomness comes from `live.utils`,
|
|
120
|
+
which is seeded.
|
|
121
|
+
|
|
122
|
+
## 4. A new track kind
|
|
123
|
+
|
|
124
|
+
Keyframe, spring, inertia, motion-path and text tracks cover most motion. A new
|
|
125
|
+
kind of track is an engine change. It is welcome when it describes motion that
|
|
126
|
+
keyframes can't, compactly and deterministically.
|
|
127
|
+
|
|
128
|
+
A track kind must provide:
|
|
129
|
+
|
|
130
|
+
| Piece | Where | Why |
|
|
131
|
+
|---|---|---|
|
|
132
|
+
| A JSON shape and type guard | `src/engine/types.ts` | Definitions are the source of truth |
|
|
133
|
+
| Evaluation at any time, with no hidden state | `src/engine/core/` | Scrubbing backwards and seeking must match playing |
|
|
134
|
+
| Duration | `src/engine/core/track.ts` | Timelines size themselves from their tracks |
|
|
135
|
+
| Validation on load | `src/engine/serialization` | Bad JSON fails loudly, not halfway through playback |
|
|
136
|
+
| Baking to keyframes | `src/engine/core/bake.ts` | CSS, Lottie and other keyframe formats can export it |
|
|
137
|
+
| A `live` / GSAP-style entry | `src/compat/gsap` | Code users can author it |
|
|
138
|
+
| Tests | beside each file | Solution values at set times, a JSON round trip, and a bake |
|
|
139
|
+
|
|
140
|
+
Springs (`spring.ts`) and inertia (`inertia.ts`) are good models: each is a
|
|
141
|
+
closed-form or fixed-step function of time, serialized as a few parameters.
|
|
142
|
+
|
|
143
|
+
## Contributing an example
|
|
144
|
+
|
|
145
|
+
Gallery examples live in `src/examples/live-demos/` (cards) and
|
|
146
|
+
`src/examples/showcases/` (full pages). Each is a plain JavaScript module that
|
|
147
|
+
exports:
|
|
148
|
+
|
|
149
|
+
- `html`: the markup, with a scoped `<style>`;
|
|
150
|
+
- `run(live, root)`: the animation. It may return a cleanup function.
|
|
151
|
+
|
|
152
|
+
The code between `// #region code` and `// #endregion code` is what the card shows
|
|
153
|
+
and what **Copy code** puts in a standalone page. Keep everything the animation
|
|
154
|
+
uses inside that region, so the copied page runs as is. Register the module in the
|
|
155
|
+
folder's `index.ts`. `npx vitest run src/examples` then runs it, checks that it
|
|
156
|
+
cleans up, and builds its standalone page.
|
|
157
|
+
|
|
158
|
+
Video scenes live in `examples/headless-video/` as `.mjs` modules that
|
|
159
|
+
default-export a scene (see [Rendering Video from Code](video-rendering.md)).
|
|
160
|
+
`npx vitest run src/headless` loads every scene there and draws each of its
|
|
161
|
+
stills, so a scene that throws or draws nothing fails the tests.
|
|
162
|
+
|
|
163
|
+
A good example:
|
|
164
|
+
|
|
165
|
+
- shows one idea well, or a whole page done properly;
|
|
166
|
+
- respects `prefers-reduced-motion` (see `live.matchMedia`);
|
|
167
|
+
- animates transforms and opacity rather than layout;
|
|
168
|
+
- stops work that isn't visible.
|