@algorisys/tinyfly 0.82.0 → 0.86.2

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 (60) hide show
  1. package/README.md +11 -4
  2. package/lib/addons/adapters.js +363 -248
  3. package/lib/addons/characters.js +1652 -1470
  4. package/lib/addons/dom-adapter-Cphr2HZn.js +372 -0
  5. package/lib/addons/gsap-compat.js +197 -187
  6. package/lib/addons/load-scene-vp14_Jj-.js +324 -0
  7. package/lib/addons/scene-3d-webgl.js +237 -0
  8. package/lib/addons/scene-3d.js +306 -0
  9. package/lib/addons/shading-ByG9UXd0.js +85 -0
  10. package/lib/browser/tinyfly-scene-3d-webgl.iife.js +114 -0
  11. package/lib/browser/tinyfly-scene-3d.iife.js +3 -0
  12. package/lib/browser/tinyfly.iife.js +4 -4
  13. package/lib/browser/tinyfly.js +3028 -2480
  14. package/lib/browser/tinyfly.umd.js +4 -4
  15. package/lib/cli/tools.js +137 -22
  16. package/lib/embed/tinyfly-embed.iife.js +4 -4
  17. package/lib/embed/tinyfly-embed.js +921 -833
  18. package/lib/engine/tinyfly-engine.js +1022 -776
  19. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  20. package/lib/headless/headless.js +264 -7
  21. package/lib/player/tinyfly-player.es.js +459 -371
  22. package/lib/player/tinyfly-player.iife.js +2 -2
  23. package/lib/player/tinyfly-player.umd.js +2 -2
  24. package/lib/types/adapters/canvas/canvas-adapter.d.ts +36 -0
  25. package/lib/types/adapters/transform-3d.d.ts +99 -0
  26. package/lib/types/adapters/webgl/webgl-adapter.d.ts +17 -0
  27. package/lib/types/characters/character.d.ts +20 -1
  28. package/lib/types/characters/index.d.ts +2 -0
  29. package/lib/types/characters/rig/body-plan.d.ts +3 -1
  30. package/lib/types/characters/rig/skeleton.d.ts +57 -0
  31. package/lib/types/characters/scene-objects.d.ts +2 -0
  32. package/lib/types/compat/gsap/vars.d.ts +8 -0
  33. package/lib/types/engine/core/bake.d.ts +3 -1
  34. package/lib/types/engine/index.d.ts +1 -0
  35. package/lib/types/engine/interpolation/interpolators.d.ts +10 -3
  36. package/lib/types/engine/math/index.d.ts +11 -0
  37. package/lib/types/engine/math/mat4.d.ts +37 -0
  38. package/lib/types/engine/math/quat.d.ts +39 -0
  39. package/lib/types/engine/math/vec3.d.ts +16 -0
  40. package/lib/types/engine/types.d.ts +23 -2
  41. package/lib/types/scene-3d/camera.d.ts +27 -0
  42. package/lib/types/scene-3d/canvas-2d-renderer.d.ts +21 -0
  43. package/lib/types/scene-3d/geometry/extrude.d.ts +17 -0
  44. package/lib/types/scene-3d/geometry/mesh.d.ts +36 -0
  45. package/lib/types/scene-3d/geometry/primitives.d.ts +16 -0
  46. package/lib/types/scene-3d/geometry/triangulate.d.ts +24 -0
  47. package/lib/types/scene-3d/index.d.ts +20 -0
  48. package/lib/types/scene-3d/load-scene.d.ts +31 -0
  49. package/lib/types/scene-3d/object-kind.d.ts +54 -0
  50. package/lib/types/scene-3d/resolve-scene.d.ts +122 -0
  51. package/lib/types/scene-3d/scene-3d-adapter.d.ts +46 -0
  52. package/lib/types/scene-3d/scene-types.d.ts +191 -0
  53. package/lib/types/scene-3d/shading.d.ts +20 -0
  54. package/lib/types/scene-3d/validate-scene.d.ts +11 -0
  55. package/lib/types/scene-3d/webgl/gl-data.d.ts +28 -0
  56. package/lib/types/scene-3d/webgl/index.d.ts +16 -0
  57. package/lib/types/scene-3d/webgl/shaders.d.ts +29 -0
  58. package/lib/types/scene-3d/webgl/webgl2-renderer.d.ts +33 -0
  59. package/package.json +10 -2
  60. package/lib/addons/dom-adapter-CrNwoomd.js +0 -243
@@ -56,6 +56,14 @@ export interface GsapStagger {
56
56
  /** Distribute the offsets through an ease */
57
57
  ease?: string;
58
58
  }
