@algorisys/tinyfly 0.93.0 → 0.95.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 (63) hide show
  1. package/README.md +6 -6
  2. package/docs/acting.md +68 -0
  3. package/docs/api-reference.md +3 -1
  4. package/docs/editor-guide.md +1 -1
  5. package/docs/examples.md +1 -1
  6. package/docs/getting-started.md +1 -1
  7. package/docs/gsap-compat.md +1 -1
  8. package/docs/llm-guide.md +25 -0
  9. package/docs/maps.md +2 -2
  10. package/docs/props.md +202 -0
  11. package/docs/scene-3d.md +141 -0
  12. package/docs/teaching.md +1 -1
  13. package/lib/addons/characters.js +5647 -2519
  14. package/lib/addons/scene-3d.js +140 -138
  15. package/lib/browser/tinyfly-scene-3d.iife.js +1 -1
  16. package/lib/browser/tinyfly.iife.js +15 -9
  17. package/lib/browser/tinyfly.js +7059 -3876
  18. package/lib/browser/tinyfly.umd.js +15 -9
  19. package/lib/engine/tinyfly-engine.js +612 -600
  20. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  21. package/lib/types/characters/acting/beat-check.d.ts +12 -5
  22. package/lib/types/characters/acting/custom.d.ts +66 -0
  23. package/lib/types/characters/acting/gags.d.ts +10 -0
  24. package/lib/types/characters/acting/hand-path.d.ts +3 -0
  25. package/lib/types/characters/acting/index.d.ts +2 -0
  26. package/lib/types/characters/acting/persona.d.ts +93 -0
  27. package/lib/types/characters/acting/script.d.ts +10 -5
  28. package/lib/types/characters/capabilities.d.ts +30 -2
  29. package/lib/types/characters/character-script-3d.d.ts +80 -0
  30. package/lib/types/characters/character.d.ts +19 -0
  31. package/lib/types/characters/figure-actions.d.ts +4 -3
  32. package/lib/types/characters/ground-path.d.ts +32 -0
  33. package/lib/types/characters/index.d.ts +3 -0
  34. package/lib/types/characters/props/clip.d.ts +5 -0
  35. package/lib/types/characters/props/draw.d.ts +60 -0
  36. package/lib/types/characters/props/effects.d.ts +12 -0
  37. package/lib/types/characters/props/families/aircraft.d.ts +37 -0
  38. package/lib/types/characters/props/families/animals.d.ts +156 -0
  39. package/lib/types/characters/props/families/birds.d.ts +86 -0
  40. package/lib/types/characters/props/families/environment.d.ts +71 -0
  41. package/lib/types/characters/props/families/vehicle.d.ts +129 -0
  42. package/lib/types/characters/props/hidden.d.ts +49 -0
  43. package/lib/types/characters/props/index.d.ts +23 -0
  44. package/lib/types/characters/props/mesh-3d.d.ts +24 -0
  45. package/lib/types/characters/props/presets.d.ts +34 -0
  46. package/lib/types/characters/props/ride-3d.d.ts +71 -0
  47. package/lib/types/characters/props/ride.d.ts +79 -0
  48. package/lib/types/characters/props/rig.d.ts +224 -0
  49. package/lib/types/characters/props/scene-objects.d.ts +2 -0
  50. package/lib/types/characters/props/script-3d.d.ts +85 -0
  51. package/lib/types/characters/props/script.d.ts +145 -0
  52. package/lib/types/characters/props/shapes.d.ts +96 -0
  53. package/lib/types/characters/props/slice.d.ts +66 -0
  54. package/lib/types/characters/props/target.d.ts +129 -0
  55. package/lib/types/characters/stick-figure.d.ts +7 -2
  56. package/lib/types/engine/authoring/index.d.ts +1 -0
  57. package/lib/types/engine/authoring/spring-follow.d.ts +25 -0
  58. package/lib/types/scene-3d/object-kind.d.ts +4 -1
  59. package/lib/types/scene-3d/scene-types.d.ts +41 -1
  60. package/llms-full.txt +512 -10
  61. package/llms.txt +28 -27
  62. package/package.json +1 -1
  63. package/skills/tinyfly/SKILL.md +11 -0
