@algorisys/tinyfly 0.81.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 (62) hide show
  1. package/README.md +12 -5
  2. package/lib/addons/adapters.js +363 -248
  3. package/lib/addons/characters.js +1658 -1342
  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 +3295 -2613
  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/dance.d.ts +47 -0
  29. package/lib/types/characters/index.d.ts +3 -1
  30. package/lib/types/characters/rig/body-plan.d.ts +3 -1
  31. package/lib/types/characters/rig/skeleton.d.ts +57 -0
  32. package/lib/types/characters/scene-objects.d.ts +2 -0
  33. package/lib/types/characters/species/human.d.ts +8 -0
  34. package/lib/types/compat/gsap/vars.d.ts +8 -0
  35. package/lib/types/engine/core/bake.d.ts +3 -1
  36. package/lib/types/engine/index.d.ts +1 -0
  37. package/lib/types/engine/interpolation/interpolators.d.ts +10 -3
  38. package/lib/types/engine/math/index.d.ts +11 -0
  39. package/lib/types/engine/math/mat4.d.ts +37 -0
  40. package/lib/types/engine/math/quat.d.ts +39 -0
  41. package/lib/types/engine/math/vec3.d.ts +16 -0
  42. package/lib/types/engine/types.d.ts +23 -2
  43. package/lib/types/scene-3d/camera.d.ts +27 -0
  44. package/lib/types/scene-3d/canvas-2d-renderer.d.ts +21 -0
  45. package/lib/types/scene-3d/geometry/extrude.d.ts +17 -0
  46. package/lib/types/scene-3d/geometry/mesh.d.ts +36 -0
  47. package/lib/types/scene-3d/geometry/primitives.d.ts +16 -0
  48. package/lib/types/scene-3d/geometry/triangulate.d.ts +24 -0
  49. package/lib/types/scene-3d/index.d.ts +20 -0
  50. package/lib/types/scene-3d/load-scene.d.ts +31 -0
  51. package/lib/types/scene-3d/object-kind.d.ts +54 -0
  52. package/lib/types/scene-3d/resolve-scene.d.ts +122 -0
  53. package/lib/types/scene-3d/scene-3d-adapter.d.ts +46 -0
  54. package/lib/types/scene-3d/scene-types.d.ts +191 -0
  55. package/lib/types/scene-3d/shading.d.ts +20 -0
  56. package/lib/types/scene-3d/validate-scene.d.ts +11 -0
  57. package/lib/types/scene-3d/webgl/gl-data.d.ts +28 -0
  58. package/lib/types/scene-3d/webgl/index.d.ts +16 -0
  59. package/lib/types/scene-3d/webgl/shaders.d.ts +29 -0
  60. package/lib/types/scene-3d/webgl/webgl2-renderer.d.ts +33 -0
  61. package/package.json +10 -2
  62. package/lib/addons/dom-adapter-CrNwoomd.js +0 -243
@@ -9,7 +9,9 @@
9
9
  * Space: +x is the character's left, +y is up, +z is the way it faces. The
10
10
  * hips sit on the y axis; the ground under them is y = 0.
11
11
  */
