@algorisys/tinyfly 0.97.0 → 0.98.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 (37) hide show
  1. package/README.md +7 -7
  2. package/docs/character-appearance.md +281 -0
  3. package/docs/editor-guide.md +14 -6
  4. package/docs/examples.md +1 -1
  5. package/docs/getting-started.md +1 -1
  6. package/docs/gsap-compat.md +1 -1
  7. package/docs/llm-guide.md +21 -1
  8. package/docs/maps.md +2 -2
  9. package/docs/props.md +8 -6
  10. package/docs/teaching.md +1 -1
  11. package/lib/addons/characters.js +5720 -4476
  12. package/lib/browser/tinyfly.iife.js +15 -15
  13. package/lib/browser/tinyfly.js +7928 -6684
  14. package/lib/browser/tinyfly.umd.js +15 -15
  15. package/lib/types/characters/capabilities.d.ts +15 -0
  16. package/lib/types/characters/cast.d.ts +284 -0
  17. package/lib/types/characters/character.d.ts +22 -4
  18. package/lib/types/characters/hands/held-items.d.ts +88 -0
  19. package/lib/types/characters/hands/index.d.ts +1 -0
  20. package/lib/types/characters/head/ears.d.ts +10 -0
  21. package/lib/types/characters/head/facial-hair.d.ts +118 -0
  22. package/lib/types/characters/head/glasses.d.ts +24 -0
  23. package/lib/types/characters/head/hair.d.ts +560 -0
  24. package/lib/types/characters/head/hats.d.ts +58 -0
  25. package/lib/types/characters/head/head-look.d.ts +53 -0
  26. package/lib/types/characters/head/index.d.ts +5 -0
  27. package/lib/types/characters/head/shell.d.ts +64 -0
  28. package/lib/types/characters/index.d.ts +4 -1
  29. package/lib/types/characters/interactions.d.ts +69 -0
  30. package/lib/types/characters/props/families/animals.d.ts +6 -0
  31. package/lib/types/characters/species/human-motion.d.ts +5 -2
  32. package/lib/types/characters/species/human.d.ts +111 -4
  33. package/lib/types/characters/wardrobe/basic-outfit.d.ts +19 -5
  34. package/llms-full.txt +355 -27
  35. package/llms.txt +29 -28
  36. package/package.json +1 -1
  37. package/skills/tinyfly/SKILL.md +10 -1
