@algorisys/tinyfly 0.101.0 → 0.103.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 (59) hide show
  1. package/README.md +17 -6
  2. package/bin/tinyfly.mjs +9 -3
  3. package/docs/DEPLOYMENT.md +2 -0
  4. package/docs/api-reference.md +61 -0
  5. package/docs/dance.md +150 -1
  6. package/docs/editor-guide.md +11 -4
  7. package/docs/examples.md +22 -1
  8. package/docs/getting-started.md +1 -1
  9. package/docs/gsap-compat.md +1 -1
  10. package/docs/llm-guide.md +38 -3
  11. package/docs/maps.md +2 -2
  12. package/docs/scene-3d.md +138 -6
  13. package/docs/teaching.md +1 -1
  14. package/docs/video-rendering.md +44 -1
  15. package/lib/addons/adapters.js +168 -123
  16. package/lib/addons/characters.js +5802 -5506
  17. package/lib/addons/scene-3d-webgl.js +30 -30
  18. package/lib/addons/scene-3d.js +650 -341
  19. package/lib/browser/tinyfly-scene-3d-webgl.iife.js +2 -2
  20. package/lib/browser/tinyfly-scene-3d.iife.js +2 -2
  21. package/lib/browser/tinyfly.iife.js +14 -14
  22. package/lib/browser/tinyfly.js +5798 -5467
  23. package/lib/browser/tinyfly.umd.js +14 -14
  24. package/lib/engine/tinyfly-engine.js +1207 -1172
  25. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  26. package/lib/headless/headless.js +150 -6
  27. package/lib/types/adapters/canvas/framing.d.ts +27 -0
  28. package/lib/types/adapters/canvas/index.d.ts +1 -0
  29. package/lib/types/characters/capabilities.d.ts +1 -0
  30. package/lib/types/characters/character-script-3d.d.ts +34 -4
  31. package/lib/types/characters/dance-circle.d.ts +59 -0
  32. package/lib/types/characters/dance-contact.d.ts +52 -0
  33. package/lib/types/characters/human-dance.d.ts +86 -0
  34. package/lib/types/characters/index.d.ts +5 -1
  35. package/lib/types/characters/rig/reach.d.ts +6 -3
  36. package/lib/types/characters/staging-3d.d.ts +56 -0
  37. package/lib/types/engine/authoring/framing.d.ts +48 -0
  38. package/lib/types/engine/authoring/index.d.ts +1 -0
  39. package/lib/types/headless/audio-mix.d.ts +40 -0
  40. package/lib/types/headless/ffmpeg-args.d.ts +2 -0
  41. package/lib/types/headless/frame-renderer.d.ts +7 -1
  42. package/lib/types/headless/index.d.ts +1 -0
  43. package/lib/types/headless/node-audio.d.ts +19 -0
  44. package/lib/types/headless/node-video.d.ts +2 -0
  45. package/lib/types/headless/video-scene.d.ts +12 -0
  46. package/lib/types/scene-3d/index.d.ts +3 -0
  47. package/lib/types/scene-3d/lighting.d.ts +58 -0
  48. package/lib/types/scene-3d/resolve-scene.d.ts +5 -1
  49. package/lib/types/scene-3d/scene-3d-adapter.d.ts +2 -0
  50. package/lib/types/scene-3d/scene-types.d.ts +14 -2
  51. package/lib/types/scene-3d/shots.d.ts +162 -0
  52. package/lib/types/scene-3d/software-renderer.d.ts +40 -0
  53. package/llms-full.txt +474 -23
  54. package/llms.txt +29 -29
  55. package/package.json +1 -1
  56. package/skills/tinyfly/SKILL.md +32 -1
  57. package/lib/types/characters/polyline.d.ts +0 -12
  58. package/lib/types/characters/sketch.d.ts +0 -54
  59. package/lib/types/compat/gsap/playhead-crossings.d.ts +0 -47
