@algorisys/tinyfly 0.94.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 (54) hide show
  1. package/README.md +6 -6
  2. package/docs/acting.md +5 -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 +17 -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 +5329 -2337
  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 +7108 -4061
  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/capabilities.d.ts +17 -0
  22. package/lib/types/characters/character-script-3d.d.ts +80 -0
  23. package/lib/types/characters/character.d.ts +19 -0
  24. package/lib/types/characters/ground-path.d.ts +32 -0
  25. package/lib/types/characters/index.d.ts +3 -0
  26. package/lib/types/characters/props/clip.d.ts +5 -0
  27. package/lib/types/characters/props/draw.d.ts +60 -0
  28. package/lib/types/characters/props/effects.d.ts +12 -0
  29. package/lib/types/characters/props/families/aircraft.d.ts +37 -0
  30. package/lib/types/characters/props/families/animals.d.ts +156 -0
  31. package/lib/types/characters/props/families/birds.d.ts +86 -0
  32. package/lib/types/characters/props/families/environment.d.ts +71 -0
  33. package/lib/types/characters/props/families/vehicle.d.ts +129 -0
  34. package/lib/types/characters/props/hidden.d.ts +49 -0
  35. package/lib/types/characters/props/index.d.ts +23 -0
  36. package/lib/types/characters/props/mesh-3d.d.ts +24 -0
  37. package/lib/types/characters/props/presets.d.ts +34 -0
  38. package/lib/types/characters/props/ride-3d.d.ts +71 -0
  39. package/lib/types/characters/props/ride.d.ts +79 -0
  40. package/lib/types/characters/props/rig.d.ts +224 -0
  41. package/lib/types/characters/props/scene-objects.d.ts +2 -0
  42. package/lib/types/characters/props/script-3d.d.ts +85 -0
  43. package/lib/types/characters/props/script.d.ts +145 -0
  44. package/lib/types/characters/props/shapes.d.ts +96 -0
  45. package/lib/types/characters/props/slice.d.ts +66 -0
  46. package/lib/types/characters/props/target.d.ts +129 -0
  47. package/lib/types/engine/authoring/index.d.ts +1 -0
  48. package/lib/types/engine/authoring/spring-follow.d.ts +25 -0
  49. package/lib/types/scene-3d/object-kind.d.ts +4 -1
  50. package/lib/types/scene-3d/scene-types.d.ts +41 -1
  51. package/llms-full.txt +428 -9
  52. package/llms.txt +28 -27
  53. package/package.json +1 -1
  54. package/skills/tinyfly/SKILL.md +8 -0