59
+ /**
60
+ * GSAP's names for transform properties, as tinyfly's. GSAP writes
61
+ * `rotation` / `rotationX` / `rotationY`; its `transformPerspective` is an
62
+ * element's own perspective (tinyfly's `perspective`), and its `perspective`
63
+ * is the CSS property on a parent, for its children (`childPerspective`).
64
+ * tinyfly's own names pass through unchanged.
65
+ */
66
+ export declare const PROPERTY_ALIASES: Record<string, string>;
59
67
  export interface SplitVars {
60
68
  /** Scheduling and lifecycle options */
61
69
  config: TweenVars;
@@ -1,4 +1,4 @@
1
- import type { AnyTrack, Track, Keyframe, EasingType, KeyframedTrack } from '../types';
1
+ import type { AnyTrack, Track, Keyframe, EasingType, KeyframedTrack, TrackInterpolation } from '../types';
2
2
  /**
3
3
  * Baking: turning a computed animation into plain keyframes.
4
4
  *
@@ -21,6 +21,8 @@ export interface BakeOptions {
21
21
  * Set to 0 to keep every sample.
22
22
  */
23
23
  tolerance?: number;
24
+ /** The track's `interpolation`, so baked rotations turn the same way (`'slerp'`) */
25
+ interpolation?: TrackInterpolation;
24
26
  }
25
27
  /**
26
28
  * Sample a spring track into an ordinary keyframe track.
@@ -5,3 +5,4 @@ export * from './serialization';
5
5
  export * from './authoring';
6
6
  export * from './path';
7
7
  export * from './text';
8
+ export * from './math';
@@ -1,4 +1,4 @@
1
- import type { AnimatableValue, Interpolator } from '../types';
1
+ import type { AnimatableValue, Interpolator, TrackInterpolation } from '../types';
2
2
  /**
3
3
  * Interpolate between two numbers.
4
4
  */
@@ -11,6 +11,12 @@ export declare const interpolateColor: Interpolator<string>;
11
11
  * Interpolate between two number arrays (element-wise).
12
12
  */
13
13
  export declare const interpolateArray: Interpolator<number[]>;
14
+ /**
15
+ * Turn between two rotations given as `[x, y, z, w]` quaternions, the short
16
+ * way round at a steady speed (spherical interpolation). The result is always
17
+ * a unit quaternion, so a rotation never shrinks part way.
18
+ */
19
+ export declare const interpolateQuaternion: Interpolator<number[]>;
14
20
  /**
15
21
  * Interpolate strings with no interpolation (discrete jump).
16
22
  */
@@ -20,6 +26,7 @@ export declare const interpolateString: Interpolator<string>;
20
26
  */
21
27
  export declare const interpolatePathString: Interpolator<string>;
22
28
  /**
23
- * Detect value type and return appropriate interpolator.
29
+ * The interpolator for a track: the one it asks for (`interpolation`), else
30
+ * one chosen from the type of its values.
24
31
  */
