@algorisys/tinyfly 0.91.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 +2785 -1794
- package/lib/addons/target-properties-BtN9skb-.js +142 -0
- package/lib/browser/tinyfly.iife.js +9 -4
- package/lib/browser/tinyfly.js +6575 -5454
- 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 +4 -0
- package/lib/types/characters/species/human-motion.d.ts +45 -0
- package/lib/types/characters/species/human.d.ts +2 -0
- package/lib/types/characters/stick-figure.d.ts +2 -0
- package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
- package/lib/types/engine/authoring/index.d.ts +1 -0
- package/llms-full.txt +12548 -0
- package/llms.txt +57 -0
- package/package.json +6 -2
- package/skills/tinyfly/SKILL.md +64 -0
- package/lib/addons/camera-C7bZOWMB.js +0 -33
package/README.md
CHANGED
|
@@ -61,7 +61,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
|
|
|
61
61
|
- **The drawing hand** - `drawnPathTarget()` draws a sketched stroke on from a `draw` track while a cartoon hand holds the pencil at its end in a writing grip; the same hand can hold the eraser. `handAt()` gives one hand for a whole scene: it follows each stroke, lifts and glides to the next, and enters and leaves the page
|
|
62
62
|
- **Erasing** - An eraser rubs out part of a target (`erasable()`, animated by an `erase` track) or of anything drawn in code (`withErased()`); clip-based, so it works in the browser and headless alike
|
|
63
63
|
- **Cartoon hands** - A hand rig in 3D, drawn flat: thumb and fingers posed by numbers (`index.curl`, `thumb.across`, `spread`, `turn`), ready-made shapes (fist, point, thumbs-up, peace, OK, pinch, wave, pencil grip…), left and right, four or five fingers, in every look; the animator's hand and (opt-in) character gloves are built on it. See [docs/cartoon-hands.md](docs/cartoon-hands.md)
|
|
64
|
-
- **Cartoon acting** - `actTracks()` turns the same key poses into acted motion: wind-ups, overshoot that settles or wobbles, joints that overlap (hips lead, wrists drag), eyes that dart ahead and blink on head turns, moving holds and jump squash, in `full`, `snappy` or `limited` styles. Gags come as data (`gag('take')`, double take, wind-up, tremble). A line of action (`bend`) curves the spine, and gaits have personality (bouncy, double bounce, sneak, strut, tired, run). Lip-sync works from text, Latin or Devanagari. `scriptTracks()` compiles a story written as beats (`{ do: 'walk', to: 640 }`, `{ do: 'take' }`, `{ do: 'say', say: '…' }`) into all of it. `cameraTracks()` films it with push-ins, cuts, shakes and follows. The cartoon zip (`{ do: 'zip' }`) has the legs wheel in place before it is gone. In the editor, a Character's **Acting** section acts its keyed poses in a style and adds gags, walks in a gait and lip-synced lines, with drawing on twos as a timeline setting. It also adds speed lines from earlier frames (`drawStickSmear()`), dust puffs, impact stars, and drawing on twos for video (`drawingRate`). Output is plain keyframes. See [docs/acting.md](docs/acting.md)
|
|
64
|
+
- **Cartoon acting** - `actTracks()` turns the same key poses into acted motion: wind-ups, overshoot that settles or wobbles, joints that overlap (hips lead, wrists drag), eyes that dart ahead and blink on head turns, moving holds and jump squash, in `full`, `snappy` or `limited` styles. Gags come as data (`gag('take')`, double take, wind-up, tremble). A line of action (`bend`) curves the spine, and gaits have personality (bouncy, double bounce, sneak, strut, tired, run). Lip-sync works from text, Latin or Devanagari. `scriptTracks()` compiles a story written as beats (`{ do: 'walk', to: 640 }`, `{ do: 'take' }`, `{ do: 'say', say: '…' }`) into all of it. `cameraTracks()` films it with push-ins, cuts, shakes and follows. The cartoon zip (`{ do: 'zip' }`) has the legs wheel in place before it is gone. Figures can act on code, Animator vs Animation style: `codePanel()` lays a listing out so every line and word is a place in the scene, and beats leap onto lines, point at them and swipe them away (`{ do: 'swipe', target: code.line(7) }`), with the line wiped, knocked off the panel or blurred out of focus on the frames the hand crosses it. Words come loose too: a figure grabs `var` and throws it, kicks another out of a loop, carries a stray `;` to where it belongs, pushes a word along its line (the text closing up behind it), and writes `mut` into a line by hand. A figure standing on a line rides it when a gap above closes (`code.ride()`). In the editor, a Character's **Acting** section acts its keyed poses in a style and adds gags, walks in a gait and lip-synced lines, with drawing on twos as a timeline setting. Characters come in builds (slim, kid, broad, curvy, stocky), and the v2 human has its own line of action, gaits and gags, posed in 3D so they read from every view. It also adds speed lines from earlier frames (`drawStickSmear()`), dust puffs, impact stars, and drawing on twos for video (`drawingRate`). Output is plain keyframes. See [docs/acting.md](docs/acting.md)
|
|
65
65
|
- **Pencil story example** - `examples/pencil-story-hindi/index.html` tells a short Hindi story (प्यासा राहगीर, the thirsty traveller) Pencilmation-style with the browser bundle alone: the hand draws the scene and writes the narration, then rubs out the pot
|
|
66
66
|
- **Captions** - `toSRT()` / `toWebVTT()` from narration cues or from a timeline's markers
|
|
67
67
|
|
|
@@ -140,6 +140,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
|
|
|
140
140
|
## Documentation
|
|
141
141
|
|
|
142
142
|
- [Getting Started](docs/getting-started.md) — Installation, setup, and your first animation
|
|
143
|
+
- [Building Animations with an LLM](docs/llm-guide.md) — The capability catalog, `describeTarget`, did-you-mean checks for beats and tracks, rendering stills to look at, and the agent skill
|
|
143
144
|
- [Editor Guide](docs/editor-guide.md) — Complete guide to the visual editor (elements, timeline, scenes, presets, shortcuts)
|
|
144
145
|
- [API Reference](docs/api-reference.md) — Full engine, player, adapter, and export API documentation
|
|
145
146
|
- [File Format](docs/file-format.md) — The tinyfly JSON format (animation documents, timelines, projects, sequences) for integrations
|
|
@@ -154,7 +155,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
|
|
|
154
155
|
|
|
155
156
|
**Feature guides:** [Symbols & Library](docs/symbols-and-library.md) · [Camera](docs/camera.md) · [Polygon & Star](docs/polygon-star.md) · [Pen tool](docs/pen-tool.md) · [Shape morph](docs/shape-morph.md) · [Grid & snapping](docs/grid-and-snapping.md) · [Onion skinning](docs/onion-skinning.md) · [Sprite-sheet export](docs/sprite-sheet-export.md)
|
|
156
157
|
|
|
157
|
-
**Docs for LLMs:** the repo root has [`llms.txt`](llms.txt), an [llmstxt.org](https://llmstxt.org) index of these docs. The built editor also serves `/llms.txt`, `/llms-full.txt`
|
|
158
|
+
**Docs for LLMs:** the repo root has [`llms.txt`](llms.txt), an [llmstxt.org](https://llmstxt.org) index of these docs, and [`llms-full.txt`](llms-full.txt): every doc, the course, and the capability catalog in one file. Both ship in the npm package with the docs and an agent skill (`skills/tinyfly/SKILL.md`), so an assistant finds them in `node_modules` at the installed version. `npx @algorisys/tinyfly capabilities` prints the catalog: every pose, expression, gag, gait, beat action, canvas property and code-panel edit, read from the library, so a name in it is accepted and a name not in it is rejected with the name probably meant (`tinyfly check beats.json`, `checkTracks`). The built editor also serves `/llms.txt`, `/llms-full.txt` and each page as raw markdown at `/docs/<page>.md`.
|
|
158
159
|
|
|
159
160
|
## Installation
|
|
160
161
|
|
|
@@ -236,7 +237,7 @@ GSAP-shaped functions at the top level. Teaching embeds are included: add
|
|
|
236
237
|
itself.
|
|
237
238
|
|
|
238
239
|
```html
|
|
239
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
240
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.93.0/cdn/tinyfly.iife.js"></script>
|
|
240
241
|
<script>
|
|
241
242
|
tinyfly.to('.box', { x: 200, rotate: 90, duration: 1, ease: 'power2.out' })
|
|
242
243
|
|
|
@@ -272,7 +273,7 @@ A teaching figure needs no code at all:
|
|
|
272
273
|
<script type="application/json" data-tinyfly-timeline>{ …timeline JSON with markers… }</script>
|
|
273
274
|
<figcaption>Appending to a full slice</figcaption>
|
|
274
275
|
</figure>
|
|
275
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
276
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.93.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
|
|
276
277
|
```
|
|
277
278
|
|
|
278
279
|
See [Teaching Animations](docs/teaching.md).
|
|
@@ -371,7 +372,7 @@ Without a build step, the player bundle puts the same functions on a `tinyfly` g
|
|
|
371
372
|
<div data-tinyfly="box" style="width: 60px; height: 60px; background: #4a9eff;"></div>
|
|
372
373
|
</div>
|
|
373
374
|
|
|
374
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
375
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.93.0/cdn/tinyfly-player.iife.js"></script>
|
|
375
376
|
<script>
|
|
376
377
|
tinyfly.play('#animation', './animation.json', { loop: -1 })
|
|
377
378
|
</script>
|
|
@@ -480,7 +481,7 @@ Or skip the code entirely with declarative embeds (see [Teaching Animations](doc
|
|
|
480
481
|
<svg viewBox="0 0 720 200">…</svg>
|
|
481
482
|
<script type="application/json" data-tinyfly-timeline>{ …timeline JSON… }</script>
|
|
482
483
|
</figure>
|
|
483
|
-
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.
|
|
484
|
+
<script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.93.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
|
|
484
485
|
```
|
|
485
486
|
|
|
486
487
|
### Audio / Video Sync
|
package/bin/tinyfly.mjs
CHANGED
|
@@ -2,6 +2,18 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* tinyfly command line.
|
|
4
4
|
*
|
|
5
|
+
* tinyfly capabilities [--json]
|
|
6
|
+
* Print everything tinyfly can do, read from the library itself: easings,
|
|
7
|
+
* track kinds, what every shape animates, the stick figure's joints,
|
|
8
|
+
* poses, expressions, gags, gaits, beat actions, dances and flips, and the
|
|
9
|
+
* code panel's languages and edits. Read it before writing an animation
|
|
10
|
+
* (it is what a language model should read). --json prints it as data.
|
|
11
|
+
*
|
|
12
|
+
* tinyfly check <beats.json>
|
|
13
|
+
* Check a beat script (an array of beats, or { "beats": [...] }) before
|
|
14
|
+
* compiling it: unknown actions, moods, joints and fields are errors that
|
|
15
|
+
* name what was probably meant. Exit 1 on errors.
|
|
16
|
+
*
|
|
5
17
|
* tinyfly validate <timeline.json> [<timeline.json> …] [--markup <figure.svg|.html>]
|
|
6
18
|
* Exit 1 when the timeline has errors: tracks aimed at elements the markup
|
|
7
19
|
* lacks, markers out of order or outside the animation, keyframes past an
|
|
@@ -69,6 +81,8 @@ function listFlag(name) {
|
|
|
69
81
|
const usage = () => {
|
|
70
82
|
console.error(
|
|
71
83
|
'Usage:\n' +
|
|
84
|
+
' tinyfly capabilities [--json]\n' +
|
|
85
|
+
' tinyfly check <beats.json>\n' +
|
|
72
86
|
' tinyfly validate <timeline.json> [<timeline.json> …] [--markup <file>]\n' +
|
|
73
87
|
' tinyfly render <timeline.json> <markup file> [--at start|end|<ms>|<marker id>]\n' +
|
|
74
88
|
' tinyfly video <scene.mjs> [-o <out.mp4>] [--stills <dir>] [--frames <i,j,…> | --times <ms,…>] [--loop-check]\n' +
|
|
@@ -86,7 +100,26 @@ const readJson = (file) => {
|
|
|
86
100
|
}
|
|
87
101
|
}
|
|
88
102
|
|
|
89
|
-
if (command === '
|
|
103
|
+
if (command === 'capabilities') {
|
|
104
|
+
const json = has('--json')
|
|
105
|
+
const characters = await import('../lib/addons/characters.js')
|
|
106
|
+
const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
|
|
107
|
+
process.stdout.write(json ? `${JSON.stringify(characters.capabilities(version), null, 2)}\n` : characters.capabilitiesMarkdown(version))
|
|
108
|
+
} else if (command === 'check') {
|
|
109
|
+
const [beatsFile] = rest
|
|
110
|
+
if (!beatsFile) usage()
|
|
111
|
+
const data = readJson(beatsFile)
|
|
112
|
+
const beats = Array.isArray(data) ? data : data?.beats
|
|
113
|
+
const { checkBeats } = await import('../lib/addons/characters.js')
|
|
114
|
+
const problems = checkBeats(beats)
|
|
115
|
+
for (const problem of problems) console.error(`${problem.level}: ${problem.beat >= 0 ? `beat ${problem.beat}: ` : ''}${problem.message}`)
|
|
116
|
+
const errors = problems.filter((problem) => problem.level === 'error').length
|
|
117
|
+
if (errors > 0) {
|
|
118
|
+
console.error(`${beatsFile}: ${errors} error(s)`)
|
|
119
|
+
process.exit(1)
|
|
120
|
+
}
|
|
121
|
+
console.error(`${beatsFile}: ok${problems.length ? ` (${problems.length} warning(s))` : ''}`)
|
|
122
|
+
} else if (command === 'validate') {
|
|
90
123
|
const markupFile = flag('--markup')
|
|
91
124
|
const timelineFiles = rest
|
|
92
125
|
if (timelineFiles.length === 0) usage()
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
# 2D Animation Roadmap — Adobe Animate gap analysis & plan
|
|
2
|
+
|
|
3
|
+
**Status:** Planning (no implementation yet)
|
|
4
|
+
**Date:** 2026-07-08
|
|
5
|
+
|
|
6
|
+
This document captures a gap analysis of tinyfly against a full Adobe Animate
|
|
7
|
+
"Complete 2D Animation Course" workflow, and a phased plan for the features and
|
|
8
|
+
UX worth pursuing. It is a living plan — we will implement from it over time.
|
|
9
|
+
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Positioning (read this first)
|
|
13
|
+
|
|
14
|
+
tinyfly is a **property-animation engine**: you place objects and animate their
|
|
15
|
+
properties over time via keyframe tracks (After Effects / GSAP style), with a
|
|
16
|
+
JSON-first, inspectable, framework-agnostic core.
|
|
17
|
+
|
|
18
|
+
Adobe Animate is a **drawing + rigging studio**: you draw pictures (often frame
|
|
19
|
+
by frame), rig them with bones, and tween them.
|
|
20
|
+
|
|
21
|
+
**Roughly 60% of a "complete Animate course" is a different product category.**
|
|
22
|
+
Matching all of it would break tinyfly's "GSAP-level power with Excalidraw-level
|
|
23
|
+
simplicity" identity and is a multi-year effort. The plan below deliberately
|
|
24
|
+
separates **on-brand wins** from **out-of-scope** studio features.
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## What the reference course covers
|
|
29
|
+
|
|
30
|
+
Freehand drawing (brush / pencil / shapes / pen), fills / strokes / gradients,
|
|
31
|
+
transform (skew / rotate / free-transform), align & distribute, **symbols +
|
|
32
|
+
Library** (convert-to-symbol, instances), **frame-by-frame** animation,
|
|
33
|
+
motion / classic / **shape tweens**, **onion skinning**, **bone rigging / IK**,
|
|
34
|
+
**lip-sync** (mouth-shape swapping), character design & turnarounds,
|
|
35
|
+
background / scene composition, a **camera**, motion blur / speed lines, and
|
|
36
|
+
publishing (video / GIF / HTML5).
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## Gap map
|
|
41
|
+
|
|
42
|
+
| Capability | tinyfly today | Verdict |
|
|
43
|
+
|---|---|---|
|
|
44
|
+
| Property tweens (move/scale/rotate/opacity/color…) | ✅ Full (tracks, easing, custom curve editor) | Core strength |
|
|
45
|
+
| Motion path, filters, clip/mask reveal, shine | ✅ | Strong |
|
|
46
|
+
| Multi-scene, transitions, sequencer | ✅ | Strong |
|
|
47
|
+
| Per-letter text, typewriter | ✅ | Strong |
|
|
48
|
+
| Audio/video elements + sync (editor & embed) | ✅ | Strong |
|
|
49
|
+
| Shape / path morph (shape tween) | ⚠️ Partial — can animate path `d`; no morph tooling | Enhance |
|
|
50
|
+
| Export | ⚠️ CSS / Lottie / GIF only | Add video / sprite |
|
|
51
|
+
| **Symbols + Library (reusable instances)** | ❌ (only flat groups) | **Do — #1** |
|
|
52
|
+
| **Camera (pan / zoom / rotate the scene)** | ❌ | **Do** |
|
|
53
|
+
| Onion skinning | ❌ | Do (small) |
|
|
54
|
+
| Drawing tools (pen / pencil, polygon / star) | ❌ (path element + editor, but no create-tool) | Partial-do |
|
|
55
|
+
| Guides / grid / rulers / object snapping | ❌ | UX polish |
|
|
56
|
+
| Bone rig / IK / armature | ❌ | Out of scope (or long-term "pivot rig") |
|
|
57
|
+
| Frame-by-frame drawing paradigm | ❌ (conflicts with the track model) | Skip |
|
|
58
|
+
| Natural-media brush studio, model-sheet tooling | ❌ | Skip |
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Phased plan (on-brand)
|
|
63
|
+
|
|
64
|
+
### Phase A — Reuse & structure (highest leverage)
|
|
65
|
+
|
|
66
|
+
1. **Symbols + Library** — a symbol is a group with its own nested timeline,
|
|
67
|
+
instanceable multiple times; edit-once-update-everywhere; fully
|
|
68
|
+
JSON-serializable. Unlocks reuse, complex compositions, and a **lightweight
|
|
69
|
+
lip-sync** (swap which symbol/instance shows per keyframe) without a bone
|
|
70
|
+
system. This is the biggest, most on-brand win.
|
|
71
|
+
- Data model: `SymbolDefinition { id, name, elements, timeline }`; instances
|
|
72
|
+
reference a symbol id + an instance transform/override.
|
|
73
|
+
- UI: a Library panel; "Convert to Symbol"; place instances; edit-in-place.
|
|
74
|
+
- Engine: instances expand to their nested timeline at play time; still JSON.
|
|
75
|
+
|
|
76
|
+
### Phase B — Cinematography & polish
|
|
77
|
+
|
|
78
|
+
2. **Camera** — a virtual camera whose pan / zoom / rotate animates the whole
|
|
79
|
+
stage. It is just an animated transform on the scene container — very
|
|
80
|
+
on-brand, big demo value.
|
|
81
|
+
3. **Onion skinning** — ghost the previous / next frames in the preview. Small,
|
|
82
|
+
high-delight.
|
|
83
|
+
4. **Guides, grid, rulers, object snapping** — editor UX the course leans on
|
|
84
|
+
constantly.
|
|
85
|
+
|
|
86
|
+
### Phase C — Authoring & output
|
|
87
|
+
|
|
88
|
+
5. **Drawing tools** — a **pen tool** (author bezier paths on canvas; reuse the
|
|
89
|
+
existing path editor), plus **polygon / star** primitives and a
|
|
90
|
+
freehand → simplified-path tool. Stops short of a full brush studio.
|
|
91
|
+
6. **Shape-tween tooling** — a proper morph between two path shapes.
|
|
92
|
+
7. **Export expansion** — **video (WebM / MP4)** and **sprite-sheet / PNG
|
|
93
|
+
sequence** (build on the existing GIF frame-capture plumbing).
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Deliberately out of scope
|
|
98
|
+
|
|
99
|
+
To protect the product's identity, we are **not** pursuing:
|
|
100
|
+
|
|
101
|
+
- Bone / IK rigging and armatures (different domain, very complex). If rigging is
|
|
102
|
+
ever wanted, do a **simplified** version: parent / pivot hierarchies on groups,
|
|
103
|
+
not full IK.
|
|
104
|
+
- Frame-by-frame drawing paradigm (conflicts with the property-track model).
|
|
105
|
+
- Natural-media brushes / paint studio.
|
|
106
|
+
- Character-design / model-sheet tooling.
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Recommended starting point
|
|
111
|
+
|
|
112
|
+
Begin with **Phase A: Symbols + Library**. It is the one item that is both a real
|
|
113
|
+
Animate gap *and* deeply on-brand (nested JSON timelines), and it retroactively
|
|
114
|
+
enables lip-sync-style workflows without a bone system. **Camera** and **onion
|
|
115
|
+
skinning** are the fast, flashy follow-ups.
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## UI / interaction plan (Animate parity, tinyfly-flavoured)
|
|
120
|
+
|
|
121
|
+
> **Note (added 2026-07-22):** this section plans the *editor UI* for each phase.
|
|
122
|
+
> Guiding rule: **Excalidraw-level simplicity** — every new surface must be
|
|
123
|
+
> loosely coupled to the engine, discoverable, and skippable. No modal-heavy,
|
|
124
|
+
> panel-explosion Animate clone. Studio-grade features live behind an optional
|
|
125
|
+
> **"Studio" mode** badge so the default editor stays approachable.
|
|
126
|
+
|
|
127
|
+
### Cross-cutting UI principles
|
|
128
|
+
|
|
129
|
+
- **One codebase, tiered UI.** Advanced tools (Library, Camera, onion skin,
|
|
130
|
+
guides, pen) surface progressively; a `Studio mode` toggle can reveal the
|
|
131
|
+
denser controls. Marketing may call the pro workflow *"tinyflash"*, but it is
|
|
132
|
+
the same app.
|
|
133
|
+
- **Reuse existing surfaces.** New capabilities extend the current header,
|
|
134
|
+
left/right collapsible panels, timeline panel, and preview overlay rather than
|
|
135
|
+
adding new windows.
|
|
136
|
+
- **Everything stays JSON + API-first.** Each UI action maps to a documented
|
|
137
|
+
store/engine call; the editor remains just one consumer.
|
|
138
|
+
|
|
139
|
+
### Phase A — Symbols + Library (UI)
|
|
140
|
+
|
|
141
|
+
- **Library panel** — a new collapsible section in the **left** sidebar (tab
|
|
142
|
+
alongside Elements/Tracks): a grid of symbol thumbnails with name, instance
|
|
143
|
+
count, and a search box. Drag a symbol onto the stage to place an instance;
|
|
144
|
+
double-click to **edit in place** (breadcrumb: `Scene ▸ SymbolName`).
|
|
145
|
+
- **Convert to Symbol** — a command on the selection (context menu + `Ctrl+K`)
|
|
146
|
+
that bundles the selected elements into a reusable symbol and replaces them
|
|
147
|
+
with an instance.
|
|
148
|
+
- **Instance properties** — the right **Property Panel** gains an "Instance"
|
|
149
|
+
section: transform overrides (x/y/scale/rotation/opacity), a **symbol swap**
|
|
150
|
+
dropdown (the lip-sync primitive), and an "Edit Symbol" button.
|
|
151
|
+
- **Nested timeline** — when editing a symbol, the bottom **Timeline** shows the
|
|
152
|
+
symbol's own tracks; a breadcrumb returns to the scene. The instance's timeline
|
|
153
|
+
in the parent scene controls *its* transform, not the symbol's internals.
|
|
154
|
+
- **Serialization** — `project.symbols: SymbolDefinition[]`; scene elements gain
|
|
155
|
+
a `symbol` type referencing `symbolId`.
|
|
156
|
+
|
|
157
|
+
### Phase B — Camera, onion skinning, guides (UI)
|
|
158
|
+
|
|
159
|
+
- **Camera** — a **Camera** toggle in the preview header adds an on-stage camera
|
|
160
|
+
frame (drag to pan, corner handles to zoom, a rotate handle). Camera state is a
|
|
161
|
+
single animated transform track (`camera.x/y/zoom/rotation`) shown as a special
|
|
162
|
+
row at the top of the timeline. A "Reset camera" and "fit" control included.
|
|
163
|
+
- **Onion skinning** — a preview-header toggle with a small popover: how many
|
|
164
|
+
before/after frames, opacity falloff, and outline-vs-ghost mode. Ghosts render
|
|
165
|
+
in the preview only.
|
|
166
|
+
- **Guides / grid / rulers / snapping** — a **View** menu (or preview-header
|
|
167
|
+
cluster): toggle grid, rulers, snapping; drag guides off the rulers; snap to
|
|
168
|
+
guides / grid / other objects with a live snap indicator.
|
|
169
|
+
|
|
170
|
+
### Phase C — Drawing, shape-tween, export (UI)
|
|
171
|
+
|
|
172
|
+
- **Pen / shape tools** — extend the left toolbar with a **Pen** (author bezier
|
|
173
|
+
paths point-by-point on the canvas, reusing the path editor), **Polygon/Star**
|
|
174
|
+
primitives (sides/points inspector), and a freehand → simplified-path tool.
|
|
175
|
+
- **Shape-tween** — select two path keyframes and "Create Shape Tween"; a small
|
|
176
|
+
morph inspector (matching hints / point count). Preview shows the interpolated
|
|
177
|
+
`d`.
|
|
178
|
+
- **Export expansion** — the existing Export dialog gains **sprite-sheet /
|
|
179
|
+
PNG-sequence** output alongside the current GIF/WebP/MP4.
|
|
180
|
+
|
|
181
|
+
### UI risks & mitigations
|
|
182
|
+
|
|
183
|
+
- **Panel overload** → keep advanced panels collapsed by default and behind
|
|
184
|
+
Studio mode; lean on the existing collapsible-sidebar system.
|
|
185
|
+
- **Edit-in-place confusion** → always show a breadcrumb and a dimmed parent
|
|
186
|
+
scene while inside a symbol.
|
|
187
|
+
- **Mobile/touch** → symbols/library are desktop-first; degrade gracefully (view
|
|
188
|
+
+ place, edit on larger screens).
|
|
189
|
+
|
|
190
|
+
See [symbols-and-library.md](symbols-and-library.md) for the detailed Phase A
|
|
191
|
+
data model and implementation plan.
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
# 3D Transforms and Rotations
|
|
2
|
+
|
|
3
|
+
Flat things (cards, images, text, shapes) can turn in 3D, move toward you and
|
|
4
|
+
be seen in perspective, the way CSS 3D transforms work, and they land on the
|
|
5
|
+
same pixels in every renderer: DOM, SVG, Canvas and WebGL. Rotations can be
|
|
6
|
+
**quaternions**, `[x, y, z, w]`, on a track that says `interpolation: "slerp"`,
|
|
7
|
+
which turn from any orientation to any other without gimbal lock. These are the
|
|
8
|
+
first steps of [3D support](3d-support-plan.md): the engine stays
|
|
9
|
+
renderer-agnostic and gains only small math helpers and one interpolation mode.
|
|
10
|
+
|
|
11
|
+
Try it on the Examples page: **Quaternion vs Euler (3D rotation)**, **3D Card
|
|
12
|
+
Flip** and **Cover Flow**.
|
|
13
|
+
|
|
14
|
+
## The 3D properties
|
|
15
|
+
|
|
16
|
+
| Property | Value | Meaning |
|
|
17
|
+
|---|---|---|
|
|
18
|
+
| `rotateX`, `rotateY` | degrees | Turn about the horizontal / vertical axis (`rotate` / `rotateZ` turns in the picture) |
|
|
19
|
+
| `z` | px | Toward the viewer; shows with perspective |
|
|
20
|
+
| `perspective` | px | The element's own `perspective()`: its distance from the viewer. Smaller is stronger; none is flat |
|
|
21
|
+
| `quaternion` | `[x, y, z, w]` | A whole rotation, on a track with `interpolation: "slerp"` (below) |
|
|
22
|
+
| `backfaceVisibility` | `"visible"` / `"hidden"` | Hidden: not drawn while its back faces you (two of them make a two-sided card) |
|
|
23
|
+
| `childPerspective`, `perspectiveOriginX`, `perspectiveOriginY` | px, % | DOM only: CSS `perspective` on a parent, so its children share one vanishing point |
|
|
24
|
+
| `transformStyle` | `"preserve-3d"` | DOM only: children keep their own depth inside the parent |
|
|
25
|
+
|
|
26
|
+
```js
|
|
27
|
+
const flip = [
|
|
28
|
+
{ id: 'p', target: 'card', property: 'perspective', keyframes: [{ time: 0, value: 600 }] },
|
|
29
|
+
{ id: 'b', target: 'card', property: 'backfaceVisibility', keyframes: [{ time: 0, value: 'hidden' }] },
|
|
30
|
+
{ id: 'r', target: 'card', property: 'rotateY', keyframes: [{ time: 0, value: 0 }, { time: 1000, value: 180, easing: 'ease-in-out' }] },
|
|
31
|
+
]
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### One transform order
|
|
35
|
+
|
|
36
|
+
Whatever order the tracks were added in, every adapter composes an element's
|
|
37
|
+
transform in the same order, about its transform origin (`originX` /
|
|
38
|
+
`originY`, the centre by default):
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
perspective → translate (x, y, z) → rotate → rotateX → rotateY → quaternion → scale → skew
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
as a CSS transform list (the right-most applies to the element first). So an
|
|
45
|
+
element is skewed and scaled in its own plane, turned, then moved, and seen in
|
|
46
|
+
perspective last. `scale` wins over `scaleX` / `scaleY` in SVG, Canvas and
|
|
47
|
+
WebGL.
|
|
48
|
+
|
|
49
|
+
### In each renderer
|
|
50
|
+
|
|
51
|
+
- **DOM and SVG:** the browser's own CSS 3D.
|
|
52
|
+
- **Canvas:** the same 4×4 matrix. Without perspective its x / y part is an
|
|
53
|
+
exact 2D transform; with perspective the target is drawn through a mesh of
|
|
54
|
+
small triangles, each a 2D transform of its own, overlapping by a pixel so no
|
|
55
|
+
seam shows. See-through targets in perspective go through one offscreen
|
|
56
|
+
layer, so the overlaps do not darken. It works in Node too (headless video).
|
|
57
|
+
- **WebGL:** the same matrix per quad, with the perspective in `w`, so textures
|
|
58
|
+
stay perspective-correct.
|
|
59
|
+
|
|
60
|
+
The cross-browser checks (`npm run e2e -- --check transforms-3d`) put one card
|
|
61
|
+
through all of them in Chromium, Firefox and WebKit: the projection maths
|
|
62
|
+
matches the browser's CSS exactly, and Canvas and WebGL land within a pixel.
|
|
63
|
+
|
|
64
|
+
### In the editor
|
|
65
|
+
|
|
66
|
+
Every element has a **3D** section under Transform: **Tilt X**, **Turn Y**,
|
|
67
|
+
**Depth** and **Perspective** at the playhead. Typing a value keys it there, so
|
|
68
|
+
a card flip is two keys on Turn Y. Every preview renderer and every export
|
|
69
|
+
(GIF, MP4, video) draws them.
|
|
70
|
+
|
|
71
|
+
## Why not just rotateX, rotateY and rotateZ?
|
|
72
|
+
|
|
73
|
+
Euler angles (`rotateX`, `rotateY`, `rotateZ`) are easy to type and still work
|
|
74
|
+
everywhere. But each angle is animated on its own, so going from one
|
|
75
|
+
orientation to another can take a strange path, tumbling about two axes, and
|
|
76
|
+
near straight up or down two of the axes line up and a turn is lost (gimbal
|
|
77
|
+
lock). A quaternion describes the whole orientation at once, and **slerp**
|
|
78
|
+
(spherical interpolation) turns from one to the other about a single axis, the
|
|
79
|
+
short way round, at a steady speed.
|
|
80
|
+
|
|
81
|
+
```js
|
|
82
|
+
import { Timeline, quat } from '@algorisys/tinyfly'
|
|
83
|
+
|
|
84
|
+
const timeline = new Timeline({
|
|
85
|
+
id: 'flip',
|
|
86
|
+
tracks: [
|
|
87
|
+
{
|
|
88
|
+
id: 'turn',
|
|
89
|
+
target: 'card',
|
|
90
|
+
property: 'quaternion',
|
|
91
|
+
interpolation: 'slerp',
|
|
92
|
+
keyframes: [
|
|
93
|
+
{ time: 0, value: quat.identity() },
|
|
94
|
+
{ time: 2000, value: quat.fromEuler(0, 180, 180), easing: 'ease-in-out' },
|
|
95
|
+
],
|
|
96
|
+
},
|
|
97
|
+
],
|
|
98
|
+
})
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Easing shapes the turn as it shapes any value; eases that overshoot (back,
|
|
102
|
+
elastic) carry on along the same arc. When a timeline is exported to a format
|
|
103
|
+
that needs baking (CSS, Lottie), the samples follow the arc too.
|
|
104
|
+
|
|
105
|
+
## Drawing it
|
|
106
|
+
|
|
107
|
+
- **DOM:** the DOM adapter draws a `quaternion` value as a CSS `matrix3d()`.
|
|
108
|
+
Give the parent `perspective` and the element `transform-style: preserve-3d`
|
|
109
|
+
as for any CSS 3D transform.
|
|
110
|
+
- **Anything else:** `mat4.fromQuat(q)` is the rotation matrix, column-major,
|
|
111
|
+
ready for WebGL, a `matrix3d()` string or your own renderer.
|
|
112
|
+
|
|
113
|
+
```js
|
|
114
|
+
const q = timeline.getStateAtTime(t).values.get('card').get('quaternion')
|
|
115
|
+
card.style.transform = `matrix3d(${mat4.fromQuat(q).join(', ')})`
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
## The math helpers
|
|
119
|
+
|
|
120
|
+
Plain arrays in, plain arrays out, no state: `vec3`, `quat` and `mat4`.
|
|
121
|
+
|
|
122
|
+
| | |
|
|
123
|
+
|---|---|
|
|
124
|
+
| Axes | right-handed, +y up, +z toward the viewer |
|
|
125
|
+
| Angles | degrees |
|
|
126
|
+
| Euler order | **YXZ** (yaw, pitch, roll): `quat.fromEuler(x, y, z)` turns as CSS `rotateY(y) rotateX(x) rotateZ(z)` |
|
|
127
|
+
| Quaternions | `[x, y, z, w]` (glTF order), unit length |
|
|
128
|
+
| Matrices | 16 numbers, column-major (WebGL, glTF, CSS `matrix3d()`); `multiply(a, b)` applies `b` first |
|
|
129
|
+
|
|
130
|
+
```js
|
|
131
|
+
import { quat, mat4, vec3 } from '@algorisys/tinyfly'
|
|
132
|
+
|
|
133
|
+
const tilt = quat.fromEuler(20, 45, 0)
|
|
134
|
+
quat.toEuler(tilt) // [20, 45, 0]
|
|
135
|
+
quat.rotateVec3(tilt, [0, 0, 1]) // where "forward" points now
|
|
136
|
+
const model = mat4.compose([0, 1, 0], tilt, [1, 1, 1])
|
|
137
|
+
const view = mat4.lookAt([0, 2, 6], [0, 1, 0])
|
|
138
|
+
const projection = mat4.perspective(50, 16 / 9, 0.1, 100)
|
|
139
|
+
mat4.transformPoint(mat4.multiply(projection, mat4.multiply(view, model)), [0, 0, 0])
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
The full list is in the [API reference](api-reference.md#3d-math).
|
|
143
|
+
|
|
144
|
+
## In the file format
|
|
145
|
+
|
|
146
|
+
A file that uses `interpolation` is written as **format version 2**, so an
|
|
147
|
+
older tinyfly refuses it with a clear message instead of blending the four
|
|
148
|
+
numbers one by one. Files without it stay at version 1 and open everywhere.
|
|
149
|
+
See [the file format](file-format.md#rotation-tracks-interpolation-slerp).
|
|
150
|
+
|
|
151
|
+
## Limits
|
|
152
|
+
|
|
153
|
+
- Elements are flat: each is turned and seen on its own (its own
|
|
154
|
+
perspective), not sorted by depth against others; they draw in layer order.
|
|
155
|
+
Real 3D scenes (cameras, lights, meshes, depth) are the next milestones.
|
|
156
|
+
- In the editor, back faces are set with a `backfaceVisibility` track (the
|
|
157
|
+
3D Card Flip sample shows how); there is no checkbox yet.
|
|
158
|
+
|
|
159
|
+
- Springs and inertia stay numeric: use them on `rotateX` and friends, not on
|
|
160
|
+
`quaternion` tracks.
|
|
161
|
+
- Use either Euler tracks or a quaternion track for one element's rotation,
|
|
162
|
+
not both.
|
|
163
|
+
- 3D scenes (cameras, lights, meshes) are the next milestones of the
|
|
164
|
+
[3D plan](3d-support-plan.md).
|