@@ -0,0 +1,85 @@
1
+ import type { Track } from '../../engine/types';
2
+ import type { ActingOptions } from '../acting/acting';
3
+ import { type GroundPoint } from '../ground-path';
4
+ import type { Prop } from './target';
5
+ export type { GroundPoint } from '../ground-path';
6
+ /**
7
+ * Prop beats in world metres, for 3D scenes: a car drives to a point or
8
+ * along a road through points, a horse walks a path, a crow flies round the
9
+ * village, each turning to face the way it goes. Wheels and strides are
10
+ * keyed with the distance covered (from the prop's `moves`), so wheels roll
11
+ * and feet step exactly; wingbeats and rotors keep time. Every other action
12
+ * (a honk, a bark, a peck, a door) plays as it does in 2D, its controls only.
13
+ *
14
+ * ```js
15
+ * const car = propScript3D('car', car(), [
16
+ * { do: 'drive', through: [[4, 3], [8, 0], [8, -6]] },
17
+ * { do: 'honk' },
18
+ * { do: 'face', toward: [0, 0] },
19
+ * ], { scene: 'village', position: [-9, 3], heading: 90 })
20
+ * ```
21
+ *
22
+ * The tracks are the scene object's own: `x`, `z` and `rotateY` (absolute,
23
+ * in metres and degrees), and its controls.
24
+ */
25
+ export interface PropBeat3D {
26
+ /** One of its moves (`drive`, `walk`, `trot`, `fly`…), `face`, `hold`, or one of its actions (`honk`, `bark`…) */
27
+ do: string;
28
+ /** When it starts, ms (default: when the beat before ends) */
29
+ at?: number;
30
+ /** How long it takes, ms (default: the distance at its move's speed, or the action's own length) */
31
+ for?: number;
32
+ /** A move: where to, [x, z] metres */
33
+ to?: GroundPoint;
34
+ /** A move: a path through these points, [x, z] metres each; it curves smoothly through them */
35
+ through?: GroundPoint[];
36
+ /** `face`: a point [x, z] to face, or a heading in degrees (0 faces +z, 90 faces +x) */
37
+ toward?: GroundPoint | number;
38
+ /** A move: metres per second (default its own speed) */
39
+ speed?: number;
40
+ /** A flying move: how high, metres; or an action's height (a bird's `land` on a roof) */
41
+ height?: number;
42
+ /** An action: doors open (true) or shut */
43
+ open?: boolean;
44
+ /** An action: lights or engines on (true) or off */
45
+ on?: boolean;
46
+ /** An action: how hard the wind blows, 0..1 */
47
+ wind?: number;
48
+ }
49
+ export declare const PROP_BEAT_3D_FIELDS: readonly ["do", "at", "for", "to", "through", "toward", "speed", "height", "open", "on", "wind"];
50
+ export interface PropScript3DOptions {
51
+ /** The scene's id: the tracks target `<scene>/<id>` */
52
+ scene: string;
53
+ /** Where it was placed, [x, z] metres (its object's position) */
54
+ position?: GroundPoint;
55
+ /** Which way it faces at first, degrees (its object's rotation about y; 0 faces +z) */
56
+ heading?: number;
57
+ /** Control values it starts with (default its defaults) */
58
+ values?: Record<string, number>;
59
+ /** For its actions: acting style and how cartoony (see `propScript`) */
60
+ style?: ActingOptions['style'];
61
+ exaggeration?: number;
62
+ }
63
+ export interface PropScript3DResult {
64
+ tracks: Track[];
65
+ duration: number;
66
+ beats: Array<{
67
+ do: string;
68
+ start: number;
69
+ end: number;
70
+ }>;
71
+ /** Where it ends up, which way it faces, and its controls then */
72
+ end: {
73
+ position: GroundPoint;
74
+ heading: number;
75
+ values: Record<string, number>;
76
+ };
77
+ }
78
+ export interface PropBeat3DProblem {
79
+ beat: number;
80
+ message: string;
81
+ }
82
+ /** Problems in 3D prop beats, naming what was probably meant. */
83
+ export declare function checkPropBeats3D(beats: unknown, prop: Prop): PropBeat3DProblem[];
84
+ /** Compiles 3D prop beats into the scene object's tracks (see the module's notes). */
85
+ export declare function propScript3D(id: string, prop: Prop, beats: PropBeat3D[], options: PropScript3DOptions): PropScript3DResult;
@@ -0,0 +1,145 @@
1
+ import type { EasingType, Track } from '../../engine/types';
2
+ import { type ActingOptions } from '../acting/acting';
3
+ import type { ScriptBeatSpan } from '../acting/script';
4
+ import { type Prop } from './target';
5
+ /**
6
+ * Prop beats: what a prop does, compiled into acted tracks, the way
7
+ * `scriptTracks` does it for a figure.
8
+ *
9
+ * ```ts
10
+ * const { tracks, beats, effects } = propScript('car', car(), [
11
+ * { do: 'drive', to: 520 },
12
+ * { do: 'turn', toward: 'viewer' },
13
+ * { do: 'honk' },
14
+ * { do: 'bump' },
15
+ * ], { from: 120, ground: 300, style: 'snappy', exaggeration: 1.5 })
16
+ * ```
17
+ *
18
+ * The animation principles live here, once for every prop. Families write
19
+ * their actions as key poses of the controls (a drive rocks back, lunges,
20
+ * dips its nose on the stop) and the acting pass adds the rest: wind-ups,
21
+ * overshoot and settle, slow in and out, and overlap from the prop's acting
22
+ * rig (what leads, what trails). `exaggeration` scales the style's wind-ups
23
+ * and overshoots and every amplitude the actions use: 0.5 is restrained, 2
24
+ * is a cartoon.
25
+ */
26
+ export interface PropBeat {
27
+ /** What happens: one of the prop's actions */
28
+ do: string;
29
+ /** When it starts, ms (default: when the beat before ends) */
30
+ at?: number;
31
+ /** How long it takes, ms (default: the action's own length) */
32
+ for?: number;
33
+ /** Where to, scene x */
34
+ to?: number;
35
+ /** `turn`: a quarter-turn value (0 the viewer, 1 right, 2 away, 3 left) or a word */
36
+ toward?: number | 'viewer' | 'right' | 'away' | 'left';
37
+ /** How fast, px per ms */
38
+ speed?: number;
39
+ /** Doors: open (true) or shut */
40
+ open?: boolean;
41
+ /** Lights, engines: on (true) or off */
42
+ on?: boolean;
43
+ /** Height to climb to, metres */
44
+ height?: number;
45
+ /** How hard the wind blows, 0..1 */
46
+ wind?: number;
47
+ }
48
+ export declare const PROP_BEAT_FIELDS: readonly ["do", "at", "for", "to", "toward", "speed", "open", "on", "height", "wind"];
49
+ export interface PropScriptOptions {
50
+ /** Scene x its middle was placed at (its `x` track is an offset from here; default 0) */
51
+ from?: number;
52
+ /** Scene y of the ground it was placed on (its `y` track is an offset; default 0) */
53
+ ground?: number;
54
+ /** px per metre, as its target draws it (default 60) */
55
+ scale?: number;
56
+ /** Acting style (default snappy) */
57
+ style?: ActingOptions['style'];
58
+ /** How cartoony: 1 as designed, 0.5 restrained, 2 a cartoon (default 1) */
59
+ exaggeration?: number;
60
+ /** Control values it starts with (default the target's defaults) */
61
+ start?: Record<string, number>;
62
+ }
63
+ /** A cartoon effect a prop script asks for, with when and where (scene px). */
64
+ export interface PropEffect {
65
+ kind: 'dust' | 'exhaust' | 'skid' | 'honk' | 'leaves' | 'smoke';
66
+ time: number;
67
+ x: number;
68
+ y: number;
69
+ /** How long it shows, ms */
70
+ length: number;
71
+ /** Which way it streams: 1 right, −1 left */
72
+ direction?: 1 | -1;
73
+ /** A skid's other end, scene x */
74
+ toX?: number;
75
+ /** Where falling things land, scene y (leaves on the ground) */
76
+ toY?: number;
77
+ }
78
+ export interface PropScriptResult {
79
+ tracks: Track[];
80
+ duration: number;
81
+ beats: ScriptBeatSpan[];
82
+ effects: PropEffect[];
83
+ }
84
+ /** What an action is given: the prop, where it is, and ways to key it. */
85
+ export interface PropActionContext {
86
+ readonly prop: Prop;
87
+ /** px per metre */
88
+ readonly scale: number;
89
+ readonly exaggeration: number;
90
+ /** Scene x of its middle, and its ground's scene y, now */
91
+ readonly x: number;
92
+ readonly floor: number;
93
+ /** Its control values now (after the keys so far) */
94
+ readonly values: Readonly<Record<string, number>>;
95
+ /** Which way it faces on screen: 1 right, −1 left, 0 toward or away from the viewer */
96
+ facing(): 1 | -1 | 0;
97
+ /** Key the acted controls (turn, pitch, squash, a door…): the acting pass winds up, overshoots and overlaps them unless `act` is false */
98
+ key(time: number, changes: Record<string, number>, options?: {
99
+ act?: boolean;
100
+ easing?: EasingType;
101
+ }): void;
102
+ /** Move its middle to a scene x (and floor), keyed exactly as given (not acted): from `from` to `to` ms */
103
+ move(from: number, to: number, x: number, options?: {
104
+ easing?: EasingType;
105
+ floor?: number;
106
+ }): void;
107
+ /** Key a control exactly, not acted (wheels that must match the ground, a rotor's turns); key its value at a move's start first */
108
+ set(control: string, time: number, value: number, easing?: EasingType): void;
109
+ /** Turn to face a quarter-turn value or a way; returns when it is facing it */
110
+ turnTo(time: number, toward: NonNullable<PropBeat['toward']>): number;
111
+ /** Where one of its anchors is now, scene px (a chimney for smoke, a canopy for leaves) */
112
+ anchor(name: string): {
113
+ x: number;
114
+ y: number;
115
+ };
116
+ effect(effect: PropEffect): void;
117
+ }
118
+ /** One thing a prop can do. */
119
+ export interface PropAction {
120
+ /** One line: what it does */
121
+ summary: string;
122
+ /** Beat fields it needs */
123
+ needs?: Array<keyof PropBeat>;
124
+ /** Beat fields it reads */
125
+ uses?: Array<keyof PropBeat>;
126
+ /** Key it, from `start` ms; say when it ends (and when it touches or lets go of something) */
127
+ run(context: PropActionContext, beat: PropBeat, start: number): {
128
+ end: number;
129
+ contact?: number;
130
+ release?: number;
131
+ };
132
+ }
133
+ /** The actions every prop has. */
134
+ export declare const PROP_COMMON_ACTIONS: Record<string, PropAction>;
135
+ /** Every action a prop's beats can use. */
136
+ export declare function propActions(prop: Prop): Record<string, PropAction>;
137
+ export interface PropBeatProblem {
138
+ level: 'error' | 'warning';
139
+ beat: number;
140
+ message: string;
141
+ }
142
+ /** Problems in a prop's beats, naming what was probably meant (as `checkBeats` does for figures). */
143
+ export declare function checkPropBeats(beats: unknown, prop: Prop): PropBeatProblem[];
144
+ /** Compile a prop's beats into tracks on `target` (a `propTarget` of the same prop). Throws on problems (see `checkPropBeats`). */
145
+ export declare function propScript(target: string, prop: Prop, beats: PropBeat[], options?: PropScriptOptions): PropScriptResult;
@@ -0,0 +1,96 @@
1
+ import type { Vec3 } from '../../engine/math';
2
+ /**
3
+ * The shapes props are built from, as small meshes: corners, and faces that
4
+ * list corners with an outward normal. A face is seen when its normal points
5
+ * at the viewer; an outline is drawn along an edge between a seen face and an
6
+ * unseen one (the silhouette) or between two seen faces that meet at an angle
7
+ * (a crease), so curved surfaces read smooth and corners read sharp.
8
+ *
9
+ * Prop space: +y up (the ground is y = 0), +z the way the prop faces (its
10
+ * front), +x its left. Units are metres, so props and characters share a
11
+ * scale; a prop target draws them at so many px per metre.
12
+ */
13
+ /** A shape, in the prop part's own space. */
14
+ export type PropShape =
15
+ /** A box centred on its origin */
16
+ {
17
+ type: 'box';
18
+ size: Vec3;
19
+ }
20
+ /** A cylinder centred on its origin along an axis: wheels, discs, drums. `spokes` draws lines on its ends that turn with it */
21
+ | {
22
+ type: 'cylinder';
23
+ radius: number;
24
+ length: number;
25
+ axis?: 'x' | 'y' | 'z';
26
+ segments?: number;
27
+ spokes?: number;
28
+ }
29
+ /** An ellipsoid (a sphere when the radii match), centred on its origin */
30
+ | {
31
+ type: 'ellipsoid';
32
+ radii: Vec3;
33
+ segments?: number;
34
+ }
35
+ /**
36
+ * A side profile made solid across x: points are (forward, up) pairs going
37
+ * round the outline, and the shape is `width` wide, centred on x = 0. Car
38
+ * bodies, house fronts, fuselages.
39
+ */
40
+ | {
41
+ type: 'extrude';
42
+ profile: Array<[number, number]>;
43
+ width: number;
44
+ }
45
+ /**
46
+ * A flat one-sided panel facing one way, drawn only from that side: windows,
47
+ * doors, lights. Points are 2D in the panel's plane (see `facing`).
48
+ */
49
+ | {
50
+ type: 'panel';
51
+ points: Array<[number, number]>;
52
+ facing: 'left' | 'right' | 'front' | 'back' | 'up';
53
+ }
54
+ /**
55
+ * A round tube through points: stems, branches, frames, skids, legs. A
56
+ * radius per point tapers it. `joined` leaves its end rings unoutlined, for
57
+ * a tube that continues into another (a segment of a bending tail)
58
+ */
59
+ | {
60
+ type: 'tube';
61
+ points: Vec3[];
62
+ radius: number | number[];
63
+ segments?: number;
64
+ joined?: boolean;
65
+ };
66
+ export interface Mesh {
67
+ vertices: Vec3[];
68
+ faces: Array<{
69
+ corners: number[];
70
+ normal: Vec3;
71
+ }>;
72
+ /** Lines drawn on the shape that move with it (a wheel's spokes), as vertex index pairs */
73
+ marks?: Array<[number, number]>;
74
+ /** Smooth surfaces only show silhouette edges; faceted ones show creases too (default true) */
75
+ creases?: boolean;
76
+ /** Its open edges are joins to another shape, not outlines (a tube segment of a bending tail) */
77
+ joined?: boolean;
78
+ /** A piece cut from a bigger shape: the column walls (x and z planes) it was cut at, whose edges are not outlines */
79
+ walls?: {
80
+ x: number[];
81
+ z: number[];
82
+ };
83
+ }
84
+ export declare function boxMesh([w, h, d]: Vec3): Mesh;
85
+ export declare function cylinderMesh(radius: number, length: number, axis?: 'x' | 'y' | 'z', segments?: number, spokes?: number): Mesh;
86
+ export declare function ellipsoidMesh([rx, ry, rz]: Vec3, segments?: number): Mesh;
87
+ export declare function extrudeMesh(profile: Array<[number, number]>, width: number): Mesh;
88
+ export declare function panelMesh(points: Array<[number, number]>, facing: 'left' | 'right' | 'front' | 'back' | 'up'): Mesh;
89
+ export declare function tubeMesh(path: Vec3[], radius: number | number[], segments?: number): Mesh;
90
+ /** A shape's mesh. */
91
+ export declare function shapeMesh(shape: PropShape): Mesh;
92
+ /**
93
+ * A smooth curve through points (Catmull-Rom), as `count` points evenly
94
+ * spread along it: a tail's line from a few points of its shape.
95
+ */
96
+ export declare function smoothPath(points: Vec3[], count: number): Vec3[];
@@ -0,0 +1,66 @@
1
+ import { type Mat4, type Vec3 } from '../../engine/math';
2
+ import type { Mesh } from './shapes';
3
+ /**
4
+ * Cutting a prop into columns, for sorting by depth among other things.
5
+ *
6
+ * A 3D scene draws pen-drawn things back to front, each whole, at one depth.
7
+ * A long prop (a bus) has one depth for all of it, so a figure standing by
8
+ * its far end and one by its near end can't both sort right against it.
9
+ * Cut on a grid into columns about a metre across (along the prop's length
10
+ * and width; up stays whole), each column sorts at its own depth. Columns
11
+ * don't overlap, so for anything outside the prop the order is right; inside
12
+ * a column the prop's parts keep their own order (a cabin over its body).
13
+ * Big shapes are cut at the column walls, and those cuts are joins, not
14
+ * outlines (`walls`), so the prop still draws as one. Small parts (a wheel,
15
+ * an eye, a tube) go whole into the column their middle is in.
16
+ */
17
+ export type Cell = readonly [number, number];
18
+ /** Where to cut along an axis: columns about `size` across, or none when it is not much longer than that. */
19
+ export declare function gridCuts(min: number, max: number, size: number): number[];
20
+ /** The column a point is in. */
21
+ export declare function cellOf(xs: number[], zs: number[], point: Vec3): Cell;
22
+ /** A mesh moved into its prop's space: its points by the part's matrix, its normals turned with it. */
23
+ export declare function meshInSpace(mesh: Mesh, m: Mat4): Mesh;
24
+ /** A mesh (in its prop's space) cut at the grid's column walls: one joined piece per column it reaches. */
25
+ export declare function cutMesh(mesh: Mesh, xs: number[], zs: number[]): Array<{
26
+ cell: Cell;
27
+ mesh: Mesh;
28
+ }>;
29
+ /** A part placed for cutting: its mesh, and its matrix into the prop's rest space. */
30
+ export interface PlacedPart<P> {
31
+ part: P;
32
+ mesh: Mesh;
33
+ local: Mat4;
34
+ /** Never cut (a tube: it is drawn along its centre line in line art) */
35
+ whole?: boolean;
36
+ }
37
+ export interface ColumnPiece<P> {
38
+ part: P;
39
+ /** Its own mesh (placed by `local`), or a piece cut from it (already in rest space) */
40
+ mesh: Mesh;
41
+ cut: boolean;
42
+ cell: Cell;
43
+ }
44
+ /** A mesh in rest space, with its bounds, cached by the matrix that put it there (most parts don't move). */
45
+ interface Placed {
46
+ /** The matrix's key */
47
+ key: string;
48
+ inSpace: Mesh;
49
+ low: Vec3;
50
+ high: Vec3;
51
+ }
52
+ /** A matrix as a cache key. */
53
+ export declare const matrixKey: (m: Mat4) => string;
54
+ /** A part's mesh in rest space, with its bounds. */
55
+ export declare function placedMesh(mesh: Mesh, local: Mat4): Placed;
56
+ /**
57
+ * A prop's parts placed in columns about `size` across, in its rest space
58
+ * (before its pitch, lift and squash, so the columns move with it): small
59
+ * parts whole in the column their middle is in, big ones cut at the column
60
+ * walls. Cuts are cached, so only parts that move are cut again.
61
+ */
62
+ export declare function propColumns<P>(parts: Array<PlacedPart<P>>, size: number): {
63
+ pieces: Array<ColumnPiece<P>>;
64
+ middle: (cell: Cell) => Vec3;
65
+ };
66
+ export {};
@@ -0,0 +1,129 @@
1
+ import type { CustomTarget } from '../../adapters/canvas/canvas-adapter';
2
+ import type { PropertyInfo } from '../../adapters/canvas/target-properties';
3
+ import type { FrameInfo } from '../../headless/video-scene';
4
+ import type { ActingRig } from '../acting/acting';
5
+ import { type PropRig, type SolvedProp } from './rig';
6
+ import { type PropDrawOptions } from './draw';
7
+ import type { PropAction } from './script';
8
+ /**
9
+ * A prop: what it is, its rig, what it can do and how it acts. Families
10
+ * (`vehicle()`, …) make them; presets (`car()`) are families with settings.
11
+ */
12
+ export interface Prop {
13
+ /** What it is: car, tree, helicopter */
14
+ kind: string;
15
+ /** The family it comes from: vehicle, plant, building, aircraft */
16
+ family: string;
17
+ summary: string;
18
+ rig: PropRig;
19
+ /** What its beats can do (see `propScript`) */
20
+ actions: Record<string, PropAction>;
21
+ /** How its controls act: which lead, which follow, which wind up and overshoot (see `actKeyframes`) */
22
+ acting: ActingRig;
23
+ /** Its colours, for effects drawn with it */
24
+ colors?: {
25
+ body?: string;
26
+ ink?: string;
27
+ };
28
+ /**
29
+ * Follow-through: controls that trail another on a spring (an antenna
30
+ * behind the car's motion). The control is how far the follower lags,
31
+ * along the way the prop faces, × `per`, capped at ± `limit`.
32
+ */
33
+ follow?: PropFollow[];
34
+ /** A wheeled prop's reference wheel radius, metres: `wheelSpin` is that wheel's turn (see `propTow`) */
35
+ wheelRadius?: number;
36
+ /**
37
+ * How it gets about, for beats in world metres (`propScript3D`): each way
38
+ * of moving with its speed and the controls keyed as it goes, so wheels
39
+ * roll and feet step exactly the distance covered.
40
+ */
41
+ moves?: Record<string, PropMove>;
42
+ }
43
+ /** One way a prop moves over the ground (or through the air), as plain data. */
44
+ export interface PropMove {
45
+ /** Its usual speed, metres per second */
46
+ speed: number;
47
+ /** Controls set as it sets off (a gait's number) */
48
+ set?: Record<string, number>;
49
+ /** Controls eased in as it sets off and out as it stops (`walking: 1`, `flapping: 1`) */
50
+ hold?: Record<string, number>;
51
+ /** Controls advanced in step with the distance, per metre (`wheelSpin` in degrees, a stride's phase in cycles) */
52
+ perMetre?: Record<string, number>;
53
+ /** Controls advanced with time, per second (a wingbeat, a rotor) */
54
+ perSecond?: Record<string, number>;
55
+ /** It flies: a beat's `height` (metres) is how high, as its `lift` */
56
+ flies?: boolean;
57
+ }
58
+ export interface PropFollow {
59
+ /** The control it drives */
60
+ control: string;
61
+ /** What it follows: a directly keyed control, usually `x` */
62
+ of: string;
63
+ /** Control units per px of lag */
64
+ per: number;
65
+ stiffness?: number;
66
+ damping?: number;
67
+ /** The most it bends either way */
68
+ limit?: number;
69
+ }
70
+ export interface PropTargetOptions {
71
+ /** Where its middle stands on the ground, scene px */
72
+ x: number;
73
+ y: number;
74
+ prop: Prop;
75
+ /** px per metre (default 60, which makes a 1.7 m figure about 100 px tall) */
76
+ scale?: number;
77
+ /** Starting control values (default each control's default) */
78
+ values?: Record<string, number>;
79
+ look?: PropDrawOptions['look'];
80
+ ink?: string;
81
+ lineWidth?: number;
82
+ pencil?: PropDrawOptions['pencil'];
83
+ seed?: number;
84
+ /** `solid` (default) or `stick`: line art to go with stick figures */
85
+ style?: PropDrawOptions['style'];
86
+ /** The paper colour a stick prop is filled with */
87
+ paper?: string;
88
+ }
89
+ /** A `custom` target made by {@link propTarget}. */
90
+ export interface PropTarget extends CustomTarget {
91
+ readonly prop: Prop;
92
+ /** px per metre */
93
+ readonly propScale: number;
94
+ readonly propDraw: Omit<PropDrawOptions, 'time' | 'rider'>;
95
+ }
96
+ /** Every control a prop has, described: the common ones and its own. */
97
+ export declare function propControls(prop: Prop): Record<string, PropertyInfo & {
98
+ default?: number;
99
+ }>;
100
+ /**
101
+ * A `custom` canvas target that draws a prop, its middle standing at x, y.
102
+ * Its props are the prop's controls, so tracks turn it, squash it, spin its
103
+ * wheels; `describeTarget` lists them with what the prop can do.
104
+ */
105
+ export declare function propTarget(options: PropTargetOptions): PropTarget;
106
+ /** The prop solved for control values, in its own space (its middle on the ground at 0, 0). */
107
+ export declare function solveAt(prop: Prop, values: Record<string, number>, scale: number): SolvedProp;
108
+ export interface PropFrame {
109
+ /** Its control values in this frame */
110
+ values: Record<string, number>;
111
+ /** Where its middle stands, scene px */
112
+ origin: {
113
+ x: number;
114
+ y: number;
115
+ };
116
+ solved: SolvedProp;
117
+ /** An anchor in scene px, with its depth (nearer is larger) */
118
+ anchor(name: string): {
119
+ x: number;
120
+ y: number;
121
+ depth: number;
122
+ };
123
+ }
124
+ /** A prop target in a frame: its values from the timeline's state, where it stands, and its anchors in scene px. */
125
+ export declare function propAt(target: PropTarget, frame: Pick<FrameInfo, 'time' | 'state'>, id: string): PropFrame;
126
+ /** Draw a prop target as it is in a frame, for immediate-mode drawing; `rider` draws a figure seated in it. */
127
+ export declare function drawProp(ctx: CanvasRenderingContext2D, target: PropTarget, frame: Pick<FrameInfo, 'time' | 'state'>, id: string, options?: {
128
+ rider?: (ctx: CanvasRenderingContext2D) => void;
129
+ }): PropFrame;
@@ -1,3 +1,4 @@
1
+ import type { Cast } from './acting/custom';
1
2
  import type { CustomTarget } from '../adapters/canvas';
