@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,156 @@
1
+ import type { Vec3 } from '../../../engine/math';
2
+ import type { ActingRig } from '../../acting/acting';
3
+ import type { PropAnchor, PropPart } from '../rig';
4
+ import type { PropAction, PropActionContext } from '../script';
5
+ import type { Prop } from '../target';
6
+ /**
7
+ * Four-legged animals. Each is a prop: a body, a neck and head, four jointed
8
+ * legs and a tail, seen from any side like the vehicles. `quadruped(spec)`
9
+ * builds one from proportions; `horse()`, `dog()`, `cat()` and `cow()` are
10
+ * presets.
11
+ *
12
+ * Their legs are worked out by the rig's `derive` from the gait (`gait`) and
13
+ * the phase of the stride (`walk`): each gait has its own footfall pattern,
14
+ * and the phase is keyed in step with the distance covered, so the feet keep
15
+ * pace with the ground.
16
+ *
17
+ * Gaits (`gait`): 0 walk (four beats), 1 trot (diagonal pairs), 2 canter
18
+ * (three beats, the body rocking), 3 gallop. A species has the ones it uses.
19
+ */
20
+ export declare const ANIMAL_GAITS: readonly ["walk", "trot", "canter", "gallop"];
21
+ export type AnimalGait = (typeof ANIMAL_GAITS)[number];
22
+ /** The horse's gaits are all of them; kept as its own name for clarity. */
23
+ export declare const HORSE_GAITS: readonly ["walk", "trot", "canter", "gallop"];
24
+ export type HorseGait = AnimalGait;
25
+ /** How a species is built: proportions in metres, its colours, its gaits, its voice and its own actions. */
26
+ export interface QuadrupedSpec {
27
+ kind: string;
28
+ summary: string;
29
+ legs: {
30
+ /** Hip to knee, knee to foot, and the foot's height */
31
+ upper: number;
32
+ lower: number;
33
+ foot: number;
34
+ /** Foot (hoof, paw) across and front to back */
35
+ footSize: [number, number];
36
+ /** Front and hind hips: forward position; how far each side of the middle */
37
+ front: number;
38
+ hind: number;
39
+ across: number;
40
+ /** Leg radius at the hip (front, hind) and below the knee */
41
+ thickness: [number, number];
42
+ lowerThickness: number;
43
+ };
44
+ /** Body radii (across, up, front to back), and how far its middle sits above the hips */
45
+ body: {
46
+ radii: Vec3;
47
+ rise: number;
48
+ };
49
+ /** The neck: where it starts (prop space) and its line, and its radius */
50
+ neck: {
51
+ at: Vec3;
52
+ points: Vec3[];
53
+ radius: number;
54
+ };
55
+ /** The head, on the neck's end: where (neck space), its radii, how it is tipped */
56
+ head: {
57
+ at: Vec3;
58
+ radii: Vec3;
59
+ rotate?: Vec3;
60
+ };
61
+ /** A muzzle or snout on the head */
62
+ muzzle?: {
63
+ at: Vec3;
64
+ radii: Vec3;
65
+ };
66
+ /** Ears on the head (mirrored left and right): where, radii, tip */
67
+ ears: {
68
+ at: Vec3;
69
+ radii: Vec3;
70
+ rotate?: Vec3;
71
+ };
72
+ /** Eyes on the head (mirrored): where, and their size */
73
+ eyes: {
74
+ at: Vec3;
75
+ size: number;
76
+ };
77
+ /** The tail: where it starts (prop space) and its line, and its radius */
78
+ tail: {
79
+ at: Vec3;
80
+ points: Vec3[];
81
+ radius: number;
82
+ };
83
+ /** A mane along the neck */
84
+ mane?: {
85
+ points: Vec3[];
86
+ radius: number;
87
+ };
88
+ /** Anything else: horns, spots, an udder, whiskers */
89
+ extras?: (colors: QuadrupedColors) => PropPart[];
90
+ colors: QuadrupedColors;
91
+ /** Its gaits */
92
+ gaits: AnimalGait[];
93
+ /** Smaller animals step quicker: × each gait's cycle time (default 1) */
94
+ cycleScale?: number;
95
+ /** What its call is called (`neigh`, `bark`, `meow`, `moo`): an action of that name */
96
+ call: string;
97
+ /** It lowers its head to the ground to eat */
98
+ grazes?: boolean;
99
+ anchors?: Record<string, PropAnchor>;
100
+ /** Its own actions (rear, wag, pounce…) */
101
+ actions?: (helpers: QuadrupedHelpers) => Record<string, PropAction>;
102
+ }
103
+ export interface QuadrupedColors {
104
+ coat: string;
105
+ /** Mane, tail tip, darker parts */
106
+ dark: string;
107
+ foot: string;
108
+ muzzle: string;
109
+ /** Inside the ears, spots */
110
+ accent: string;
111
+ }
112
+ /** What a species' own actions can use: its sizes and shared moves. */
113
+ export interface QuadrupedHelpers {
114
+ /** Hip to foot, metres */
115
+ legLength: number;
116
+ /** Hip to knee, knee to foot, the foot's height */
117
+ upper: number;
118
+ lower: number;
119
+ foot: number;
120
+ front: number;
121
+ hind: number;
122
+ /** Its tail hangs down (a horse's) rather than curling up (a dog's) */
123
+ tailHangs: boolean;
124
+ /** A sound from its mouth (honk lines from the muzzle) at `time` */
125
+ call(context: PropActionContext, time: number): void;
126
+ }
127
+ /** Ground covered by one full cycle of a gait: each foot sweeps 2 · L · sin(swing) while planted, twice a cycle. */
128
+ export declare function animalStrideLength(legLength: number, gait: AnimalGait): number;
129
+ /** A four-legged animal from a spec. */
130
+ export declare function quadruped(spec: QuadrupedSpec): Prop;
131
+ /**
132
+ * Sitting, worked out from the legs: the body pitched up about its front feet
133
+ * (lowered so they stay down, the front legs kept upright), the lowered hind
134
+ * hips' thighs lying forward, the lower legs reaching back down to the
135
+ * ground, and the paws turned flat on it.
136
+ */
137
+ export declare function sittingPose(h: Pick<QuadrupedHelpers, 'upper' | 'lower' | 'foot' | 'front' | 'hind' | 'legLength' | 'tailHangs'>): Record<string, number>;
138
+ /** The body leads; the neck, legs and tail follow it. */
139
+ export declare const QUADRUPED_ACTING: ActingRig;
140
+ /** Kept for the horse's name. */
141
+ export declare const HORSE_ACTING: ActingRig;
142
+ export interface AnimalOptions {
143
+ kind?: string;
144
+ summary?: string;
145
+ colors?: Partial<QuadrupedColors>;
146
+ }
147
+ /** A cartoon horse: walks, trots, canters and gallops, rears, bucks, neighs, grazes, swishes its tail. */
148
+ export declare function horse(options?: AnimalOptions): Prop;
149
+ /** A cartoon dog: walks, trots and runs, barks, wags its tail, sits, jumps, sniffs. */
150
+ export declare function dog(options?: AnimalOptions): Prop;
151
+ /** A cartoon cat: walks, trots and runs, meows, arches its back, pounces, sits, swishes its tail. */
152
+ export declare function cat(options?: AnimalOptions): Prop;
153
+ /** A cartoon cow: walks, moos, grazes, swishes its tail; patches, horns and an udder. */
154
+ export declare function cow(options?: AnimalOptions): Prop;
155
+ /** Ground covered by one full cycle of a horse's gait. */
156
+ export declare function horseStrideLength(gait: HorseGait): number;
@@ -0,0 +1,86 @@
1
+ import type { Vec3 } from '../../../engine/math';
2
+ import type { ActingRig } from '../../acting/acting';
3
+ import type { Prop } from '../target';
4
+ /**
5
+ * Birds. A bird is a prop: a body, a head with a beak and eyes, two wings
6
+ * hinged at the shoulders, a tail and two thin legs, seen from any side.
7
+ * Its wings fold back along the body at rest and spread out (`spread`); they
8
+ * flap from the shoulders (`flap`, and the rig's `derive` beats them from a
9
+ * phase, `wingbeat`, while `flapping` is on, so wingbeats keep a rhythm).
10
+ * Its head pecks (`peck`), and its legs step (a chicken walks) or it hops.
11
+ *
12
+ * `bird(spec)` builds one from proportions; `songbird()`, `crow()` and
13
+ * `chicken()` are presets.
14
+ */
15
+ export interface BirdSpec {
16
+ kind: string;
17
+ summary: string;
18
+ /** Body radii (across, up, front to back), and how high its middle is */
19
+ body: {
20
+ radii: Vec3;
21
+ height: number;
22
+ };
23
+ /** Head: where its middle is (prop space) and its radius */
24
+ head: {
25
+ at: Vec3;
26
+ radius: number;
27
+ };
28
+ /** Beak: its length and its thickness at the head */
29
+ beak: {
30
+ length: number;
31
+ thickness: number;
32
+ };
33
+ /** Wings: the shoulder (prop space, left side; mirrored), span and chord */
34
+ wing: {
35
+ shoulder: Vec3;
36
+ span: number;
37
+ chord: number;
38
+ };
39
+ /** Tail feathers: where they start, their length and width, and how far the tip is raised, degrees (default 15) */
40
+ tail: {
41
+ at: Vec3;
42
+ length: number;
43
+ width: number;
44
+ raised?: number;
45
+ };
46
+ /** Leg length (hip to foot) and the hips' spacing */
47
+ legs: {
48
+ length: number;
49
+ across: number;
50
+ };
51
+ /** A crest or comb on the head, and wattles */
52
+ comb?: boolean;
53
+ colors: {
54
+ body: string;
55
+ wing: string;
56
+ beak: string;
57
+ legs: string;
58
+ belly?: string;
59
+ comb?: string;
60
+ };
61
+ /** What its call is called: `tweet`, `caw`, `cluck` */
62
+ call: string;
63
+ /** How fast its wings beat in flight, beats per second (default 4) */
64
+ beatsPerSecond?: number;
65
+ /** How far its body tips forward to peck, degrees (default 12) */
66
+ stoop?: number;
67
+ /** How far its neck stretches down as it pecks, metres at a full peck (default 0; a chicken reaches) */
68
+ neckReach?: number;
69
+ /** It can fly (default true; a chicken only flutters) */
70
+ flies?: boolean;
71
+ }
72
+ /** A bird from a spec. */
73
+ export declare function bird(spec: BirdSpec): Prop;
74
+ export declare const BIRD_ACTING: ActingRig;
75
+ /** A small songbird: hops, pecks, tweets, flies and lands. */
76
+ export declare function songbird(options?: {
77
+ colors?: Partial<BirdSpec['colors']>;
78
+ }): Prop;
79
+ /** A crow: walks, hops, pecks, caws, flies and lands. */
80
+ export declare function crow(options?: {
81
+ colors?: Partial<BirdSpec['colors']>;
82
+ }): Prop;
83
+ /** A chicken: walks with a bobbing head, pecks, clucks, flutters (it cannot really fly). */
84
+ export declare function chicken(options?: {
85
+ colors?: Partial<BirdSpec['colors']>;
86
+ }): Prop;
@@ -0,0 +1,71 @@
1
+ import type { ActingRig } from '../../acting/acting';
2
+ import type { Prop } from '../target';
3
+ /**
4
+ * The world the figures stand in: trees and houses. They mostly stay put,
5
+ * but they are never still: a tree sways in gusts with its canopy trailing
6
+ * its trunk (overlapping action), shakes and sheds leaves; a house opens its
7
+ * door, lights its windows, puffs smoke and shakes when a door slams.
8
+ * Both face the viewer by default (`turn` 0) and turn like any prop.
9
+ */
10
+ export interface TreeSpec {
11
+ kind?: string;
12
+ summary?: string;
13
+ /** Trunk height to the canopy, metres (default 2.4) */
14
+ height?: number;
15
+ trunkRadius?: number;
16
+ /** Canopy: main radius (default 1.1), the number of extra lobes (default 7), and a seed for their placement */
17
+ canopy?: {
18
+ radius?: number;
19
+ lobes?: number;
20
+ seed?: number;
21
+ shape?: 'round' | 'tall';
22
+ };
23
+ colors?: {
24
+ trunk?: string;
25
+ leaves?: string;
26
+ };
27
+ }
28
+ /** A tree: a trunk and a canopy of round lobes, swaying in the wind. */
29
+ export declare function tree(spec?: TreeSpec): Prop;
30
+ /** The trunk leads; the canopy follows it a beat later (overlapping action). */
31
+ export declare const TREE_ACTING: ActingRig;
32
+ export interface HouseSpec {
33
+ kind?: string;
34
+ summary?: string;
35
+ /** Across, front to back, wall height, roof height and overhang, metres */
36
+ width?: number;
37
+ depth?: number;
38
+ wallHeight?: number;
39
+ roofHeight?: number;
40
+ overhang?: number;
41
+ /** The front door: across position of its middle, size */
42
+ door?: {
43
+ at?: number;
44
+ width?: number;
45
+ height?: number;
46
+ };
47
+ /** Front windows: across position of the middle, height of the bottom, size */
48
+ windows?: Array<{
49
+ at: number;
50
+ low: number;
51
+ width: number;
52
+ height: number;
53
+ }>;
54
+ /** A chimney on the roof (across, front to back) */
55
+ chimney?: {
56
+ at?: number;
57
+ back?: number;
58
+ } | false;
59
+ colors?: {
60
+ walls?: string;
61
+ roof?: string;
62
+ door?: string;
63
+ doorway?: string;
64
+ glass?: string;
65
+ lit?: string;
66
+ chimney?: string;
67
+ };
68
+ }
69
+ /** A house: walls, a gable roof, a front door on a hinge, windows that light up, a chimney that smokes. */
70
+ export declare function house(spec?: HouseSpec): Prop;
71
+ export declare const HOUSE_ACTING: ActingRig;
@@ -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[];