@algorisys/tinyfly 0.98.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 (48) hide show
  1. package/README.md +10 -10
  2. package/docs/acting.md +81 -14
  3. package/docs/character-appearance.md +96 -10
  4. package/docs/editor-guide.md +76 -4
  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 +29 -9
  9. package/docs/maps.md +2 -2
  10. package/docs/props.md +61 -1
  11. package/docs/scene-3d.md +3 -1
  12. package/docs/teaching.md +1 -1
  13. package/lib/addons/characters.js +6709 -5248
  14. package/lib/browser/tinyfly.iife.js +15 -15
  15. package/lib/browser/tinyfly.js +7532 -6071
  16. package/lib/browser/tinyfly.umd.js +15 -15
  17. package/lib/types/characters/acting/character-script.d.ts +56 -0
  18. package/lib/types/characters/acting/index.d.ts +1 -0
  19. package/lib/types/characters/acting/script.d.ts +9 -0
  20. package/lib/types/characters/capabilities.d.ts +2 -0
  21. package/lib/types/characters/character.d.ts +21 -2
  22. package/lib/types/characters/chart.d.ts +52 -14
  23. package/lib/types/characters/hair-follow.d.ts +82 -0
  24. package/lib/types/characters/hands/held-items.d.ts +6 -2
  25. package/lib/types/characters/head/face.d.ts +6 -1
  26. package/lib/types/characters/head/hair.d.ts +27 -1
  27. package/lib/types/characters/head/head-look.d.ts +5 -2
  28. package/lib/types/characters/head/index.d.ts +1 -1
  29. package/lib/types/characters/index.d.ts +4 -2
  30. package/lib/types/characters/interactions.d.ts +60 -0
  31. package/lib/types/characters/props/draw.d.ts +9 -0
  32. package/lib/types/characters/props/families/animals.d.ts +6 -0
  33. package/lib/types/characters/props/families/birds.d.ts +16 -0
  34. package/lib/types/characters/props/families/furniture.d.ts +102 -0
  35. package/lib/types/characters/props/index.d.ts +1 -0
  36. package/lib/types/characters/props/presets.d.ts +15 -2
  37. package/lib/types/characters/props/prop-surface.d.ts +14 -3
  38. package/lib/types/characters/props/ride-3d.d.ts +34 -2
  39. package/lib/types/characters/props/target.d.ts +5 -1
  40. package/lib/types/characters/scenery.d.ts +126 -0
  41. package/lib/types/characters/species/human-motion.d.ts +17 -0
  42. package/lib/types/characters/species/human.d.ts +8 -0
  43. package/lib/types/characters/wardrobe/basic-outfit.d.ts +16 -5
  44. package/lib/types/characters/whiteboard.d.ts +13 -1
  45. package/llms-full.txt +400 -70
  46. package/llms.txt +29 -29
  47. package/package.json +2 -2
  48. package/skills/tinyfly/SKILL.md +22 -10
