@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.
- package/README.md +10 -10
- package/docs/acting.md +76 -13
- package/docs/character-appearance.md +329 -0
- package/docs/editor-guide.md +54 -9
- package/docs/examples.md +1 -1
- package/docs/getting-started.md +1 -1
- package/docs/gsap-compat.md +1 -1
- package/docs/llm-guide.md +29 -2
- package/docs/maps.md +2 -2
- package/docs/props.md +8 -6
- package/docs/scene-3d.md +3 -1
- package/docs/teaching.md +1 -1
- package/lib/addons/characters.js +5911 -4230
- package/lib/browser/tinyfly.iife.js +14 -14
- package/lib/browser/tinyfly.js +8545 -6864
- package/lib/browser/tinyfly.umd.js +14 -14
- package/lib/types/characters/acting/character-script.d.ts +44 -0
- package/lib/types/characters/acting/index.d.ts +1 -0
- package/lib/types/characters/capabilities.d.ts +15 -0
- package/lib/types/characters/cast.d.ts +284 -0
- package/lib/types/characters/character.d.ts +35 -5
- package/lib/types/characters/chart.d.ts +52 -14
- package/lib/types/characters/hair-follow.d.ts +76 -0
- package/lib/types/characters/hands/held-items.d.ts +88 -0
- package/lib/types/characters/hands/index.d.ts +1 -0
- package/lib/types/characters/head/ears.d.ts +10 -0
- package/lib/types/characters/head/facial-hair.d.ts +118 -0
- package/lib/types/characters/head/glasses.d.ts +24 -0
- package/lib/types/characters/head/hair.d.ts +586 -0
- package/lib/types/characters/head/hats.d.ts +58 -0
- package/lib/types/characters/head/head-look.d.ts +56 -0
- package/lib/types/characters/head/index.d.ts +5 -0
- package/lib/types/characters/head/shell.d.ts +64 -0
- package/lib/types/characters/index.d.ts +5 -1
- package/lib/types/characters/interactions.d.ts +69 -0
- package/lib/types/characters/props/draw.d.ts +9 -0
- package/lib/types/characters/props/families/animals.d.ts +6 -0
- package/lib/types/characters/props/prop-surface.d.ts +14 -3
- package/lib/types/characters/props/ride-3d.d.ts +31 -2
- package/lib/types/characters/props/target.d.ts +5 -1
- package/lib/types/characters/species/human-motion.d.ts +5 -2
- package/lib/types/characters/species/human.d.ts +113 -4
- package/lib/types/characters/wardrobe/basic-outfit.d.ts +19 -5
- package/lib/types/characters/whiteboard.d.ts +13 -1
- package/llms-full.txt +549 -56
- package/llms.txt +29 -28
- package/package.json +1 -1
- 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;
|
|
@@ -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
|
|
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
|
|
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
|
|
9
|
-
* bar, highlight the dip,
|
|
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
|
|
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
|
|
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
|
|
54
|
-
|
|
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
|
|
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
|
-
/**
|
|
86
|
-
piece(anchor: string):
|
|
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[];
|