@algorisys/tinyfly 0.102.0 → 0.103.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 +16 -5
- package/docs/DEPLOYMENT.md +2 -0
- package/docs/api-reference.md +61 -0
- package/docs/dance.md +150 -1
- package/docs/editor-guide.md +11 -4
- package/docs/examples.md +22 -1
- package/docs/getting-started.md +1 -1
- package/docs/gsap-compat.md +1 -1
- package/docs/llm-guide.md +30 -1
- package/docs/maps.md +2 -2
- package/docs/scene-3d.md +21 -1
- package/docs/teaching.md +1 -1
- package/lib/addons/characters.js +4216 -4017
- package/lib/browser/tinyfly.iife.js +14 -14
- package/lib/browser/tinyfly.js +5611 -5412
- package/lib/browser/tinyfly.umd.js +14 -14
- package/lib/types/characters/capabilities.d.ts +1 -0
- package/lib/types/characters/character-script-3d.d.ts +14 -4
- package/lib/types/characters/dance-circle.d.ts +59 -0
- package/lib/types/characters/dance-contact.d.ts +52 -0
- package/lib/types/characters/human-dance.d.ts +86 -0
- package/lib/types/characters/index.d.ts +3 -0
- package/lib/types/characters/rig/reach.d.ts +6 -3
- package/llms-full.txt +305 -15
- package/llms.txt +29 -29
- package/package.json +1 -1
- package/skills/tinyfly/SKILL.md +28 -0
- package/lib/types/characters/polyline.d.ts +0 -12
- package/lib/types/characters/sketch.d.ts +0 -54
- package/lib/types/compat/gsap/playhead-crossings.d.ts +0 -47
|
@@ -4,11 +4,13 @@ import { GAITS } from './gaits';
|
|
|
4
4
|
import { type HumanPoseName } from './species/human';
|
|
5
5
|
import { type HumanGagName } from './species/human-motion';
|
|
6
6
|
import { type GroundPoint } from './ground-path';
|
|
7
|
+
import { type HumanDanceName } from './human-dance';
|
|
7
8
|
/**
|
|
8
9
|
* Characters in world metres, for 3D scenes: a v2 character walks to a point
|
|
9
10
|
* or along a path through points, turning to face the way first, its gait's
|
|
10
11
|
* phase keyed with the distance so its feet stay planted; it faces things,
|
|
11
|
-
*
|
|
12
|
+
* spins full signed turns, dances native routines, strikes poses and plays
|
|
13
|
+
* gags. It writes the scene object's tracks: `x`,
|
|
12
14
|
* `z`, `rotateY`, its walk (`walk`, `walking`, `gait`, which the character
|
|
13
15
|
* object turns into the stepping pose as it draws) and pose fields.
|
|
14
16
|
*
|
|
@@ -23,11 +25,19 @@ import { type GroundPoint } from './ground-path';
|
|
|
23
25
|
* ```
|
|
24
26
|
*/
|
|
25
27
|
export interface CharacterBeat3D {
|
|
26
|
-
/** A gait
|
|
28
|
+
/** A gait, `face` (shortest turn), `spin` (signed/fractional turns), `dance`, `hold`, `pose`, `gag`, `place`, `say`, or `look`. */
|
|
27
29
|
do: string;
|
|
30
|
+
/** `spin`: signed revolutions, default 1. Positive turns toward +x. */
|
|
31
|
+
turns?: number;
|
|
32
|
+
/** `dance`: a native human routine. */
|
|
33
|
+
dance?: HumanDanceName;
|
|
34
|
+
/** `dance`: tempo, beats per minute (default the style's tempo). */
|
|
35
|
+
bpm?: number;
|
|
36
|
+
/** `dance`: length in beats; defaults to one routine, or for * bpm / 60000 when for is given. With both, beats are fitted into for ms. */
|
|
37
|
+
beats?: number;
|
|
28
38
|
/** When it starts, ms (default: when the beat before ends) */
|
|
29
39
|
at?: number;
|
|
30
|
-
/**
|
|
40
|
+
/** Positive finite duration, ms: move defaults to distance at gait pace, pose to 500, spin to 1000. face consumes it even without turning. */
|
|
31
41
|
for?: number;
|
|
32
42
|
/** A move: where to, [x, z] metres */
|
|
33
43
|
to?: GroundPoint;
|
|
@@ -46,7 +56,7 @@ export interface CharacterBeat3D {
|
|
|
46
56
|
/** `look`: a point [x, z] (at eye height) or [x, y, z] to look at with the head and eyes, or `camera` for the viewer; `toward` as `face` takes it */
|
|
47
57
|
look?: GroundPoint | [number, number, number] | 'camera';
|
|
48
58
|
}
|
|
49
|
-
export declare const CHARACTER_BEAT_3D_FIELDS: readonly ["do", "at", "for", "to", "through", "toward", "speed", "pose", "gag", "say", "look"];
|
|
59
|
+
export declare const CHARACTER_BEAT_3D_FIELDS: readonly ["do", "at", "for", "to", "through", "toward", "speed", "pose", "gag", "say", "look", "turns", "dance", "bpm", "beats"];
|
|
50
60
|
/** How long a line takes to say, ms: by its length, never shorter than a beat. */
|
|
51
61
|
export declare const speechLength: (text: string) => number;
|
|
52
62
|
/**
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { type Character } from './character';
|
|
2
|
+
import { type DancePartner } from './dance-contact';
|
|
3
|
+
import { type HumanDanceName, type HumanDanceStyle } from './human-dance';
|
|
4
|
+
import type { Pose } from './rig/body-plan';
|
|
5
|
+
import type { GroundPoint } from './ground-path';
|
|
6
|
+
import type { Track } from '../engine/types';
|
|
7
|
+
export interface DanceCircleOptions {
|
|
8
|
+
/** Ground center [x,z], default [0,0]. */
|
|
9
|
+
center?: GroundPoint;
|
|
10
|
+
/** Positive radius in the same units as character height. */
|
|
11
|
+
radius: number;
|
|
12
|
+
/** Positive integer member count, default 8 for direct sampling; must match targets when baking. */
|
|
13
|
+
count?: number;
|
|
14
|
+
/** Beats per revolution, positive; default 32. */
|
|
15
|
+
beatsPerTurn?: number;
|
|
16
|
+
/** Initial angle in degrees: 0 places the first dancer along +z. */
|
|
17
|
+
angle?: number;
|
|
18
|
+
/** Clockwise viewed from above (+1, default), or counterclockwise (-1). */
|
|
19
|
+
direction?: 1 | -1;
|
|
20
|
+
/** Default inward; numeric heading in degrees (0 faces +z, 90 faces +x). */
|
|
21
|
+
facing?: 'inward' | 'outward' | 'tangent' | number;
|
|
22
|
+
/** Extra signed/fractional body revolutions per orbit, independent of travel. Default 0. */
|
|
23
|
+
spins?: number;
|
|
24
|
+
/** Local routine, default garba. */
|
|
25
|
+
style?: HumanDanceName | HumanDanceStyle;
|
|
26
|
+
/** Body used for contact geometry, default a human of height 1.7. Match the rendered build. */
|
|
27
|
+
character?: Character;
|
|
28
|
+
/** Base pose; formation heading overrides turn. Use the same base when rendering baked tracks. */
|
|
29
|
+
pose?: Pose;
|
|
30
|
+
/** Lock each support toe during its stance, then release smoothly. Default true. */
|
|
31
|
+
plantFeet?: boolean;
|
|
32
|
+
}
|
|
33
|
+
export interface DanceCircleMember extends DancePartner {
|
|
34
|
+
/** World heading in degrees, also included in pose.turn as quarter-turns. */
|
|
35
|
+
heading: number;
|
|
36
|
+
strike: number;
|
|
37
|
+
/** True only for a reachable plant at full stance weight; false during release or with planting disabled. */
|
|
38
|
+
planted: boolean;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* A deterministic circle formation: world x/z travel, body heading and the
|
|
42
|
+
* local dance have separate phases. Sample by absolute beat, in any order.
|
|
43
|
+
* All placement units match the character's height (default 1.7 metres).
|
|
44
|
+
*/
|
|
45
|
+
export declare function danceCircleAt(beat: number, options: DanceCircleOptions): DanceCircleMember[];
|
|
46
|
+
/**
|
|
47
|
+
* Bake a formation into ordinary scene tracks. With zero roll, heading uses
|
|
48
|
+
* rotateY; rolled poses keep heading in turn and set rotateY to zero so yaw
|
|
49
|
+
* precedes roll and grounding exactly as in direct sampling.
|
|
50
|
+
* Requires beats; bpm defaults to 120 (independent of style), start to 0 ms
|
|
51
|
+
* and samplesPerBeat to 16. Member count comes from targets.length. Keys are
|
|
52
|
+
* linear; unchanged base/rest pose fields are omitted, placement is retained.
|
|
53
|
+
*/
|
|
54
|
+
export declare function danceCircleTracks(targets: string[], options: DanceCircleOptions & {
|
|
55
|
+
bpm?: number;
|
|
56
|
+
beats: number;
|
|
57
|
+
start?: number;
|
|
58
|
+
samplesPerBeat?: number;
|
|
59
|
+
}): Track[];
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import type { Character } from './character';
|
|
2
|
+
import type { Pose, Vec3 } from './rig/body-plan';
|
|
3
|
+
/** Position and height use the same units (pixels in 2D, metres in a 3D scene). */
|
|
4
|
+
export interface DancePartner {
|
|
5
|
+
character: Character;
|
|
6
|
+
pose: Pose;
|
|
7
|
+
position: Vec3;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* A joint in world space, with pose.turn (quarter-turns), roll, ground contact
|
|
11
|
+
* and position applied. Scene object rotations are not read. Index 2 is the
|
|
12
|
+
* wrist/ankle, and leg index 3 is the toe.
|
|
13
|
+
*/
|
|
14
|
+
export declare function danceJoint(partner: DancePartner, chain: string, joint: number): Vec3;
|
|
15
|
+
export interface DanceFootPlant extends DancePartner {
|
|
16
|
+
/** Joint error is less than 0.002 times the character height. */
|
|
17
|
+
reached: boolean;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Keep one ankle or toe at a world point while the body travels or turns.
|
|
21
|
+
* Apply the returned position as well as the pose: its y correction carries
|
|
22
|
+
* weight onto the supporting leg. An unreachable target is reported, never
|
|
23
|
+
* hidden by translating the body sideways.
|
|
24
|
+
*/
|
|
25
|
+
export declare function plantDanceFoot(partner: DancePartner, side: 'left' | 'right', target: Vec3, point?: 'ankle' | 'toe'): DanceFootPlant;
|
|
26
|
+
export interface DandiyaStick {
|
|
27
|
+
grip: Vec3;
|
|
28
|
+
tip: Vec3;
|
|
29
|
+
}
|
|
30
|
+
export interface DandiyaMeeting {
|
|
31
|
+
/** Solved poses for the two partners; positions are unchanged. */
|
|
32
|
+
a: Pose;
|
|
33
|
+
b: Pose;
|
|
34
|
+
sticks: [DandiyaStick, DandiyaStick];
|
|
35
|
+
point: Vec3;
|
|
36
|
+
/** Both tips are within 0.002 times the shorter height of point. */
|
|
37
|
+
reached: boolean;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Both sticks reach one shared 3D strike point. Stick length defaults to
|
|
41
|
+
* 0.22 of the shorter dancer's height; the point defaults to chest height
|
|
42
|
+
* between them. Draw the returned grip→tip segments with each arm's depth.
|
|
43
|
+
* Call on strike frames, or blend its poses with recovery poses between hits.
|
|
44
|
+
* Both selected hands default to right and use the hold shape. Inspect
|
|
45
|
+
* reached before applying a solve: unreachable tips are not snapped to point.
|
|
46
|
+
*/
|
|
47
|
+
export declare function meetDandiya(a: DancePartner, b: DancePartner, options?: {
|
|
48
|
+
sideA?: 'left' | 'right';
|
|
49
|
+
sideB?: 'left' | 'right';
|
|
50
|
+
point?: Vec3;
|
|
51
|
+
length?: number;
|
|
52
|
+
}): DandiyaMeeting;
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import type { Pose } from './rig/body-plan';
|
|
2
|
+
import type { Track } from '../engine/types';
|
|
3
|
+
/**
|
|
4
|
+
* Native, body-local dance keys. Heading belongs to the caller, not the clip.
|
|
5
|
+
* Foot plants assume left/right alternation each integer beat, starting left,
|
|
6
|
+
* with stance through 0.6 of the beat. Custom footwork that changes that
|
|
7
|
+
* pattern should use danceCircleAt with plantFeet: false and supply its own contacts.
|
|
8
|
+
*/
|
|
9
|
+
export interface HumanDanceStyle {
|
|
10
|
+
label: string;
|
|
11
|
+
bpm: number;
|
|
12
|
+
beats: number;
|
|
13
|
+
keys: Array<{
|
|
14
|
+
beat: number;
|
|
15
|
+
pose: Pose;
|
|
16
|
+
}>;
|
|
17
|
+
/** Claps or stick strikes, in beats from the start of the loop. */
|
|
18
|
+
strikes: number[];
|
|
19
|
+
}
|
|
20
|
+
export interface HumanDanceFrame {
|
|
21
|
+
pose: Pose;
|
|
22
|
+
/** Alternating support side and absolute integer planting beat; weight is 1 through phase 0.6, then fades to 0. */
|
|
23
|
+
contact: {
|
|
24
|
+
side: 'left' | 'right';
|
|
25
|
+
start: number;
|
|
26
|
+
weight: number;
|
|
27
|
+
};
|
|
28
|
+
/** 1 on a strike, fading to 0 a quarter beat either side. */
|
|
29
|
+
strike: number;
|
|
30
|
+
}
|
|
31
|
+
/** Simple stylised routines, editable as JSON; not a motion-capture recording. */
|
|
32
|
+
export declare const HUMAN_DANCES: {
|
|
33
|
+
garba: {
|
|
34
|
+
label: string;
|
|
35
|
+
bpm: number;
|
|
36
|
+
beats: number;
|
|
37
|
+
strikes: number[];
|
|
38
|
+
keys: {
|
|
39
|
+
beat: number;
|
|
40
|
+
pose: Pose;
|
|
41
|
+
}[];
|
|
42
|
+
};
|
|
43
|
+
garbaThreeClap: {
|
|
44
|
+
label: string;
|
|
45
|
+
bpm: number;
|
|
46
|
+
beats: number;
|
|
47
|
+
strikes: number[];
|
|
48
|
+
keys: {
|
|
49
|
+
beat: number;
|
|
50
|
+
pose: Pose;
|
|
51
|
+
}[];
|
|
52
|
+
};
|
|
53
|
+
dandiya: {
|
|
54
|
+
label: string;
|
|
55
|
+
bpm: number;
|
|
56
|
+
beats: number;
|
|
57
|
+
strikes: number[];
|
|
58
|
+
keys: {
|
|
59
|
+
beat: number;
|
|
60
|
+
pose: Pose;
|
|
61
|
+
}[];
|
|
62
|
+
};
|
|
63
|
+
};
|
|
64
|
+
export type HumanDanceName = keyof typeof HUMAN_DANCES;
|
|
65
|
+
/** Random-access evaluation: turning never changes the authored local limb motion. */
|
|
66
|
+
export declare function humanDanceFrame(style: HumanDanceName | HumanDanceStyle, beat: number, base?: Pose): HumanDanceFrame;
|
|
67
|
+
export interface HumanDanceTrackOptions {
|
|
68
|
+
/** A native name or custom JSON routine. */
|
|
69
|
+
style: HumanDanceName | HumanDanceStyle;
|
|
70
|
+
/** Beats per minute; default the style's tempo. Positive and finite. */
|
|
71
|
+
bpm?: number;
|
|
72
|
+
/** Length from beat 0; default one routine. Positive and finite. */
|
|
73
|
+
beats?: number;
|
|
74
|
+
/** Start time in milliseconds, default 0; finite. */
|
|
75
|
+
start?: number;
|
|
76
|
+
/** Base pose, default HUMAN_REST; use the same pose on the rendered target. */
|
|
77
|
+
pose?: Pose;
|
|
78
|
+
/** Sampling density, default 16; positive and finite. */
|
|
79
|
+
samplesPerBeat?: number;
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Ordinary linear JSON pose tracks, including hands; view/roll remain
|
|
83
|
+
* independently animated. Unchanged base/rest fields are omitted. Between
|
|
84
|
+
* samples, linear playback approximates the smoothly evaluated frame.
|
|
85
|
+
*/
|
|
86
|
+
export declare function humanDanceTracks(target: string, options: HumanDanceTrackOptions): Track[];
|
|
@@ -6,6 +6,9 @@
|
|
|
6
6
|
*/
|
|
7
7
|
export * from './stick-figure';
|
|
8
8
|
export * from './dance';
|
|
9
|
+
export * from './human-dance';
|
|
10
|
+
export * from './dance-circle';
|
|
11
|
+
export * from './dance-contact';
|
|
9
12
|
export * from './gaits';
|
|
10
13
|
export * from './acrobatics';
|
|
11
14
|
export { stickToHuman } from './stick-to-human';
|
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
import type { BodyPlan, Pose, Vec3 } from './body-plan';
|
|
2
2
|
export interface ReachOptions {
|
|
3
|
-
/**
|
|
3
|
+
/** Character height in the same units as target (pixels or scene metres). */
|
|
4
4
|
height: number;
|
|
5
5
|
}
|
|
6
6
|
/**
|
|
7
7
|
* The pose with chain `chainId` reaching for `target`, a point in the
|
|
8
|
-
* character's 3D space in
|
|
9
|
-
*
|
|
8
|
+
* character's unplaced 3D space, in the same units as height (+x its left,
|
|
9
|
+
* +y up, +z forward). Body turn, roll, lift and grounding are excluded from
|
|
10
|
+
* the solve. The chain must hang down at rest (arms, legs). Authored bone
|
|
11
|
+
* yaw, including human hip turn-out, is retained; reaching the existing
|
|
12
|
+
* endpoint returns the original pose, including a straight limb at full reach.
|
|
10
13
|
*/
|
|
11
14
|
export declare function reachPose(plan: BodyPlan, pose: Pose, chainId: string, target: Vec3, options: ReachOptions): Pose;
|