@@ -49,6 +49,8 @@ export declare function drawScene3D(ctx: CanvasRenderingContext2D, scene: Loaded
49
49
  time?: number;
50
50
  /** A looping video's period (a frame's `period`): trails wrap at it */
51
51
  period?: number;
52
+ /** Draw through a software depth buffer (shapes that cut through each other draw right; hard edges) instead of back to front */
53
+ depthBuffer?: boolean;
52
54
  valuesAt?: (time: number) => SceneValues;
53
55
  stateAt?: (time: number) => {
54
56
  values: SceneValues;
@@ -19,8 +19,10 @@ export interface Scene3D {
19
19
  /** In order: parents before children; array order breaks depth ties */
20
20
  objects: Object3D[];
21
21
  materials?: Record<string, Material3D>;
22
- /** Background colour, or 'transparent' (default) */
23
- background?: string;
22
+ /** Background colour, or 'transparent' (default), or a sky: a vertical gradient from `top` to `bottom` */
23
+ background?: string | SkyGradient;
24
+ /** The ground's height, metres, where blob shadows lie (default 0) */
25
+ ground?: number;
24
26
  /** Fog from `near` to `far` metres from the camera, toward `color` (outlines fade with it too) */
25
27
  fog?: {
26
28
  color: string;
@@ -67,6 +69,16 @@ export interface MeshObject extends ObjectBase {
67
69
  geometry: Geometry3D;
68
70
  /** A key of `materials` */
69
71
  material: string;
72
+ /** A soft blob shadow on the ground under it (default none): `true`, or its opacity and a ground height of its own */
73
+ shadow?: boolean | {
74
+ opacity?: number;
75
+ ground?: number;
76
+ };
77
+ }
78
+ /** A sky as a vertical gradient: `top` at the top of the frame to `bottom` at the bottom. */
79
+ export interface SkyGradient {
80
+ top: string;
81
+ bottom: string;
70
82
  }
71
83
  interface CameraBase extends ObjectBase {
72
84
  kind: 'camera';
@@ -0,0 +1,162 @@
1
+ import type { Track } from '../engine/types';
2
+ import type { EasingType } from '../engine/types';
3
+ import type { SceneValues } from './resolve-scene';
4
+ /**
5
+ * Shots and cameras for a film made from a 3D scene: a shot list as data,
6
+ * cuts and transitions that any frame can be asked about, camera moves as
7
+ * presets that write ordinary tracks, and a seeded handheld shake. Nothing
8
+ * here renders: the tracks join the timeline, and `transitionAt` tells a
9
+ * frame which two cameras to draw and how to blend them.
10
+ *
11
+ * const shots: Shot[] = [
12
+ * { id: 'wide', start: 0, end: 4000, camera: 'wide' },
13
+ * { id: 'close', start: 4000, end: 7000, camera: 'close', transition: { kind: 'crossfade', duration: 600 } },
14
+ * ]
15
+ * const tracks = [...shotTracks(shots, 'stage'), ...cameraMoveTracks({ scene: 'stage', camera: 'wide', start: 0, end: 4000,
16
+ * from: { target: [0, 1, 0], yaw: 20, pitch: 15, distance: 9 }, to: { yaw: 60, distance: 6 } })]
17
+ */
18
+ export type Vec3 = [number, number, number];
19
+ export interface ShotTransition {
20
+ /** How the shot comes in: a hard cut (the default), a crossfade from the shot before, a dip to black, or a wipe */
21
+ kind: 'cut' | 'crossfade' | 'dipToBlack' | 'wipe';
22
+ /** ms, from the shot's start */
23
+ duration: number;
24
+ /** A wipe's direction (default `left`: the new shot sweeps in from the left) */
25
+ direction?: 'left' | 'right' | 'up' | 'down';
26
+ /** A dip's colour (default black) */
27
+ color?: string;
28
+ }
29
+ export interface Shot {
30
+ id: string;
31
+ /** ms */
32
+ start: number;
33
+ end: number;
34
+ /** The camera's object id */
35
+ camera: string;
36
+ /** A caption for the storyboard and the stills */
37
+ label?: string;
38
+ transition?: ShotTransition;
39
+ }
40
+ /** The shot playing at a time (the last one that has started), or undefined before the first. */
41
+ export declare function shotAt(shots: ReadonlyArray<Shot>, time: number): Shot | undefined;
42
+ /** Problems with a shot list, as sentences; empty when fine. */
43
+ export declare function checkShots(shots: ReadonlyArray<Shot>): string[];
44
+ /**
45
+ * The cut track: `activeCamera` on the scene, one keyframe per shot (a cut
46
+ * is one keyframe; a transition still cuts at the shot's start and blends
47
+ * the shot before over it, see `transitionAt`).
48
+ */
49
+ export declare function shotTracks(shots: ReadonlyArray<Shot>, sceneId: string): Track[];
50
+ /** One marker per shot, for the timeline's `config.markers` (stills and captions step through them). */
51
+ export declare function shotMarkers(shots: ReadonlyArray<Shot>): Array<{
52
+ id: string;
53
+ time: number;
54
+ label: string;
55
+ }>;
56
+ export interface ActiveTransition {
57
+ kind: ShotTransition['kind'];
58
+ /** 0 at the shot's start to 1 when the transition is over */
59
+ progress: number;
60
+ /** The shot going out and the shot coming in */
61
+ from: Shot;
62
+ to: Shot;
63
+ direction: NonNullable<ShotTransition['direction']>;
64
+ color: string;
65
+ }
66
+ /** The transition under way at a time, if one is: which two shots, and how far along. */
67
+ export declare function transitionAt(shots: ReadonlyArray<Shot>, time: number): ActiveTransition | undefined;
68
+ /**
69
+ * Shots cut on the beat: each shot's start (but the first's) moved to the
70
+ * nearest beat of a grid (`detectTempo` on the music, or `{ bpm, offset }`),
71
+ * ends following; transitions keep their lengths. Nothing moves more than
72
+ * half a beat.
73
+ */
74
+ export declare function snapShotsToBeats(shots: ReadonlyArray<Shot>, grid: {
75
+ bpm: number;
76
+ offset: number;
77
+ }): Shot[];
78
+ /** The scene's values with another camera active: to draw the shot going out during a transition. */
79
+ export declare function withActiveCamera(values: SceneValues | undefined, sceneId: string, cameraId: string): SceneValues;
80
+ /** Where a camera is and looks, as an orbit round a target (or a fixed position), with its field of view. */
81
+ export interface CameraPose {
82
+ /** What it orbits and looks at (default the origin) */
83
+ target?: Vec3;
84
+ /** Degrees round the target (0 is in front, +z) */
85
+ yaw?: number;
86
+ /** Degrees up from level */
87
+ pitch?: number;
88
+ /** Metres from the target */
89
+ distance?: number;
90
+ /** A fixed position instead of the orbit (a pan or tilt turns the camera where it stands) */
91
+ position?: Vec3;
92
+ /** Where it looks (default the target) */
93
+ lookAt?: Vec3;
94
+ /** Vertical field of view, degrees (a zoom changes it) */
95
+ fov?: number;
96
+ }
97
+ export interface CameraMoveOptions {
98
+ scene: string;
99
+ camera: string;
100
+ /** ms */
101
+ start: number;
102
+ end: number;
103
+ /** Where the move starts and ends: `to` fills in from `from` */
104
+ from: CameraPose;
105
+ to: Partial<CameraPose>;
106
+ /** Easing over the move (default `ease-in-out`) */
107
+ easing?: EasingType;
108
+ /** Key spacing, ms (default 33): the path between keys is a straight line */
109
+ every?: number;
110
+ }
111
+ /** A camera pose at a point of a move, `t` 0..1 (eased already). */
112
+ export declare function cameraPoseAt(from: CameraPose, to: Partial<CameraPose>, t: number): {
113
+ position: Vec3;
114
+ lookAt: Vec3;
115
+ fov?: number;
116
+ };
117
+ /**
118
+ * A camera move as tracks on the camera (`position`, `lookAt`, and `fov`
119
+ * when it zooms): an orbit (change `yaw`), a dolly (`distance`), a crane
120
+ * (`pitch` and `distance`), a pan or tilt (`position` fixed, `lookAt`
121
+ * moving), a zoom (`fov`), or any mix, eased over the move.
122
+ */
123
+ export declare function cameraMoveTracks(options: CameraMoveOptions): Track[];
124
+ export interface CameraFollowOptions {
125
+ scene: string;
126
+ camera: string;
127
+ start: number;
128
+ end: number;
129
+ /** Where the subject is at a time (its position in the scene) */
130
+ subjectAt: (time: number) => Vec3;
131
+ /** The camera's place relative to the subject, metres (default behind and above: [0, 2, 6]) */
132
+ offset?: Vec3;
133
+ /** How far the camera lags behind the subject's motion, ms (default 0) */
134
+ lag?: number;
135
+ every?: number;
136
+ }
137
+ /** Tracks that keep a camera on a moving subject: its position an offset from the subject, looking at it. */
138
+ export declare function cameraFollowTracks(options: CameraFollowOptions): Track[];
139
+ export interface HandheldOptions {
140
+ scene: string;
141
+ camera: string;
142
+ start: number;
143
+ end: number;
144
+ /** How far the camera drifts, metres (default 0.04), and how far its aim wanders, metres at the subject (default 0.08) */
145
+ amount?: number;
146
+ aim?: number;
147
+ /** How quickly it wanders (default 1.2 wobbles a second) */
148
+ rate?: number;
149
+ seed?: number | string;
150
+ /** The camera's rest, when no move's tracks are given: its authored position and where it looks */
151
+ base?: {
152
+ position: Vec3;
153
+ lookAt: Vec3;
154
+ };
155
+ every?: number;
156
+ }
157
+ /**
158
+ * A deterministic handheld shake: seeded, smooth, and added onto a move's
159
+ * `position` and `lookAt` tracks (or a still camera's `base`). The same
160
+ * seed always shakes the same way.
161
+ */
162
+ export declare function cameraHandheldTracks(tracks: ReadonlyArray<Track>, options: HandheldOptions): Track[];
@@ -0,0 +1,40 @@
1
+ import type { ResolvedScene3D } from './resolve-scene';
2
+ import type { Renderer3D } from './canvas-2d-renderer';
3
+ /**
4
+ * A software depth buffer for the Canvas 2D path: every triangle is
5
+ * rasterised into a pixel buffer with a depth per pixel, so shapes that cut
6
+ * through each other, huge floors and long meshes draw right with no `layer`
7
+ * needed, in Node as well as on a page. Each triangle keeps its one shaded
8
+ * colour (and its fog), edges are hard (no anti-aliasing), and the ink is
9
+ * drawn into the same buffer with a depth test, so an outline never shows
10
+ * through what is in front of it. Deterministic: the same frame gives the
11
+ * same bytes anywhere.
12
+ *
13
+ * Layers keep their meaning: a lower layer is drawn first and a higher one
14
+ * paints over it whatever the depths (the depth buffer is cleared between
15
+ * layers). Objects drawn whole with the canvas API (characters in their pen
16
+ * looks, lines, trails) go on top of the meshes, as on the WebGL2 renderer's
17
+ * overlay; solid characters are meshes and sort by depth.
18
+ */
19
+ export interface RasterImage {
20
+ width: number;
21
+ height: number;
22
+ /** RGBA bytes, row by row */
23
+ data: Uint8ClampedArray;
24
+ /** The nearest depth drawn at each pixel, metres; Infinity where nothing was */
25
+ depth: Float32Array;
26
+ }
27
+ export interface RasterOptions {
28
+ /** Start from these pixels instead of the background (what was on the canvas under a transparent scene) */
29
+ under?: Uint8ClampedArray;
30
+ }
31
+ /** Rasterise a resolved frame's triangles and ink into a pixel buffer with a depth per pixel. */
32
+ export declare function rasterizeResolvedScene(frame: ResolvedScene3D, options?: RasterOptions): RasterImage;
33
+ /** Draw a resolved frame on `ctx` through the depth buffer, then its drawables on top. */
34
+ export declare function drawResolvedSceneWithDepth(ctx: CanvasRenderingContext2D, frame: ResolvedScene3D): void;
35
+ /** The depth-buffered renderer, for the adapter: `new Scene3DAdapter(new SoftwareRenderer(ctx), …)`. */
36
+ export declare class SoftwareRenderer implements Renderer3D {
37
+ private readonly ctx;
38
+ constructor(ctx: CanvasRenderingContext2D);
39
+ render(frame: ResolvedScene3D): void;
40
+ }