@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,129 @@
1
+ import type { Vec3 } from '../../../engine/math';
2
+ import type { ActingRig } from '../../acting/acting';
3
+ import type { PropPart, PropAnchor } from '../rig';
4
+ import type { Prop } from '../target';
5
+ /**
6
+ * Wheeled vehicles: a body from a side profile, an optional cabin of glass,
7
+ * wheels that turn by exactly the distance driven (no skating), doors on
8
+ * hinges, lights and an antenna that trails the motion. `car()` is a preset;
9
+ * trucks, buses, tractors and carts are the same family with other settings.
10
+ *
11
+ * Its actions: `drive` (a rock back, a lunge, a nose-dive stop that settles),
12
+ * `brake` (a skid with the wheels locked), `bump`, `honk`, `door`, `lights`,
13
+ * plus `turn` and `hold`, which every prop has.
14
+ */
15
+ export interface VehicleSpec {
16
+ kind?: string;
17
+ summary?: string;
18
+ /** Body side profile: (forward, up) points round its outline, metres (its middle is forward 0); none for a bike, which is all frame */
19
+ body?: Array<[number, number]>;
20
+ /** Body width, metres */
21
+ width: number;
22
+ /** Frame tubes (a bike's, a cart's shafts): points in prop space, and a radius */
23
+ frame?: Array<{
24
+ points: Vec3[];
25
+ radius?: number;
26
+ color?: string;
27
+ }>;
28
+ /** Windows along both sides: forward range and height range */
29
+ windows?: Array<{
30
+ from: number;
31
+ to: number;
32
+ low: number;
33
+ high: number;
34
+ }>;
35
+ /** Anything else, as parts (a cargo box, a seat, a lamp) */
36
+ extras?: PropPart[];
37
+ /** A cabin of glass on top: its side profile, and its width (default 85% of the body's) */
38
+ cabin?: {
39
+ profile: Array<[number, number]>;
40
+ width?: number;
41
+ pillars?: number[];
42
+ };
43
+ /**
44
+ * Wheels: forward position, how far each side of the middle (both sides get
45
+ * one; `side: 0` puts one wheel on the middle line, as on a bike), radius and
46
+ * thickness. `style`: `hub` a hubcap with spokes (default), `spoked` thin
47
+ * wire or wooden spokes and no hub (bikes, carts).
48
+ */
49
+ wheels: Array<{
50
+ forward: number;
51
+ side: number;
52
+ radius: number;
53
+ thickness?: number;
54
+ style?: 'hub' | 'spoked';
55
+ }>;
56
+ /** Its usual driving speed in a 3D scene, metres per second (default 6) */
57
+ speed?: number;
58
+ /** Doors on each side: forward range and height range, metres; hinged at the front */
59
+ door?: {
60
+ from: number;
61
+ to: number;
62
+ low: number;
63
+ high: number;
64
+ };
65
+ /** Headlights and tail lights: across positions, height range, and the front and back faces' forward position */
66
+ lights?: {
67
+ across: number;
68
+ low: number;
69
+ high: number;
70
+ front: number;
71
+ back: number;
72
+ size?: number;
73
+ };
74
+ /** A whip antenna on the roof, trailing the motion: where it stands (across, up, forward) */
75
+ antenna?: Vec3;
76
+ /** Where a driver sits (across, seat height, forward) */
77
+ seat?: Vec3;
78
+ /** More anchors (a cart's shaft tips, where it hitches to a horse) */
79
+ anchors?: Record<string, PropAnchor>;
80
+ colors?: {
81
+ body?: string;
82
+ trim?: string;
83
+ glass?: string;
84
+ tyre?: string;
85
+ hub?: string;
86
+ light?: string;
87
+ tail?: string;
88
+ inside?: string;
89
+ seat?: string;
90
+ };
91
+ }
92
+ /** A wheeled vehicle from a spec: the family's rig, actions and acting. */
93
+ export declare function vehicle(spec: VehicleSpec): Prop;
94
+ /** How a vehicle's controls act: the turn and lift lead, the body's pitch and squash follow, doors and antenna trail. */
95
+ export declare const VEHICLE_ACTING: ActingRig;
96
+ /** A cartoon car: a rounded red body, a glass cabin, four wheels, doors, lights, a whip antenna and a driver's seat. */
97
+ export declare function car(options?: {
98
+ colors?: VehicleSpec['colors'];
99
+ antenna?: boolean;
100
+ }): Prop;
101
+ /** A box truck: a cab with a glass windscreen, a cargo box, and two rear axles. */
102
+ export declare function truck(options?: {
103
+ colors?: VehicleSpec['colors'];
104
+ cargo?: string;
105
+ }): Prop;
106
+ /** A bus: a long box with a row of windows down each side and a front door. */
107
+ export declare function bus(options?: {
108
+ colors?: VehicleSpec['colors'];
109
+ }): Prop;
110
+ /** A tractor: big rear wheels, small front ones, a narrow hood, a glass cab and an exhaust stack. */
111
+ export declare function tractor(options?: {
112
+ colors?: VehicleSpec['colors'];
113
+ }): Prop;
114
+ /** A wooden cart: a plank bed on one axle of big spoked wheels, with shafts for a horse (or a figure) to pull. */
115
+ export declare function cart(options?: {
116
+ colors?: VehicleSpec['colors'];
117
+ }): Prop;
118
+ /** A railway carriage: a long body with a rounded roof, windows down the sides and bogie wheels. */
119
+ export declare function trainCar(options?: {
120
+ colors?: VehicleSpec['colors'];
121
+ }): Prop;
122
+ /** A bicycle: a wire-spoked pair of wheels on a diamond frame, a saddle and handlebars. */
123
+ export declare function bike(options?: {
124
+ colors?: VehicleSpec['colors'];
125
+ }): Prop;
126
+ /** A motorbike: a tank and saddle, an engine block, forks, handlebars and a headlight. */
127
+ export declare function motorbike(options?: {
128
+ colors?: VehicleSpec['colors'];
129
+ }): Prop;
@@ -0,0 +1,49 @@
1
+ import { type Mat4, type Vec3 } from '../../engine/math';
2
+ import type { Mesh } from './shapes';
3
+ /**
4
+ * Faces no one can see: inside another solid part of the same prop, or lying
5
+ * against one of its faces (a house's wall tops under its roof, a car body's
6
+ * top under its cabin, a tyre's tread inside the fender, the top of a leg
7
+ * inside a horse's barrel). Drawn face by face among other things (a 3D
8
+ * scene), such faces would show wherever the order of the faces in front is
9
+ * not exact; left out, their edges become outlines where the parts meet.
10
+ * Only whole faces are left out: where a part sits partly into another (a
11
+ * cabin into a car's body), its `layer` says which is drawn over.
12
+ *
13
+ * Only convex closed shapes hide faces (boxes, cylinders, ellipsoids, convex
14
+ * profiles): for them, inside is behind every face's plane.
15
+ */
16
+ export interface Solid {
17
+ part: string;
18
+ /** Where it is (its placement's cache key) */
19
+ key: string;
20
+ planes: Array<{
21
+ normal: Vec3;
22
+ offset: number;
23
+ }>;
24
+ low: Vec3;
25
+ high: Vec3;
26
+ }
27
+ /** The prop's convex solid parts, from their meshes placed in one space (with their bounds there). */
28
+ export declare function solidsOf(parts: Array<{
29
+ part: string;
30
+ key: string;
31
+ mesh: Mesh;
32
+ inSpace: Mesh;
33
+ low: Vec3;
34
+ high: Vec3;
35
+ }>): Solid[];
36
+ /**
37
+ * Whether a face of `part` (its corners and outward normal, in the prop's
38
+ * space) is hidden by another solid: all of it inside, or on one of its faces
39
+ * and facing into it. A face may stick a little out past a side it stands
40
+ * across (a tyre's tread past a car's side), not past one it lies along (a
41
+ * door on a car's side shows).
42
+ */
43
+ export declare function isHidden(part: string, corners: Vec3[], normal: Vec3, solids: Solid[]): boolean;
44
+ /**
45
+ * Which faces of a part (or a cut piece of one) are hidden, by face index,
46
+ * with `local` placing its mesh among `solids`. Cached by where it and the
47
+ * solids are, so a prop that holds still pays for this once.
48
+ */
49
+ export declare function hiddenFaces(part: string, mesh: Mesh, local: Mat4, localKey: string, solids: Solid[]): boolean[];
@@ -0,0 +1,23 @@
1
+ /**
2
+ * Props: everyday objects with behaviours, for stories with the stick figure
3
+ * and the v2 character. A prop is a 3D rig of simple parts on pivots with
4
+ * named controls, seen through the same kind of view as a character (so it
5
+ * turns toward the camera), drawn with the characters' pens (clean, pencil,
6
+ * silhouette), and acted from beats through the same acting pass.
7
+ */
8
+ export * from './shapes';
9
+ export * from './rig';
10
+ export * from './draw';
11
+ export * from './target';
12
+ export * from './script';
13
+ export * from './effects';
14
+ export * from './families/vehicle';
15
+ export * from './ride';
16
+ export * from './families/environment';
17
+ export * from './families/aircraft';
18
+ export * from './families/animals';
19
+ export * from './families/birds';
20
+ export * from './presets';
21
+ export * from './scene-objects';
22
+ export * from './script-3d';
23
+ export * from './ride-3d';
@@ -0,0 +1,24 @@
1
+ import { type Mat4 } from '../../engine/math';
2
+ import { type PreparedMesh } from '../../scene-3d/load-scene';
3
+ import type { PlacedMesh } from '../../scene-3d/object-kind';
4
+ import type { Material3D } from '../../scene-3d/scene-types';
5
+ import { type PropPart, type SolvedPart } from './rig';
6
+ import type { Prop } from './target';
7
+ import type { PropShape } from './shapes';
8
+ /**
9
+ * A part's shape as a scene mesh: its faces fanned into triangles, wound so
10
+ * they face the way the face does, leaving out the faces `hidden` says no
11
+ * one can see (inside or against another part).
12
+ */
13
+ export declare function propPartMesh(shape: PropShape, hidden?: boolean[]): PreparedMesh;
14
+ export interface PropMeshLook {
15
+ /** How it is lit (default toon) */
16
+ shading?: Material3D['shading'];
17
+ /** Outline colour (default near-black), and width in px (default 2; × each part's `outline`) */
18
+ ink?: string;
19
+ outline?: number;
20
+ }
21
+ /** How a part looks as a mesh: its fill, lit; its glow as light of its own; glass see-through; faded as it fades. */
22
+ export declare function propPartMaterial(part: PropPart, solved: Pick<SolvedPart, 'glow' | 'opacity'>, look?: PropMeshLook): Material3D;
23
+ /** Its contact shadow as a mesh: a soft dark ellipse on the ground under it, smaller and fainter as it lifts. */
24
+ export declare function propShadowMesh(prop: Prop, values: Record<string, number>, world: Mat4): PlacedMesh;
@@ -0,0 +1,34 @@
1
+ import type { Prop } from './target';
2
+ import { car, truck, bus, tractor, cart, trainCar, bike, motorbike } from './families/vehicle';
3
+ import { tree, house } from './families/environment';
4
+ import { helicopter, airplane } from './families/aircraft';
5
+ import { horse, dog, cat, cow } from './families/animals';
6
+ import { songbird, crow, chicken } from './families/birds';
7
+ /**
8
+ * Every prop preset by name, so a prop can be named in plain data (a 3D
9
+ * scene's `{ kind: 'prop', prop: 'car' }`, the catalog).
10
+ */
11
+ export declare const PROP_PRESETS: {
12
+ car: typeof car;
13
+ truck: typeof truck;
14
+ bus: typeof bus;
15
+ tractor: typeof tractor;
16
+ cart: typeof cart;
17
+ trainCar: typeof trainCar;
18
+ bike: typeof bike;
19
+ motorbike: typeof motorbike;
20
+ tree: typeof tree;
21
+ house: typeof house;
22
+ helicopter: typeof helicopter;
23
+ airplane: typeof airplane;
24
+ horse: typeof horse;
25
+ dog: typeof dog;
26
+ cat: typeof cat;
27
+ cow: typeof cow;
28
+ songbird: typeof songbird;
29
+ crow: typeof crow;
30
+ chicken: typeof chicken;
31
+ };
32
+ export type PropPresetName = keyof typeof PROP_PRESETS;
33
+ /** A preset by name, with its options (colours, sizes); throws on a name it does not know, with the one probably meant. */
34
+ export declare function propPreset(name: string, options?: Record<string, unknown>): Prop;
@@ -0,0 +1,71 @@
1
+ import type { Track } from '../../engine/types';
2
+ import type { Vec3 } from '../../engine/math';
3
+ import type { Pose } from '../rig/body-plan';
4
+ import { type CharacterOptions } from '../character';
5
+ import type { Prop } from './target';
6
+ /**
7
+ * Riding in a 3D scene: a character carried by a prop, its hips kept on a
8
+ * seat anchor (a horse's `saddle`, a cart's or a bike's `seat`) as the prop
9
+ * moves, turns, bobs with its stride and pitches. Like `propRide` in 2D, it
10
+ * reads the prop's tracks (from `propScript3D`) and writes the rider's `x`,
11
+ * `y`, `z` and `rotateY`; `spliceTracks` puts them into the rider's own
12
+ * script for the stretch it rides.
13
+ *
14
+ * ```js
15
+ * const ride = propRide3D({ prop: horse(), propId: 'horse', propTracks: horseScript.tracks, scene: 'village',
16
+ * placement: { position: [-1, 0, 3] }, anchor: 'saddle', riderId: 'tum', pose: RIDING_POSES.astride,
17
+ * start: 2000, end: horseScript.duration })
18
+ * const tumTracks = spliceTracks(tumScript.tracks, ride, { from: 2000, to: horseScript.duration })
19
+ * ```
20
+ *
21
+ * Seat the rider in the pose given (the rider's own pose tracks should hold
22
+ * it too). The rider is drawn part by part among the prop's parts, so a leg
23
+ * astride a horse shows on each side of it.
24
+ */
25
+ export interface PropRide3DOptions {
26
+ prop: Prop;
27
+ /** The prop's object id in the scene */
28
+ propId: string;
29
+ /** The prop's tracks (its `propScript3D` tracks) */
30
+ propTracks: Track[];
31
+ scene: string;
32
+ /** Where the prop's object was placed, as in the scene JSON: its position, its rotation about y, its control values */
33
+ placement?: {
34
+ position?: Vec3;
35
+ heading?: number;
36
+ values?: Record<string, number>;
37
+ };
38
+ /** The anchor the rider sits on (`saddle`, `seat`) */
39
+ anchor: string;
40
+ /** The rider's object id */
41
+ riderId: string;
42
+ /** From and to, ms */
43
+ start: number;
44
+ end: number;
45
+ /** The pose it rides in (default sitting): its hips go on the anchor */
46
+ pose?: Pose;
47
+ /** The rider's look and build (its object's `character`), and height in metres (default 1.7) */
48
+ character?: CharacterOptions;
49
+ height?: number;
50
+ /** Which way it faces from the prop's way, degrees (default 0: the way the prop faces) */
51
+ facing?: number;
52
+ /** Getting on: hops up onto the seat from this point on the ground, [x, z] metres, over `for` ms (default 450) */
53
+ mount?: {
54
+ from: [number, number];
55
+ for?: number;
56
+ };
57
+ /** Getting off: hops down from the seat to this point on the ground, over `for` ms (default 450) */
58
+ dismount?: {
59
+ to: [number, number];
60
+ for?: number;
61
+ };
62
+ /** Sample spacing, ms (default 33) */
63
+ every?: number;
64
+ }
65
+ /** Riding poses for a human: on a seat, and astride a saddle (legs apart round a horse's barrel). */
66
+ export declare const RIDING_POSES: {
67
+ seated: Pose;
68
+ astride: Pose;
69
+ };
70
+ /** The rider's `x`, `y`, `z` and `rotateY` tracks while it rides (see the module's notes). */
71
+ export declare function propRide3D(options: PropRide3DOptions): Track[];
@@ -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;