@algorisys/tinyfly 0.97.0 → 0.99.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 +76 -13
  3. package/docs/character-appearance.md +329 -0
  4. package/docs/editor-guide.md +54 -9
  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 -2
  9. package/docs/maps.md +2 -2
  10. package/docs/props.md +8 -6
  11. package/docs/scene-3d.md +3 -1
  12. package/docs/teaching.md +1 -1
  13. package/lib/addons/characters.js +5911 -4230
  14. package/lib/browser/tinyfly.iife.js +14 -14
  15. package/lib/browser/tinyfly.js +8545 -6864
  16. package/lib/browser/tinyfly.umd.js +14 -14
  17. package/lib/types/characters/acting/character-script.d.ts +44 -0
  18. package/lib/types/characters/acting/index.d.ts +1 -0
  19. package/lib/types/characters/capabilities.d.ts +15 -0
  20. package/lib/types/characters/cast.d.ts +284 -0
  21. package/lib/types/characters/character.d.ts +35 -5
  22. package/lib/types/characters/chart.d.ts +52 -14
  23. package/lib/types/characters/hair-follow.d.ts +76 -0
  24. package/lib/types/characters/hands/held-items.d.ts +88 -0
  25. package/lib/types/characters/hands/index.d.ts +1 -0
  26. package/lib/types/characters/head/ears.d.ts +10 -0
  27. package/lib/types/characters/head/facial-hair.d.ts +118 -0
  28. package/lib/types/characters/head/glasses.d.ts +24 -0
  29. package/lib/types/characters/head/hair.d.ts +586 -0
  30. package/lib/types/characters/head/hats.d.ts +58 -0
  31. package/lib/types/characters/head/head-look.d.ts +56 -0
  32. package/lib/types/characters/head/index.d.ts +5 -0
  33. package/lib/types/characters/head/shell.d.ts +64 -0
  34. package/lib/types/characters/index.d.ts +5 -1
  35. package/lib/types/characters/interactions.d.ts +69 -0
  36. package/lib/types/characters/props/draw.d.ts +9 -0
  37. package/lib/types/characters/props/families/animals.d.ts +6 -0
  38. package/lib/types/characters/props/prop-surface.d.ts +14 -3
  39. package/lib/types/characters/props/ride-3d.d.ts +31 -2
  40. package/lib/types/characters/props/target.d.ts +5 -1
  41. package/lib/types/characters/species/human-motion.d.ts +5 -2
  42. package/lib/types/characters/species/human.d.ts +113 -4
  43. package/lib/types/characters/wardrobe/basic-outfit.d.ts +19 -5
  44. package/lib/types/characters/whiteboard.d.ts +13 -1
  45. package/llms-full.txt +549 -56
  46. package/llms.txt +29 -28
  47. package/package.json +1 -1
  48. package/skills/tinyfly/SKILL.md +18 -4
@@ -0,0 +1,44 @@
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
+ * 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.
33
+ */
34
+ export type CharacterScriptOptions = Omit<ScriptOptions, 'height'>;
35
+ export interface CharacterScriptResult extends Omit<ScriptResult, 'keys'> {
36
+ /** The key poses on the human body, before acting */
37
+ keys: CharacterPoseKey[];
38
+ }
39
+ /**
40
+ * Ground one gait cycle covers for this character, px: its own height and
41
+ * legs (a child's are shorter), so the feet stay planted.
42
+ */
43
+ export declare function characterStrideLength(who: Character, gait: Gait | string | undefined, stride?: number): number;
44
+ export declare function characterScript(target: string, who: Character, beats: Beat[], options?: CharacterScriptOptions): CharacterScriptResult;
@@ -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';
@@ -62,6 +62,21 @@ export interface Capabilities {
62
62
  poses: string[];
63
63
  expressions: string[];
64
64
  gags: string[];
65
+ /** `build` option */
66
+ builds: string[];
67
+ /** `hair` option (`{ style, color, length, … }` changes any field) */
68
+ hair: string[];
69
+ hairColors: Record<string, string>;
70
+ /** `facialHair` option */
71
+ facialHair: string[];
72
+ glasses: string[];
73
+ hats: string[];
74
+ /** `castMember(name, height)` */
75
+ cast: string[];
76
+ /** `holding: { left | right | both: item }`, and which hands each takes */
77
+ heldItems: Record<string, string>;
78
+ /** `meetHands(kind, a, b)` */
79
+ handMeetings: string[];
65
80
  };