@@ -0,0 +1,64 @@
1
+ import type { Point } from '../../adapters/canvas/sketch';
2
+ import type { Vec3 } from '../rig/body-plan';
3
+ import { type SolvedHead } from '../rig/skeleton';
4
+ /**
5
+ * Regions on and around the head: hair, a beard, a hat's crown. A region is
6
+ * described in the head's own terms and drawn wherever the head's turn, nod
7
+ * and tilt put it, so it turns with the head through every view instead of
8
+ * being a flat drawing pasted on.
9
+ *
10
+ * A point on the head is named by two numbers:
11
+ * - `around`: radians around the head from the middle of the face, toward the
12
+ * character's left +, so ±π is the back of the head;
13
+ * - `up`: head radii from the head's centre, +1 the crown, -1 under the chin
14
+ * (below -1 only for things that hang, like long hair or a long beard).
15
+ *
16
+ * The region says where it is (`inside`, positive inside) and where each of
17
+ * its points sits (`position`, in head radii: x toward the character's left,
18
+ * y up, z forward). It is cut into the part facing the viewer and the part
19
+ * facing away; each part's outline is traced (marching squares over a grid
20
+ * of `around` × `up`) and projected to the screen. The far part is drawn
21
+ * before the head and the near part after it, so a bob shows beside the face
22
+ * and its fringe crosses the forehead, and from behind the hair covers the
23
+ * whole head. Same input, same outline: no randomness, no state.
24
+ */
25
+ export interface ShellRegion {
26
+ /** Positive inside the region, negative outside; continuous across the boundary */
27
+ inside(around: number, up: number): number;
28
+ /** Where a point of the region is, head radii (x toward its left, y up, z forward) */
29
+ position(around: number, up: number): Vec3;
30
+ /** Which way the surface faces there (default: away from the head's centre) */
31
+ normal?(around: number, up: number): Vec3;
32
+ /** Highest `up` the region reaches (default 1, the crown) */
33
+ top?: number;
34
+ /** Lowest `up` the region reaches (default -1, under the chin) */
35
+ bottom?: number;
36
+ }
37
+ /** The two halves of a region as seen: outlines on the screen. */
38
+ export interface ShellOutlines {
39
+ /** The part facing the viewer: drawn over the head */
40
+ near: Point[][];
41
+ /** The part facing away: drawn behind the head */
42
+ far: Point[][];
43
+ }
44
+ /** A point on the unit sphere from `around` and `up`. */
45
+ export declare function spherePoint(around: number, up: number): Vec3;
46
+ /** How directly a head-space direction faces the viewer: 1 straight on, 0 at the edge, negative away. */
47
+ export declare function facingOf(head: SolvedHead, [x, y, z]: Vec3): number;
48
+ /** A head-space point (head radii) on the screen. */
49
+ export declare function onScreen(head: SolvedHead, point: Vec3): Point;
50
+ /** Smallest angle between two `around` values. */
51
+ export declare function aroundDistance(a: number, b: number): number;
52
+ /**
53
+ * Trace the outlines of a region's near and far parts, on the screen.
54
+ * `columns` around the head: more for fine texture (spikes, curls).
55
+ */
56
+ export declare function shellOutlines(head: SolvedHead, region: ShellRegion, columns?: number): ShellOutlines;
57
+ export declare function cachedOutlines(head: SolvedHead, key: unknown, make: () => ShellOutlines): ShellOutlines;
58
+ /**
59
+ * Run `draw` with the head's disc cut out of the canvas, for things behind
60
+ * the head: they show only around it, even when the head is see-through.
61
+ */
62
+ export declare function behindHead(ctx: CanvasRenderingContext2D, head: SolvedHead, draw: () => void): void;
63
+ /** Split a head-space polyline into the runs that face the viewer, on the screen. */
64
+ export declare function visibleRuns(head: SolvedHead, points: Vec3[], normals: Vec3[], threshold?: number): Point[][];
@@ -23,11 +23,14 @@ 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, type HumanBuild, type HumanPoseName } from './species/human';
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';
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';
27
29
  export * from './species/human-motion';
28
30
  export type { BodyPlan, ChainSpec, BoneSpec, BoneAngles, ContactSpec, HeadSpec, Pose as CharacterPose, Vec3 } from './rig/body-plan';
29
31
  export { createPen, ellipsePoints, type Pen, type Look, type PencilOptions, type PenOptions } from './look/pen';
30
32
  export { basicOutfit, type BasicOutfitOptions } from './wardrobe/basic-outfit';
33
+ export * from './head';
31
34
  export * from './hands';
32
35
  export * from './acting';
33
36
  export * from './capabilities';
