@algorisys/tinyfly 0.94.0 → 0.97.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 (66) hide show
  1. package/README.md +6 -6
  2. package/docs/acting.md +170 -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 +41 -2
  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 +6188 -2261
  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 +17 -9
  17. package/lib/browser/tinyfly.js +8077 -4095
  18. package/lib/browser/tinyfly.umd.js +17 -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/index.d.ts +1 -0
  22. package/lib/types/characters/acting/surface-script.d.ts +92 -0
  23. package/lib/types/characters/capabilities.d.ts +22 -0
  24. package/lib/types/characters/character-script-3d.d.ts +80 -0
  25. package/lib/types/characters/character.d.ts +19 -0
  26. package/lib/types/characters/chart.d.ts +108 -0
  27. package/lib/types/characters/code-panel.d.ts +21 -46
  28. package/lib/types/characters/ground-path.d.ts +32 -0
  29. package/lib/types/characters/index.d.ts +6 -0
  30. package/lib/types/characters/props/clip.d.ts +5 -0
  31. package/lib/types/characters/props/draw.d.ts +60 -0
  32. package/lib/types/characters/props/effects.d.ts +12 -0
  33. package/lib/types/characters/props/families/aircraft.d.ts +37 -0
  34. package/lib/types/characters/props/families/animals.d.ts +156 -0
  35. package/lib/types/characters/props/families/birds.d.ts +86 -0
  36. package/lib/types/characters/props/families/environment.d.ts +71 -0
  37. package/lib/types/characters/props/families/vehicle.d.ts +129 -0
  38. package/lib/types/characters/props/hidden.d.ts +49 -0
  39. package/lib/types/characters/props/index.d.ts +24 -0
  40. package/lib/types/characters/props/mesh-3d.d.ts +24 -0
  41. package/lib/types/characters/props/presets.d.ts +34 -0
  42. package/lib/types/characters/props/prop-surface.d.ts +63 -0
  43. package/lib/types/characters/props/ride-3d.d.ts +71 -0
  44. package/lib/types/characters/props/ride.d.ts +79 -0
  45. package/lib/types/characters/props/rig.d.ts +224 -0
  46. package/lib/types/characters/props/scene-objects.d.ts +2 -0
  47. package/lib/types/characters/props/script-3d.d.ts +85 -0
  48. package/lib/types/characters/props/script.d.ts +145 -0
  49. package/lib/types/characters/props/shapes.d.ts +96 -0
  50. package/lib/types/characters/props/slice.d.ts +66 -0
  51. package/lib/types/characters/props/target.d.ts +129 -0
  52. package/lib/types/characters/surface/edit-log.d.ts +47 -0
  53. package/lib/types/characters/surface/index.d.ts +11 -0
  54. package/lib/types/characters/surface/pieces.d.ts +61 -0
  55. package/lib/types/characters/surface/ride.d.ts +31 -0
  56. package/lib/types/characters/surface/surface-box.d.ts +18 -0
  57. package/lib/types/characters/surface/surface.d.ts +79 -0
  58. package/lib/types/characters/whiteboard.d.ts +131 -0
  59. package/lib/types/engine/authoring/index.d.ts +1 -0
  60. package/lib/types/engine/authoring/spring-follow.d.ts +25 -0
  61. package/lib/types/scene-3d/object-kind.d.ts +4 -1
  62. package/lib/types/scene-3d/scene-types.d.ts +41 -1
  63. package/llms-full.txt +699 -11
  64. package/llms.txt +28 -27
  65. package/package.json +1 -1
  66. package/skills/tinyfly/SKILL.md +37 -9
@@ -1,5 +1,9 @@
1
1
  import type { CustomTarget } from '../adapters/canvas/canvas-adapter';
2
- import type { EasingType, Track } from '../engine/types';
2
+ import type { Track } from '../engine/types';
3
+ import { type EditOptions } from './surface/edit-log';
4
+ import { type FlingOptions, type SurfacePiece, type TimedPoint } from './surface/pieces';
5
+ import { type Surface, type SurfaceAbout, type SurfaceEditOptions } from './surface/surface';
6
+ import { type SurfaceBox } from './surface/surface-box';
3
7
  /**
4
8
  * A code listing as a scene object characters can act on: they stand on its
5
9
  * lines, point at its tokens and swipe lines away.
@@ -66,23 +70,9 @@ export interface CodePanelOptions {
66
70
  theme?: Partial<CodeTheme>;
67
71
  }
68
72
  /** A place on the panel, scene px. Stand on `top`; point at `x`, `y` (the centre). */