25
- export declare function getInterpolator<T extends AnimatableValue>(sampleValue: T): Interpolator<T>;
32
+ export declare function getInterpolator<T extends AnimatableValue>(sampleValue: T, interpolation?: TrackInterpolation): Interpolator<T>;
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Small, pure 3D math for rotations and transforms: vectors, quaternions and
3
+ * 4×4 matrices as plain number arrays (JSON as they are). Grouped by kind, so
4
+ * `quat.multiply` and `mat4.multiply` read as what they are.
5
+ */
6
+ export * as vec3 from './vec3';
7
+ export * as quat from './quat';
8
+ export * as mat4 from './mat4';
9
+ export type { Vec3 } from './vec3';
10
+ export type { Quat } from './quat';
11
+ export type { Mat4 } from './mat4';
@@ -0,0 +1,37 @@
1
+ import type { Vec3 } from './vec3';
2
+ import type { Quat } from './quat';
3
+ /**
4
+ * 4×4 matrices as 16 numbers in **column-major** order (`m[column * 4 + row]`),
5
+ * the order WebGL, glTF and CSS `matrix3d()` use. Points are columns, so
6
+ * `multiply(a, b)` applies `b` first, then `a`. Every function is pure and
7
+ * returns a new array.
8
+ */
9
+ export type Mat4 = number[];
10
+ export declare function identity(): Mat4;
11
+ /** `a · b`: transform by `b`, then by `a`. */
12
+ export declare function multiply(a: Mat4, b: Mat4): Mat4;
13
+ export declare function translation(v: Vec3): Mat4;
14
+ export declare function scaling(v: Vec3): Mat4;
15
+ /** The rotation of a unit quaternion. */
16
+ export declare function fromQuat(q: Quat): Mat4;
17
+ /** Translate · rotate · scale: an object's local matrix (scale first, then rotate, then move). */
18
+ export declare function compose(position: Vec3, rotation: Quat, scale: Vec3): Mat4;
19
+ export declare function transpose(m: Mat4): Mat4;
20
+ /** The inverse, or `null` when `m` has none (it flattens space). */
21
+ export declare function invert(m: Mat4): Mat4 | null;
22
+ /**
23
+ * A perspective projection: vertical field of view in degrees, width / height,
24
+ * and the near and far planes (positive distances in front of the camera,
25
+ * which looks down -z). Depth maps to -1..1, as WebGL clip space.
26
+ */
27
+ export declare function perspective(fovY: number, aspect: number, near: number, far: number): Mat4;
28
+ /** An orthographic projection of the box `left..right`, `bottom..top`, `near..far` (depth -1..1). */
29
+ export declare function orthographic(left: number, right: number, bottom: number, top: number, near: number, far: number): Mat4;
30
+ /**
31
+ * A view matrix for a camera at `eye` looking at `target`, with `up` (default
32
+ * +y) keeping it level. It moves the world so the camera sits at the origin
33
+ * looking down -z.
34
+ */
35
+ export declare function lookAt(eye: Vec3, target: Vec3, up?: Vec3): Mat4;
36
+ /** A point transformed by `m`, divided by w (so it works through a projection). */
37
+ export declare function transformPoint(m: Mat4, p: Vec3): Vec3;
@@ -0,0 +1,39 @@
1
+ import type { Vec3 } from './vec3';
2
+ /**
3
+ * Rotations as unit quaternions, `[x, y, z, w]` (glTF's order). Quaternions
4
+ * turn smoothly between any two orientations without gimbal lock, which Euler
5
+ * angles cannot. Every function is pure and returns a new array.
6
+ *
7
+ * Euler angles are degrees, applied in **YXZ** order (yaw, then pitch, then
8
+ * roll): `fromEuler(x, y, z)` turns the same way as CSS
9
+ * `rotateY(y) rotateX(x) rotateZ(z)`.
10
+ */
11
+ export type Quat = [number, number, number, number];
12
+ export declare function identity(): Quat;
13
+ /** A turn of `degrees` about `axis` (any length; it is normalised). */
14
+ export declare function fromAxisAngle(axis: Vec3, degrees: number): Quat;
15
+ /** From Euler degrees in YXZ order: yaw `y`, then pitch `x`, then roll `z`. */
16
+ export declare function fromEuler(x: number, y: number, z: number): Quat;
17
+ /**
18
+ * Back to Euler degrees `[x, y, z]` in YXZ order. At straight up or down
19
+ * (pitch ±90°) yaw and roll turn about the same axis; the roll is then 0 and
20
+ * the yaw carries the whole turn.
21
+ */
22
+ export declare function toEuler(q: Quat): Vec3;
23
+ /** `a × b`: rotate by `b`, then by `a`. */
24
+ export declare function multiply(a: Quat, b: Quat): Quat;
25
+ export declare function dot(a: Quat, b: Quat): number;
26
+ export declare function length(q: Quat): number;
27
+ /** `q` at length 1; a zero quaternion (no rotation described) becomes the identity. */
28
+ export declare function normalize(q: Quat): Quat;
29
+ /** The opposite turn of a unit quaternion. */
30
+ export declare function conjugate(q: Quat): Quat;
31
+ /**
32
+ * Spherical interpolation: turns from `a` to `b` at a steady angular speed,
33
+ * the short way round (`q` and `-q` are the same rotation, so `b` is flipped
34
+ * when that is shorter). `t` 0 gives `a` and 1 gives `b`, both normalised;
35
+ * eased `t` outside 0..1 (back, elastic) carries on along the same arc.
36
+ */
37
+ export declare function slerp(a: Quat, b: Quat, t: number): Quat;
38
+ /** `v` turned by `q`. */
39
+ export declare function rotateVec3(q: Quat, v: Vec3): Vec3;
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Three-component vectors as plain `[x, y, z]` arrays, so they serialise to
3
+ * JSON as they are. Every function is pure and returns a new array.
4
+ */
5
+ export type Vec3 = [number, number, number];
6
+ export declare function add(a: Vec3, b: Vec3): Vec3;
7
+ export declare function subtract(a: Vec3, b: Vec3): Vec3;
8
+ export declare function scale(v: Vec3, factor: number): Vec3;
9
+ export declare function dot(a: Vec3, b: Vec3): number;
10
+ /** Right-handed: `cross([1, 0, 0], [0, 1, 0])` is `[0, 0, 1]`. */
11
+ export declare function cross(a: Vec3, b: Vec3): Vec3;
12
+ export declare function length(v: Vec3): number;
13
+ export declare function distance(a: Vec3, b: Vec3): number;
14
+ /** `v` scaled to length 1; the zero vector stays zero (there is no direction to keep). */
15
+ export declare function normalize(v: Vec3): Vec3;
16
+ export declare function lerp(a: Vec3, b: Vec3, t: number): Vec3;
@@ -93,7 +93,17 @@ export interface Track<T extends AnimatableValue = AnimatableValue> {
93
93
  targets?: string[];
94
94
  /** Per-target time offsets for `targets`. Ignored when `targets` is absent. */
95
95
  stagger?: StaggerConfig;
96
+ /**
97
+ * How keyframe values blend. Absent: chosen from the value, as always
98
+ * (numbers, colours, arrays element-wise, path morphs). `'slerp'`: the
99
+ * values are rotations as `[x, y, z, w]` quaternions, turned the short way
100
+ * round at a steady speed. It is data, not guessed from a 4-number array,
101
+ * so a file says what it means. A file that uses it is format version 2.
102
+ */
103
+ interpolation?: TrackInterpolation;
96
104
  }