@@ -0,0 +1,56 @@
1
+ import { type Beat, type ScriptOptions, type ScriptResult } from './script';
2
+ import { type Gait } from '../gaits';
3
+ import { type Character, type CharacterPoseKey } from '../character';
4
+ /**
5
+ * Beat scripts for v2 characters: the same beats `scriptTracks` compiles for
6
+ * the stick figure (walk and the other gaits, `say`, `look`, `face`, poses,
7
+ * gags, `zip`, `leap`, `grab`, `throw`, `kick`, `put`, `write`, `push`, your
8
+ * own actions and gaits), compiled into tracks for a `characterTarget`.
9
+ *
10
+ * ```js
11
+ * const amy = character(castMember('youngWoman', 170))
12
+ * const script = characterScript('amy', amy, [
13
+ * { do: 'walk', to: 330, mood: 'happy' },
14
+ * { do: 'say', say: 'Is that box ticking?', mood: 'worried' },
15
+ * { do: 'take' },
16
+ * { do: 'zip', to: -200 },
17
+ * ], { from: 90 })
18
+ * const timeline = deserializeTimeline({ id: 'scene', tracks: script.tracks })
19
+ * ```
20
+ *
21
+ * How it works: the stick-figure script plans the story (timing, where the
22
+ * figure is, which way it faces, its gait, its speech); its key poses are
23
+ * taken onto the human body (`stickToHuman`, mirrored when it faces left, so
24
+ * the character's `turn` runs negative that way); the human acting pass then
25
+ * winds up, overshoots and overlaps on this body, and the lines are
26
+ * lip-synced over its mouth. The walk phase is rekeyed to the character's own
27
+ * stride (its height and legs), so its feet stay planted. The `walk`,
28
+ * `walking` and `gait` tracks step the gait as the target draws, as the 3D
29
+ * character object does.
30
+ *
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.
37
+ */
38
+ export type CharacterScriptOptions = Omit<ScriptOptions, 'height'>;
39
+ export interface CharacterScriptResult extends Omit<ScriptResult, 'keys'> {
40
+ /** The key poses on the human body, before acting */
41
+ keys: CharacterPoseKey[];
42
+ }
43
+ /**
44
+ * Ground one gait cycle covers for this character, px: its own height and
45
+ * legs (a child's are shorter), so the feet stay planted.
46
+ */
47
+ export declare function characterStrideLength(who: Character, gait: Gait | string | undefined, stride?: number): number;
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
+ };
@@ -15,3 +15,4 @@ export * from './beat-check';
15
15
  export * from './surface-script';
16
16
  export * from './custom';
17
17
  export * from './persona';
18
+ export * from './character-script';
@@ -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,10 @@ 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';
11
+ import type { Gait } from './gaits';
10
12
  import { type BasicOutfitOptions } from './wardrobe/basic-outfit';
11
13
  import { type Holding, type HoldingSpec } from './hands/held-items';
12
14
  import { type HandPose } from './hands/hand-rig';
@@ -89,6 +91,10 @@ export interface CharacterOptions extends HeadLookOptions {
89
91
  handStyle?: 'glove' | 'natural';
90
92
  /** Cartoon hand length, wrist to fingertip, fraction of the height (default 0.17 for gloves, 0.14 natural) */
91
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;
92
98
  }
93
99
  /** A character, with every option resolved. Plain data plus its plan. */
