@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
package/docs/scene-3d.md
ADDED
|
@@ -0,0 +1,299 @@
|
|
|
1
|
+
# 3D Scenes
|
|
2
|
+
|
|
3
|
+
`@algorisys/tinyfly/scene-3d` draws real 3D scenes: cameras, lights and
|
|
4
|
+
meshes, in world space, seen through a perspective or orthographic camera. The
|
|
5
|
+
scene is plain JSON; its motion is ordinary timeline tracks. It draws on a 2D
|
|
6
|
+
canvas in the **stylized** look (flat, smooth or toon shading, ink outlines,
|
|
7
|
+
fog), in browsers, Web Workers and Node, so the same scene plays on a page and
|
|
8
|
+
renders to MP4 with `tinyfly video`. No WebGL, no GPU, no dependencies.
|
|
9
|
+
|
|
10
|
+
Try it on the Examples page: **3D Scene: Orbiting Camera** and **3D Scene:
|
|
11
|
+
Dancing Characters** (under **3D**).
|
|
12
|
+
The plan for what comes next (a WebGL renderer, glTF models, 3D characters,
|
|
13
|
+
the realistic look, films) is [3D support](3d-support-plan.md).
|
|
14
|
+
|
|
15
|
+
```js
|
|
16
|
+
import { Timeline } from '@algorisys/tinyfly'
|
|
17
|
+
import { loadScene3D, drawScene3D } from '@algorisys/tinyfly/scene-3d'
|
|
18
|
+
|
|
19
|
+
const scene = loadScene3D({
|
|
20
|
+
id: 'stage',
|
|
21
|
+
camera: 'cam',
|
|
22
|
+
background: '#1e293b',
|
|
23
|
+
materials: { red: { color: '#ef4444', shading: 'toon', outline: { width: 2, color: '#0f172a' } } },
|
|
24
|
+
objects: [
|
|
25
|
+
{ id: 'cam', kind: 'camera', projection: 'perspective', fov: 45, near: 0.1, far: 50, position: [0, 2, 6], lookAt: [0, 0, 0] },
|
|
26
|
+
{ id: 'sun', kind: 'light', light: 'directional', color: '#ffffff', intensity: 0.9, position: [3, 5, 4] },
|
|
27
|
+
{ id: 'box', kind: 'mesh', geometry: { type: 'box', size: [1, 1, 1] }, material: 'red' },
|
|
28
|
+
],
|
|
29
|
+
})
|
|
30
|
+
|
|
31
|
+
const timeline = new Timeline({
|
|
32
|
+
id: 'spin',
|
|
33
|
+
tracks: [{ id: 'turn', target: 'stage/box', property: 'rotateY', keyframes: [{ time: 0, value: 0 }, { time: 2000, value: 360 }] }],
|
|
34
|
+
})
|
|
35
|
+
|
|
36
|
+
// Each frame:
|
|
37
|
+
drawScene3D(ctx, scene, timeline.getStateAtTime(time).values, { width: 800, height: 450 })
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
On a page with no build step, load `tinyfly-scene-3d.iife.js` after
|
|
41
|
+
`tinyfly.iife.js`; it adds these functions to the same `tinyfly` global.
|
|
42
|
+
|
|
43
|
+
## The scene
|
|
44
|
+
|
|
45
|
+
| | |
|
|
46
|
+
|---|---|
|
|
47
|
+
| Units | metres |
|
|
48
|
+
| Axes | right-handed: +x right, +y up, +z toward the default camera (a camera looks down its own -z) |
|
|
49
|
+
| Angles | degrees; Euler `rotation` in YXZ order (yaw, pitch, roll), or a `quaternion` `[x, y, z, w]` |
|
|
50
|
+
| Order | `objects` is an array: parents before children; ties in depth are broken by array order |
|
|
51
|
+
|
|
52
|
+
**Objects** share `id`, `position`, `rotation` or `quaternion`, `scale` (one
|
|
53
|
+
number or three), `parent` (an earlier object it moves with), `visible`, and
|
|
54
|
+
`layer` (below).
|
|
55
|
+
|
|
56
|
+
| `kind` | Fields |
|
|
57
|
+
|---|---|
|
|
58
|
+
| `group` | (just a transform: move several objects together, or carry a camera) |
|
|
59
|
+
| `mesh` | `geometry`, `material` (a key of `materials`) |
|
|
60
|
+
| `camera` | `projection: 'perspective'` with `fov` (vertical, degrees), or `'orthographic'` with `height` (metres); `near`, `far`; optional `lookAt: [x, y, z]` |
|
|
61
|
+
| `light` | `light: 'ambient' \| 'directional' \| 'point' \| 'spot'`, `color`, `intensity` (1 is full light); directional and spot shine from their position toward `target` (default the origin); point and spot fade to nothing at `range`; spot's cone is `angle` (half-angle, default 30°) |
|
|
62
|
+
|
|
63
|
+
**Geometry**: `box` (`size: [w, h, d]`), `sphere` (`radius`, `segments`),
|
|
64
|
+
`cylinder` and `cone` (`radius`, `height`, `segments`), `torus` (`radius` to
|
|
65
|
+
the tube's middle, `tube`, `segments`), `plane` (a floor: `size: [w, d]`
|
|
66
|
+
facing up, `segments` per side), and `extrude`: any SVG `path` made solid,
|
|
67
|
+
`depth` metres thick and scaled to `width` metres wide (default 1), with
|
|
68
|
+
`curveSegments` points per curve (default 12). Subpaths inside others are
|
|
69
|
+
holes (an "o", a ring); outlines inside holes are solid again. The path's y
|
|
70
|
+
(down) is flipped to 3D's y (up). All centred on the origin.
|
|
71
|
+
|
|
72
|
+
```js
|
|
73
|
+
{ id: 'star', kind: 'mesh', material: 'gold',
|
|
74
|
+
geometry: { type: 'extrude', path: 'M 50 0 L 61 35 L 98 35 L 68 57 L 79 91 L 50 70 L 21 91 L 32 57 L 2 35 L 39 35 Z', depth: 0.3, width: 1.4 } }
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
**Materials**: `color`, `opacity`, `doubleSided`, and for the stylized look:
|
|
78
|
+
|
|
79
|
+
| `shading` | Looks |
|
|
80
|
+
|---|---|
|
|
81
|
+
| `unlit` | the colour as it is |
|
|
82
|
+
| `flat` | lit per face: faceted |
|
|
83
|
+
| `lambert` (default) | lit with smoothed normals: curved shapes read as round |
|
|
84
|
+
| `toon` | lit in `bands` steps (default 3) |
|
|
85
|
+
|
|
86
|
+
`outline: { width, color }` inks silhouettes, creases (edges sharper than 30°)
|
|
87
|
+
and open rims. `emissive` is light the surface gives off itself: it is added
|
|
88
|
+
after lighting, so the surface shows in the dark, in both renderers. Pair it
|
|
89
|
+
with a video's `bloom` (see [Rendering Video from Code](video-rendering.md#bloom))
|
|
90
|
+
for a neon glow: `{ color: '#000000', emissive: '#ff2bd6', shading: 'unlit' }`.
|
|
91
|
+
`roughness` and `metalness` are for the realistic look (three.js, a later
|
|
92
|
+
milestone); the stylized renderers ignore them, so one material serves both.
|
|
93
|
+
|
|
94
|
+
The scene can have `background` and `fog: { color, near, far }` (metres from
|
|
95
|
+
the camera). A scene with no lights gets a soft default (ambient plus a key
|
|
96
|
+
light from upper right).
|
|
97
|
+
|
|
98
|
+
## Animating it
|
|
99
|
+
|
|
100
|
+
Tracks address objects as **`<sceneId>/<objectId>`**, so a 3D scene's tracks
|
|
101
|
+
live in the same timeline as everything else.
|
|
102
|
+
|
|
103
|
+
| Property | On | Value |
|
|
104
|
+
|---|---|---|
|
|
105
|
+
| `x`, `y`, `z` or `position` | any object | metres |
|
|
106
|
+
| `rotateX`, `rotateY`, `rotateZ` or `quaternion` | any object | degrees (YXZ), or `[x, y, z, w]` on a track with `interpolation: "slerp"` |
|
|
107
|
+
| `scale`, `scaleX`, `scaleY`, `scaleZ` | any object | |
|
|
108
|
+
| `visible` | any object | 0 or 1 (children hide with their parent) |
|
|
109
|
+
| `opacity` | meshes | 0..1, times the material's |
|
|
110
|
+
| `color` | meshes, lights | a colour, over the material's or light's |
|
|
111
|
+
| `intensity`, `target` | lights | |
|
|
112
|
+
| `fov` / `height`, `lookAt` | cameras | |
|
|
113
|
+
| `color`, `width`, `opacity` | lines, trails | |
|
|
114
|
+
| `length` | trails | ms |
|
|
115
|
+
| `activeCamera` | the scene, target `<sceneId>` | a camera's id: **a cut is one keyframe** |
|
|
116
|
+
|
|
117
|
+
Animate either the components (`x`, `rotateY`) or the vector (`position`,
|
|
118
|
+
`quaternion`) of one object, not both: `validateScene3D(scene, tracks)` says
|
|
119
|
+
so instead of picking a winner.
|
|
120
|
+
|
|
121
|
+
**Orbiting** is a rotation, not a path: put the camera on a `group` and turn
|
|
122
|
+
the group. `orbitPosition(target, yaw, pitch, distance)` and
|
|
123
|
+
`dollyPosition(eye, target, amount)` place cameras for keyframes.
|
|
124
|
+
|
|
125
|
+
## Lines and trails
|
|
126
|
+
|
|
127
|
+
Two more kinds of object draw a band that faces the camera, as wide as
|
|
128
|
+
`width` metres (so it narrows with distance):
|
|
129
|
+
|
|
130
|
+
```js
|
|
131
|
+
// A polyline through points in its own space (it moves with its transform and parent)
|
|
132
|
+
{ id: 'ring', kind: 'line', points: [[0, 0, 0], [1, 0, 0], [1, 1, 0]], closed: true, width: 0.04, color: '#b6ff3b' }
|
|
133
|
+
// Where another object has been over the last `length` ms
|
|
134
|
+
{ id: 'tail', kind: 'trail', follow: 'comet', length: 1200, samples: 64, width: 0.1, color: '#00e5ff', blend: 'add' }
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
| Field | Meaning |
|
|
138
|
+
|---|---|
|
|
139
|
+
| `color`, `width` (default 0.05), `opacity` | |
|
|
140
|
+
| `taper`, `fade` | 0..1: how much it narrows and fades toward its start (a line's first point, a trail's tail). Trails default to 1, lines to 0 |
|
|
141
|
+
| `blend` | `normal` paints over what is behind; `add` adds its light: glowing beams, best on dark scenes and with [bloom](video-rendering.md#bloom) |
|
|
142
|
+
| `follow`, `length`, `samples` (trail) | The object it follows, how far back it reaches (ms), points along it (default 32) |
|
|
143
|
+
| `period` (trail) | For motion that repeats every `period` ms: earlier times wrap, so a loop's first frame already has the last lap's tail |
|
|
144
|
+
|
|
145
|
+
Each segment of the band is placed in the draw order by its own depth, so a
|
|
146
|
+
trail passes behind one shape and in front of another. Fog turns a normal
|
|
147
|
+
band toward the fog colour and dims an added one. The head ends round.
|
|
148
|
+
|
|
149
|
+
A trail is not a history of frames: it asks where the object was at earlier
|
|
150
|
+
times, so the same time always draws the same trail (scrubbing, seeking,
|
|
151
|
+
frames in any order, loops). The renderer needs a way to ask:
|
|
152
|
+
|
|
153
|
+
- in a video, nothing to do: the frame carries `stateAt`, and
|
|
154
|
+
`drawScene3D(ctx, scene, frame.state?.values, frame)` passes it on;
|
|
155
|
+
- elsewhere, `valuesAt`: `drawScene3D(ctx, scene, values, { width, height, time, valuesAt: (t) => timeline.getStateAtTime(t).values })`,
|
|
156
|
+
`resolveScene3D(…, { time, valuesAt })`, or `new Scene3DAdapter(renderer, { width, height, valuesAt })`.
|
|
157
|
+
|
|
158
|
+
Without it a trail draws nothing. `examples/headless-video/comet-trails.mjs`
|
|
159
|
+
is a looping comet video; the **3D Scene: Comet Trails** demo is the live
|
|
160
|
+
version. With the WebGL2 renderer, lines and trails go on the overlay, in
|
|
161
|
+
front of the meshes. For trails on a plain 2D canvas, see `drawTrail` in
|
|
162
|
+
[Rendering Video from Code](video-rendering.md#light-trails).
|
|
163
|
+
|
|
164
|
+
## Drawing
|
|
165
|
+
|
|
166
|
+
```ts
|
|
167
|
+
loadScene3D(json): LoadedScene3D // validates and builds meshes once (throws with every problem)
|
|
168
|
+
validateScene3D(json, tracks?): string[] // problems as sentences, empty when fine
|
|
169
|
+
resolveScene3D(loaded, values, { width, height, time?, valuesAt? }): ResolvedScene3D // pure: matrices, camera, lights, sorted triangles
|
|
170
|
+
drawScene3D(ctx, loaded, values, { width, height, time?, valuesAt? | stateAt? }) // resolve and draw, in one call
|
|
171
|
+
new Scene3DAdapter(new Canvas2DRenderer(ctx), { width, height, valuesAt? }) // registerScene, applyState(state), render()
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
`resolveScene3D` is the whole 3D pipeline as data: world matrices, the
|
|
175
|
+
camera's view and projection, lights in world space, and every visible
|
|
176
|
+
triangle on screen with its depth, normals and outline edges, sorted. A
|
|
177
|
+
renderer only paints it. The same values always give the same frame, and
|
|
178
|
+
frames can be drawn in any order.
|
|
179
|
+
|
|
180
|
+
**In a video**, draw the scene from the frame's timeline state:
|
|
181
|
+
|
|
182
|
+
```js
|
|
183
|
+
export default {
|
|
184
|
+
width: 1280, height: 720, duration: 9000,
|
|
185
|
+
timeline: { id: 'orbit', tracks: [ /* stage/... tracks */ ] },
|
|
186
|
+
draw(ctx, frame) {
|
|
187
|
+
drawScene3D(ctx, scene, frame.state?.values, frame)
|
|
188
|
+
},
|
|
189
|
+
}
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
`examples/headless-video/scene-3d-orbit.mjs` orbits a camera around lit
|
|
193
|
+
shapes and cuts to a wide shot; `characters-3d-dance.mjs` has two characters
|
|
194
|
+
dance while the camera cranes up, then cuts to a close shot.
|
|
195
|
+
|
|
196
|
+
Golden frames (`src/scene-3d/golden/`) pin the look: the same scenes must draw
|
|
197
|
+
exactly the same pixels on every run.
|
|
198
|
+
|
|
199
|
+
## In the editor
|
|
200
|
+
|
|
201
|
+
The editor's **🧊 3D Scene** element holds a scene like these: add shapes,
|
|
202
|
+
characters and lights, move and key them, dance characters from the playhead,
|
|
203
|
+
pick camera views and cut between cameras. Its tracks are on the element,
|
|
204
|
+
named `object.property` (`box.rotateY`); see the
|
|
205
|
+
[Editor Guide](editor-guide.md#3d-scenes).
|
|
206
|
+
|
|
207
|
+
## Characters
|
|
208
|
+
|
|
209
|
+
tinyfly's v2 characters stand in 3D scenes, seen by the scene's camera from
|
|
210
|
+
anywhere: in front, behind, from above. A character is an object like any
|
|
211
|
+
other; drawing it comes from the characters add-on, so this entry stays small:
|
|
212
|
+
|
|
213
|
+
```js
|
|
214
|
+
import { loadScene3D, drawScene3D } from '@algorisys/tinyfly/scene-3d'
|
|
215
|
+
import { characterObjects, danceFrame, stickToHuman } from '@algorisys/tinyfly/characters'
|
|
216
|
+
|
|
217
|
+
const scene = loadScene3D({
|
|
218
|
+
id: 'stage', camera: 'cam', /* … */
|
|
219
|
+
objects: [
|
|
220
|
+
/* camera, lights, a floor … */
|
|
221
|
+
{ id: 'tum', kind: 'character', position: [-0.9, 0, 0], character: { look: 'clean', skin: '#f2c49b', hands: 'cartoon' } },
|
|
222
|
+
{ id: 'didi', kind: 'character', look: 'solid', position: [0.9, 0, 0], solid: { color: '#7c3aed' } },
|
|
223
|
+
],
|
|
224
|
+
}, { kinds: [characterObjects] })
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
| Field | |
|
|
228
|
+
|---|---|
|
|
229
|
+
| `character` | `character()` options: `figure`, `look` (`clean`, `pencil`, `silhouette`), `ink`, `skin`, `hands`, `handStyle`, … |
|
|
230
|
+
| `height` | metres (default 1.7) |
|
|
231
|
+
| `pose` | its pose: character pose fields (`arm.right.spread`, `turn`, `lean`, …) |
|
|
232
|
+
| `look` | `pen` (default): drawn by its pens, in perspective, with its face and hands. `solid`: shaded capsules along its bones, an ellipsoid head with eyes, lit, outlined and depth-sorted like the scene's meshes |
|
|
233
|
+
| `solid` | the solid look's `color`, `skin`, `shading` (default toon) and `outline` (or `false`) |
|
|
234
|
+
| `shadow` | a soft shadow on the ground under it (default true) |
|
|
235
|
+
|
|
236
|
+
A character faces +z before any turn and stands on its object's ground: its
|
|
237
|
+
lowest point at the object's y, so at y 0 it stands on a floor at y 0. Its
|
|
238
|
+
pose fields are tracks on its object, next to `x`, `rotateY` and the rest:
|
|
239
|
+
`stage/tum` `arm.right.spread`, `stage/tum` `turn`. Every dance and flip
|
|
240
|
+
plays in 3D: `stickToHuman(danceFrame(style, beat))` gives the pose, and
|
|
241
|
+
`mirrorHumanPose()` its mirror image for a partner. Its `turn`, `roll`,
|
|
242
|
+
`lift` and ground contact behave as they do front-on; seen front-on through a
|
|
243
|
+
flat camera, a character is exactly the 2D figure.
|
|
244
|
+
|
|
245
|
+
Outside scenes, `drawCharacterInView(ctx, character, pose, projection, { height })`
|
|
246
|
+
draws a character through any camera (`projection.toView` / `toScreen`), and
|
|
247
|
+
`skeletonInView` / `stagePlanSpace` give its joints.
|
|
248
|
+
|
|
249
|
+
**Other object kinds** come the same way: an `ObjectKind` validates its
|
|
250
|
+
objects, prepares them once, and each frame returns meshes (shaded and sorted
|
|
251
|
+
with the scene's) and drawables (drawn whole at their depth). Pass it in
|
|
252
|
+
`loadScene3D(scene, { kinds })`.
|
|
253
|
+
|
|
254
|
+
## The WebGL2 renderer
|
|
255
|
+
|
|
256
|
+
`@algorisys/tinyfly/scene-3d/webgl` (`tinyfly-scene-3d-webgl.iife.js` for
|
|
257
|
+
script tags) draws the same resolved frame with WebGL2:
|
|
258
|
+
|
|
259
|
+
```js
|
|
260
|
+
import { loadScene3D, resolveScene3D } from '@algorisys/tinyfly/scene-3d'
|
|
261
|
+
import { WebGL2Renderer } from '@algorisys/tinyfly/scene-3d/webgl'
|
|
262
|
+
|
|
263
|
+
const renderer = new WebGL2Renderer(canvas.getContext('webgl2'), { overlay })
|
|
264
|
+
renderer.render(resolveScene3D(scene, values, { width: canvas.width, height: canvas.height }))
|
|
265
|
+
// or drive it from a timeline: new Scene3DAdapter(renderer, { width, height })
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
- **A depth buffer**: shapes that cut through each other, huge floors and
|
|
269
|
+
long meshes draw right, with no `layer` needed.
|
|
270
|
+
- **Light per pixel**: smooth shading is smooth, toon bands and spot pools
|
|
271
|
+
have clean edges, fog fades per pixel. The same light model as the Canvas
|
|
272
|
+
2D renderer (up to 8 lights).
|
|
273
|
+
- **Outlines** by the inverted hull: silhouettes in the ink colour and
|
|
274
|
+
width. (Creases inside a silhouette are inked only by the Canvas 2D
|
|
275
|
+
renderer.)
|
|
276
|
+
- **See-through meshes** are drawn after the opaque ones, far to near.
|
|
277
|
+
- Objects drawn whole, such as characters in their pen look, lines and
|
|
278
|
+
trails, go on `overlay`, a 2D canvas laid over the GL one (in front of the meshes);
|
|
279
|
+
solid characters are meshes and sort properly.
|
|
280
|
+
|
|
281
|
+
It runs on a page or in a Worker (OffscreenCanvas). Node has no WebGL2, so
|
|
282
|
+
headless video uses the Canvas 2D renderer. The cross-browser checks
|
|
283
|
+
(`npm run e2e -- --check scene-3d-webgl`) compile it in Chromium, Firefox and
|
|
284
|
+
WebKit, compare its silhouettes with the Canvas 2D renderer's and check the
|
|
285
|
+
depth buffer.
|
|
286
|
+
|
|
287
|
+
## Draw order and its limits
|
|
288
|
+
|
|
289
|
+
The Canvas 2D renderer paints back to front (painter's algorithm), culling
|
|
290
|
+
back faces and clipping at the camera's near plane. Within a `layer`
|
|
291
|
+
(default 0) triangles sort far to near; lower layers draw first, so a floor at
|
|
292
|
+
`layer: -1` never covers what stands on it. Triangles that cross each other,
|
|
293
|
+
or very long ones, can sort wrongly: give big planes `segments`, keep meshes
|
|
294
|
+
modest, or use a layer. Each triangle has one colour, so smooth shading is
|
|
295
|
+
smoothed per triangle, not per pixel; more segments look rounder. The WebGL2
|
|
296
|
+
renderer (above) has a depth buffer and per-pixel light.
|
|
297
|
+
|
|
298
|
+
Rendering speed in Node: a 1280×720 scene of a few thousand triangles renders
|
|
299
|
+
at a few frames a second; parallel rendering for long films is planned.
|
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
# Scroll-driven animation
|
|
2
|
+
|
|
3
|
+
Scroll animation in tinyfly is a **driver**, not a special kind of timeline.
|
|
4
|
+
|
|
5
|
+
The engine is a pure function of time: give it a time, it gives you values. A
|
|
6
|
+
driver is the boundary where something real-world — a clock, a scroll position,
|
|
7
|
+
a drag — becomes a time. `ScrollDriver` does nothing but call `seek()` on an
|
|
8
|
+
ordinary timeline, which means every animation you already have can be
|
|
9
|
+
scroll-driven without changing it, and a scroll animation still exports to the
|
|
10
|
+
same JSON.
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
import { VisibilityDriver, ScrollDriver } from '@algorisys/tinyfly/drivers'
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Which driver do you want?
|
|
17
|
+
|
|
18
|
+
**"Play it when it comes into view"** → `VisibilityDriver`. This is the common
|
|
19
|
+
case and it is much simpler — no geometry, no scrub maths, just
|
|
20
|
+
IntersectionObserver.
|
|
21
|
+
|
|
22
|
+
**"Tie it to how far I've scrolled"** → `ScrollDriver`.
|
|
23
|
+
|
|
24
|
+
Each has a one-call form that creates the driver and starts it:
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
import { playWhenVisible, scrubOnScroll } from '@algorisys/tinyfly/drivers'
|
|
28
|
+
|
|
29
|
+
const visible = playWhenVisible({ timeline, trigger: section }) // a started VisibilityDriver
|
|
30
|
+
const scrub = scrubOnScroll({ timeline, trigger: panel, scrub: true }) // a started ScrollDriver
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
**Drivers move the playhead; they do not render.** `VisibilityDriver` calls
|
|
34
|
+
`timeline.play()`, so something must still tick the timeline and apply its state
|
|
35
|
+
(a `Clock` or your own rAF loop).
|
|
36
|
+
`ScrollDriver` calls `timeline.seek()`, so apply the state in `onUpdate`:
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
new ScrollDriver({
|
|
40
|
+
timeline,
|
|
41
|
+
trigger: panel,
|
|
42
|
+
scrub: true,
|
|
43
|
+
onUpdate: () => adapter.applyState(timeline.getStateAtTime(timeline.currentTime)),
|
|
44
|
+
}).start()
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## VisibilityDriver
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
import { VisibilityDriver } from '@algorisys/tinyfly/drivers'
|
|
51
|
+
|
|
52
|
+
const driver = new VisibilityDriver({
|
|
53
|
+
timeline,
|
|
54
|
+
trigger: document.querySelector('#section')!,
|
|
55
|
+
behaviour: 'once', // 'once' | 'repeat' | 'reset'
|
|
56
|
+
threshold: 0.25, // fraction visible before it counts
|
|
57
|
+
})
|
|
58
|
+
driver.start()
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
| `behaviour` | What happens |
|
|
62
|
+
|---|---|
|
|
63
|
+
| `once` (default) | Plays the first time it appears, never again |
|
|
64
|
+
| `repeat` | Rewinds and plays on every appearance |
|
|
65
|
+
| `reset` | Plays on appear, rewinds when it leaves |
|
|
66
|
+
|
|
67
|
+
Options: `rootMargin` and `root` pass through to IntersectionObserver;
|
|
68
|
+
`onEnter` / `onLeave` fire on every crossing regardless of behaviour.
|
|
69
|
+
|
|
70
|
+
Where `IntersectionObserver` does not exist (SSR, a worker, an old browser) the
|
|
71
|
+
driver plays immediately — better to show the animation than to leave it stuck
|
|
72
|
+
on frame 0 forever.
|
|
73
|
+
|
|
74
|
+
Call `driver.reset()` to let a `once` driver fire again.
|
|
75
|
+
|
|
76
|
+
## ScrollDriver
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
import { ScrollDriver } from '@algorisys/tinyfly/drivers'
|
|
80
|
+
|
|
81
|
+
const driver = new ScrollDriver({
|
|
82
|
+
timeline,
|
|
83
|
+
trigger: document.querySelector('#panel')!,
|
|
84
|
+
start: 'top bottom', // when the panel's top hits the viewport's bottom
|
|
85
|
+
end: 'bottom top', // when the panel's bottom hits the viewport's top
|
|
86
|
+
scrub: true,
|
|
87
|
+
})
|
|
88
|
+
driver.start()
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
The driver pauses the timeline when it starts — scroll position is now the only
|
|
92
|
+
thing advancing it.
|
|
93
|
+
|
|
94
|
+
### Trigger positions
|
|
95
|
+
|
|
96
|
+
A position is `"<element edge> <viewport edge>"`:
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
'top bottom' the element's top reaching the viewport's bottom
|
|
100
|
+
'center center' the element's middle at the viewport's middle
|
|
101
|
+
'bottom top' the element's bottom reaching the viewport's top
|
|
102
|
+
'25% 75%' percentages work for either edge
|
|
103
|
+
'top top+=400' 400px past that point
|
|
104
|
+
'top bottom-=100' 100px before it
|
|
105
|
+
300 a bare number: 300px down from the element's top
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Keywords: `top`/`left`/`start` (0), `center`/`centre`/`middle` (0.5),
|
|
109
|
+
`bottom`/`right`/`end` (1). A single token is read as the element edge with the
|
|
110
|
+
viewport edge defaulting to `top`.
|
|
111
|
+
|
|
112
|
+
A common fixed-length scrub — `end` starting with `+=` is measured from the start:
|
|
113
|
+
|
|
114
|
+
```ts
|
|
115
|
+
{ start: 'top top', end: '+=500' } // 500px of scrolling, exactly
|
|
116
|
+
{ start: 'top top', end: '+=150%' } // one and a half viewport heights
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### Scrub modes
|
|
120
|
+
|
|
121
|
+
```ts
|
|
122
|
+
scrub: true // playhead tracks scroll exactly — snappy, frame-accurate
|
|
123
|
+
scrub: 0.5 // playhead eases toward the scroll position over ~0.5s
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Smoothing feels nicer but makes the displayed time frame-rate dependent, since
|
|
127
|
+
it advances by elapsed time. `scrub: true` is the exact path; use it when the
|
|
128
|
+
animation needs to land on specific frames.
|
|
129
|
+
|
|
130
|
+
### Callbacks
|
|
131
|
+
|
|
132
|
+
`onUpdate(progress, velocity)` fires whenever progress or scroll speed changes.
|
|
133
|
+
`velocity` is in px/s, positive scrolling down, and returns to 0 (with one more
|
|
134
|
+
call) about 120 ms after scrolling stops — enough for skew-on-scroll effects.
|
|
135
|
+
`onEnter` / `onLeave` / `onEnterBack` / `onLeaveBack` fire at the edges of the
|
|
136
|
+
active range, with `Back` meaning you were scrolling up. A scroll that jumps
|
|
137
|
+
across the whole range in one step (a fast flick, or loading the page already
|
|
138
|
+
past it) fires both edges, in order.
|
|
139
|
+
|
|
140
|
+
Without a `timeline`, the driver only reports progress and fires callbacks.
|
|
141
|
+
|
|
142
|
+
### Nested scrollers
|
|
143
|
+
|
|
144
|
+
```ts
|
|
145
|
+
new ScrollDriver({ timeline, trigger, scroller: document.querySelector('#pane')! })
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Positions are then measured against that element's box instead of the viewport.
|
|
149
|
+
|
|
150
|
+
### Performance, and re-measuring
|
|
151
|
+
|
|
152
|
+
**Scrolling does no layout work.** The driver measures the trigger when it
|
|
153
|
+
starts and on window resize, turning `start` and `end` into absolute scroll
|
|
154
|
+
offsets. A scroll event then reads only the scroll offset. With `scrub: <seconds>`
|
|
155
|
+
its frame loop runs only until the playhead catches up, then stops.
|
|
156
|
+
|
|
157
|
+
So if layout changes without a resize — images or web fonts loading, content
|
|
158
|
+
inserted above the trigger — call `driver.refresh()` (or
|
|
159
|
+
`ScrollDriver.refreshAll()` for every driver, in the order they started).
|
|
160
|
+
`driver.progress` is the current progress, 0..1; `driver.velocity` the scroll
|
|
161
|
+
speed.
|
|
162
|
+
|
|
163
|
+
On touch devices, resizes that only change the height by less than a quarter
|
|
164
|
+
(the address bar showing and hiding) are skipped, so pins do not jump mid-scroll.
|
|
165
|
+
`start` and `end` may be functions, called again on every refresh, and
|
|
166
|
+
`onRefresh` runs before each re-measure (after the first), which is where
|
|
167
|
+
`invalidateOnRefresh` rebuilds an animation.
|
|
168
|
+
|
|
169
|
+
### Snap, markers and horizontal containers
|
|
170
|
+
|
|
171
|
+
- **`snap`** takes a progress step, a list of points, a function, or
|
|
172
|
+
`{ snapTo, duration, delay, ease }`. It scrolls to the nearest point once
|
|
173
|
+
scrolling stops inside the range, allowing for the speed scrolling had, and
|
|
174
|
+
stops at once if the person scrolls, touches, clicks or types.
|
|
175
|
+
`snapProgress(progress, velocity, snapTo)` is the pure choice.
|
|
176
|
+
- **`markers: true`** draws the start and end lines while developing.
|
|
177
|
+
- **`container: { range(), progress(), shiftAt(progress) }`** puts a trigger
|
|
178
|
+
inside something that moves sideways as the page scrolls. `containerProgressAt()`
|
|
179
|
+
is the pure solver, and `live` builds `container` for you from
|
|
180
|
+
`containerAnimation`.
|
|
181
|
+
|
|
182
|
+
### Smooth scrolling
|
|
183
|
+
|
|
184
|
+
`SmoothScroll` (and `live.smoothScroll()`) eases wheel scrolling on the page's
|
|
185
|
+
real scroll position, so drivers follow it with no setup, and adds `data-speed` /
|
|
186
|
+
`data-lag` parallax layers. It rests those layers while drivers measure and
|
|
187
|
+
measures them again after pins apply (`ScrollDriver.onRefresh`). See
|
|
188
|
+
[Smooth scrolling](./gsap-compat.md#smooth-scrolling).
|
|
189
|
+
|
|
190
|
+
```ts
|
|
191
|
+
const smoother = new SmoothScroll({ smooth: 0.8, effects: true }).start()
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
### Smooth-scroll libraries
|
|
195
|
+
|
|
196
|
+
Libraries that keep native scrolling (Lenis, and Locomotive Scroll v5 built on
|
|
197
|
+
it) fire ordinary `scroll` events, so drivers follow them with no setup. For a
|
|
198
|
+
scroller that moves content with transforms instead, push its position:
|
|
199
|
+
|
|
200
|
+
```ts
|
|
201
|
+
virtualScroller.on('scroll', ({ scroll }) => driver.update(scroll))
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
## Pinning
|
|
205
|
+
|
|
206
|
+
`pin: true` holds the trigger in place for the length of the range; pass an
|
|
207
|
+
element to pin something else:
|
|
208
|
+
|
|
209
|
+
```ts
|
|
210
|
+
new ScrollDriver({
|
|
211
|
+
timeline,
|
|
212
|
+
trigger: document.querySelector('.panels')!,
|
|
213
|
+
start: 'top top',
|
|
214
|
+
end: '+=2000', // stays pinned for 2000px of scrolling
|
|
215
|
+
scrub: true,
|
|
216
|
+
pin: true,
|
|
217
|
+
}).start()
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
It is the CSS sticky recipe below, automated. The element is wrapped in a
|
|
221
|
+
`div.pin-spacer` as tall as the element plus the pinned distance, and made
|
|
222
|
+
`position: sticky` at the offset where the range starts, so content after it is
|
|
223
|
+
pushed down by that distance and the browser does the holding. Nothing is
|
|
224
|
+
written while scrolling. `destroy()` removes the spacer and restores the
|
|
225
|
+
element's styles.
|
|
226
|
+
|
|
227
|
+
Two things to know:
|
|
228
|
+
|
|
229
|
+
- Sticky positioning stops working if an ancestor between the element and the
|
|
230
|
+
scroller has `overflow: hidden` or `auto`.
|
|
231
|
+
- Create pinned drivers top to bottom. A pin pushes the content below it down,
|
|
232
|
+
and resize refreshes run in start order so later drivers measure after it.
|
|
233
|
+
|
|
234
|
+
### Doing it by hand
|
|
235
|
+
|
|
236
|
+
The same effect in plain CSS, if you prefer to own the layout:
|
|
237
|
+
|
|
238
|
+
```html
|
|
239
|
+
<div class="pin-container">
|
|
240
|
+
<div class="pin-target">…animated content…</div>
|
|
241
|
+
</div>
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
```css
|
|
245
|
+
.pin-container { height: 300vh; } /* how long the pin lasts */
|
|
246
|
+
.pin-target { position: sticky; top: 0; height: 100vh; }
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
Then drive the animation off the container:
|
|
250
|
+
|
|
251
|
+
```ts
|
|
252
|
+
new ScrollDriver({
|
|
253
|
+
timeline,
|
|
254
|
+
trigger: document.querySelector('.pin-container')!,
|
|
255
|
+
start: 'top top',
|
|
256
|
+
end: 'bottom bottom',
|
|
257
|
+
scrub: true,
|
|
258
|
+
})
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
The element sticks for the container's height while the timeline scrubs across
|
|
262
|
+
it.
|
|
263
|
+
|
|
264
|
+
## With the GSAP-style API
|
|
265
|
+
|
|
266
|
+
`live` accepts GSAP's `scrollTrigger` vars on a timeline or a single tween, built
|
|
267
|
+
on the same driver — see [gsap-compat.md](gsap-compat.md#scroll-triggers).
|
|
268
|
+
|
|
269
|
+
## Authoring in the editor
|
|
270
|
+
|
|
271
|
+
Click **⇅ Scroll** in the preview header to switch the preview into scroll-scrub
|
|
272
|
+
mode. A scrollable strip appears with a trigger element inside it; scroll the
|
|
273
|
+
strip and the animation scrubs.
|
|
274
|
+
|
|
275
|
+
This is not a simulation. The preview attaches a real `ScrollDriver` to a real
|
|
276
|
+
scroll container, so a start/end pair tuned here behaves identically on your
|
|
277
|
+
page. The panel shows the exact snippet to reproduce what you are looking at:
|
|
278
|
+
|
|
279
|
+
- **Start** / **End** — the trigger positions, from the same grammar above
|
|
280
|
+
- **Scrub** — `exact`, or a smoothing time
|
|
281
|
+
- **Runway** — how much space sits above and below the trigger
|
|
282
|
+
- A live progress percentage, and the code to paste
|
|
283
|
+
|
|
284
|
+
Normal playback is paused while the mode is on, because scroll position is the
|
|
285
|
+
only thing that should be moving the playhead — the same as in production.
|
|
286
|
+
|
|
287
|
+
## Determinism
|
|
288
|
+
|
|
289
|
+
A driver is not a hole in the determinism guarantee. The engine is deterministic
|
|
290
|
+
*given a time*; it was never deterministic given a wall clock, and the existing
|
|
291
|
+
rAF `Clock` already reads real time. A scroll driver is the same kind of
|
|
292
|
+
boundary — and `scrollProgress()` itself is a pure function of geometry, unit
|
|
293
|
+
tested without a browser.
|
|
294
|
+
|
|
295
|
+
The geometry helpers are exported for the same reason: `parseTrigger(position)`,
|
|
296
|
+
`triggerDistance(rect, viewportHeight, position)` (px until a trigger fires,
|
|
297
|
+
positive while it is still ahead), `scrollProgress(rect, viewportHeight, start,
|
|
298
|
+
end)`, and `smoothToward(current, target, smoothingSeconds, deltaMs)` (the
|
|
299
|
+
smoothing behind `scrub: <seconds>`). See the
|
|
300
|
+
[API reference](./api-reference.md#drivers).
|
|
301
|
+
|
|
302
|
+
## Cleaning up
|
|
303
|
+
|
|
304
|
+
```ts
|
|
305
|
+
driver.stop() // remove listeners, keep the driver usable
|
|
306
|
+
driver.destroy() // stop and release everything
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
Both are safe to call twice.
|
|
310
|
+
|
|
311
|
+
## See also
|
|
312
|
+
|
|
313
|
+
- [`docs/gsap-compat.md`](./gsap-compat.md) — how this compares to ScrollTrigger
|
|
314
|
+
- [`docs/api-reference.md`](./api-reference.md) — the underlying timeline API
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Shape morphing (shape tween)
|
|
2
|
+
|
|
3
|
+
Animate one path into another — a hexagon into a star, a blob into a circle — by
|
|
4
|
+
tweening the path's `d` over the timeline.
|
|
5
|
+
|
|
6
|
+
## Using it
|
|
7
|
+
|
|
8
|
+
1. Select a path (a ⬡ Polygon / ★ Star, or any path).
|
|
9
|
+
2. In **Properties → 🌀 Shape Morph**, pick the **target** shape (Polygon or Star)
|
|
10
|
+
and its points / inner %.
|
|
11
|
+
3. Click **Create shape morph →**. A `d` track is added that tweens from the
|
|
12
|
+
current shape to the target across the timeline.
|
|
13
|
+
4. Press **Play** to watch it morph. The `d` track appears in the timeline like
|
|
14
|
+
any other; edit or delete it there.
|
|
15
|
+
|
|
16
|
+
## How it works
|
|
17
|
+
|
|
18
|
+
The engine interpolates path `d` strings natively. `getInterpolator` detects path
|
|
19
|
+
data (a string starting with a moveto) and routes it to a **path morph**:
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
// src/engine/path/path-morph.ts
|
|
23
|
+
morphPath(fromD, toD, progress, { shapeIndex? })
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Both paths are resampled into matching point lists, which are blended by
|
|
27
|
+
`progress`. The matching is worked out once per pair of shapes and cached:
|
|
28
|
+
|
|
29
|
+
- **Subpaths are paired** when both paths have the same number, so holes morph
|
|
30
|
+
into holes.
|
|
31
|
+
- **The start point and winding are chosen** so points travel least (about each
|
|
32
|
+
shape's centre) — nothing twists or turns inside out. Pass `shapeIndex` to
|
|
33
|
+
force a particular alignment.
|
|
34
|
+
- **Corners are kept**: samples are spaced by length and always include every
|
|
35
|
+
corner of both shapes.
|
|
36
|
+
- Open paths stay open; at progress 0 and 1 the original strings come back
|
|
37
|
+
exactly.
|
|
38
|
+
|
|
39
|
+
It is deterministic and needs no DOM (it runs in the engine, workers, and tests).
|
|
40
|
+
From code, use `morphSVG` in `live` or `tf` — see
|
|
41
|
+
[gsap-compat.md](gsap-compat.md#shape-morphing).
|
|
42
|
+
|
|
43
|
+
## Where it renders
|
|
44
|
+
|
|
45
|
+
Because morphing is engine-level, it works everywhere a `d` value can be applied:
|
|
46
|
+
|
|
47
|
+
- **DOM preview** — the path binds its `d` to the animated value.
|
|
48
|
+
- **SVG preview** — the SVG adapter sets the `d` attribute.
|
|
49
|
+
- **Canvas preview & raster export** — the Canvas adapter rebuilds a `Path2D`
|
|
50
|
+
from the animated `d` each frame.
|
|
51
|
+
- **Embeds / player** — the DOM adapter drives the child `<path>`'s `d`.
|
|
52
|
+
|
|
53
|
+
## Limitations / later
|
|
54
|
+
|
|
55
|
+
- Mid-morph shapes are drawn as dense polylines (about one point per 2.5px of
|
|
56
|
+
length, plus every corner), so curves are faithful at normal sizes; very large
|
|
57
|
+
curved shapes can show faint facets mid-tween.
|
|
58
|
+
- Fill/stroke morph independently via their own tracks; only geometry is tweened
|
|
59
|
+
by the `d` track.
|
|
60
|
+
- In the editor, authoring targets are polygon/star today. From code, `morphSVG`
|
|
61
|
+
morphs between any paths or basic shapes.
|