@algorisys/tinyfly 0.99.0 → 0.101.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 (77) hide show
  1. package/README.md +9 -9
  2. package/bin/tinyfly.mjs +7 -3
  3. package/docs/acting.md +10 -6
  4. package/docs/character-appearance.md +71 -7
  5. package/docs/editor-guide.md +38 -3
  6. package/docs/examples.md +1 -1
  7. package/docs/getting-started.md +1 -1
  8. package/docs/gsap-compat.md +1 -1
  9. package/docs/llm-guide.md +34 -9
  10. package/docs/maps.md +2 -2
  11. package/docs/props.md +61 -1
  12. package/docs/scene-3d.md +23 -4
  13. package/docs/teaching.md +1 -1
  14. package/docs/video-rendering.md +154 -0
  15. package/lib/addons/adapters.js +387 -333
  16. package/lib/addons/characters.js +4795 -3752
  17. package/lib/addons/load-scene-oWNsYYC1.js +372 -0
  18. package/lib/addons/scene-3d-webgl.js +1 -1
  19. package/lib/addons/scene-3d.js +323 -277
  20. package/lib/addons/shading-0lPgnXmD.js +96 -0
  21. package/lib/browser/tinyfly-scene-3d.iife.js +2 -2
  22. package/lib/browser/tinyfly.iife.js +14 -14
  23. package/lib/browser/tinyfly.js +7294 -5893
  24. package/lib/browser/tinyfly.umd.js +14 -14
  25. package/lib/engine/tinyfly-engine.js +1389 -1031
  26. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  27. package/lib/headless/headless.js +39 -0
  28. package/lib/types/adapters/canvas/impossible.d.ts +15 -0
  29. package/lib/types/adapters/canvas/index.d.ts +3 -0
  30. package/lib/types/adapters/canvas/nested-zoom.d.ts +40 -0
  31. package/lib/types/adapters/canvas/zoom-blur.d.ts +49 -0
  32. package/lib/types/characters/acting/character-script.d.ts +14 -2
  33. package/lib/types/characters/acting/script.d.ts +9 -0
  34. package/lib/types/characters/capabilities.d.ts +2 -0
  35. package/lib/types/characters/character.d.ts +28 -1
  36. package/lib/types/characters/hair-follow.d.ts +12 -6
  37. package/lib/types/characters/hands/held-items.d.ts +6 -2
  38. package/lib/types/characters/head/face.d.ts +23 -1
  39. package/lib/types/characters/index.d.ts +3 -2
  40. package/lib/types/characters/interactions.d.ts +60 -0
  41. package/lib/types/characters/props/families/animals.d.ts +6 -0
  42. package/lib/types/characters/props/families/birds.d.ts +16 -0
  43. package/lib/types/characters/props/families/furniture.d.ts +102 -0
  44. package/lib/types/characters/props/index.d.ts +1 -0
  45. package/lib/types/characters/props/presets.d.ts +15 -2
  46. package/lib/types/characters/props/ride-3d.d.ts +4 -1
  47. package/lib/types/characters/scenery.d.ts +126 -0
  48. package/lib/types/characters/species/human-motion.d.ts +17 -0
  49. package/lib/types/characters/species/human.d.ts +6 -0
  50. package/lib/types/characters/wardrobe/basic-outfit.d.ts +16 -5
  51. package/lib/types/engine/authoring/beat-loop.d.ts +46 -0
  52. package/lib/types/engine/authoring/curve.d.ts +26 -0
  53. package/lib/types/engine/authoring/index.d.ts +3 -0
  54. package/lib/types/engine/authoring/periodic.d.ts +89 -0
  55. package/lib/types/engine/path/goo.d.ts +103 -0
  56. package/lib/types/engine/path/impossible.d.ts +92 -0
  57. package/lib/types/engine/path/index.d.ts +6 -0
  58. package/lib/types/engine/path/similarity.d.ts +48 -0
  59. package/lib/types/headless/index.d.ts +1 -0
  60. package/lib/types/headless/loop-audio.d.ts +21 -0
  61. package/lib/types/headless/node-audio.d.ts +20 -0
  62. package/lib/types/headless/video-scene.d.ts +9 -0
  63. package/lib/types/scene-3d/camera.d.ts +11 -2
  64. package/lib/types/scene-3d/geometry/mesh.d.ts +2 -0
  65. package/lib/types/scene-3d/geometry/primitives.d.ts +7 -0
  66. package/lib/types/scene-3d/impossible-3d.d.ts +29 -0
  67. package/lib/types/scene-3d/index.d.ts +4 -3
  68. package/lib/types/scene-3d/resolve-scene.d.ts +13 -1
  69. package/lib/types/scene-3d/scene-3d-adapter.d.ts +2 -0
  70. package/lib/types/scene-3d/scene-types.d.ts +29 -4
  71. package/lib/types/scene-3d/shading.d.ts +2 -0
  72. package/llms-full.txt +423 -47
  73. package/llms.txt +29 -29
  74. package/package.json +2 -2
  75. package/skills/tinyfly/SKILL.md +20 -6
  76. package/lib/addons/load-scene-CQvcFWGJ.js +0 -331
  77. package/lib/addons/shading-o5T_v9DT.js +0 -89