105
+ /** Explicit interpolation modes a track can ask for (see `Track.interpolation`). */
106
+ export type TrackInterpolation = 'slerp';
97
107
  /** Where a stagger starts fanning out from */
98
108
  export type StaggerFrom = 'start' | 'end' | 'center' | 'edges' | number;
99
109
  /**
@@ -148,8 +158,19 @@ export interface TimelineMarker {
148
158
  /** A question to show while stopped here, before revealing the next step */
149
159
  question?: string;
150
160
  }
151
- /** The JSON format version this engine writes and reads. */
152
- export declare const FORMAT_VERSION = 1;
161
+ /**
162
+ * The newest JSON format version this engine reads. It writes the lowest
163
+ * version a file needs (see `formatVersionFor`), so files that use nothing new
164
+ * still open in older players.
165
+ *
166
+ * - 1: the original format.
167
+ * - 2: tracks may set `interpolation: 'slerp'` (quaternion rotations).
168
+ */
169
+ export declare const FORMAT_VERSION = 2;
170
+ /** The format version a timeline's tracks need: 2 when any track sets `interpolation`, else 1. */
171
+ export declare function formatVersionFor(tracks: ReadonlyArray<{
172
+ interpolation?: TrackInterpolation;
173
+ }>): number;
153
174
  /** Serializable timeline definition */
