@algorisys/tinyfly 0.92.0 → 0.94.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/README.md +7 -6
  2. package/bin/tinyfly.mjs +34 -1
  3. package/docs/2d-animation-roadmap.md +191 -0
  4. package/docs/3d-rotations.md +164 -0
  5. package/docs/3d-support-plan.md +628 -0
  6. package/docs/DEPLOYMENT.md +414 -0
  7. package/docs/acting.md +529 -0
  8. package/docs/api-reference.md +2353 -0
  9. package/docs/camera.md +94 -0
  10. package/docs/cartoon-hands.md +96 -0
  11. package/docs/character-system-m1.md +218 -0
  12. package/docs/character-system-plan.md +384 -0
  13. package/docs/dance.md +315 -0
  14. package/docs/editor-guide.md +1249 -0
  15. package/docs/examples.md +765 -0
  16. package/docs/extending.md +168 -0
  17. package/docs/file-format.md +690 -0
  18. package/docs/getting-started.md +314 -0
  19. package/docs/grid-and-snapping.md +64 -0
  20. package/docs/gsap-compat.md +1241 -0
  21. package/docs/llm-guide.md +131 -0
  22. package/docs/maps.md +116 -0
  23. package/docs/onion-skinning.md +41 -0
  24. package/docs/pen-tool.md +65 -0
  25. package/docs/polygon-star.md +44 -0
  26. package/docs/scene-3d.md +299 -0
  27. package/docs/scroll-animation.md +314 -0
  28. package/docs/shape-morph.md +61 -0
  29. package/docs/sprite-sheet-export.md +54 -0
  30. package/docs/symbols-and-library.md +137 -0
  31. package/docs/teaching.md +348 -0
  32. package/docs/video-rendering.md +728 -0
  33. package/lib/addons/adapters.js +22 -18
  34. package/lib/addons/characters.js +3045 -2024
  35. package/lib/addons/target-properties-BtN9skb-.js +142 -0
  36. package/lib/browser/tinyfly.iife.js +9 -4
  37. package/lib/browser/tinyfly.js +6968 -5817
  38. package/lib/browser/tinyfly.umd.js +9 -4
  39. package/lib/engine/tinyfly-engine.js +286 -258
  40. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  41. package/lib/types/adapters/canvas/canvas-adapter.d.ts +6 -0
  42. package/lib/types/adapters/canvas/index.d.ts +1 -0
  43. package/lib/types/adapters/canvas/target-properties.d.ts +68 -0
  44. package/lib/types/characters/acting/beat-check.d.ts +102 -0
  45. package/lib/types/characters/acting/custom.d.ts +66 -0
  46. package/lib/types/characters/acting/gags.d.ts +10 -0
  47. package/lib/types/characters/acting/hand-path.d.ts +35 -0
  48. package/lib/types/characters/acting/index.d.ts +4 -0
  49. package/lib/types/characters/acting/persona.d.ts +93 -0
  50. package/lib/types/characters/acting/script.d.ts +75 -11
  51. package/lib/types/characters/capabilities.d.ts +61 -0
  52. package/lib/types/characters/code-panel.d.ts +201 -0
  53. package/lib/types/characters/figure-actions.d.ts +12 -0
  54. package/lib/types/characters/figure-props.d.ts +87 -0
  55. package/lib/types/characters/gaits.d.ts +8 -0
  56. package/lib/types/characters/index.d.ts +3 -0
  57. package/lib/types/characters/stick-figure.d.ts +9 -2
  58. package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
  59. package/lib/types/engine/authoring/index.d.ts +1 -0
  60. package/llms-full.txt +12631 -0
  61. package/llms.txt +57 -0
  62. package/package.json +6 -2
  63. package/skills/tinyfly/SKILL.md +67 -0
  64. package/lib/addons/camera-C7bZOWMB.js +0 -33
@@ -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.