69
- export interface CodeBox {
70
- x: number;
71
- y: number;
72
- left: number;
73
- right: number;
74
- top: number;
75
- bottom: number;
76
- width: number;
77
- height: number;
78
- }
79
- export interface CodeEditOptions {
80
- /** When the edit starts, ms */
81
- at: number;
82
- /** ms (default 300) */
83
- duration?: number;
84
- easing?: EasingType;
85
- }
73
+ export type CodeBox = SurfaceBox;
74
+ export type CodeEditOptions = EditOptions;
75
+ export type { TimedPoint };
86
76
  /** How a removed line goes: wiped away, knocked off the panel, or out of focus. */
87
77
  export type CodeRemoveStyle = 'wipe' | 'fly' | 'blur';
88
78
  export declare const REMOVE_STYLES: readonly CodeRemoveStyle[];
@@ -94,38 +84,15 @@ export interface CodeRemoveOptions extends CodeEditOptions {
94
84
  /** How long the lines below take to close the gap, ms (default 250) */
95
85
  close?: number;
96
86
  }
97
- /** A word that can come loose from its line: made by `piece()`. */
98
- export interface CodePiece {
99
- /** Its key in the panel's props (`piece.K.x`…) */
100
- readonly id: number;
87
+ /** A word that can come loose from its line: made by `piece()`. Its `home` is where it sits in its line. */
88
+ export interface CodePiece extends SurfacePiece {
101
89
  readonly line: number;
102
90
  readonly column: number;
103
91
  readonly text: string;
104
- /** Where it sits in its line */
105
- readonly home: CodeBox;
106
- }
107
- /** A point at a time, scene px: a path for a piece to follow (see `handPath`). */
108
- export interface TimedPoint {
109
- time: number;
110
- x: number;
111
- y: number;
112
- }
113
- export interface CodeFlingOptions {
114
- /** When it leaves, ms */
115
- at: number;
116
- /** px/ms (default: how fast it was moving along its `follow` path at `at`, or up and to the right) */
117
- velocity?: {
118
- x: number;
119
- y: number;
120
- };
121
- /** Turns, degrees per ms (default 0.6, signed by the throw's direction) */
122
- spin?: number;
123
- /** px/ms² (default 0.0016) */
124
- gravity?: number;
125
- /** How long it flies before it is gone, ms (default 900) */
126
- duration?: number;
127
92
  }
128
- export interface CodePanel {
93
+ export type CodeFlingOptions = FlingOptions;
94
+ export interface CodePanel extends Surface {
95
+ readonly kind: 'code';
129
96
  /** The canvas target that draws the panel; put it in the scene's targets */
130
97
  readonly target: CustomTarget;
131
98
  readonly lines: readonly string[];
@@ -147,6 +114,12 @@ export interface CodePanel {
147
114
  type(n: number, options: CodeEditOptions): CodePanel;
148
115
  /** Make the `occurrence`th `text` on line `n` a piece that can come loose */
149
116
  piece(n: number, text: string, occurrence?: number): CodePiece;
117
+ /** Make the word at a token anchor (`token:7:Println`) a piece that can come loose */
118
+ piece(anchor: string): CodePiece;
119
+ /** The box at a named place: `box`, `line:N`, `token:N:TEXT` (`token:N#K:TEXT` for the Kth), `spot:N:C` or `spot:N:C:W` */
120
+ anchor(name: string, time?: number): CodeBox;
121
+ /** Change the panel at a time by name, at named places (see `CODE_SURFACE.edits`): `edit('highlight', 'line:4', { at: 1200 })` */
122
+ edit(name: string, anchor: string | string[], options: SurfaceEditOptions): CodePanel;
150
123
  /** Carry a piece along a path of scene points (its centre follows them) */
151
124
  follow(piece: CodePiece, path: TimedPoint[]): CodePanel;
152
125
  /** Throw or kick a piece away: it flies on a ballistic arc, spinning, and fades */
@@ -188,6 +161,8 @@ export interface CodePanel {
188
161
  /** The recorded edits as tracks on `target` (the panel's key in the scene) */
189
162
  tracks(target: string): Track[];
190
163
  }
164
+ /** A code panel's anchors and edits, as data: for its `about`, the capability catalog and the checks. */
165
+ export declare const CODE_SURFACE: SurfaceAbout;
191
166
  export declare function codePanel(options: CodePanelOptions): CodePanel;
192
167
  /** What a code panel's methods do, for its `about` and the capability catalog. */
193
168
  export declare const CODE_PANEL_EDITS: Record<string, string>;
@@ -0,0 +1,32 @@
1
+ import type { Keyframe } from '../engine/types';
2
+ /**
3
+ * Paths on the ground, for things moving through a 3D scene in world metres
4
+ * (props with `propScript3D`, characters with `characterScript3D`): smooth
5
+ * paths through points, the point and direction a distance along one,
6
+ * headings (0 faces +z, 90 faces +x, as an object's `rotation` y turns it),
7
+ * and the time an eased move reaches a distance.
8
+ */
9
+ /** A point on the ground, [x, z] metres. */
10
+ export type GroundPoint = [number, number];
11
+ export declare const isGroundPoint: (value: unknown) => value is GroundPoint;
12
+ /** The way from `heading` to `toward`, degrees, the shorter way round (−180..180). */
13
+ export declare function turnBetween(heading: number, toward: number): number;
14
+ /** Keys in time order, one per time (the last given wins). */
15
+ export declare function tidy(frames: Keyframe<number>[]): Keyframe<number>[];
16
+ /** Heading from one point to another, degrees: 0 along +z, 90 along +x (as `rotation` y turns a prop). */
17
+ export declare function headingOf(from: GroundPoint, to: GroundPoint): number;
18
+ /** A path through points, curving smoothly through them, with the distance along it at each point. */
19
+ export declare function groundPath(points: GroundPoint[]): Array<{
20
+ point: GroundPoint;
21
+ at: number;
22
+ }>;
23
+ /** The point `s` metres along a path, and the way the path goes there. */
24
+ export declare function along(path: Array<{
25
+ point: GroundPoint;
26
+ at: number;
27
+ }>, s: number): {
28
+ point: GroundPoint;
29
+ direction: GroundPoint;
30
+ };
31
+ /** The input at which an easing reaches `y` (eases are rising), by halving. */
32
+ export declare function inverse(ease: (u: number) => number, y: number): number;
@@ -11,10 +11,15 @@ export * from './acrobatics';
11
11
  export { stickToHuman } from './stick-to-human';
12
12
  export { skeletonInView, solvePlanSpace, stagePlanSpace, type ViewProjection, type PlanSpace, type StagedSpace } from './rig/skeleton';
13
13
  export { characterObjects } from './scene-objects';
14
+ export { characterScript3D, checkCharacterBeats3D, CHARACTER_GAIT_SPEEDS, CHARACTER_BEAT_3D_FIELDS, type CharacterBeat3D, type CharacterScript3DOptions, type CharacterScript3DResult } from './character-script-3d';
15
+ export { type GroundPoint } from './ground-path';
14
16
  export * from '../adapters/canvas/sketch';
15
17
  export * from '../adapters/canvas/camera';
16
18
  export * from './erase';
17
19
  export * from './code-panel';
20
+ export * from './whiteboard';
21
+ export * from './chart';
22
+ export * from './surface';
18
23
  export * from '../adapters/canvas/polyline';
19
24
  export * from './hand';
20
25
  export * from './character';
@@ -27,3 +32,4 @@ export * from './hands';
27
32
  export * from './acting';
28
33
  export * from './capabilities';
29
34
  export { describeTarget, checkTracks, animatableProperties, CANVAS_PROPERTIES, type PropertyInfo, type TargetAbout, type TargetDescription, type TrackProblem } from '../adapters/canvas/target-properties';
35
+ export * from './props';
@@ -0,0 +1,5 @@
1
+ import type { Vec3 } from '../../engine/math';
2
+ /** A closed polygon cut to the part in front of the near plane (empty when none of it is). */
3
+ export declare function clipPolygon(points: Vec3[], near: number): Vec3[];
4
+ /** An open line cut into the runs in front of the near plane. */
5
+ export declare function clipPolyline(points: Vec3[], near: number): Vec3[][];
@@ -0,0 +1,60 @@
1
+ import { type Look, type PencilOptions } from '../look/pen';
2
+ import type { SolvedPart, SolvedProp } from './rig';
3
+ /**
4
+ * Drawing a solved prop with the characters' pens, so a car in the pencil
5
+ * look boils like the figure beside it. Each part gets its own pen seeded by
6
+ * its id: as a prop turns its parts change drawing order, and a pen seeded by
7
+ * stroke order would make every line jump.
8
+ */
9
+ export interface PropDrawOptions {
10
+ look?: Look;
11
+ /** Outline colour (default near-black) */
12
+ ink?: string;
13
+ /** Outline width, px (default from the prop's size) */
14
+ lineWidth?: number;
15
+ /** ms, for the pencil's boil */
16
+ time?: number;
17
+ seed?: number;
18
+ pencil?: PencilOptions;
19
+ /** Draws a rider (a figure in a seat or a doorway): seen only through the prop's see-through parts, and under its `overRider` parts (doors) */
20
+ rider?: (ctx: CanvasRenderingContext2D) => void;
21
+ /** Draw its contact shadow on the ground (default true) */
22
+ shadow?: boolean;
23
+ /**
24
+ * `solid` (default): shaded shapes with outlines. `stick`: line art to go
25
+ * with stick figures — tubes (legs, necks, tails, frames) drawn as single
26
+ * even strokes, other shapes outlined and filled with the paper colour,
27
+ * dark details (eyes, noses, tyres) kept dark.
28
+ */
29
+ style?: 'solid' | 'stick';
30
+ /** The paper colour a stick prop's shapes are filled with (default cream) */
31
+ paper?: string;
32
+ /** The fog's colour, for faces lit by a scene (`light`, `fog` on the solved faces) */
33
+ fog?: string;
34
+ }
35
+ /** Draws in the prop's own space: feet at 0, 0, up is −y. */
36
+ export declare function drawSolvedProp(ctx: CanvasRenderingContext2D, solved: SolvedProp, options?: PropDrawOptions): void;
37
+ /** The outline width a prop is drawn with: weighted by how big it looks, so a cat drawn large and a bus drawn small both read. */
38
+ export declare function propLineWidth(solved: SolvedProp, options?: Pick<PropDrawOptions, 'lineWidth'>): number;
39
+ /** Its contact shadow on the ground. */
40
+ export declare function drawPropShadow(ctx: CanvasRenderingContext2D, solved: SolvedProp, options?: Pick<PropDrawOptions, 'ink'>): void;
41
+ /**
42
+ * One solved part on its own, with the prop's outline width
43
+ * (`propLineWidth`): for drawing a prop's parts one by one among other
44
+ * things, each at its own depth (a 3D scene).
45
+ */
46
+ export declare function drawSolvedPart(ctx: CanvasRenderingContext2D, part: SolvedPart, lineWidth: number, options?: PropDrawOptions): void;
47
+ /**
48
+ * Pieces of a prop drawn face by face, nearest last, each face followed by
49
+ * its own outlines and marks: so a wheel tucked under a car's hood, or a
50
+ * seat inside its cabin, is covered where the faces in front cover it. The
51
+ * pieces need face outlines (solved with `slice`); a 3D scene draws a prop's
52
+ * columns this way.
53
+ */
54
+ export declare function drawSolvedFaces(ctx: CanvasRenderingContext2D, parts: SolvedPart[], lineWidth: number, options?: PropDrawOptions): void;
55
+ /** A colour lit (tone above 1) or shaded (below 1). */
56
+ export declare function shade(color: string, tone: number): string;
57
+ /** A colour under a scene's light (RGB, 1 is full light), then into its fog. */
58
+ export declare function lit(color: string, light: [number, number, number], fog: number, fogColor?: string): string;
59
+ /** `a` blended toward `b` by `t` (hex colours; otherwise `b` once past half). */
60
+ export declare function mixColors(a: string, b: string, t: number): string;
@@ -0,0 +1,12 @@
1
+ import type { PropEffect } from './script';
2
+ /**
3
+ * The secondary action a prop script asks for, drawn at its time and place:
4
+ * dust kicked up, exhaust puffs, skid marks, honk lines. Effects are plain
5
+ * cues (`PropScriptResult.effects`); this draws them in a simple ink style,
6
+ * or draw your own from the same cues.
7
+ */
8
+ export declare function drawPropEffects(ctx: CanvasRenderingContext2D, effects: PropEffect[], time: number, options?: {
9
+ color?: string;
10
+ size?: number;
11
+ leafColor?: string;
12
+ }): void;
@@ -0,0 +1,37 @@
1
+ import type { ActingRig } from '../../acting/acting';
2
+ import type { Prop } from '../target';
3
+ /**
4
+ * Flying craft. A helicopter is a fuselage from a side profile, a tail boom,
5
+ * skids, a main rotor and a tail rotor. Its rotors spin from `rotor`, keyed
6
+ * exactly (they are not acted), and the main rotor reads as a blurred disc
7
+ * once it is spinning fast. It takes off (the skids squash as it spools up,
8
+ * then it lifts nose-down), flies with its nose down and banking into the
9
+ * move, hovers with a bob, and lands with a squash and dust.
10
+ */
11
+ export interface HelicopterSpec {
12
+ kind?: string;
13
+ summary?: string;
14
+ colors?: {
15
+ body?: string;
16
+ glass?: string;
17
+ trim?: string;
18
+ rotor?: string;
19
+ };
20
+ }
21
+ /** A cartoon helicopter. */
22
+ export declare function helicopter(spec?: HelicopterSpec): Prop;
23
+ /** Lift leads; the body's pitch, roll and squash follow. */
24
+ export declare const AIRCRAFT_ACTING: ActingRig;
25
+ export interface AirplaneSpec {
26
+ kind?: string;
27
+ summary?: string;
28
+ colors?: {
29
+ body?: string;
30
+ wings?: string;
31
+ glass?: string;
32
+ trim?: string;
33
+ stripe?: string;
34
+ };
35
+ }
36
+ /** A cartoon propeller plane: fuselage, wings, a tail, landing gear and a propeller that blurs into a disc. */
37
+ export declare function airplane(spec?: AirplaneSpec): Prop;
@@ -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;