154
175
  export interface TimelineDefinition {
155
176
  /**
@@ -0,0 +1,27 @@
1
+ import { type Mat4, type Vec3 } from '../engine/math';
2
+ /**
3
+ * Camera matrices and camera moves, as pure functions. A camera looks down
4
+ * its own -z with +y up, as in WebGL and glTF.
5
+ */
6
+ /** A view matrix looking from `eye` at `target`, level (when looking straight up or down, -z is "up" instead). */
7
+ export declare function lookAtView(eye: Vec3, target: Vec3): Mat4;
8
+ /**
9
+ * A point on a sphere around `target`: `yaw` degrees around the up axis (0 is
10
+ * in front, +z), `pitch` degrees up from level, `distance` metres away. Animate
11
+ * yaw for an orbit, pitch for a crane, distance for a dolly.
12
+ */
13
+ export declare function orbitPosition(target: Vec3, yaw: number, pitch: number, distance: number): Vec3;
14
+ /** `eye` moved toward `target` by `amount` metres (negative moves away); it never passes the target. */
15
+ export declare function dollyPosition(eye: Vec3, target: Vec3, amount: number): Vec3;
16
+ /** The projection for a camera: perspective by vertical field of view, or orthographic by view height. */
17
+ export declare function projectionMatrix(camera: {
18
+ projection: 'perspective';
19
+ fov: number;
20
+ near: number;
21
+ far: number;
22
+ } | {
23
+ projection: 'orthographic';
24
+ height: number;
25
+ near: number;
26
+ far: number;
27
+ }, aspect: number): Mat4;
@@ -0,0 +1,21 @@
1
+ import type { ResolvedScene3D } from './resolve-scene';
2
+ /** What renders a resolved frame: synchronous, it never loads anything. */
3
+ export interface Renderer3D {
4
+ render(frame: ResolvedScene3D): void;
5
+ }
6
+ /**
7
+ * Draws a resolved scene on a 2D canvas: back to front, each triangle filled
8
+ * with its shaded colour, then its ink. Works in browsers, Workers
9
+ * (OffscreenCanvas) and Node (`@napi-rs/canvas`), and gives the same pixels
10
+ * for the same frame on the same canvas backend.
11
+ *
12
+ * Painter's order: long triangles that cross one another can sort wrongly;
13
+ * keep meshes modest in size, or use more segments.
14
+ */
15
+ export declare class Canvas2DRenderer implements Renderer3D {
16
+ private readonly ctx;
17
+ constructor(ctx: CanvasRenderingContext2D);
18
+ render(frame: ResolvedScene3D): void;
19
+ }
20
+ /** Draw a resolved frame on `ctx` at (0, 0), `frame.width` × `frame.height`. */
21
+ export declare function drawResolvedScene(ctx: CanvasRenderingContext2D, frame: ResolvedScene3D): void;
@@ -0,0 +1,17 @@
1
+ import { type Mesh } from './mesh';
2
+ /**
3
+ * An SVG path made solid: its shape as front and back faces, `depth` apart,
4
+ * joined by walls. Any tinyfly path (a logo, a letter, a star) becomes a 3D
5
+ * object. Subpaths inside others are holes (an "o", a ring), outlines inside
6
+ * holes are islands again.
7
+ *
8
+ * SVG's y points down, 3D's up: the shape is flipped, centred on the origin
9
+ * and scaled so it is `width` metres wide (default 1).
10
+ */
11
+ export interface ExtrudeOptions {
12
+ depth: number;
13
+ width?: number;
14
+ /** Points per curve (default 12) */
15
+ curveSegments?: number;
16
+ }
17
+ export declare function extrudeMesh(d: string, options: ExtrudeOptions): Mesh;
@@ -0,0 +1,36 @@
1
+ /**
2
+ * A triangle mesh as plain arrays: vertex positions and normals (flat x, y, z
3
+ * runs) and triangles as vertex index triples. Triangles wind
4
+ * counter-clockwise seen from outside, so `(b - a) × (c - a)` points out.
5
+ */
6
+ export interface Mesh {
7
+ positions: number[];
8
+ /** Per vertex, unit length: what smooth (lambert) shading reads */
9
+ normals: number[];
10
+ indices: number[];
11
+ }
12
+ /** A mesh edge: two vertex indices and the one or two triangles that share it. */
13
+ export interface MeshEdge {
14
+ a: number;
15
+ b: number;
16
+ faces: number[];
17
+ }
18
+ /** Builds a mesh one vertex and one triangle at a time. */
19
+ export declare class MeshBuilder {
20
+ readonly positions: number[];
21
+ readonly normals: number[];
22
+ readonly indices: number[];
23
+ /** Add a vertex; returns its index. */
24
+ vertex(x: number, y: number, z: number, nx: number, ny: number, nz: number): number;
25
+ /** Add a triangle, counter-clockwise seen from its front. */
26
+ triangle(a: number, b: number, c: number): void;
27
+ /** Add a quad a-b-c-d (counter-clockwise) as two triangles. */
28
+ quad(a: number, b: number, c: number, d: number): void;
29
+ build(): Mesh;
30
+ }
31
+ /**
32
+ * The mesh's edges, with the triangles on each side. Vertices at the same
33
+ * position count as one (a box's corners are split for hard normals, but its
34
+ * edges are still shared), so outlines can find silhouettes and creases.
35
+ */
36
+ export declare function meshEdges(mesh: Mesh): MeshEdge[];
@@ -0,0 +1,16 @@
1
+ import type { Geometry3D } from '../scene-types';
2
+ import { type Mesh } from './mesh';
3
+ export declare function boxMesh([w, h, d]: [number, number, number]): Mesh;
4
+ /**
5
+ * A floor: `width` along x, `depth` along z, facing +y, cut into a grid of
6
+ * `segments` × `segments` cells (default 1). More cells sort better against
7
+ * what stands on it, and fog and light vary across it.
8
+ */
9
+ export declare function planeMesh([width, depth]: [number, number], segments?: number): Mesh;
10
+ export declare function sphereMesh(radius: number, segments?: number): Mesh;
11
+ export declare function cylinderMesh(radius: number, height: number, segments?: number): Mesh;
12
+ export declare function coneMesh(radius: number, height: number, segments?: number): Mesh;
13
+ /** A ring in the xz plane: `radius` to the middle of the tube, `tube` its thickness. */
14
+ export declare function torusMesh(radius: number, tube: number, segments?: number): Mesh;
15
+ /** The mesh for a geometry description. */
16
+ export declare function geometryMesh(geometry: Geometry3D): Mesh;
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Triangulating flat shapes with holes, by ear clipping: each hole is joined
3
+ * to its outline by a bridge to a vertex it can see, then ears (corners whose
4
+ * triangle holds no other vertex) are cut off one by one. O(n²): meant for
5
+ * logos and letters of a few hundred points, not maps.
6
+ */
7
+ export interface Point2 {
8
+ x: number;
9
+ y: number;
10
+ }
11
+ /** Twice the signed area: positive for counter-clockwise (y up). */
12
+ export declare function signedArea(points: Point2[]): number;
13
+ /** Whether `point` lies inside `polygon` (even-odd). */
14
+ export declare function pointInPolygon(point: Point2, polygon: Point2[]): boolean;
15
+ /**
16
+ * Triangles covering `outline` minus its `holes`, as index triples into the
17
+ * returned `points` (the outline's and holes' points, in order). Orientation
18
+ * is fixed here: the outline counter-clockwise, holes clockwise, triangles
19
+ * counter-clockwise.
20
+ */
21
+ export declare function triangulate(outline: Point2[], holes?: Point2[][]): {
22
+ points: Point2[];
23
+ triangles: number[];
24
+ };
@@ -0,0 +1,20 @@
1
+ /**
2
+ * `@algorisys/tinyfly/scene-3d`: 3D scenes as JSON (cameras, lights,
3
+ * meshes), animated by ordinary tracks addressed to `<sceneId>/<objectId>`,
4
+ * drawn by a Canvas 2D renderer in the stylized look (flat, smooth, toon,
5
+ * outlines, fog) in browsers, Workers and Node. No DOM, no GPU, no glTF
6
+ * here: those are separate entries, so this one stays small.
7
+ */
8
+ export type * from './scene-types';
9
+ export { validateScene3D } from './validate-scene';
10
+ export { loadScene3D, prepareMesh, type LoadedScene3D, type PreparedMesh, type LoadOptions } from './load-scene';
11
+ export type { ObjectKind, ObjectContext, ObjectView, PlacedMesh, Drawable } from './object-kind';
12
+ export { resolveScene3D, type ResolvedScene3D, type ResolvedDrawable, type ResolvedCamera, type ResolvedLight, type DrawTriangle, type SceneValues, type ScreenPoint, type ResolveOptions } from './resolve-scene';
13
+ export { lookAtView, orbitPosition, dollyPosition, projectionMatrix } from './camera';
14
+ export { shadeTriangle, lightAt, fogAmount, parseColor } from './shading';
15
+ export { Canvas2DRenderer, drawResolvedScene, type Renderer3D } from './canvas-2d-renderer';
16
+ export { Scene3DAdapter, drawScene3D } from './scene-3d-adapter';
17
+ export { boxMesh, planeMesh, sphereMesh, cylinderMesh, coneMesh, torusMesh, geometryMesh } from './geometry/primitives';
18
+ export { MeshBuilder, meshEdges, type Mesh, type MeshEdge } from './geometry/mesh';
19
+ export { extrudeMesh, type ExtrudeOptions } from './geometry/extrude';
20
+ export { triangulate, signedArea, pointInPolygon, type Point2 } from './geometry/triangulate';
@@ -0,0 +1,31 @@
1
+ import type { Scene3D } from './scene-types';
2
+ import type { ObjectKind } from './object-kind';
3
+ import { type Mesh } from './geometry/mesh';
4
+ /** A mesh with what outlines need: for each triangle, its three edges and the triangle across each (-1: none). */
5
+ export interface PreparedMesh extends Mesh {
6
+ faceEdges: Array<Array<{
7
+ a: number;
8
+ b: number;
9
+ across: number;
10
+ }>>;
11
+ }
12
+ /** A scene ready to render: validated, with its meshes built once. */
13
+ export interface LoadedScene3D {
14
+ scene: Scene3D;
15
+ meshes: Map<string, PreparedMesh>;
16
+ /** Object kinds added at load (characters), by kind */
17
+ kinds: Map<string, ObjectKind>;
18
+ /** What each such kind prepared for each of its objects, by id */
19
+ prepared: Map<string, unknown>;
20
+ }
21
+ export interface LoadOptions {
22
+ /** Object kinds beyond the built-in ones, such as `characterObjects` from the characters add-on */
23
+ kinds?: ObjectKind[];
24
+ }
25
+ export declare function prepareMesh(mesh: Mesh): PreparedMesh;
26
+ /**
27
+ * Check a scene and build its meshes. Rendering a frame never loads or builds
28
+ * anything, so frames stay quick, pure and in any order. Throws with every
29
+ * problem listed when the scene is not valid.
30
+ */
31
+ export declare function loadScene3D(scene: Scene3D, options?: LoadOptions): LoadedScene3D;
@@ -0,0 +1,54 @@
1
+ import type { Mat4, Vec3 } from '../engine/math';
2
+ import type { AnimatableValue } from '../engine/types';
3
+ import type { Material3D, Object3D } from './scene-types';
4
+ import type { PreparedMesh } from './load-scene';
5
+ import type { ResolvedCamera, ResolvedScene3D, ScreenPoint } from './resolve-scene';
6
+ /**
7
+ * A kind of scene object beyond the built-in meshes, lights and cameras,
8
+ * added when a scene is loaded: characters come this way, from the
9
+ * characters add-on, so this entry stays small. The scene JSON is the same
10
+ * either way; only drawing it needs the kind.
11
+ */
12
+ export interface ObjectKind {
13
+ /** The `kind` in the scene JSON it handles, e.g. 'character' */
14
+ kind: string;
15
+ /** Problems with one object of this kind, as sentences */
16
+ validate?(object: Object3D): string[];
17
+ /** Built once when the scene loads; handed back to `resolve` */
18
+ prepare?(object: Object3D): unknown;
19
+ /** The object at one moment: meshes to place in the world and things to draw, or null for nothing */
20
+ resolve(context: ObjectContext): ObjectView | null;
21
+ }
22
+ /** What an object of an added kind shows at one moment. */
23
+ export interface ObjectView {
24
+ /** Meshes in world space: shaded, outlined and depth-sorted like the scene's own */
25
+ meshes?: PlacedMesh[];
26
+ /** Things drawn whole, each at its depth (a pen-drawn figure, a shadow) */
27
+ drawables?: Drawable[];
28
+ }
29
+ export interface PlacedMesh {
30
+ mesh: PreparedMesh;
31
+ /** Where it is: its world matrix */
32
+ world: Mat4;
33
+ material: Material3D;
34
+ }
35
+ export interface ObjectContext {
36
+ object: Object3D;
37
+ prepared: unknown;
38
+ /** Its animated values (target `<sceneId>/<objectId>`) */
39
+ values: ReadonlyMap<string, AnimatableValue>;
40
+ /** Its world matrix */
41
+ world: Mat4;
42
+ camera: ResolvedCamera;
43
+ /** Canvas size, px */
44
+ width: number;
45
+ height: number;
46
+ /** A view-space point on the canvas, px */
47
+ toScreen(view: Vec3): ScreenPoint;
48
+ }
49
+ /** Something a kind draws, placed in the scene's draw order by its depth. */
50
+ export interface Drawable {
51
+ /** Distance in front of the camera, metres (the triangles sort by the same) */
52
+ depth: number;
53
+ draw(ctx: CanvasRenderingContext2D, frame: ResolvedScene3D): void;
54
+ }
@@ -0,0 +1,122 @@
1
+ import { type Mat4, type Vec3 } from '../engine/math';
2
+ import type { AnimatableValue } from '../engine/types';
3
+ import type { LoadedScene3D, PreparedMesh } from './load-scene';
4
+ import type { LightObject, Material3D, Scene3D } from './scene-types';
5
+ import type { Drawable } from './object-kind';
6
+ /**
7
+ * From a loaded scene and the animation's values at one moment to plain data
8
+ * a renderer draws: world matrices, the camera, lights in world space, and
9
+ * every visible triangle on screen, sorted far to near. Pure: no canvas, no
10
+ * GPU, the same input always gives the same frame.
11
+ *
12
+ * Tracks address objects as `<sceneId>/<objectId>`:
13
+ * - every object: `x`, `y`, `z` or `position`; `rotateX`, `rotateY`,
14
+ * `rotateZ` (degrees, YXZ) or `quaternion` (a slerp track); `scale` or
15
+ * `scaleX` / `scaleY` / `scaleZ`; `visible` (0 or 1); `opacity`;
16
+ * - meshes and lights: `color`; lights: `intensity`, `target`;
17
+ * - cameras: `fov` (perspective), `height` (orthographic), `lookAt`;
18
+ * - the scene itself, `<sceneId>`: `activeCamera` (a camera's id: a cut is one keyframe).
19
+ */
20
+ /** Animated values by target, then property: an `AnimationState`'s `values`. */
21
+ export type SceneValues = ReadonlyMap<string, ReadonlyMap<string, AnimatableValue>>;
22
+ export interface ScreenPoint {
23
+ x: number;
24
+ y: number;
25
+ }
26
+ export interface ResolvedCamera {
27
+ id: string;
28
+ view: Mat4;
29
+ projection: Mat4;
30
+ /** World position */
31
+ position: Vec3;
32
+ /** The way it looks, unit length */
33
+ forward: Vec3;
34
+ orthographic: boolean;
35
+ near: number;
36
+ far: number;
37
+ }
38
+ export interface ResolvedLight {
39
+ id: string;
40
+ light: LightObject['light'];
41
+ color: string;
42
+ intensity: number;
43
+ position: Vec3;
44
+ /** Directional and spot: the way the light travels, unit length */
45
+ direction: Vec3;
46
+ range?: number;
47
+ /** Spot: the cone's half-angle, degrees */
48
+ angle: number;
49
+ }
50
+ export interface DrawTriangle {
51
+ objectId: string;
52
+ objectIndex: number;
53
+ /** The object's draw-order group: lower first */
54
+ layer: number;
55
+ face: number;
56
+ /** On the canvas, px (y down) */
57
+ screen: [ScreenPoint, ScreenPoint, ScreenPoint];
58
+ /** Distance in front of the camera, metres: what the draw order sorts by */
59
+ depth: number;
60
+ /** World centre of the face (lighting, fog) */
61
+ centroid: Vec3;
62
+ /** World face normal, unit, toward the viewer */
63
+ normal: Vec3;
64
+ /** World vertex normals, for smooth shading */
65
+ vertexNormals: [Vec3, Vec3, Vec3];
66
+ material: Material3D;
67
+ /** The object's own colour, over the material's (an animated `color`) */
68
+ color?: string;
69
+ /** The object's opacity times the material's */
70
+ opacity: number;
71
+ /** Edges to ink on top of this triangle (silhouettes, creases, open rims), when the material has an outline */
72
+ outline: Array<[ScreenPoint, ScreenPoint]>;
73
+ }
74
+ /**
75
+ * A visible mesh in world space, for renderers that keep geometry 3D (the
76
+ * WebGL2 renderer): the scene's meshes and those added kinds place.
77
+ */
78
+ export interface ResolvedMesh {
79
+ objectId: string;
80
+ objectIndex: number;
81
+ mesh: PreparedMesh;
82
+ world: Mat4;
83
+ material: Material3D;
84
+ /** An animated colour over the material's */
85
+ color?: string;
86
+ /** The object's opacity times the material's */
87
+ opacity: number;
88
+ }
89
+ /** A drawable from an added object kind, in the draw order. */
90
+ export interface ResolvedDrawable extends Drawable {
91
+ objectId: string;
92
+ objectIndex: number;
93
+ layer: number;
94
+ }
95
+ export interface ResolvedScene3D {
96
+ id: string;
97
+ width: number;
98
+ height: number;
99
+ /** ms: the moment drawn (for looks that move with time, such as a boiling pencil line) */
100
+ time: number;
101
+ background?: string;
102
+ fog?: Scene3D['fog'];
103
+ camera: ResolvedCamera;
104
+ lights: ResolvedLight[];
105
+ /** World matrices by object id */
106
+ worlds: Map<string, Mat4>;
107
+ /** By layer, then far to near: draw in this order */
108
+ triangles: DrawTriangle[];
109
+ /** Objects of added kinds (characters), each placed among the triangles by layer and depth */
110
+ drawables: ResolvedDrawable[];
111
+ /** Every visible mesh in world space (renderers with a depth buffer draw these instead of `triangles`) */
112
+ meshes: ResolvedMesh[];
113
+ }
114
+ export interface ResolveOptions {
115
+ /** Canvas size, px */
116
+ width: number;
117
+ height: number;
118
+ /** ms: the moment drawn, for looks that move with time (default 0) */
119
+ time?: number;
120
+ }
121
+ /** The frame at these animated values (an `AnimationState`'s `values`, or none for the scene as authored). */
122
+ export declare function resolveScene3D(loaded: LoadedScene3D, values: SceneValues | undefined, options: ResolveOptions): ResolvedScene3D;
@@ -0,0 +1,46 @@
1
+ import type { AnimationState } from '../engine/types';
2
+ import type { LoadedScene3D } from './load-scene';
3
+ import { type SceneValues } from './resolve-scene';
4
+ import { type Renderer3D } from './canvas-2d-renderer';
5
+ /**
6
+ * Plays 3D scenes from a timeline, like the other adapters: `applyState`
7
+ * takes the engine's values, `render` hands each scene's resolved frame to
8
+ * the renderer. Knows nothing about time.
9
+ *
10
+ * ```js
11
+ * const scene = loadScene3D(sceneJson)
12
+ * const adapter = new Scene3DAdapter(new Canvas2DRenderer(ctx), { width: 800, height: 450 })
13
+ * adapter.registerScene(scene)
14
+ * timeline.onUpdate = (state) => { adapter.applyState(state); adapter.render() }
15
+ * ```
16
+ */
17
+ export declare class Scene3DAdapter {
18
+ private readonly renderer;
19
+ private width;
20
+ private height;
21
+ private readonly scenes;
22
+ private values;
23
+ constructor(renderer: Renderer3D, options: {
24
+ width: number;
25
+ height: number;
26
+ });
27
+ /** Add a scene; its tracks address `<scene.id>/<objectId>`. */
28
+ registerScene(scene: LoadedScene3D): void;
29
+ unregisterScene(id: string): void;
30
+ resize(width: number, height: number): void;
31
+ applyState(state: Pick<AnimationState, 'values'> & {
32
+ currentTime?: number;
33
+ }): void;
34
+ private time;
35
+ render(): void;
36
+ }
37
+ /**
38
+ * Draw a scene at these animated values in one call: for a headless video
39
+ * scene's `draw(ctx, frame)` (`drawScene3D(ctx, scene, frame.state?.values, frame)`)
40
+ * or a canvas target's custom draw.
41
+ */
42
+ export declare function drawScene3D(ctx: CanvasRenderingContext2D, scene: LoadedScene3D, values: SceneValues | undefined, size: {
43
+ width: number;
44
+ height: number;
45
+ time?: number;
46
+ }): void;