@@ -0,0 +1,69 @@
1
+ import { type Character } from './character';
2
+ import type { Pose } from './rig/body-plan';
3
+ /**
4
+ * Two characters whose hands meet: a handshake, a high five, a fist bump, or
5
+ * a parcel handed from one to the other. Rather than playing two clips and
6
+ * hoping the hands line up, both arms reach (exactly, see `reachCharacter`)
7
+ * for one shared point, worked out from where the two stand and how tall
8
+ * they are. The result is two poses and the point, plain data to key as
9
+ * tracks; any field of the poses can still be changed.
10
+ *
11
+ * Both stand on the same ground line, `a` on the left facing right and `b`
12
+ * on the right facing left, turned three-quarters toward the viewer (or side
13
+ * on, with `view: 'side'`). Hands are the characters' right hands (a hand
14
+ * over uses both).
15
+ */
16
+ export type HandMeeting = 'handshake' | 'highFive' | 'fistBump' | 'handOver';
17
+ export interface MeetingPartner {
18
+ character: Character;
19
+ /** Starting pose (default rest); its arms are replaced, the rest kept */
20
+ pose?: Pose;
21
+ /** Scene x of the feet */
22
+ x: number;
23
+ }
24
+ export interface MeetHandsOptions {
25
+ /** `threeQuarter` (default): turned toward the viewer as well as each other; `side`: in profile */
26
+ view?: 'threeQuarter' | 'side';
27
+ /** Where the hands meet, as a share of the shorter one's height above the ground (default by kind) */
28
+ height?: number;
29
+ }
30
+ export interface HandsMeet {
31
+ a: Pose;
32
+ b: Pose;
33
+ /** Where the hands meet: scene x, and px above the ground (negative y, as drawing space) */
34
+ point: {
35
+ x: number;
36
+ y: number;
37
+ };
38
+ /** Both reached it (they stand close enough; see `meetingSpacing`) */
39
+ reached: boolean;
40
+ }
41
+ /**
42
+ * Each kind: how high the hands meet and how far apart the two stand for
43
+ * it (both as a share of the shorter one's height), and how far they lean in.
44
+ */
45
+ export declare const HAND_MEETINGS: {
46
+ handshake: {
47
+ height: number;
48
+ spacing: number;
49
+ lean: number;
50
+ };
51
+ highFive: {
52
+ height: number;
53
+ spacing: number;
54
+ lean: number;
55
+ };
56
+ fistBump: {
57
+ height: number;
58
+ spacing: number;
59
+ lean: number;
60
+ };
61
+ handOver: {
62
+ height: number;
63
+ spacing: number;
64
+ lean: number;
65
+ };
66
+ };
67
+ /** How far apart (px, feet to feet) two characters stand for their hands to meet comfortably. */
68
+ export declare function meetingSpacing(kind: HandMeeting, a: Character, b: Character): number;
69
+ export declare function meetHands(kind: HandMeeting, a: MeetingPartner, b: MeetingPartner, options?: MeetHandsOptions): HandsMeet;
@@ -139,6 +139,12 @@ export declare function sittingPose(h: Pick<QuadrupedHelpers, 'upper' | 'lower'
139
139
  export declare const QUADRUPED_ACTING: ActingRig;
140
140
  /** Kept for the horse's name. */
141
141
  export declare const HORSE_ACTING: ActingRig;
142
+ /**
143
+ * Lying down with the head up (a sphinx pose): the body lowered until the
144
+ * folded hind legs and the belly are on the ground, the front legs stretched
145
+ * forward along it, paws flat.
146
+ */
147
+ export declare function lyingPose(h: Pick<QuadrupedHelpers, 'upper' | 'lower' | 'foot' | 'legLength' | 'tailHangs'>): Record<string, number>;
142
148
  export interface AnimalOptions {
143
149
  kind?: string;
144
150
  summary?: string;
@@ -8,8 +8,11 @@ import { type Gait, type GaitName } from '../gaits';
8
8
  * `base`'s. `stride` scales the swing.
9
9
  */
10
10
  export declare function humanGaitPose(gait: GaitName | Gait | string | undefined, phase: number, base?: Pose, stride?: number): Pose;
11
- /** Ground covered by one gait cycle (two steps) for a character `height` px tall: the feet stay planted. */
12
- export declare function humanGaitStrideLength(gait: GaitName | Gait | string | undefined, height: number, stride?: number): number;
11
+ /**
12
+ * Ground covered by one gait cycle (two steps) for a character `height` px
13
+ * tall: the feet stay planted. `legLength` is the build's (see HUMAN_BUILDS).
14
+ */
15
+ export declare function humanGaitStrideLength(gait: GaitName | Gait | string | undefined, height: number, stride?: number, legLength?: number): number;
13
16
  /** One step of a gag: when (ms in), what changes from the pose so far, and the ease into it. */
14
17
  export interface HumanGagStep {
15
18
  after: number;
@@ -1,5 +1,4 @@
1
1
  import type { BodyPlan, Pose } from '../rig/body-plan';
2
- import { type ExpressionName } from '../stick-figure';
3
2
  /**
4
3
  * The human body plan for the v2 character system: a two-bone spine, a neck,
5
4
  * two arms and two legs with feet, and a head.
@@ -19,7 +18,10 @@ import { type ExpressionName } from '../stick-figure';
19
18
  * turned-out plié), and the same for `.right`
20
19
  * - `stretch` (1 normal), `lift` (fraction of height above the ground), `roll` (whole-figure roll, degrees)
21
20
  * - the face: `mouth`, `smile`, `mouthWidth`, `blink`, `eye.left`, `eye.right`,
22
- * `brow.left`, `brow.right`, `browTilt`, `lookX`, `lookY` (as the v1 stick figure)
21
+ * `brow.left`, `brow.right`, `browTilt`, `lookX`, `lookY` (as the v1 stick figure),
22
+ * and marks that fade in from 0 to 1: `blush` (cheeks), `tears`, `sweat` (a bead at the temple)
23
+ * - `held.left`, `held.right`, `held.both`: whether what the character holds
24
+ * there shows (1, the default) or has been let go (below 0.5)
23
25
  *
24
26
  * The character's left is +x: facing the viewer its left arm is on screen-right.
25
27
  */
@@ -30,7 +32,67 @@ export interface HumanBuild {
30
32
  shoulderWidth?: number;
31
33
  /** Half the hip width, fraction of the height (0: both legs from one point) */
32
34
  hipWidth?: number;
35
+ /** Leg length, as a share of the standard (default 1); the body takes up the difference */
36
+ legLength?: number;
37
+ /** Arm length, as a share of the standard (default 1) */
38
+ armLength?: number;
33
39
  }
40
+ /**
41
+ * Ready-made builds: proportions only, so the same poses, gaits and actions
42
+ * work on each. Age, posture and clothes are separate choices: a child build
43
+ * has a larger head and shorter limbs, nothing more. How tall a character
44
+ * stands is its `height`; a build changes how that height is shared out.
45
+ */
46
+ export declare const HUMAN_BUILDS: {
47
+ standard: {};
48
+ slim: {
49
+ headSize: number;
50
+ shoulderWidth: number;
51
+ hipWidth: number;
52
+ };
53
+ tall: {
54
+ headSize: number;
55
+ legLength: number;
56
+ armLength: number;
57
+ };
58
+ short: {
59
+ headSize: number;
60
+ legLength: number;
61
+ shoulderWidth: number;
62
+ hipWidth: number;
63
+ };
64
+ broad: {
65
+ shoulderWidth: number;
66
+ hipWidth: number;
67
+ };
68
+ curvy: {
69
+ shoulderWidth: number;
70
+ hipWidth: number;
71
+ };
72
+ stocky: {
73
+ headSize: number;
74
+ shoulderWidth: number;
75
+ hipWidth: number;
76
+ };
77
+ kid: {
78
+ headSize: number;
79
+ };
80
+ child: {
81
+ headSize: number;
82
+ legLength: number;
83
+ armLength: number;
84
+ shoulderWidth: number;
85
+ hipWidth: number;
86
+ };
87
+ toddler: {
88
+ headSize: number;
89
+ legLength: number;
90
+ armLength: number;
91
+ shoulderWidth: number;
92
+ hipWidth: number;
93
+ };
94
+ };
95
+ export type HumanBuildName = keyof typeof HUMAN_BUILDS;
34
96
  export declare const HUMAN_REST: Pose;
35
97
  /** A full human pose from the fields that differ from rest. */
36
98
  export declare function humanPose(changes?: Pose): Pose;
@@ -59,6 +121,17 @@ export declare const HUMAN_POSES: {
59
121
  crouch: Pose;
60
122
  crawl: Pose;
61
123
  lieDown: Pose;
124
+ sleep: Pose;
125
+ stretch: Pose;
126
+ sitFloor: Pose;
127
+ carry: Pose;
128
+ lift: Pose;
129
+ push: Pose;
130
+ pull: Pose;
131
+ drink: Pose;
132
+ phone: Pose;
133
+ read: Pose;
134
+ type: Pose;
62
135
  };
63
136
  export type HumanPoseName = keyof typeof HUMAN_POSES;
64
137
  /** A human body plan; the same pose fields work on every build. */
@@ -67,6 +140,40 @@ export declare function humanPlan(build?: HumanBuild): BodyPlan;
67
140
  export declare function humanFieldLabel(field: string): string;
68
141
  /**
69
142
  * The ready-made faces (happy, sad, surprised, angry…), as human pose fields.
70
- * Each sets every face field, so applying one replaces the whole face.
143
+ * Each sets every face field, so applying one replaces the whole face; any
144
+ * two blend. The second group, from the emotions reference sheet, uses the
145
+ * human face's marks (blush, tears, sweat).
71
146
  */
72
- export declare const HUMAN_EXPRESSIONS: Record<ExpressionName, Pose>;
147
+ export declare const HUMAN_EXPRESSIONS: {
148
+ laughing: Pose;
149
+ afraid: Pose;
150
+ bored: Pose;
151
+ tired: Pose;
152
+ embarrassed: Pose;
153
+ proud: Pose;
154
+ determined: Pose;
155
+ affectionate: Pose;
156
+ hurt: Pose;
157
+ suspicious: Pose;
158
+ relieved: Pose;
159
+ excited: Pose;
160
+ neutral: Pose;
161
+ happy: Pose;
162
+ joyful: Pose;
163
+ sad: Pose;
164
+ crying: Pose;
165
+ surprised: Pose;
166
+ shocked: Pose;
167
+ angry: Pose;
168
+ furious: Pose;
169
+ worried: Pose;
170
+ scared: Pose;
171
+ confused: Pose;
172
+ skeptical: Pose;
173
+ thinking: Pose;
174
+ sleepy: Pose;
175
+ disgusted: Pose;
176
+ smug: Pose;
177
+ wink: Pose;
178
+ };
179
+ export type HumanExpressionName = keyof typeof HUMAN_EXPRESSIONS;
@@ -1,14 +1,28 @@
1
1
  import type { CharacterLayers } from '../character';
2
2
  /**
3
- * A first outfit for the human character: a T-shirt and trousers, drawn as
4
- * layers on the body's parts, through the character's pen (so it matches the
5
- * look). The sleeves grow out of the shirt's shoulders with no seam. The full
6
- * wardrobe is a later milestone; this is the shape every garment will follow.
3
+ * Clothes for the human character, as plain data, drawn as layers on the
4
+ * body's parts through the character's pen (so they match the look). The
5
+ * base is a top and trousers whose sleeves grow out of the shirt's shoulders
6
+ * with no seam; the options change its cut (long or no sleeves, shorts, a
7
+ * skirt) and add pieces worn over it (a collar, a tie, an apron, a lab coat).
8
+ * The defaults are the original T-shirt and trousers, unchanged.
7
9
  */
8
10
  export interface BasicOutfitOptions {
9
11
  /** Shirt colour (default red) */
10
12
  shirt?: string;
11
- /** Trouser colour (default navy) */
13
+ /** Trouser (or shorts, or skirt) colour (default navy) */
12
14
  trousers?: string;
15
+ /** Sleeves: `short` (default), `long` (to the wrist) or `none` */
16
+ sleeves?: 'short' | 'long' | 'none';
17
+ /** Below the waist: `trousers` (default), `shorts` (to the knee) or `skirt` */
18
+ bottom?: 'trousers' | 'shorts' | 'skirt';
19
+ /** A shirt collar at the neck */
20
+ collar?: boolean;
21
+ /** A tie down the front, in this colour */
22
+ tie?: string | null;
23
+ /** Worn over the clothes: an apron or a lab coat (default none) */
24
+ over?: 'apron' | 'labCoat' | null;
25
+ /** The apron's or lab coat's colour (default: white coat, tan apron) */
26
+ overColor?: string;
13
27
  }
14
28
  export declare function basicOutfit(options?: BasicOutfitOptions): CharacterLayers;