12
- export type Vec3 = [number, number, number];
12
+ import type { Vec3 } from '../../engine/math';
13
+ /** A point or direction, `[x, y, z]` (the engine's 3D math type). */
14
+ export type { Vec3 };
13
15
  export interface BoneSpec {
14
16
  /** Length, fraction of the height */
15
17
  length: number;
@@ -60,7 +60,64 @@ export interface SolveOptions {
60
60
  /** 'ground' (default) rests the lowest contact point on y = 0; 'none' keeps the hips at standing height */
61
61
  contact?: 'ground' | 'none';
62
62
  }
63
+ /** A pose solved in the character's own 3D space (+x its left, +y up, +z forward), before any view. */
64
+ export interface PlanSpace {
65
+ height: number;
66
+ /** The hips, where the chains hang from */
67
+ root: Vec3;
68
+ chains: Record<string, {
69
+ joints3: Vec3[];
70
+ frames: BoneFrame[];
71
+ }>;
72
+ head: {
73
+ center: Vec3;
74
+ rx: number;
75
+ ry: number;
76
+ toBody: (v: Vec3) => Vec3;
77
+ };
78
+ }
79
+ /** Forward kinematics: every chain's joints and the head, in the character's own space. */
80
+ export declare function solvePlanSpace(plan: BodyPlan, pose: Pose, height: number): PlanSpace;
63
81
  export declare function solveSkeleton(plan: BodyPlan, pose: Pose, options: SolveOptions): Skeleton;
82
+ /**
83
+ * Seeing a character through a camera: `toView` takes a point of the
84
+ * character's staged space (turned by its `turn`, rolled, set down: px or
85
+ * metres, +y up, the ground at y = 0) to view space (x right, y up, z toward
86
+ * the viewer); `toScreen` takes a view-space point to the canvas.
87
+ */
88
+ export interface ViewProjection {
89
+ toView(v: Vec3): Vec3;
90
+ toScreen(v: Vec3): Point;
91
+ }
92
+ /**
93
+ * A pose solved in 3D and seen through a camera (a 3D scene's), instead of
94
+ * flattened front-on: the same bones, turn, roll, lift and ground contact as
95
+ * {@link solveSkeleton}, then projected through `projection`. Screen points
96
+ * are canvas px; depths, radii and `height` are px at the hips, so the pens
97
+ * draw it as they draw any figure. Under an orthographic camera looking down
98
+ * -z it gives what `solveSkeleton` gives.
99
+ */
100
+ /** A pose in 3D, turned, rolled and set down on its ground (y = 0): what a 3D renderer places in its world. */
101
+ export interface StagedSpace {
102
+ height: number;
103
+ /** The hips */
104
+ hip: Vec3;
105
+ /** Every chain's joints */
106
+ chains: Record<string, Vec3[]>;
107
+ head: {
108
+ center: Vec3;
109
+ rx: number;
110
+ ry: number;
111
+ axes: [Vec3, Vec3, Vec3];
112
+ };
113
+ }
114
+ /**
115
+ * The pose's joints in its own 3D space with its turn, roll, lift and ground
116
+ * contact applied, as front-on drawing applies them, but kept 3D: +x right of
117
+ * the authored view, +y up from the ground, +z toward that view.
118
+ */
119
+ export declare function stagePlanSpace(plan: BodyPlan, pose: Pose, options: SolveOptions): StagedSpace;
120
+ export declare function skeletonInView(plan: BodyPlan, pose: Pose, options: SolveOptions, projection: ViewProjection): Skeleton;
64
121
  /** A point on the head from head coordinates: x to its left, y up, z forward, each -1..1 of a radius. */
65
122
  export declare function headPoint(head: SolvedHead, [x, y, z]: Vec3): {
66
123
  point: Point;
@@ -0,0 +1,2 @@
1
+ import type { ObjectKind } from '../scene-3d/object-kind';
2
+ export declare const characterObjects: ObjectKind;
@@ -32,6 +32,14 @@ export interface HumanBuild {
32
32
  export declare const HUMAN_REST: Pose;
33
33
  /** A full human pose from the fields that differ from rest. */
34
34
  export declare function humanPose(changes?: Pose): Pose;
35
+ /**
36
+ * The mirror image of a pose, as if seen in a mirror beside the picture: the
37
+ * left limbs, eye, brow and hand take the right's values and the other way
38
+ * round, and the body turns, tips and rolls the other way (`turn` 1, facing
39
+ * screen-right, becomes -1, facing screen-left). Fields of other body plans
40
+ * pass through.
41
+ */
42
+ export declare function mirrorHumanPose(pose: Pose): Pose;
35
43
  /**
36
44
  * Ready-made human poses. Several rest on something other than the feet (a
37
45
  * knee, the hands, the back): the figure is set down on whatever is lowest.
@@ -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
+ }