@@ -0,0 +1,79 @@
1
+ import type { Track } from '../../engine/types';
2
+ import { type PropTarget } from './target';
3
+ /**
4
+ * Riding: a figure carried by a prop, its feet kept where a seat anchor puts
5
+ * them as the prop drives, bumps and turns toward the camera. Like
6
+ * `code.ride()`, it reads the prop's tracks and writes the figure's.
7
+ *
8
+ * ```ts
9
+ * const ride = propRide({ prop: carTarget, propId: 'car', propTracks: carScript.tracks, anchor: 'seat',
10
+ * figure: { x: 80, y: 300 }, figureId: 'hero', start: 2400, end: 9000, offset: { y: seatHeight(100) } })
11
+ * const heroTracks = spliceTracks(heroScript.tracks, ride, { from: 2400, to: 9000 })
12
+ * ```
13
+ */
14
+ export interface PropRideOptions {
15
+ prop: PropTarget;
16
+ /** The prop target's id in the scene */
17
+ propId: string;
18
+ /** The prop's tracks (its script's) */
19
+ propTracks: Track[];
20
+ /** The anchor the figure rides at (`seat`) */
21
+ anchor: string;
22
+ /** Where the figure was placed (its feet), scene px: its tracks are offsets from here */
23
+ figure: {
24
+ x: number;
25
+ y: number;
26
+ };
27
+ /** The figure target's id */
28
+ figureId: string;
29
+ /** From and to, ms */
30
+ start: number;
31
+ end: number;
32
+ /** Where the figure's feet are from the anchor, px (a seated stick figure: `{ y: seatHeight(height) }`, so its hips are on the seat) */
33
+ offset?: {
34
+ x?: number;
35
+ y?: number;
36
+ };
37
+ /** Also turn the figure with the prop: its `turn` and `facing` (default true) */
38
+ turn?: boolean;
39
+ /** Sample spacing, ms (default 33) */
40
+ every?: number;
41
+ }
42
+ /** The figure's `x` and `y` (and `turn`, `facing`) tracks while it rides. */
43
+ export declare function propRide(options: PropRideOptions): Track[];
44
+ /**
45
+ * `base` tracks with `replacement` keys taking over between `from` and `to`
46
+ * ms, property by property: keys of `base` inside the window are dropped,
47
+ * and the replacement's are spliced in (a figure's script, with a ride in the
48
+ * middle). Properties only in `replacement` are added.
49
+ */
50
+ export declare function spliceTracks(base: Track[], replacement: Track[], window: {
51
+ from: number;
52
+ to: number;
53
+ }): Track[];
54
+ /**
55
+ * Towing: a prop pulled by another (a cart behind a horse, a trailer behind
56
+ * a car). The towed prop turns with the leader and keeps its own anchor
57
+ * (`shafts`) on the leader's (`hitch`); its wheels roll exactly the distance
58
+ * it covers. Returns its `x`, `turn` and `wheelSpin` tracks.
59
+ *
60
+ * ```ts
61
+ * const cartTracks = propTow({ leader: horseTarget, leaderId: 'horse', leaderTracks: horseScript.tracks, hitch: 'hitch',
62
+ * towed: cartTarget, towedId: 'cart', anchor: 'shafts', start: 0, end: horseScript.duration })
63
+ * ```
64
+ */
65
+ export interface PropTowOptions {
66
+ leader: PropTarget;
67
+ leaderId: string;
68
+ leaderTracks: Track[];
69
+ /** The leader's anchor the towed prop hangs on */
70
+ hitch: string;
71
+ towed: PropTarget;
72
+ towedId: string;
73
+ /** The towed prop's anchor that meets the hitch */
74
+ anchor: string;
75
+ start: number;
76
+ end: number;
77
+ every?: number;
78
+ }
79
+ export declare function propTow(options: PropTowOptions): Track[];
@@ -0,0 +1,224 @@
1
+ import { type Mat4, type Vec3 } from '../../engine/math';
2
+ import type { Point } from '../../adapters/canvas/sketch';
3
+ import type { PropertyInfo } from '../../adapters/canvas/target-properties';
4
+ import { type ViewProjection } from '../rig/skeleton';
5
+ import { type Mesh, type PropShape } from './shapes';
6
+ /**
7
+ * A prop's rig: parts on pivots, controls that move them, and anchors where
8
+ * other things attach (a seat, a door handle). Like a character's body plan,
9
+ * it is plain data; `solveProp` poses it with control values and projects it
10
+ * through a view, the same `ViewProjection` contract the v2 human is drawn
11
+ * with, so a car turns toward the camera the way a character does.
12
+ *
13
+ * Prop space: +y up (the ground is y = 0), +z the way the prop faces, +x its
14
+ * left. Units are metres.
15
+ */
16
+ export interface PropPart {
17
+ id: string;
18
+ /** The part it hangs from (its `at` is in that part's space); default the prop itself */
19
+ parent?: string;
20
+ shape: PropShape;
21
+ /** Where its origin sits in its parent's space (default 0, 0, 0) */
22
+ at?: Vec3;
23
+ /** Turned about its origin as built, degrees about x, then y, then z (a head tipped down from its neck) */
24
+ rotate?: Vec3;
25
+ /** Fill colour (none when omitted) */
26
+ fill?: string;
27
+ /** Outline colour (default the prop's ink) */
28
+ ink?: string;
29
+ /** Outline weight, × the prop's line width (default 1; 0 draws no outline) */
30
+ outline?: number;
31
+ /** Drawn after a rider (a figure in a seat or a doorway), so it covers the rider: a car's doors, a house's door */
32
+ overRider?: boolean;
33
+ /** A rider shows through it: glass, an open doorway. A rider is clipped to these, so the rest of the prop hides it */
34
+ seeThrough?: boolean;
35
+ /** Left out of the stick look (line art): rounding that only the solid look needs, such as knee joints */
36
+ solidOnly?: boolean;
37
+ /**
38
+ * Where parts sit into each other, which one is drawn over in a 3D scene
39
+ * (default 0): a cabin sitting down into a car's body is drawn over it (1).
40
+ * Seen in perspective from anywhere, overlapping parts can't always be
41
+ * ordered by depth; this says how they overlap.
42
+ */
43
+ layer?: number;
44
+ /** The fill blends toward this colour as the control goes 0 → 1: lights, lit windows */
45
+ glow?: {
46
+ control: string;
47
+ color: string;
48
+ };
49
+ /** Its opacity follows a control: `from` at 0, `to` at 1 (a rotor disc that appears as the blades blur) */
50
+ fade?: {
51
+ control: string;
52
+ from: number;
53
+ to: number;
54
+ };
55
+ }
56
+ /** How a control moves parts: per unit of the control's value. */
57
+ export interface ControlBinding {
58
+ parts: string[];
59
+ /** Turn about an axis through `pivot` (in the part's space), `degrees` per unit */
60
+ rotate?: {
61
+ axis: 'x' | 'y' | 'z';
62
+ degrees: number;
63
+ pivot?: Vec3;
64
+ };
65
+ /** Move by this much per unit, metres */
66
+ translate?: Vec3;
67
+ /** Scale toward this at 1 (1 + (s − 1) × value), about the part's origin */
68
+ scale?: Vec3;
69
+ }
70
+ export interface ControlSpec extends PropertyInfo {
71
+ /** Its value before anything moves it (default 0) */
72
+ default?: number;
73
+ bind?: ControlBinding[];
74
+ }
75
+ export interface PropAnchor {
76
+ /** The part it moves with (default the prop itself) */
77
+ part?: string;
78
+ at: Vec3;
79
+ }
80
+ export interface PropRig {
81
+ parts: PropPart[];
82
+ /** The prop's own controls; every prop also has the common ones (`PROP_COMMON_CONTROLS`) */
83
+ controls: Record<string, ControlSpec>;
84
+ anchors?: Record<string, PropAnchor>;
85
+ /** Front to back and its height, metres: the size of its box */
86
+ length: number;
87
+ height: number;
88
+ /** Its footprint on the ground, across and front to back, metres, for its contact shadow (default 45% of its length across, its length) */
89
+ footprint?: [number, number];
90
+ /**
91
+ * Controls worked out from the others before the rig is posed, returned to
92
+ * replace them: an animal's leg angles, its own pose (a rear's tucked front
93
+ * legs) plus its stride from its gait and phase. Pure: the same values
94
+ * always give the same result.
95
+ */
96
+ derive?: (values: Record<string, number>) => Record<string, number>;
97
+ }
98
+ /** Controls every prop has: how it is seen, and how its whole body squashes, tips and leans. */
99
+ export declare const PROP_COMMON_CONTROLS: Record<string, ControlSpec>;
100
+ /** A view of a prop: turned by `turn`, looked down on by `tilt`, drawn at `scale` px per metre (feet at 0, 0; up is −y). */
101
+ export declare function propView(turn: number, tilt: number, scale: number): ViewProjection;
102
+ export interface SolveOptions {
103
+ /**
104
+ * The view is a perspective camera's (a 3D scene's), with the eye at the
105
+ * view's origin looking down −z: faces are seen when they turn toward the
106
+ * eye, not just toward +z.
107
+ */
108
+ perspective?: boolean;
109
+ /**
110
+ * With `perspective`: the camera's near plane, metres in front of the eye.
111
+ * What is nearer than that (or behind the eye) is cut away before it is
112
+ * projected, so a camera close to a prop, or inside it, sees it rightly.
113
+ */
114
+ near?: number;
115
+ /**
116
+ * Cut the prop into columns about this many metres across (`cells`),
117
+ * each with its own depth: for drawing it among other things, a column at
118
+ * a time (a 3D scene). Off by default.
119
+ */
120
+ slice?: number;
121
+ /**
122
+ * Light each seen face as a scene would: given its middle and outward
123
+ * normal in the prop's space, the light reaching it (RGB, 1 is full light)
124
+ * and how much fog covers it. Without it, faces are shaded by a light that
125
+ * follows the camera (`tone`).
126
+ */
127
+ light?: (middle: Vec3, normal: Vec3) => {
128
+ light: [number, number, number];
129
+ fog: number;
130
+ };
131
+ }
132
+ /** A seen face, ready to draw. */
133
+ export interface SolvedFace {
134
+ points: Point[];
135
+ /** Nearer is larger */
136
+ depth: number;
137
+ /** Lit (1.05) to shaded (0.72), from how it faces the light */
138
+ tone: number;
139
+ /** With `slice`: the outlines that belong to this face (it is the nearest seen face beside them) */
140
+ edges?: Point[][];
141
+ /** With `slice`: the marks drawn on this face (a wheel's spokes) */
142
+ marks?: Point[][];
143
+ /** With `light`: the light reaching it (RGB, 1 is full light) and how much fog covers it, 0..1 */
144
+ light?: [number, number, number];
145
+ fog?: number;
146
+ /** With `slice`: its middle and its normal, in view space (to find the face a panel lies on) */
147
+ center?: Vec3;
148
+ normal?: Vec3;
149
+ }
150
+ export interface SolvedPart {
151
+ part: PropPart;
152
+ /** Nearer is larger */
153
+ depth: number;
154
+ /** Seen faces, far to near */
155
+ faces: SolvedFace[];
156
+ /** Outlines (silhouette and creases), chained into strokes */
157
+ edges: Point[][];
158
+ /** Marks that move with it (spokes) */
159
+ marks: Point[][];
160
+ /** How lit its glow is, 0..1 */
161
+ glow: number;
162
+ /** How opaque it is, 0..1 */
163
+ opacity: number;
164
+ /** A tube's centre line on screen, for drawing it as a single stroke (the stick look) */
165
+ spine?: Point[];
166
+ /** A piece cut from its part at column walls (with `slice`): its faces meet the next piece's along the cuts */
167
+ cut?: boolean;
168
+ }
169
+ export interface SolvedProp {
170
+ /** Parts far to near, those drawn under a rider first */
171
+ under: SolvedPart[];
172
+ over: SolvedPart[];
173
+ anchors: Record<string, {
174
+ point: Point;
175
+ depth: number;
176
+ }>;
177
+ /** Where a rider shows through: the seen faces of its see-through parts (glass, doorways), in drawing space */
178
+ openings: Point[][];
179
+ /** Its contact shadow: an ellipse on the ground under it, smaller and fainter as it lifts */
180
+ shadow: {
181
+ points: Point[];
182
+ opacity: number;
183
+ };
184
+ /**
185
+ * With `slice`: the prop cut into columns, each with its depth (nearer is
186
+ * larger) and its pieces in drawing order, for drawing column by column
187
+ * among other things
188
+ */
189
+ cells?: Array<{
190
+ depth: number;
191
+ parts: SolvedPart[];
192
+ }>;
193
+ /** Screen px per metre at the prop */
194
+ pxPerUnit: number;
195
+ /** How tall the prop is on screen, px (its outlines are weighted by it) */
196
+ sizePx: number;
197
+ }
198
+ /** A shape's mesh, built once (shared, so caches keyed by it hold). */
199
+ export declare const propShapeMesh: (shape: PropShape) => Mesh;
200
+ /** A control's value: the given one, else its default. */
201
+ export declare function controlValue(rig: PropRig, values: Record<string, number>, name: string): number;
202
+ /**
203
+ * The prop posed with control values and seen through a view: its parts'
204
+ * seen faces, outlines and marks, sorted far to near, and its anchors.
205
+ */
206
+ export declare function solveProp(rig: PropRig, given: Record<string, number>, view: ViewProjection, scale: number, options?: SolveOptions): SolvedProp;
207
+ /**
208
+ * Its parts placed in its own 3D space (metres), with its controls applied
209
+ * (derived ones too), and how much each glows and shows: for drawing them as
210
+ * a scene's meshes.
211
+ */
212
+ export declare function propPartsInSpace(rig: PropRig, given: Record<string, number>): Array<{
213
+ part: PropPart;
214
+ matrix: Mat4;
215
+ local: Mat4;
216
+ glow: number;
217
+ opacity: number;
218
+ }>;
219
+ /**
220
+ * Its anchors in its own 3D space, metres (+y up from the ground, +z its
221
+ * front), with its controls applied (a horse's stride bobbing its saddle,
222
+ * a car's pitch): where a rider sits in a 3D scene.
223
+ */
224
+ export declare function propAnchors3D(rig: PropRig, given: Record<string, number>): Record<string, Vec3>;
@@ -0,0 +1,2 @@
1
+ import type { ObjectKind } from '../../scene-3d/object-kind';
2
+ export declare const propObjects: ObjectKind;
@@ -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[];