2
3
  import type { FrameInfo } from '../headless/video-scene';
3
4
  import type { EasingType, Track } from '../engine/types';
@@ -411,9 +412,9 @@ export type Dancer = (beat: number) => DanceFrame;
411
412
  * cycle (by `walking`), a dance (by `dancing`) and the chatter of `talk`
412
413
  * folded in, and the dance's hand shapes.
413
414
  */
414
- export declare function resolveStickFrame(props: StickFigureProps, time: number, dance?: Dancer): DanceFrame;
415
+ export declare function resolveStickFrame(props: StickFigureProps, time: number, dance?: Dancer, gaits?: Cast['gaits']): DanceFrame;
415
416
  /** The pose of {@link resolveStickFrame}. */
416
- export declare function resolveStickPose(props: StickFigureProps, time: number, dance?: Dancer): StickPose;
417
+ export declare function resolveStickPose(props: StickFigureProps, time: number, dance?: Dancer, gaits?: Cast['gaits']): StickPose;
417
418
  /** Prop names for a hand's pose fields on a stick-figure target: `hand.left.index.curl`, … */
418
419
  export declare const handProp: (side: StickSide, field: string) => string;
419
420
  export interface StickFigureTargetOptions {
@@ -428,6 +429,8 @@ export interface StickFigureTargetOptions {
428
429
  * (see `dancer()` and `danceTracks()`). Its hand shapes show when the style has `hands`.
429
430
  */
430
431
  dance?: Dancer;
432
+ /** Your own actions and gaits (see `defineAction`, `defineGait`): it draws the gaits, and lists the actions in `about` */
433
+ cast?: Cast;
431
434
  }
432
435
  /** A `custom` target made by {@link stickFigureTarget}. */
433
436
  export interface StickFigureTarget extends CustomTarget {
@@ -435,6 +438,8 @@ export interface StickFigureTarget extends CustomTarget {
435
438
  readonly figureStyle: StickStyle;
436
439
  /** The dance it plays, if any */
437
440
  readonly figureDance?: Dancer;
441
+ /** Its cast's own gaits, if any */
442
+ readonly figureGaits?: Cast['gaits'];
438
443
  }
439
444
  /**
440
445
  * A `custom` canvas target that draws a stick figure. Its props are the pose
@@ -5,3 +5,4 @@ export * from './narration';
5
5
  export * from './beats';
6
6
  export * from './camera-shots';
7
7
  export * from './did-you-mean';
8
+ export * from './spring-follow';
@@ -0,0 +1,25 @@
1
+ import type { Keyframe } from '../types';
2
+ /**
3
+ * Follow-through as keyframes: a value that chases another on a spring, so a
4
+ * secondary part lags behind and overshoots a primary one — a car's antenna
5
+ * after the car, leaves after a branch, a load on a truck.
6
+ *
7
+ * const chase = springFollow((t) => valueOf(xTrack, t), { start: 0, end: 4000 })
8
+ * // the antenna's bend is how far the follower is behind: (chase − x) × k
9
+ *
10
+ * The spring is stepped in fixed 1 ms steps from `start`, so the same input
11
+ * always gives the same keys. It starts at rest on the primary's value.
12
+ */
13
+ export interface SpringFollowOptions {
14
+ /** From and to, ms */
15
+ start: number;
16
+ end: number;
17
+ /** Key spacing, ms (default 33) */
18
+ step?: number;
19
+ /** Spring stiffness (default 120): higher follows more tightly */
20
+ stiffness?: number;
21
+ /** Damping (default 9): lower wobbles longer */
22
+ damping?: number;
23
+ mass?: number;
24
+ }
25
+ export declare function springFollow(primary: (time: number) => number, options: SpringFollowOptions): Keyframe<number>[];
@@ -2,7 +2,7 @@ import type { Mat4, Vec3 } from '../engine/math';
2
2
  import type { AnimatableValue } from '../engine/types';
3
3
  import type { Material3D, Object3D } from './scene-types';
4
4
  import type { PreparedMesh } from './load-scene';
5
- import type { ResolvedCamera, ResolvedScene3D, ScreenPoint } from './resolve-scene';
5
+ import type { ResolvedCamera, ResolvedLight, ResolvedScene3D, ScreenPoint } from './resolve-scene';
6
6
  /**
7
7
  * A kind of scene object beyond the built-in meshes, lights and cameras,
8
8
  * added when a scene is loaded: characters come this way, from the
@@ -40,6 +40,9 @@ export interface ObjectContext {
40
40
  /** Its world matrix */
41
41
  world: Mat4;
42
42
  camera: ResolvedCamera;
43
+ /** The scene's lights (empty when it brings none), and its fog: for kinds that light what they draw as the meshes are */
44
+ lights: ResolvedLight[];
45
+ fog?: ResolvedScene3D['fog'];
43
46
  /** Canvas size, px */
44
47
  width: number;
45
48
  height: number;