66
81
  codePanel: {
67
82
  languages: readonly string[];
@@ -0,0 +1,284 @@
1
+ import type { CharacterOptions } from './character';
2
+ /**
3
+ * A ready-made recurring cast: a family of characters a viewer can tell
4
+ * apart at a glance, by build, hair, facial hair, glasses and clothes. Each
5
+ * member is plain character options (no height: `scale` is how tall they
6
+ * stand next to an adult), so it can be saved, changed field by field, or
7
+ * given any pose, expression or action.
8
+ *
9
+ * These are starting points from the age-and-cast reference sheet, not rules:
10
+ * any hairstyle, build or outfit suits anyone, and age is shown by hair and
11
+ * proportions, never by a stoop or a walking aid unless one is chosen.
12
+ */
13
+ export interface CastMember {
14
+ /** What to call them in a picker */
15
+ label: string;
16
+ /** `family` (ages and looks) or `work` (dressed for a job, from the occupations sheet) */
17
+ group: 'family' | 'work';
18
+ /** Height next to an adult (1) */
19
+ scale: number;
20
+ /** Everything else about them */
21
+ options: Omit<CharacterOptions, 'height'>;
22
+ }
23
+ export declare const CHARACTER_CAST: {
24
+ boy: {
25
+ label: string;
26
+ group: "family";
27
+ scale: number;
28
+ options: {
29
+ build: "child";
30
+ hair: "short";
31
+ ears: true;
32
+ outfit: {
33
+ shirt: string;
34
+ trousers: string;
35
+ bottom: "shorts";
36
+ };
37
+ };
38
+ };
39
+ girl: {
40
+ label: string;
41
+ group: "family";
42
+ scale: number;
43
+ options: {
44
+ build: "child";
45
+ hair: {
46
+ style: "bob";
47
+ color: "#7b4a2b";
48
+ };
49
+ ears: true;
50
+ outfit: {
51
+ shirt: string;
52
+ trousers: string;
53
+ bottom: "skirt";
54
+ };
55
+ };
56
+ };
57
+ youngMan: {
58
+ label: string;
59
+ group: "family";
60
+ scale: number;
61
+ options: {
62
+ build: "tall";
63
+ hair: "spiky";
64
+ ears: true;
65
+ outfit: {
66
+ shirt: string;
67
+ trousers: string;
68
+ };
69
+ };
70
+ };
71
+ youngWoman: {
72
+ label: string;
73
+ group: "family";
74
+ scale: number;
75
+ options: {
76
+ build: "slim";
77
+ hair: {
78
+ style: "highPonytail";
79
+ color: "#9a4426";
80
+ };
81
+ ears: true;
82
+ outfit: {
83
+ shirt: string;
84
+ trousers: string;
85
+ };
86
+ };
87
+ };
88
+ man: {
89
+ label: string;
90
+ group: "family";
91
+ scale: number;
92
+ options: {
93
+ build: "broad";
94
+ hair: "sidePart";
95
+ facialHair: "chevron";
96
+ ears: true;
97
+ outfit: {
98
+ shirt: string;
99
+ trousers: string;
100
+ sleeves: "long";
101
+ collar: true;
102
+ tie: string;
103
+ };
104
+ };
105
+ };
106
+ woman: {
107
+ label: string;
108
+ group: "family";
109
+ scale: number;
110
+ options: {
111
+ build: "curvy";
112
+ hair: {
113
+ style: "shoulderWaves";
114
+ color: "#22201f";
115
+ };
116
+ ears: true;
117
+ outfit: {
118
+ shirt: string;
119
+ trousers: string;
120
+ sleeves: "long";
121
+ };
122
+ };
123
+ };
124
+ grandpa: {
125
+ label: string;
126
+ group: "family";
127
+ scale: number;
128
+ options: {
129
+ build: "stocky";
130
+ hair: {
131
+ style: "receding";
132
+ color: "#a7a29c";
133
+ };
134
+ facialHair: {
135
+ style: "shortBoxed";
136
+ color: "#ecebe7";
137
+ };
138
+ glasses: "square";
139
+ ears: true;
140
+ outfit: {
141
+ shirt: string;
142
+ trousers: string;
143
+ sleeves: "long";
144
+ collar: true;
145
+ };
146
+ };
147
+ };
148
+ grandma: {
149
+ label: string;
150
+ group: "family";
151
+ scale: number;
152
+ options: {
153
+ build: "short";
154
+ hair: {
155
+ style: "topBun";
156
+ color: "#ecebe7";
157
+ };
158
+ glasses: "round";
159
+ ears: true;
160
+ outfit: {
161
+ shirt: string;
162
+ trousers: string;
163
+ sleeves: "long";
164
+ bottom: "skirt";
165
+ };
166
+ };
167
+ };
168
+ doctor: {
169
+ label: string;
170
+ group: "work";
171
+ scale: number;
172
+ options: {
173
+ build: "slim";
174
+ hair: {
175
+ style: "lowPonytail";
176
+ color: "#22201f";
177
+ };
178
+ ears: true;
179
+ outfit: {
180
+ shirt: string;
181
+ trousers: string;
182
+ over: "labCoat";
183
+ collar: true;
184
+ };
185
+ };
186
+ };
187
+ cook: {
188
+ label: string;
189
+ group: "work";
190
+ scale: number;
191
+ options: {
192
+ build: "stocky";
193
+ hair: "crewCut";
194
+ facialHair: "shortMoustache";
195
+ ears: true;
196
+ outfit: {
197
+ shirt: string;
198
+ trousers: string;
199
+ sleeves: "long";
200
+ over: "apron";
201
+ overColor: string;
202
+ };
203
+ };
204
+ };
205
+ builder: {
206
+ label: string;
207
+ group: "work";
208
+ scale: number;
209
+ options: {
210
+ build: "broad";
211
+ hair: "short";
212
+ facialHair: "stubble";
213
+ hat: "hardHat";
214
+ ears: true;
215
+ outfit: {
216
+ shirt: string;
217
+ trousers: string;
218
+ };
219
+ };
220
+ };
221
+ courier: {
222
+ label: string;
223
+ group: "work";
224
+ scale: number;
225
+ options: {
226
+ build: "standard";
227
+ hair: "short";
228
+ hat: {
229
+ style: "cap";
230
+ color: string;
231
+ };
232
+ ears: true;
233
+ outfit: {
234
+ shirt: string;
235
+ trousers: string;
236
+ bottom: "shorts";
237
+ };
238
+ };
239
+ };
240
+ teacher: {
241
+ label: string;
242
+ group: "work";
243
+ scale: number;
244
+ options: {
245
+ build: "tall";
246
+ hair: "slickBack";
247
+ glasses: "square";
248
+ ears: true;
249
+ outfit: {
250
+ shirt: string;
251
+ trousers: string;
252
+ sleeves: "long";
253
+ collar: true;
254
+ tie: string;
255
+ };
256
+ };
257
+ };
258
+ farmer: {
259
+ label: string;
260
+ group: "work";
261
+ scale: number;
262
+ options: {
263
+ build: "stocky";
264
+ hair: {
265
+ style: "shoulderStraight";
266
+ color: "#d9b55a";
267
+ };
268
+ hat: "sunHat";
269
+ ears: true;
270
+ outfit: {
271
+ shirt: string;
272
+ trousers: string;
273
+ sleeves: "long";
274
+ };
275
+ };
276
+ };
277
+ };
278
+ export type CastName = keyof typeof CHARACTER_CAST;
279
+ /**
280
+ * Character options for a cast member at an adult `height` (px; they stand
281
+ * at their own scale of it), with any options changed: `castMember('grandpa',
282
+ * 300, { look: 'pencil' })`.
283
+ */
284
+ export declare function castMember(name: CastName, height?: number, changes?: Partial<CharacterOptions>): CharacterOptions;
@@ -5,7 +5,11 @@ 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 HumanPoseName } from './species/human';
8
+ import { type HeadLook, type HeadLookOptions } from './head/head-look';
9
+ import { type HumanBuildName, type HumanPoseName } from './species/human';
10
+ import type { Gait } from './gaits';
11
+ import { type BasicOutfitOptions } from './wardrobe/basic-outfit';
12
+ import { type Holding, type HoldingSpec } from './hands/held-items';
9
13
  import { type HandPose } from './hands/hand-rig';