94
100
  export interface Character {
@@ -110,6 +116,8 @@ export interface Character {
110
116
  head: HeadLook;
111
117
  /** What each hand holds (drawn by its layers) */
112
118
  holding: Holding;
119
+ /** What an open mouth shows */
120
+ face: Required<FaceOptions>;
113
121
  }
114
122
  export declare function character(options?: CharacterOptions): Character;
115
123
  /** Where every part of a character is, as drawn, in its drawing space (feet at 0, 0; up is -y). */
@@ -209,14 +217,25 @@ export interface CharacterTargetOptions {
209
217
  character: Character;
210
218
  /** Starting pose (default rest) */
211
219
  pose?: Pose;
220
+ /** Your own gaits, by the names a `gait` track uses (built-in names need no entry) */
221
+ gaits?: Record<string, Gait>;
212
222
  }
213
223
  /** A `custom` target made by {@link characterTarget}. */
214
224
  export interface CharacterTarget extends CustomTarget {
215
225
  readonly character: Character;
226
+ readonly gaits?: Record<string, Gait>;
216
227
  }
228
+ /**
229
+ * The pose a target's props describe: its pose fields, with its gait stepped
230
+ * in as far as `walking` says (`walk` is the phase, `gait` which gait), on the
231
+ * pose it holds. Props that are not pose fields (`facing`, strings) are left
232
+ * out.
233
+ */
234
+ export declare function characterPoseOf(props: Record<string, unknown>, rest?: Pose, gaits?: Record<string, Gait>): Pose;
217
235
  /**
218
236
  * A `custom` canvas target that draws a character. Every pose field is a
219
- * prop, so timeline tracks pose, turn and roll it. `x`/`y` are the feet.
237
+ * prop, so timeline tracks pose, turn and roll it; `walk`, `walking` and
238
+ * `gait` tracks step its gait (see `characterScript`). `x`/`y` are the feet.
220
239
  */
221
240
  export declare function characterTarget(options: CharacterTargetOptions): CharacterTarget;
222
241
  /** Joints moved from a character's drawing space to a scene where its feet stand at (x, y). */
@@ -5,8 +5,9 @@ import { type FlingOptions, type SurfacePiece, type TimedPoint } from './surface
5
5
  import { type Surface, type SurfaceAbout, type SurfaceEditOptions } from './surface/surface';
6
6
  import { type SurfaceBox } from './surface/surface-box';
7
7
  /**
8
- * A bar or line chart as a scene object figures act on: they point at a
9
- * bar, highlight the dip, and stand on a bar as it grows.
8
+ * A bar, line, pie or donut chart as a scene object figures act on: they
9
+ * point at a bar, highlight the dip, stand on a bar as it grows, pull a
10
+ * slice out of a pie and kick it away.
10
11
  *
11
12
  * ```ts
12
13
  * const sales = chart({
@@ -20,17 +21,27 @@ import { type SurfaceBox } from './surface/surface-box';
20
21
  * sales.edit('highlight', 'bar:q2', { at: 600 })
21
22
  * sales.edit('show', 'bar:q3', { at: 1200 }) // grows in from the axis
22
23
  * sales.edit('set', 'bar:q1', { at: 2000, value: 80 }) // and its value label counts up
24
+ *
25
+ * const traffic = chart({ x: 500, y: 30, width: 300, height: 280, kind: 'donut', data: [...] })
26
+ * traffic.edit('pull', 'slice:mobile', { at: 400 }) // out from the centre
27
+ * traffic.fling(traffic.piece('slice:other'), { at: 900 })
23
28
  * ```
24
29
  *
30
+ * Several series (`series: [{ id: 'a' }, { id: 'b' }]`, values as
31
+ * `values: { a: 10, b: 12 }`) draw grouped bars or one line each, with a
32
+ * legend; their places are `bar:ID:SERIES`. A pie shows one series.
33
+ *
25
34
  * The data is declared up front; the scale (`max`) is fixed when it is made
26
35
  * (from the data, or given), so a bar set past it grows out of the plot.
27
36
  * Its places follow the values: `anchor('bar:q1', time)` is the bar as it
28
37
  * stands at `time` (default: after every edit; a surface script aims beats
29
38
  * at it as laid out). A figure standing on a bar's top is carried up and
30
39
  * down with it (`ride()`). Edits are keys on its props: `bar.ID.value`,
31
- * `bar.ID.show`, `bar.ID.highlight` (or `point.ID.…` on a line chart).
40
+ * `bar.ID.show`, `bar.ID.highlight` (or `point.ID.…` on a line chart,
41
+ * `slice.ID.…` and `slice.ID.pull` on a pie; `bar.ID.SERIES.…` with several
42
+ * series).
32
43
  */
33
- export type ChartKind = 'bar' | 'line';
44
+ export type ChartKind = 'bar' | 'line' | 'pie' | 'donut';
34
45
  export declare const CHART_KINDS: readonly ChartKind[];
35
46
  export type ChartThemeName = 'light' | 'dark';
36
47
  export interface ChartTheme {
@@ -38,20 +49,33 @@ export interface ChartTheme {
38
49
  text: string;
39
50
  /** Axis and grid lines */
40
51
  grid: string;
41
- /** Bars, the line and its points */
52
+ /** Bars, the line and its points (the first series) */
42
53
  color: string;
43
- /** A highlighted bar or point */
54
+ /** A highlighted bar, point or slice */
44
55
  highlight: string;
56
+ /** Slices and series in turn (the first is `color`) */
57
+ palette: string[];
45
58
  font: string;
46
59
  }
47
60
  export declare const CHART_THEMES: Record<ChartThemeName, ChartTheme>;
48
- /** One bar or point. */
61
+ /** One of several series: its own colour, a bar in each group or a line of its own. */
62
+ export interface ChartSeries {
63
+ id: string;
64
+ /** In the legend (default its id) */
65
+ label?: string;
66
+ /** Its colour (default the theme's palette, in turn) */
67
+ color?: string;
68
+ }
69
+ /** One bar, point or slice. */
49
70
  export interface ChartDatum {
50
71
  id: string;
51
72
  /** Under it, on the axis (default its id) */
52
73
  label?: string;
53
- value: number;
54
- /** Start at nothing: a bar flat on the axis, a point the line has not reached; brought in with `show` */
74
+ /** Its value (one series) */
75
+ value?: number;
76
+ /** Its value in each series, by series id (several series) */
77
+ values?: Record<string, number>;
78
+ /** Start at nothing: a bar flat on the axis, a point the line has not reached, a slice of no width; brought in with `show` */
55
79
  hidden?: boolean;
56
80
  }
57
81
  export interface ChartOptions {
@@ -62,28 +86,42 @@ export interface ChartOptions {
62
86
  height: number;
63
87
  kind: ChartKind;
64
88
  data: ChartDatum[];
89
+ /** Several series (bar and line charts): each datum then gives `values` by series id */
90
+ series?: ChartSeries[];
65
91
  /** The value at the top of the plot (default: a round number above the largest value) */
66
92
  max?: number;
67
93
  title?: string;
94
+ /** Axis titles (bar and line charts) */
95
+ axis?: {
96
+ x?: string;
97
+ y?: string;
98
+ };
99
+ /** Show the legend with several series (default true) */
100
+ legend?: boolean;
68
101
  theme?: ChartThemeName | Partial<ChartTheme>;
69
102
  /** Value labels: decimal places (default 0), and text before and after the number */
70
103
  decimals?: number;
71
104
  prefix?: string;
72
105
  suffix?: string;
73
- /** Show each value above its bar or point (default true) */
106
+ /** Show each value above its bar or point, or on its slice (default true) */
74
107
  values?: boolean;
75
108
  }
109
+ /** A slice of a pie or donut that has come loose. */
110
+ export interface ChartSlicePiece extends SurfacePiece {
111
+ /** The datum it is the slice of */
112
+ readonly datum: string;
113
+ }
76
114
  export interface Chart extends Surface {
77
115
  readonly kind: 'chart';
78
116
  readonly chartKind: ChartKind;
79
117
  readonly target: CustomTarget;
80
118
  readonly box: SurfaceBox;
81
- /** The value at the top of the plot */
119
+ /** The value at the top of the plot (pies: the total of the data) */
82
120
  readonly max: number;
83
- /** The box at a named place, as it stands at `time`: `box`, `bar:ID` or `point:ID`, `label:ID`, `value:ID` */
121
+ /** The box at a named place, as it stands at `time`: `box`, `bar:ID`, `point:ID`, `slice:ID` (`:SERIES` after the id with several series), `label:ID`, `value:ID`, `legend:SERIES` */
84
122
  anchor(name: string, time?: number): SurfaceBox;
85
- /** A chart has no pieces: this throws */
86
- piece(anchor: string): SurfacePiece;
123
+ /** Make the slice at a `slice:` place a piece that can come loose (pies and donuts) */
124
+ piece(anchor: string): ChartSlicePiece;
87
125
  /** Change the chart at a time by name, at named places (see `CHART_SURFACE.edits`) */
88
126
  edit(name: string, anchor: string | string[], options: SurfaceEditOptions): Chart;
89
127
  follow(piece: SurfacePiece, path: TimedPoint[]): Chart;
@@ -0,0 +1,82 @@
1
+ import type { Track } from '../engine/types';
2
+ import type { Pose } from './rig/body-plan';
3
+ import { type Character } from './character';
4
+ import type { Gait } from './gaits';
5
+ /**
6
+ * Hair follow-through: hanging hair (long hair, ponytails, braids) lags
7
+ * behind the head, swinging round it after a turn, streaming back on a run,
8
+ * dropping on a jump and lifting on the landing. The drawing stays stateless:
9
+ * the lag is three pose fields (`hair.swing`, `hair.trail`, `hair.lift`), and
10
+ * this module works them out ahead of time from the head's motion, the way
11
+ * `Prop.follow` does for a car's antenna or a dog's tail.
12
+ *
13
+ * // Timelines: add the hair's tracks after the character's own.
14
+ * const tracks = characterPoseTracks('amy', keys)
15
+ * tracks.push(...hairFollowTracks('amy', tracks, amy))
16
+ *
17
+ * // Code that poses a character every frame: key the lag once for the
18
+ * // loop, then read it at each frame's time.
19
+ * const keys = hairFollow((t) => ({ x: xAt(t), y: 0, turn: turnAt(t) }), { end: 8000, headRadius: 24 })
20
+ * drawCharacter(ctx, amy, humanPose({ turn: turnAt(t), ...hairMotionAt(keys, t) }), t)
21
+ *
22
+ * Each lag chases its primary on a spring stepped in fixed 1 ms steps
23
+ * (`springFollow`), so the same motion always gives the same keys.
24
+ */
25
+ /** Where the head is at a time: screen x and y (px) and the body's view (`turn`), plus the head's own turn (degrees). */
26
+ export interface HairFollowSample {
27
+ x: number;
28
+ y: number;
29
+ /** The pose's `turn` (0 front, 1 profile facing screen-right, 2 back…) */
30
+ turn: number;
31
+ /** The pose's `head.turn`, degrees toward the character's left (default 0) */
32
+ headTurn?: number;
33
+ }
34
+ export interface HairFollowOptions {
35
+ /** From and to, ms (start defaults to 0) */
36
+ start?: number;
37
+ end: number;
38
+ /** The head's radius on screen, px: the lag is measured in head radii */
39
+ headRadius: number;
40
+ /** Key spacing, ms (default 33) */
41
+ step?: number;
42
+ /** Spring stiffness (default 70): higher follows the head more tightly */
43
+ stiffness?: number;
44
+ /** Damping (default 6): lower swings longer */
45
+ damping?: number;
46
+ /** How much the hair lags, 1 the default feel; 0 pins it to the head */
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;
50
+ }
51
+ /** The hair's lag at one time. */
52
+ export interface HairFollowKey {
53
+ time: number;
54
+ /** `hair.swing`: round the head toward the character's left (+), degrees */
55
+ swing: number;
56
+ /** `hair.trail`: streaming back behind the head (+), head radii */
57
+ trail: number;
58
+ /** `hair.lift`: lifted (+) or dropped (−), head radii */
59
+ lift: number;
60
+ }
61
+ /**
62
+ * Key the hair's lag over a span, from where the head is at each moment.
63
+ * Returns a key every `step` ms from `start` to `end`.
64
+ */
65
+ export declare function hairFollow(sample: (time: number) => HairFollowSample, options: HairFollowOptions): HairFollowKey[];
66
+ /** The hair's lag at a time, between keys, as the pose fields it sets (`hair.swing`, `hair.trail`, `hair.lift`). */
67
+ export declare function hairMotionAt(keys: HairFollowKey[], time: number): Pose;
68
+ export interface HairFollowTrackOptions extends Pick<HairFollowOptions, 'step' | 'stiffness' | 'damping' | 'amount' | 'wind'> {
69
+ /** How long the hair keeps settling after the last key, ms (default 1500) */
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>;
73
+ }
74
+ /**
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.
81
+ */
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;
@@ -1,3 +1,4 @@
1
+ import type { Pose } from '../rig/body-plan';
1
2
  import type { SolvedHead } from '../rig/skeleton';
2
3
  import type { Pen } from '../look/pen';
3
4
  import { type ShellRegion } from './shell';
@@ -13,7 +14,30 @@ import { type ShellRegion } from './shell';
13
14
  * turn, the back view shows the back of the hair, and a ponytail stays tied
14
15
  * to the same place. The part facing away is drawn before the head, the part
15
16
  * facing the viewer after it.
17
+ *
18
+ * Hair that hangs (long hair, ponytails, braids) also swings: three pose
19
+ * fields (`hair.swing`, `hair.trail`, `hair.lift`) carry how far its ends
20
+ * lag behind the head, and `hairFollow` works them out from the head's
21
+ * motion as keyframes, so drawing stays stateless.
22
+ */
23
+ /**
24
+ * How far hanging hair lags behind the head, at its ends (the roots stay on
25
+ * the head). Plain numbers that live in the pose as `hair.swing`,
26
+ * `hair.trail` and `hair.lift`, so they key, save and mirror like any field.
16
27
  */
28
+ export interface HairMotion {
29
+ /** Swung round the head toward the character's left (+) or right (−), degrees */
30
+ swing: number;
31
+ /** Streaming back behind the head (+) or thrown forward (−), head radii */
32
+ trail: number;
33
+ /** Lifted (+) or dropped (−), head radii */
34
+ lift: number;
35
+ }
36
+ export declare const HAIR_STILL: HairMotion;
37
+ /** The hair motion a pose carries (`hair.swing`, `hair.trail`, `hair.lift`; missing fields are still). */
38
+ export declare function hairMotionOf(pose: Pose | undefined): HairMotion;
39
+ /** Whether a style has anything that swings: hair hanging below the head, or a ponytail or braid. */
40
+ export declare function hairHangs(hair: Hair): boolean;
17
41
  export type HairTexture = 'smooth' | 'spiky' | 'curly' | 'wavy' | 'locs';
18
42
  /** Detail lines drawn on the hair: none, a parting, strands swept from a parting, combed back, hanging strands, a few thin strands */
19
43
  export type HairStrands = 'none' | 'part' | 'sweep' | 'combed' | 'hanging' | 'thin';
@@ -544,12 +568,14 @@ export declare function hairlineAt(hair: Hair, around: number): number;
544
568
  * The hair as a region on the head. `pad` (head radii) lifts it clear of
545
569
  * the head's own outline, so a thick head line never shows through it.
546
570
  */
547
- export declare function hairRegion(hair: Hair, pad: number): ShellRegion;
571
+ export declare function hairRegion(hair: Hair, pad: number, motion?: HairMotion): ShellRegion;
548
572
  export interface HairDrawOptions {
549
573
  /** The character's line width, px */
550
574
  lineWidth: number;
551
575
  /** Skin colour, for the scalp under close-cropped hair */
552
576
  skin: string;
577
+ /** How far hanging hair lags behind the head (default still) */
578
+ motion?: HairMotion;
553
579
  }
554
580
  /**
555
581
  * The hair behind the head: the part facing away, and ties on the far side.
@@ -21,6 +21,9 @@ import { type Hat, type HatSpec, type HatStyle } from './hats';
21
21
  * Which part wins where two overlap is fixed by that order: the face's eyes
22
22
  * and brows draw over a fringe, the mouth over a beard (which leaves an
23
23
  * opening for it), a moustache over the mouth's top, and a hat over the hair.
24
+ *
25
+ * Hanging hair lags behind the head by the pose's `hair.swing`, `hair.trail`
26
+ * and `hair.lift` (see `hairFollow`); the passes read them from the pose.
24
27
  */
25
28
  export interface HeadLookOptions {
26
29
  /** Hair: a style name, a style with changes (`{ style: 'bob', color: '#9a4426' }`), or null for none (the default) */
@@ -46,8 +49,8 @@ export interface HeadDrawOptions {
46
49
  lineWidth: number;
47
50
  skin: string;
48
51
  }
49
- export declare function drawHeadBehind(ctx: CanvasRenderingContext2D, pen: Pen, look: HeadLook, head: SolvedHead, _pose: Pose, options: HeadDrawOptions): void;
52
+ export declare function drawHeadBehind(ctx: CanvasRenderingContext2D, pen: Pen, look: HeadLook, head: SolvedHead, pose: Pose, options: HeadDrawOptions): void;
50
53
  /** The head's front pass; `drawFace` draws the face at its place in the order. */
51
54
  export declare function drawHeadFront(_ctx: CanvasRenderingContext2D, pen: Pen, look: HeadLook, head: SolvedHead, pose: Pose, options: HeadDrawOptions, drawFace: () => void): void;
52
55
  /** After the whole figure: the hair and hat, when the head is turned away. */
53
- export declare function drawHeadOver(_ctx: CanvasRenderingContext2D, pen: Pen, look: HeadLook, head: SolvedHead, _pose: Pose, options: HeadDrawOptions): void;
56
+ export declare function drawHeadOver(_ctx: CanvasRenderingContext2D, pen: Pen, look: HeadLook, head: SolvedHead, pose: Pose, options: HeadDrawOptions): void;
@@ -1,4 +1,4 @@
1
- export { HAIR_STYLES, HAIR_COLORS, resolveHair, hairlineAt, type Hair, type HairSpec, type HairStyleName, type HairTexture, type HairStrands, type HairTie } from './hair';
1
+ export { HAIR_STYLES, HAIR_COLORS, HAIR_STILL, resolveHair, hairlineAt, hairHangs, hairMotionOf, type Hair, type HairMotion, type HairSpec, type HairStyleName, type HairTexture, type HairStrands, type HairTie } from './hair';
2
2
  export { FACIAL_HAIR_STYLES, resolveFacialHair, type FacialHair, type FacialHairSpec, type FacialHairStyleName, type MoustacheStyle, type BeardStyle } from './facial-hair';
3
3
  export { GLASSES_STYLES, resolveGlasses, type Glasses, type GlassesSpec, type GlassesStyle } from './glasses';
4
4
  export { HAT_STYLES, resolveHat, type Hat, type HatSpec, type HatStyle } from './hats';
@@ -23,16 +23,18 @@ 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';
32
32
  export { basicOutfit, type BasicOutfitOptions } from './wardrobe/basic-outfit';
33
33
  export * from './head';
34
+ export { hairFollow, hairFollowTracks, hairMotionAt, type HairFollowSample, type HairFollowOptions, type HairFollowKey, type HairFollowTrackOptions } from './hair-follow';
34
35
  export * from './hands';
35
36
  export * from './acting';
36
37
  export * from './capabilities';
37
38
  export { describeTarget, checkTracks, animatableProperties, CANVAS_PROPERTIES, type PropertyInfo, type TargetAbout, type TargetDescription, type TrackProblem } from '../adapters/canvas/target-properties';
38
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;
@@ -31,6 +31,15 @@ export interface PropDrawOptions {
31
31
  paper?: string;
32
32
  /** The fog's colour, for faces lit by a scene (`light`, `fog` on the solved faces) */
33
33
  fog?: string;
34
+ /** Parts that have come loose (see `propSurface().piece`): drawn carried from where they sit and turned about their middle, by part id */
35
+ loose?: Record<string, LoosePart>;
36
+ }
37
+ /** Where a loose part has gone: px from its place in the prop's space, its turn (degrees) and how faded it is. */
38
+ export interface LoosePart {
39
+ x: number;
40
+ y: number;
41
+ rotate: number;
42
+ opacity: number;
34
43
  }
35
44
  /** Draws in the prop's own space: feet at 0, 0, up is −y. */
36
45
  export declare function drawSolvedProp(ctx: CanvasRenderingContext2D, solved: SolvedProp, options?: PropDrawOptions): void;
@@ -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;