@algorisys/tinyfly 0.99.0 → 0.100.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 (38) hide show
  1. package/README.md +8 -8
  2. package/docs/acting.md +10 -6
  3. package/docs/character-appearance.md +45 -7
  4. package/docs/editor-guide.md +38 -3
  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 +20 -7
  9. package/docs/maps.md +2 -2
  10. package/docs/props.md +61 -1
  11. package/docs/teaching.md +1 -1
  12. package/lib/addons/characters.js +5882 -4858
  13. package/lib/browser/tinyfly.iife.js +14 -14
  14. package/lib/browser/tinyfly.js +7145 -6121
  15. package/lib/browser/tinyfly.umd.js +14 -14
  16. package/lib/types/characters/acting/character-script.d.ts +14 -2
  17. package/lib/types/characters/acting/script.d.ts +9 -0
  18. package/lib/types/characters/capabilities.d.ts +2 -0
  19. package/lib/types/characters/character.d.ts +8 -1
  20. package/lib/types/characters/hair-follow.d.ts +12 -6
  21. package/lib/types/characters/hands/held-items.d.ts +6 -2
  22. package/lib/types/characters/head/face.d.ts +6 -1
  23. package/lib/types/characters/index.d.ts +3 -2
  24. package/lib/types/characters/interactions.d.ts +60 -0
  25. package/lib/types/characters/props/families/animals.d.ts +6 -0
  26. package/lib/types/characters/props/families/birds.d.ts +16 -0
  27. package/lib/types/characters/props/families/furniture.d.ts +102 -0
  28. package/lib/types/characters/props/index.d.ts +1 -0
  29. package/lib/types/characters/props/presets.d.ts +15 -2
  30. package/lib/types/characters/props/ride-3d.d.ts +4 -1
  31. package/lib/types/characters/scenery.d.ts +126 -0
  32. package/lib/types/characters/species/human-motion.d.ts +17 -0
  33. package/lib/types/characters/species/human.d.ts +6 -0
  34. package/lib/types/characters/wardrobe/basic-outfit.d.ts +16 -5
  35. package/llms-full.txt +205 -40
  36. package/llms.txt +29 -29
  37. package/package.json +2 -2
  38. package/skills/tinyfly/SKILL.md +13 -6
@@ -28,8 +28,12 @@ import { type Character, type CharacterPoseKey } from '../character';
28
28
  * `walking` and `gait` tracks step the gait as the target draws, as the 3D
29
29
  * character object does.
30
30
  *
31
- * Hands reach in the stick figure's proportions, so a `grab` or a `point`
32
- * lands near its target on the human body, not exactly on it.
31
+ * The stick-figure script solves every reach (a `point`, a `grab`, a `kick`…)
32
+ * for its own body. The human's arms and legs reach differently, so the plan
33
+ * is made with its own reach (`reach`: the figure steps to where the human
34
+ * limb reaches), and while a beat's hand or foot is on its target the human
35
+ * limb is re-aimed (`reachCharacter`) at where the stick figure's landed, so
36
+ * it lands exactly.
33
37
  */
34
38
  export type CharacterScriptOptions = Omit<ScriptOptions, 'height'>;
35
39
  export interface CharacterScriptResult extends Omit<ScriptResult, 'keys'> {
@@ -42,3 +46,11 @@ export interface CharacterScriptResult extends Omit<ScriptResult, 'keys'> {
42
46
  */
43
47
  export declare function characterStrideLength(who: Character, gait: Gait | string | undefined, stride?: number): number;
44
48
  export declare function characterScript(target: string, who: Character, beats: Beat[], options?: CharacterScriptOptions): CharacterScriptResult;
49
+ /**
50
+ * How far the character's straight arm and leg reach, as a share of the stick
51
+ * figure's at the same height: the script stands it that much nearer.
52
+ */
53
+ export declare function reachOf(who: Character): {
54
+ arm: number;
55
+ leg: number;
56
+ };
@@ -103,6 +103,15 @@ export interface ScriptOptions extends ActingOptions, Cast {
103
103
  start?: StickPose;
104
104
  /** Lip-sync energy (default 1) */
105
105
  energy?: number;
106
+ /**
107
+ * How far the arm and leg reach, as a share of the stick figure's own (default 1):
108
+ * a body with other proportions (a v2 character) plans its steps to where its
109
+ * limbs reach
110
+ */
111
+ reach?: {
112
+ arm?: number;
113
+ leg?: number;
114
+ };
106
115
  }
107
116
  export interface ScriptResult {
108
117
  /** Every track the script writes, on the target */
@@ -71,6 +71,8 @@ export interface Capabilities {
71
71
  facialHair: string[];
72
72
  glasses: string[];
73
73
  hats: string[];
74
+ /** `feet` option */
75
+ feet: string[];
74
76
  /** `castMember(name, height)` */
75
77
  cast: string[];
76
78
  /** `holding: { left | right | both: item }`, and which hands each takes */
@@ -5,8 +5,9 @@ import type { FrameInfo } from '../headless/video-scene';
5
5
  import type { BodyPlan, Pose, Vec3 } from './rig/body-plan';
6
6
  import { type SolvedHead, type ViewProjection } from './rig/skeleton';
7
7
  import { type Look, type Pen, type PencilOptions } from './look/pen';
8
+ import { type FaceOptions } from './head/face';
8
9
  import { type HeadLook, type HeadLookOptions } from './head/head-look';
9
- import { type HumanBuildName, type HumanPoseName } from './species/human';
10
+ import { type HumanBuildName, type HumanPoseName, type FootShape } from './species/human';
10
11
  import type { Gait } from './gaits';
11
12
  import { type BasicOutfitOptions } from './wardrobe/basic-outfit';
12
13
  import { type Holding, type HoldingSpec } from './hands/held-items';
@@ -90,6 +91,10 @@ export interface CharacterOptions extends HeadLookOptions {
90
91
  handStyle?: 'glove' | 'natural';
91
92
  /** Cartoon hand length, wrist to fingertip, fraction of the height (default 0.17 for gloves, 0.14 natural) */
92
93
  handSize?: number;
94
+ /** The feet's shape: `round` (default), `flat`, `pointed` or `big` */
95
+ feet?: FootShape;
96
+ /** What an open mouth shows: `teeth` (a row of upper teeth) and a `tongue` (default neither) */
97
+ face?: FaceOptions;
93
98
  }
94
99
  /** A character, with every option resolved. Plain data plus its plan. */
95
100
  export interface Character {
@@ -111,6 +116,8 @@ export interface Character {
111
116
  head: HeadLook;
112
117
  /** What each hand holds (drawn by its layers) */
113
118
  holding: Holding;
119
+ /** What an open mouth shows */
120
+ face: Required<FaceOptions>;
114
121
  }
115
122
  export declare function character(options?: CharacterOptions): Character;
116
123
  /** Where every part of a character is, as drawn, in its drawing space (feet at 0, 0; up is -y). */
@@ -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,9 @@ 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
+ /** What an open mouth shows: a row of upper teeth, and a tongue (default neither, as the plain face). */
18
+ export interface FaceOptions {
19
+ teeth?: boolean;
20
+ tongue?: boolean;
21
+ }
22
+ export declare function drawFace(pen: Pen, head: SolvedHead, pose: Pose, lineWidth: number, options?: FaceOptions): 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;