10
14
  /**
11
15
  * Characters (v2): any body plan, posed by numbers, turned in 3D, drawn flat
@@ -19,9 +23,10 @@ export type FigureStyle = 'fluid' | 'stick';
19
23
  /**
20
24
  * Draws part of a character: clothes, hair, a prop. The context is in the
21
25
  * character's drawing space (feet at 0, 0), saved and restored around the
22
- * call. Draw with `pen` so it matches the look.
26
+ * call. Draw with `pen` so it matches the look. `pose` is the full pose being
27
+ * drawn (for a layer that a pose field switches, like a held item's `held.*`).
23
28
  */
24
- export type CharacterLayer = (ctx: CanvasRenderingContext2D, joints: CharacterJoints, pen: Pen, time: number) => void;
29
+ export type CharacterLayer = (ctx: CanvasRenderingContext2D, joints: CharacterJoints, pen: Pen, time: number, pose?: Pose) => void;
25
30
  export interface CharacterLayers {
26
31
  /** Before anything (a shadow, a cape) */
27
32
  behind?: CharacterLayer;
@@ -33,9 +38,19 @@ export interface CharacterLayers {
33
38
  /** After everything (a prop in front) */
34
39
  front?: CharacterLayer;
35
40
  }
36
- export interface CharacterOptions {
41
+ export interface CharacterOptions extends HeadLookOptions {
37
42
  /** Body plan (default: human, built from the options below) */
38
43
  plan?: BodyPlan;
44
+ /** A named build (`child`, `tall`, `broad`…; see HUMAN_BUILDS): its proportions, unless the options below set them */
45
+ build?: HumanBuildName;
46
+ /** Leg length, as a share of the standard (default 1) */
47
+ legLength?: number;
48
+ /** Arm length, as a share of the standard (default 1) */
49
+ armLength?: number;
50
+ /** A T-shirt and trousers in these colours (see basicOutfit), as data; drawn under any `layers` */
51
+ outfit?: BasicOutfitOptions | null;
52
+ /** What each hand holds (`{ right: 'mug' }`, `{ both: 'parcel' }`); a pose field `held.<side>` below 0.5 lets go */
53
+ holding?: HoldingSpec | null;
39
54
  figure?: FigureStyle;
40
55
  look?: Look;
41
56
  /** Feet to top of head, px (default 300) */
@@ -92,6 +107,10 @@ export interface Character {
92
107
  hands: 'dot' | 'cartoon';
93
108
  handStyle: 'glove' | 'natural';
94
109
  handSize: number;
110
+ /** Hair, facial hair, glasses, a hat and ears: every choice spelled out, so a saved character never changes when a preset does */
111
+ head: HeadLook;
112
+ /** What each hand holds (drawn by its layers) */
113
+ holding: Holding;
95
114
  }
96
115
  export declare function character(options?: CharacterOptions): Character;
97
116
  /** Where every part of a character is, as drawn, in its drawing space (feet at 0, 0; up is -y). */
@@ -191,14 +210,25 @@ export interface CharacterTargetOptions {
191
210
  character: Character;
192
211
  /** Starting pose (default rest) */
193
212
  pose?: Pose;
213
+ /** Your own gaits, by the names a `gait` track uses (built-in names need no entry) */
214
+ gaits?: Record<string, Gait>;
194
215
  }
195
216
  /** A `custom` target made by {@link characterTarget}. */
196
217
  export interface CharacterTarget extends CustomTarget {
197
218
  readonly character: Character;
219
+ readonly gaits?: Record<string, Gait>;
198
220
  }
221
+ /**
222
+ * The pose a target's props describe: its pose fields, with its gait stepped
223
+ * in as far as `walking` says (`walk` is the phase, `gait` which gait), on the
224
+ * pose it holds. Props that are not pose fields (`facing`, strings) are left
225
+ * out.
226
+ */
227
+ export declare function characterPoseOf(props: Record<string, unknown>, rest?: Pose, gaits?: Record<string, Gait>): Pose;
199
228
  /**
200
229
  * A `custom` canvas target that draws a character. Every pose field is a
201
- * prop, so timeline tracks pose, turn and roll it. `x`/`y` are the feet.
230
+ * prop, so timeline tracks pose, turn and roll it; `walk`, `walking` and
231
+ * `gait` tracks step its gait (see `characterScript`). `x`/`y` are the feet.
202
232
  */
203
233
  export declare function characterTarget(options: CharacterTargetOptions): CharacterTarget;
204
234
  /** 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,76 @@
1
+ import type { Track } from '../engine/types';
2
+ import type { Pose } from './rig/body-plan';
3
+ import { type Character } from './character';
4
+ /**
5
+ * Hair follow-through: hanging hair (long hair, ponytails, braids) lags
6
+ * behind the head, swinging round it after a turn, streaming back on a run,
7
+ * dropping on a jump and lifting on the landing. The drawing stays stateless:
8
+ * the lag is three pose fields (`hair.swing`, `hair.trail`, `hair.lift`), and
9
+ * this module works them out ahead of time from the head's motion, the way
10
+ * `Prop.follow` does for a car's antenna or a dog's tail.
11
+ *
12
+ * // Timelines: add the hair's tracks after the character's own.
13
+ * const tracks = characterPoseTracks('amy', keys)
14
+ * tracks.push(...hairFollowTracks('amy', tracks, amy))
15
+ *
16
+ * // Code that poses a character every frame: key the lag once for the
17
+ * // loop, then read it at each frame's time.
18
+ * const keys = hairFollow((t) => ({ x: xAt(t), y: 0, turn: turnAt(t) }), { end: 8000, headRadius: 24 })
19
+ * drawCharacter(ctx, amy, humanPose({ turn: turnAt(t), ...hairMotionAt(keys, t) }), t)
20
+ *
21
+ * Each lag chases its primary on a spring stepped in fixed 1 ms steps
22
+ * (`springFollow`), so the same motion always gives the same keys.
23
+ */
24
+ /** 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). */
25
+ export interface HairFollowSample {
26
+ x: number;
27
+ y: number;
28
+ /** The pose's `turn` (0 front, 1 profile facing screen-right, 2 back…) */
29
+ turn: number;
30
+ /** The pose's `head.turn`, degrees toward the character's left (default 0) */
31
+ headTurn?: number;
32
+ }
33
+ export interface HairFollowOptions {
34
+ /** From and to, ms (start defaults to 0) */
35
+ start?: number;
36
+ end: number;
37
+ /** The head's radius on screen, px: the lag is measured in head radii */
38
+ headRadius: number;
39
+ /** Key spacing, ms (default 33) */
40
+ step?: number;
41
+ /** Spring stiffness (default 70): higher follows the head more tightly */
42
+ stiffness?: number;
43
+ /** Damping (default 6): lower swings longer */
44
+ damping?: number;
45
+ /** How much the hair lags, 1 the default feel; 0 pins it to the head */
46
+ amount?: number;
47
+ }
48
+ /** The hair's lag at one time. */
49
+ export interface HairFollowKey {
50
+ time: number;
51
+ /** `hair.swing`: round the head toward the character's left (+), degrees */
52
+ swing: number;
53
+ /** `hair.trail`: streaming back behind the head (+), head radii */
54
+ trail: number;
55
+ /** `hair.lift`: lifted (+) or dropped (−), head radii */
56
+ lift: number;
57
+ }
58
+ /**
59
+ * Key the hair's lag over a span, from where the head is at each moment.
60
+ * Returns a key every `step` ms from `start` to `end`.
61
+ */
62
+ export declare function hairFollow(sample: (time: number) => HairFollowSample, options: HairFollowOptions): HairFollowKey[];
63
+ /** The hair's lag at a time, between keys, as the pose fields it sets (`hair.swing`, `hair.trail`, `hair.lift`). */
64
+ export declare function hairMotionAt(keys: HairFollowKey[], time: number): Pose;
65
+ export interface HairFollowTrackOptions extends Pick<HairFollowOptions, 'step' | 'stiffness' | 'damping' | 'amount'> {
66
+ /** How long the hair keeps settling after the last key, ms (default 1500) */
67
+ settle?: number;
68
+ }
69
+ /**
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
+ */
76
+ export declare function hairFollowTracks(target: string, tracks: Track[], who: Character, options?: HairFollowTrackOptions): Track[];