@@ -1,6 +1,7 @@
1
1
  import type { Track } from '../engine/types';
2
2
  import type { Pose } from './rig/body-plan';
3
3
  import { type Character } from './character';
4
+ import type { Gait } from './gaits';
4
5
  /**
5
6
  * Hair follow-through: hanging hair (long hair, ponytails, braids) lags
6
7
  * behind the head, swinging round it after a turn, streaming back on a run,
@@ -44,6 +45,8 @@ export interface HairFollowOptions {
44
45
  damping?: number;
45
46
  /** How much the hair lags, 1 the default feel; 0 pins it to the head */
46
47
  amount?: number;
48
+ /** The wind, −1 (from the right) to 1 (from the left): the hair streams downwind as if the head were moving against it */
49
+ wind?: number;
47
50
  }
48
51
  /** The hair's lag at one time. */
49
52
  export interface HairFollowKey {
@@ -62,15 +65,18 @@ export interface HairFollowKey {
62
65
  export declare function hairFollow(sample: (time: number) => HairFollowSample, options: HairFollowOptions): HairFollowKey[];
63
66
  /** The hair's lag at a time, between keys, as the pose fields it sets (`hair.swing`, `hair.trail`, `hair.lift`). */
64
67
  export declare function hairMotionAt(keys: HairFollowKey[], time: number): Pose;
65
- export interface HairFollowTrackOptions extends Pick<HairFollowOptions, 'step' | 'stiffness' | 'damping' | 'amount'> {
68
+ export interface HairFollowTrackOptions extends Pick<HairFollowOptions, 'step' | 'stiffness' | 'damping' | 'amount' | 'wind'> {
66
69
  /** How long the hair keeps settling after the last key, ms (default 1500) */
67
70
  settle?: number;
71
+ /** Your own gaits, by the names a `gait` track uses (built-in names need no entry) */
72
+ gaits?: Record<string, Gait>;
68
73
  }
69
74
  /**
70
- * Tracks that key a character target's hair lag from its own tracks: the
71
- * target's `x` and `y`, and the pose's `turn` and `head.turn`. Nothing is
72
- * added for hair that has nothing to swing (short hair, a bun, no hair).
73
- * Hair fields the tracks already key (a flick written by hand) keep their
74
- * values, with the lag added on.
75
+ * Tracks that key a character target's hair lag from its own tracks: where
76
+ * its head is (the target's `x` and `y`, plus the head's place in the pose,
77
+ * so a gait's bob, a crouch and a jump all move it), and the pose's `turn`
78
+ * and `head.turn`. Nothing is added for hair that has nothing to swing
79
+ * (short hair, a bun, no hair). Hair fields the tracks already key (a flick
80
+ * written by hand) keep their values, with the lag added on.
75
81
  */
76
82
  export declare function hairFollowTracks(target: string, tracks: Track[], who: Character, options?: HairFollowTrackOptions): Track[];
@@ -4,7 +4,7 @@ import type { Pose } from '../rig/body-plan';
4
4
  import type { Pen } from '../look/pen';
5
5
  /**
6
6
  * Things a character holds: a mug, a phone, a book, bags, an umbrella, a
7
- * broom, a parcel. Each is plain data (`holding: { right: 'mug' }`) drawn at
7
+ * broom, a cane, a parcel. Each is plain data (`holding: { right: 'mug' }`) drawn at
8
8
  * the hand's grip, so it follows the hand through any pose, gait or turn, and
9
9
  * sorts with that arm (behind the body when the arm is). An item held in
10
10
  * `both` hands sits between them.
@@ -15,7 +15,7 @@ import type { Pen } from '../look/pen';
15
15
  * taker's goes to 1, with their hands meeting there (see `meetHands`).
16
16
  * `handGrip` gives the grip for drawing anything else in a hand.
17
17
  */
18
- export type HeldItemName = 'mug' | 'phone' | 'book' | 'bag' | 'briefcase' | 'umbrella' | 'broom' | 'parcel';
18
+ export type HeldItemName = 'mug' | 'phone' | 'book' | 'bag' | 'briefcase' | 'umbrella' | 'broom' | 'cane' | 'parcel';
19
19
  export interface HeldItem {
20
20
  item: HeldItemName;
21
21
  /** Main colour (each item has its own default) */
@@ -58,6 +58,10 @@ export declare const HELD_ITEMS: {
58
58
  color: string;
59
59
  hands: "one";
60
60
  };
61
+ cane: {
62
+ color: string;
63
+ hands: "one";
64
+ };
61
65
  parcel: {
62
66
  color: string;
63
67
  hands: "both";
@@ -14,4 +14,26 @@ export declare function faceToScreen(head: SolvedHead, points: Point[], centre:
14
14
  points: Point[];
15
15
  facing: number;
16
16
  };
17
- export declare function drawFace(pen: Pen, head: SolvedHead, pose: Pose, lineWidth: number): void;
17
+ /** The pupil's circle on the screen, for drawing inside it. */
18
+ export interface PupilCircle {
19
+ x: number;
20
+ y: number;
21
+ r: number;
22
+ side: 'left' | 'right';
23
+ }
24
+ /** What an open mouth shows: a row of upper teeth, and a tongue (default neither, as the plain face); a nose; what is in the pupils. */
25
+ export interface FaceOptions {
26
+ teeth?: boolean;
27
+ tongue?: boolean;
28
+ /** A small nose between the eyes and the mouth (default none) */
29
+ nose?: boolean;
30
+ /** The head's fill, for lids that cover the eye (default white) */
31
+ skin?: string;
32
+ /**
33
+ * Draw inside each pupil: the context is clipped to the pupil's circle and
34
+ * the hook draws there in screen space (another scene, the same head again
35
+ * for a Droste face). Needs the context passed to `drawFace`.
36
+ */
37
+ inPupil?: (ctx: CanvasRenderingContext2D, pupil: PupilCircle) => void;
38
+ }
39
+ export declare function drawFace(pen: Pen, head: SolvedHead, pose: Pose, lineWidth: number, options?: FaceOptions, ctx?: CanvasRenderingContext2D): void;
@@ -23,9 +23,9 @@ export * from './surface';
23
23
  export * from '../adapters/canvas/polyline';
24
24
  export * from './hand';
25
25
  export * from './character';
26
- export { humanPlan, humanPose, mirrorHumanPose, humanFieldLabel, HUMAN_REST, HUMAN_POSES, HUMAN_EXPRESSIONS, HUMAN_BUILDS, type HumanBuild, type HumanBuildName, type HumanPoseName, type HumanExpressionName } from './species/human';
26
+ export { humanPlan, humanPose, mirrorHumanPose, humanFieldLabel, HUMAN_REST, HUMAN_POSES, HUMAN_EXPRESSIONS, HUMAN_BUILDS, FOOT_SHAPES, type FootShape, type HumanBuild, type HumanBuildName, type HumanPoseName, type HumanExpressionName } from './species/human';
27
27
  export { CHARACTER_CAST, castMember, type CastMember, type CastName } from './cast';
28
- export { meetHands, meetingSpacing, HAND_MEETINGS, type HandMeeting, type HandsMeet, type MeetingPartner, type MeetHandsOptions } from './interactions';
28
+ export { meetHands, meetingSpacing, HAND_MEETINGS, embrace, embraceSpacing, EMBRACE, helpUp, helpUpSpacing, HELP_UP, type HandMeeting, type HandsMeet, type MeetingPartner, type MeetHandsOptions, type Embrace, type EmbraceOptions, type HelpUp, type HelpUpOptions } from './interactions';
29
29
  export * from './species/human-motion';
30
30
  export type { BodyPlan, ChainSpec, BoneSpec, BoneAngles, ContactSpec, HeadSpec, Pose as CharacterPose, Vec3 } from './rig/body-plan';
31
31
  export { createPen, ellipsePoints, type Pen, type Look, type PencilOptions, type PenOptions } from './look/pen';
@@ -37,3 +37,4 @@ export * from './acting';
37
37
  export * from './capabilities';
38
38
  export { describeTarget, checkTracks, animatableProperties, CANVAS_PROPERTIES, type PropertyInfo, type TargetAbout, type TargetDescription, type TrackProblem } from '../adapters/canvas/target-properties';
39
39
  export * from './props';
40
+ export { scenery, scenePreset, buildScene, skyColors, SCENERY_COLORS, type Scenery, type SceneryOptions, type SceneryColors, type SceneryHorizon, type ScenePreset, type ScenePresetName, type ScenePresetOptions, type PlacedProp } from './scenery';
@@ -67,3 +67,63 @@ export declare const HAND_MEETINGS: {
67
67
  /** How far apart (px, feet to feet) two characters stand for their hands to meet comfortably. */
68
68
  export declare function meetingSpacing(kind: HandMeeting, a: Character, b: Character): number;
69
69
  export declare function meetHands(kind: HandMeeting, a: MeetingPartner, b: MeetingPartner, options?: MeetHandsOptions): HandsMeet;
70
+ /**
71
+ * Two characters in each other's arms: a hug. Both turn toward each other
72
+ * (three-quarters to the viewer, or side on), lean in and tilt their heads
73
+ * together, and each reaches its right arm over the other's far shoulder and
74
+ * its left round the other's waist, exactly, from where the two stand. Plain
75
+ * data, like `meetHands`.
76
+ */
77
+ export interface EmbraceOptions {
78
+ /** `threeQuarter` (default): turned toward the viewer as well as each other; `side`: in profile */
79
+ view?: 'threeQuarter' | 'side';
80
+ }
81
+ export interface Embrace {
82
+ a: Pose;
83
+ b: Pose;
84
+ /** Both pairs of arms got round the other (they stand close enough; see `embraceSpacing`) */
85
+ reached: boolean;
86
+ }
87
+ /** A hug: how far apart the two stand (a share of the shorter one's height), how far they lean in and tilt their heads together. */
88
+ export declare const EMBRACE: {
89
+ spacing: number;
90
+ lean: number;
91
+ tilt: number;
92
+ };
93
+ /** How far apart (px, feet to feet) two characters stand to hug. */
94
+ export declare function embraceSpacing(a: Character, b: Character): number;
95
+ export declare function embrace(a: MeetingPartner, b: MeetingPartner, options?: EmbraceOptions): Embrace;
96
+ /**
97
+ * One character helping another up off the floor, as a function of how far
98
+ * along it is: at `progress` 0 the sitter sits on the floor (`sitFloor`) and
99
+ * the helper bends down to take its hand; at 1 both stand. In between the
100
+ * sitter's pose blends from sitting to standing and the helper straightens,
101
+ * while both right hands stay joined at a point that rises with them. Key
102
+ * it at a few values of `progress` (or sample it) for the rise.
103
+ */
104
+ export interface HelpUp {
105
+ helper: Pose;
106
+ sitter: Pose;
107
+ /** Where the hands are joined: scene x, and px above the ground (negative y, as drawing space) */
108
+ point: {
109
+ x: number;
110
+ y: number;
111
+ };
112
+ /** Both hands got there (they are the spacing apart; see `helpUpSpacing`) */
113
+ reached: boolean;
114
+ }
115
+ export interface HelpUpOptions {
116
+ /** `threeQuarter` (default) or `side` */
117
+ view?: 'threeQuarter' | 'side';
118
+ }
119
+ /** A help-up: how far apart they are (a share of the shorter one's height), how high the joined hands are at the start and the end, and how far the helper bows down. */
120
+ export declare const HELP_UP: {
121
+ spacing: number;
122
+ low: number;
123
+ high: number;
124
+ helperLean: number;
125
+ helperBend: number;
126
+ };
127
+ /** How far apart (px, feet to feet) a helper stands from someone on the floor to take their hand. */
128
+ export declare function helpUpSpacing(helper: Character, sitter: Character): number;
129
+ export declare function helpUp(helper: MeetingPartner, sitter: MeetingPartner, progress: number, options?: HelpUpOptions): HelpUp;
@@ -160,3 +160,9 @@ export declare function cat(options?: AnimalOptions): Prop;
160
160
  export declare function cow(options?: AnimalOptions): Prop;
161
161
  /** Ground covered by one full cycle of a horse's gait. */
162
162
  export declare function horseStrideLength(gait: HorseGait): number;
163
+ /** A goat: a shaggy coat, short horns, a beard and a stubby tail; walks, trots, gallops, bleats, grazes, butts. */
164
+ export declare function goat(options?: AnimalOptions): Prop;
165
+ /** A rabbit: long ears, a round body low to the ground, a puff of a tail; hops (its gallop), nibbles, squeaks, sits up. */
166
+ export declare function rabbit(options?: AnimalOptions): Prop;
167
+ /** A squirrel: tiny, with a great bushy tail curled up over its back; scampers (gallop), chatters, sits up to nibble. */
168
+ export declare function squirrel(options?: AnimalOptions): Prop;
@@ -84,3 +84,19 @@ export declare function crow(options?: {
84
84
  export declare function chicken(options?: {
85
85
  colors?: Partial<BirdSpec['colors']>;
86
86
  }): Prop;
87
+ /** A pigeon: plump and grey with a green and purple sheen at the neck; walks with a bobbing head, pecks, coos, flies and lands. */
88
+ export declare function pigeon(options?: {
89
+ colors?: Partial<BirdSpec['colors']>;
90
+ }): Prop;
91
+ /** A duck: a low body on orange legs, a broad flat bill; waddles, dabbles, quacks, flies and lands. */
92
+ export declare function duck(options?: {
93
+ colors?: Partial<BirdSpec['colors']>;
94
+ }): Prop;
95
+ /** An owl: a big round head on a round body, a short hooked beak, soft slow wingbeats; hoots, flies and lands (a branch at night). */
96
+ export declare function owl(options?: {
97
+ colors?: Partial<BirdSpec['colors']>;
98
+ }): Prop;
99
+ /** A parrot: bright green with a red head, a big hooked beak and a long tail; squawks, flies and lands on a perch. */
100
+ export declare function parrot(options?: {
101
+ colors?: Partial<BirdSpec['colors']>;
102
+ }): Prop;
@@ -0,0 +1,102 @@
1
+ import type { ActingRig } from '../../acting/acting';
2
+ import type { Prop } from '../target';
3
+ /**
4
+ * Furniture: a chair, a desk, a bed, a door and a wheelchair, with the places
5
+ * a figure uses them at as anchors (`seat`, `top`, `mattress`, `handle`…) so
6
+ * a script can sit, work, lie and go through. They stand on the ground facing the viewer
7
+ * (`turn` 0) and turn like any prop; a chair tips back on its rear legs, a
8
+ * desk's drawer slides out, a bed's mattress gives when someone lands on it,
9
+ * and a door opens on its hinge, slams, and rattles when knocked.
10
+ */
11
+ export interface ChairSpec {
12
+ kind?: string;
13
+ summary?: string;
14
+ /** Seat width and depth, seat height, and the back's height above the floor, metres */
15
+ width?: number;
16
+ depth?: number;
17
+ seatHeight?: number;
18
+ backHeight?: number;
19
+ colors?: {
20
+ wood?: string;
21
+ seat?: string;
22
+ };
23
+ }
24
+ /** A chair: a seat on four legs with a back; tips back on its rear legs. */
25
+ export declare function chair(spec?: ChairSpec): Prop;
26
+ export declare const CHAIR_ACTING: ActingRig;
27
+ export interface DeskSpec {
28
+ kind?: string;
29
+ summary?: string;
30
+ /** Across, front to back, and the top's height, metres */
31
+ width?: number;
32
+ depth?: number;
33
+ height?: number;
34
+ colors?: {
35
+ wood?: string;
36
+ top?: string;
37
+ knob?: string;
38
+ };
39
+ }
40
+ /** A desk: a top on four legs, with a drawer that slides out of the front. */
41
+ export declare function desk(spec?: DeskSpec): Prop;
42
+ export declare const DESK_ACTING: ActingRig;
43
+ export interface BedSpec {
44
+ kind?: string;
45
+ summary?: string;
46
+ /** Length (head to foot), width, the mattress top's height, and the headboard's height, metres */
47
+ length?: number;
48
+ width?: number;
49
+ height?: number;
50
+ headboard?: number;
51
+ colors?: {
52
+ wood?: string;
53
+ mattress?: string;
54
+ blanket?: string;
55
+ pillow?: string;
56
+ };
57
+ }
58
+ /** A bed: a frame with a headboard, a mattress with a blanket, a pillow; the mattress gives when someone lands on it. */
59
+ export declare function bed(spec?: BedSpec): Prop;
60
+ export declare const BED_ACTING: ActingRig;
61
+ export interface DoorSpec {
62
+ kind?: string;
63
+ summary?: string;
64
+ /** The opening's width and height, metres */
65
+ width?: number;
66
+ height?: number;
67
+ /** Which side the hinge is on, seen from the front (default left) */
68
+ hinge?: 'left' | 'right';
69
+ colors?: {
70
+ frame?: string;
71
+ door?: string;
72
+ handle?: string;
73
+ beyond?: string;
74
+ };
75
+ }
76
+ /** A door in its frame: opens on its hinge, slams, and rattles when knocked; the doorway behind shows when it opens. */
77
+ export declare function door(spec?: DoorSpec): Prop;
78
+ export declare const DOOR_ACTING: ActingRig;
79
+ export interface WheelchairSpec {
80
+ /** Seat width, metres (default 0.5) */
81
+ width?: number;
82
+ /** Seat height off the ground, metres (default 0.5) */
83
+ seatHeight?: number;
84
+ /** The big wheels' radius, metres (default 0.3) */
85
+ wheelRadius?: number;
86
+ colors?: {
87
+ frame?: string;
88
+ seat?: string;
89
+ tyre?: string;
90
+ };
91
+ kind?: string;
92
+ summary?: string;
93
+ }
94
+ /**
95
+ * A wheelchair: a seat and back on a frame, two big rimmed wheels at the back
96
+ * (hand rims a rider turns), two castors at the front, footrests and push
97
+ * handles. Any character rides it (`propRide3D` on its `seat` in the
98
+ * `wheeling` pose); a pusher stands at `handles`. It is an accessory, not an
99
+ * age or a build: who sits in it is the story's choice.
100
+ */
101
+ export declare function wheelchair(spec?: WheelchairSpec): Prop;
102
+ export declare const WHEELCHAIR_ACTING: ActingRig;
@@ -14,6 +14,7 @@ export * from './effects';
14
14
  export * from './families/vehicle';
15
15
  export * from './ride';
16
16
  export * from './families/environment';
17
+ export * from './families/furniture';
17
18
  export * from './families/aircraft';
18
19
  export * from './families/animals';
19
20
  export * from './families/birds';
@@ -1,9 +1,10 @@
1
1
  import type { Prop } from './target';
2
2
  import { car, truck, bus, tractor, cart, trainCar, bike, motorbike } from './families/vehicle';
3
3
  import { tree, house } from './families/environment';
4
+ import { chair, desk, bed, door, wheelchair } from './families/furniture';
4
5
  import { helicopter, airplane } from './families/aircraft';
5
- import { horse, dog, cat, cow } from './families/animals';
6
- import { songbird, crow, chicken } from './families/birds';
6
+ import { horse, dog, cat, cow, goat, rabbit, squirrel } from './families/animals';
7
+ import { songbird, crow, chicken, pigeon, duck, owl, parrot } from './families/birds';
7
8
  /**
8
9
  * Every prop preset by name, so a prop can be named in plain data (a 3D
9
10
  * scene's `{ kind: 'prop', prop: 'car' }`, the catalog).
@@ -19,15 +20,27 @@ export declare const PROP_PRESETS: {
19
20
  motorbike: typeof motorbike;
20
21
  tree: typeof tree;
21
22
  house: typeof house;
23
+ chair: typeof chair;
24
+ desk: typeof desk;
25
+ bed: typeof bed;
26
+ door: typeof door;
27
+ wheelchair: typeof wheelchair;
22
28
  helicopter: typeof helicopter;
23
29
  airplane: typeof airplane;
24
30
  horse: typeof horse;
25
31
  dog: typeof dog;
26
32
  cat: typeof cat;
27
33
  cow: typeof cow;
34
+ goat: typeof goat;
35
+ rabbit: typeof rabbit;
36
+ squirrel: typeof squirrel;
28
37
  songbird: typeof songbird;
29
38
  crow: typeof crow;
30
39
  chicken: typeof chicken;
40
+ pigeon: typeof pigeon;
41
+ duck: typeof duck;
42
+ owl: typeof owl;
43
+ parrot: typeof parrot;
31
44
  };
32
45
  export type PropPresetName = keyof typeof PROP_PRESETS;
33
46
  /** A preset by name, with its options (colours, sizes); throws on a name it does not know, with the one probably meant. */
@@ -65,12 +65,15 @@ export interface PropRide3DOptions {
65
65
  /**
66
66
  * Riding poses for a human: on a seat, astride a saddle (legs apart round a
67
67
  * horse's barrel), driving (hands forward on a wheel) and on a bike's saddle
68
- * (leaning to the handlebars; the legs cycle with `pedallingPose`).
68
+ * (leaning to the handlebars; the legs cycle with `pedallingPose`), and
69
+ * wheeling a wheelchair (sitting up, the arms down at the sides to the hand
70
+ * rims).
69
71
  */
70
72
  export declare const RIDING_POSES: {
71
73
  seated: Pose;
72
74
  astride: Pose;
73
75
  driving: Pose;
76
+ wheeling: Pose;
74
77
  cycling: Pose;
75
78
  };
76
79
  /**
@@ -0,0 +1,126 @@
1
+ import type { CustomTarget } from '../adapters/canvas/canvas-adapter';
2
+ import type { Track } from '../engine/types';
3
+ import { type EditOptions } from './surface/edit-log';
4
+ import { type PropPresetName } from './props/presets';
5
+ import { type PropTarget } from './props/target';
6
+ /**
7
+ * Scenery behind the figures: a sky with the sun and moon on their arcs, stars
8
+ * at night, clouds drifting on the wind, rain that slants with it and snow
9
+ * that drifts, hills or a city on the horizon and the ground; or a room with
10
+ * a wall, a floor and a window on that sky. It is a canvas target whose
11
+ * values (`hour`, `clouds`, `wind`, `rain`, `snow`) are tracks, so a day
12
+ * passes and weather comes and goes as keyframes, and every frame is drawn
13
+ * from its time alone. `scenePreset` lays out a park, a street, an office or
14
+ * a home with it.
15
+ *
16
+ * ```ts
17
+ * const sky = scenery({ x: 0, y: 0, width: 720, height: 400, hour: 9, clouds: 0.4, horizon: 'hills' })
18
+ * sky.set('hour', { at: 0, value: 20, duration: 12000 }) // a day passes
19
+ * sky.set('rain', { at: 5000, value: 0.8, duration: 1500 })
20
+ * const tracks = sky.tracks('sky')
21
+ * ```
22
+ */
23
+ export type SceneryHorizon = 'hills' | 'city' | 'flat';
24
+ export interface SceneryOptions {
25
+ /** The backdrop's box, scene px */
26
+ x: number;
27
+ y: number;
28
+ width: number;
29
+ height: number;
30
+ /** Outdoors under a sky (default), or a room */
31
+ kind?: 'sky' | 'room';
32
+ /** Scene y of the ground line (default 85% of the way down the box) */
33
+ ground?: number;
34
+ /** Time of day, 0..24 (default 12): the sky's colours and where the sun and moon are */
35
+ hour?: number;
36
+ /** Cloud cover, 0..1 (default 0.3) */
37
+ clouds?: number;
38
+ /** Wind, −1..1 (default 0): clouds drift, rain slants, snow drifts; hair streams (see `hairFollow`) */
39
+ wind?: number;
40
+ /** Rain and snow, 0..1 (default 0) */
41
+ rain?: number;
42
+ snow?: number;
43
+ /** What is on the horizon (default hills outdoors) */
44
+ horizon?: SceneryHorizon;
45
+ /** A room: a window on the sky (default true) */
46
+ window?: boolean;
47
+ /** The particles' and the clouds' seed (default 1) */
48
+ seed?: number;
49
+ colors?: Partial<SceneryColors>;
50
+ }
51
+ export interface SceneryColors {
52
+ ground: string;
53
+ hills: string;
54
+ city: string;
55
+ cloud: string;
56
+ sun: string;
57
+ moon: string;
58
+ rain: string;
59
+ snow: string;
60
+ wall: string;
61
+ floor: string;
62
+ skirting: string;
63
+ frame: string;
64
+ }
65
+ export declare const SCENERY_COLORS: SceneryColors;
66
+ export interface Scenery {
67
+ readonly kind: 'scenery';
68
+ readonly target: CustomTarget;
69
+ /** Scene y of the ground line */
70
+ readonly ground: number;
71
+ /** Where a named place is at a time: `sun`, `moon`, `horizon`, `ground` (scene px; the sun and moon when up, else where they are below the horizon) */
72
+ anchor(name: 'sun' | 'moon' | 'horizon' | 'ground', time?: number): {
73
+ x: number;
74
+ y: number;
75
+ };
76
+ /** Change a value at a time: `hour`, `clouds`, `wind`, `rain`, `snow` */
77
+ set(prop: 'hour' | 'clouds' | 'wind' | 'rain' | 'snow', edit: EditOptions & {
78
+ value: number;
79
+ }): Scenery;
80
+ /** The recorded changes as tracks on `target` (the scenery's key in the scene) */
81
+ tracks(target: string): Track[];
82
+ }
83
+ /** The sky's colours at an hour. */
84
+ export declare function skyColors(hour: number): {
85
+ top: string;
86
+ bottom: string;
87
+ };
88
+ export declare function scenery(options: SceneryOptions): Scenery;
89
+ export type ScenePresetName = 'park' | 'street' | 'office' | 'home';
90
+ export interface ScenePresetOptions {
91
+ /** The scene's size, scene px */
92
+ width: number;
93
+ height: number;
94
+ /** Scene y of the ground (default 85% of the height) */
95
+ ground?: number;
96
+ /** Px per metre for the props (default: a quarter of the height per metre) */
97
+ scale?: number;
98
+ /** Overrides for the scenery (an hour, weather, colours) */
99
+ scenery?: Partial<SceneryOptions>;
100
+ }
101
+ /** A prop in a preset: which, where its middle stands (scene x), facing which way, with its scale. */
102
+ export interface PlacedProp {
103
+ preset: PropPresetName;
104
+ x: number;
105
+ turn?: number;
106
+ scale: number;
107
+ values?: Record<string, number>;
108
+ }
109
+ export interface ScenePreset {
110
+ scenery: SceneryOptions;
111
+ props: PlacedProp[];
112
+ }
113
+ /**
114
+ * Ready-made scenes as plain data: the scenery and where the props stand, as
115
+ * shares of the width. A park under a late-morning sky with trees and a
116
+ * bench; a street at the end of the afternoon with houses, a car and a
117
+ * tree against the city; an office with a desk, a chair and a door; a home
118
+ * with a bed, a chair and a door.
119
+ */
120
+ export declare function scenePreset(name: ScenePresetName | string, options: ScenePresetOptions): ScenePreset;
121
+ /** A preset built: its scenery target and its props as prop targets standing on the ground, in drawing order (left to right). */
122
+ export declare function buildScene(name: ScenePresetName | string, options: ScenePresetOptions): {
123
+ scenery: Scenery;
124
+ props: PropTarget[];
125
+ ground: number;
126
+ };
@@ -46,3 +46,20 @@ export declare function humanGag(name: HumanGagName, options: {
46
46
  }): Array<CharacterPoseKey & {
47
47
  pose: Pose;
48
48
  }>;
49
+ /**
50
+ * Everyday actions as cycles, like a gait: the pose at `phase` (0 → 1 is one
51
+ * stroke and back), built on `base`. Sweeping holds a broom in both hands
52
+ * (`holding: { right: 'broom' }` draws it) and sweeps it side to side, the
53
+ * body turning a little with it; brushing works a hand across a surface in
54
+ * front at chest height (a wall, a window, a horse's flank).
55
+ */
56
+ export declare function sweepingPose(phase: number, base?: Pose): Pose;
57
+ export declare function brushingPose(phase: number, base?: Pose): Pose;
58
+ /** The cycles by name, for `humanCyclePose`. */
59
+ export declare const HUMAN_CYCLES: {
60
+ readonly sweeping: typeof sweepingPose;
61
+ readonly brushing: typeof brushingPose;
62
+ };
63
+ export type HumanCycleName = keyof typeof HUMAN_CYCLES;
64
+ /** The pose of a named cycle at `phase` (0 → 1 is one stroke and back), built on `base`. */
65
+ export declare function humanCyclePose(name: HumanCycleName | string, phase: number, base?: Pose): Pose;
@@ -38,6 +38,8 @@ export interface HumanBuild {
38
38
  legLength?: number;
39
39
  /** Arm length, as a share of the standard (default 1) */
40
40
  armLength?: number;
41
+ /** The feet's shape (default round) */
42
+ feet?: FootShape;
41
43
  }
42
44
  /**
43
45
  * Ready-made builds: proportions only, so the same poses, gaits and actions
@@ -127,6 +129,7 @@ export declare const HUMAN_POSES: {
127
129
  stretch: Pose;
128
130
  sitFloor: Pose;
129
131
  carry: Pose;
132
+ cane: Pose;
130
133
  lift: Pose;
131
134
  push: Pose;
132
135
  pull: Pose;
@@ -137,6 +140,9 @@ export declare const HUMAN_POSES: {
137
140
  };
138
141
  export type HumanPoseName = keyof typeof HUMAN_POSES;
139
142
  /** A human body plan; the same pose fields work on every build. */
143
+ /** The shape of the feet: round (the default), flat (a shoe), pointed (a slipper, an elf), or big (clown's feet). */
144
+ export type FootShape = 'round' | 'flat' | 'pointed' | 'big';
145
+ export declare const FOOT_SHAPES: readonly FootShape[];
140
146
  export declare function humanPlan(build?: HumanBuild): BodyPlan;
141
147
  /** Plain-language names for the human pose fields, for timelines and property panels. */
142
148
  export declare function humanFieldLabel(field: string): string;
@@ -4,8 +4,9 @@ import type { CharacterLayers } from '../character';
4
4
  * body's parts through the character's pen (so they match the look). The
5
5
  * base is a top and trousers whose sleeves grow out of the shirt's shoulders
6
6
  * with no seam; the options change its cut (long or no sleeves, shorts, a
7
- * skirt) and add pieces worn over it (a collar, a tie, an apron, a lab coat).
8
- * The defaults are the original T-shirt and trousers, unchanged.
7
+ * skirt) and add pieces worn over it (a collar, a tie, an apron, a lab coat,
8
+ * a hoodie, a cardigan, overalls, a sari) and boots on the feet. The defaults
9
+ * are the original T-shirt and trousers, unchanged.
9
10
  */
10
11
  export interface BasicOutfitOptions {
11
12
  /** Shirt colour (default red) */
@@ -20,9 +21,19 @@ export interface BasicOutfitOptions {
20
21
  collar?: boolean;
21
22
  /** A tie down the front, in this colour */
22
23
  tie?: string | null;
23
- /** Worn over the clothes: an apron or a lab coat (default none) */
24
- over?: 'apron' | 'labCoat' | null;
25
- /** The apron's or lab coat's colour (default: white coat, tan apron) */
24
+ /**
25
+ * Worn over the clothes (default none): an apron, a lab coat, a hoodie (a
26
+ * loose top with a hood at the back, a front pocket and long sleeves), a
27
+ * cardigan (open down the front, buttoned, long sleeves), overalls (a bib
28
+ * on the chest with straps over the shoulders, in the trousers' colour) or
29
+ * a sari (a drape to the ankles with the pallu over the near shoulder)
30
+ */
31
+ over?: 'apron' | 'labCoat' | 'hoodie' | 'cardigan' | 'overalls' | 'sari' | null;
32
+ /** The colour of what is worn over (default: white coat, tan apron, grey hoodie, olive cardigan, green sari) */
26
33
  overColor?: string;
34
+ /** On the feet: nothing (default), or boots to above the ankle */
35
+ shoes?: 'none' | 'boots';
36
+ /** The boots' colour (default dark brown) */
37
+ shoeColor?: string;
27
38
  }
28
39
  export declare function basicOutfit(options?: BasicOutfitOptions): CharacterLayers;
@@ -0,0 +1,46 @@
1
+ import { type BeatGrid } from './beats';
2
+ /**
3
+ * Beats and sound for loops. A loop closes when its length is a whole number
4
+ * of beats, so the pulse on its last beat runs straight into its first:
5
+ * `loopBeats` fits a grid to a period (or a period to a grid), `beatPulse`
6
+ * is a pulse that spikes on every beat, and `audioEnvelope` turns samples
7
+ * into a level per frame for motion that follows the music. All pure.
8
+ */
9
+ /** How many ms a whole number of beats takes. */
10
+ export declare function beatPeriod(grid: Pick<BeatGrid, 'bpm'>, beats: number): number;
11
+ /**
12
+ * Cut a tempo to a loop: the nearest whole number of beats in `period` ms,
13
+ * and the tempo nudged so they fit it exactly (a drone or riser stretched a
14
+ * hair, never cut mid-beat). The grid's `offset` is kept.
15
+ */
16
+ export declare function loopBeats(period: number, grid: BeatGrid): {
17
+ beats: number;
18
+ grid: BeatGrid;
19
+ };
20
+ export interface BeatPulseOptions {
21
+ /** How fast the pulse rises, as a share of a beat (default 0.05) */
22
+ attack?: number;
23
+ /** How long it takes to fall back, as a share of a beat (default 0.4) */
24
+ decay?: number;
25
+ /** Stress the first beat of each bar this much more, 0.. (default 0: all beats alike) */
26
+ barAccent?: number;
27
+ }
28
+ /**
29
+ * A pulse that spikes to 1 on every beat and decays, as a function of time:
30
+ * scale a shape by `1 + 0.2 * beatPulse(t, grid)` and it bobs to the music.
31
+ * Over a loop that is a whole number of beats (`loopBeats`), it repeats
32
+ * exactly.
33
+ */
34
+ export declare function beatPulse(time: number, grid: BeatGrid, options?: BeatPulseOptions): number;
35
+ export interface EnvelopeOptions {
36
+ /** Levels per second (default 30: one per video frame) */
37
+ fps?: number;
38
+ /** How much each level keeps of the last, 0..1 (default 0.5): higher is smoother, slower to fall */
39
+ smoothing?: number;
40
+ /** Scale so the loudest level is 1 (default true) */
41
+ normalize?: boolean;
42
+ }
43
+ /** The loudness of audio over time: one level (0..1) per frame, smoothed. Deterministic. */
44
+ export declare function audioEnvelope(samples: Float32Array, sampleRate: number, options?: EnvelopeOptions): Float32Array;
45
+ /** The envelope's level at a time, between its frames; with `period` the time wraps, for a loop. */
46
+ export declare function envelopeAt(levels: Float32Array, time: number, fps?: number, period?: number): number;