@algorisys/tinyfly 0.87.0 → 0.89.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 (34) hide show
  1. package/README.md +6 -4
  2. package/lib/addons/adapters.js +370 -310
  3. package/lib/addons/characters.js +1878 -1449
  4. package/lib/addons/load-scene-CQvcFWGJ.js +331 -0
  5. package/lib/addons/scene-3d.js +299 -215
  6. package/lib/browser/tinyfly-scene-3d.iife.js +2 -2
  7. package/lib/browser/tinyfly.iife.js +4 -4
  8. package/lib/browser/tinyfly.js +4395 -3858
  9. package/lib/browser/tinyfly.umd.js +4 -4
  10. package/lib/engine/tinyfly-engine.js +155 -106
  11. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  12. package/lib/headless/headless.js +8 -4
  13. package/lib/types/adapters/canvas/index.d.ts +1 -0
  14. package/lib/types/adapters/canvas/trail.d.ts +57 -0
  15. package/lib/types/browser/index.d.ts +2 -0
  16. package/lib/types/characters/acting/act-tracks.d.ts +28 -0
  17. package/lib/types/characters/acting/acting.d.ts +187 -0
  18. package/lib/types/characters/acting/effects.d.ts +65 -0
  19. package/lib/types/characters/acting/gags.d.ts +54 -0
  20. package/lib/types/characters/acting/index.d.ts +10 -0
  21. package/lib/types/characters/acting/rigs.d.ts +9 -0
  22. package/lib/types/characters/character.d.ts +7 -0
  23. package/lib/types/characters/index.d.ts +1 -0
  24. package/lib/types/characters/stick-figure.d.ts +7 -0
  25. package/lib/types/engine/core/clock.d.ts +7 -0
  26. package/lib/types/engine/path/index.d.ts +2 -0
  27. package/lib/types/engine/path/trail.d.ts +79 -0
  28. package/lib/types/headless/video-scene.d.ts +9 -0
  29. package/lib/types/scene-3d/resolve-scene.d.ts +6 -0
  30. package/lib/types/scene-3d/scene-3d-adapter.d.ts +9 -1
  31. package/lib/types/scene-3d/scene-types.d.ts +40 -1
  32. package/lib/types/scene-3d/strokes.d.ts +30 -0
  33. package/package.json +1 -1
  34. package/lib/addons/load-scene-vp14_Jj-.js +0 -324
@@ -0,0 +1,54 @@
1
+ import type { EasingType } from '../../engine/types';
2
+ import { type PoseKey, type PoseName, type StickPose } from '../stick-figure';
3
+ /**
4
+ * Cartoon gags as data: short, already-timed sequences of stick-figure poses
5
+ * that splice into a list of keys. Their timing is the gag (a held wind-up, a
6
+ * zip, a squash on landing), so their keys are marked `act: false` and the
7
+ * acting pass leaves them as written.
8
+ *
9
+ * ```ts
10
+ * const keys = [
11
+ * { time: 0, pose: 'rest' },
12
+ * ...gag('take', { at: 800 }),
13
+ * { time: 3000, pose: 'shrug' },
14
+ * ]
15
+ * actTracks('hero', keys, { style: 'snappy' })
16
+ * ```
17
+ */
18
+ /** One step of a gag: when (ms after it starts), what changes from the pose it starts on, and the ease into it. */
19
+ export interface GagStep {
20
+ after: number;
21
+ pose: Partial<StickPose>;
22
+ easing?: EasingType;
23
+ }
24
+ /**
25
+ * The gags, each built on the pose it starts from (so a take works sitting,
26
+ * turned or mid-wave). Each ends on a pose the next key can move on from.
27
+ */
28
+ export declare const GAGS: {
29
+ /** The classic take: squash down in a squint, then shoot up stretched with eyes popping, hang, and land squashed. */
30
+ take: (from: StickPose) => GagStep[];
31
+ /** Glance at something, look away unbothered, then snap back to it in shock. */
32
+ doubleTake: (from: StickPose) => GagStep[];
33
+ /** Rear back for a zip-off: lean back, one knee up, arms cocked, hold, then pitch forward ready to run. */
34
+ windUp: () => GagStep[];
35
+ /** Coming down to the ground: stretched in the fall, squashed on contact, a spring back up. */
36
+ land: (from: StickPose) => GagStep[];
37
+ /** A frightened shiver: small, fast shakes with wide eyes, then still. */
38
+ tremble: (from: StickPose) => GagStep[];
39
+ /** A sigh: the body sags, shoulders drop, head and eyes go down. */
40
+ deflate: (from: StickPose) => GagStep[];
41
+ };
42
+ export type GagName = keyof typeof GAGS;
43
+ export interface GagOptions {
44
+ /** When the gag starts, ms */
45
+ at: number;
46
+ /** The pose it starts on: a name or a full pose (default rest) */
47
+ from?: PoseName | StickPose;
48
+ /** Time scale: 1 as designed, 2 twice as long (default 1) */
49
+ speed?: number;
50
+ }
51
+ /** The keys of a gag, starting at `at` on the pose it starts from; splice them into a key list. */
52
+ export declare function gag(name: GagName, options: GagOptions): PoseKey[];
53
+ /** How long a gag lasts at a speed, ms. */
54
+ export declare function gagDuration(name: GagName, speed?: number): number;
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Acting: cartoon timing for character poses (anticipation, overshoot,
3
+ * overlap, eyes that lead, blinks, moving holds, jump squash), gags as data,
4
+ * and motion effects (speed lines, dust, impact stars).
5
+ */
6
+ export * from './acting';
7
+ export * from './rigs';
8
+ export * from './act-tracks';
9
+ export * from './gags';
10
+ export * from './effects';
@@ -0,0 +1,9 @@
1
+ import type { ActingRig } from './acting';
2
+ /**
3
+ * Acting rigs: which pose fields lead, which drag, which wind up and how far.
4
+ * Limits are in each field's own units (degrees for joints).
5
+ */
6
+ /** The v1 stick figure (`StickPose`). */
7
+ export declare const STICK_ACTING_RIG: ActingRig;
8
+ /** The v2 human body plan (`HUMAN_REST` fields). */
9
+ export declare const HUMAN_ACTING_RIG: ActingRig;
@@ -200,7 +200,14 @@ export interface CharacterPoseKey {
200
200
  pose?: HumanPoseName | Pose;
201
201
  /** Easing into this key */
202
202
  easing?: EasingType;
203
+ /** `false`: the acting pass (`actCharacterTracks`) takes the move into this key as written */
204
+ act?: boolean;
203
205
  }
206
+ /**
207
+ * The pose at each key: a named pose, or the previous key's pose with the
208
+ * key's changes (the first builds on `rest`).
209
+ */
210
+ export declare function resolveCharacterPoseKeys(keys: CharacterPoseKey[], rest?: Pose): Pose[];
204
211
  /**
205
212
  * Keyframe tracks that move a character target through a sequence of poses.
206
213
  * Each key is a named pose or changes from the previous key (the first builds
@@ -20,3 +20,4 @@ export type { BodyPlan, ChainSpec, BoneSpec, BoneAngles, ContactSpec, HeadSpec,
20
20
  export { createPen, ellipsePoints, type Pen, type Look, type PencilOptions, type PenOptions } from './look/pen';
21
21
  export { basicOutfit, type BasicOutfitOptions } from './wardrobe/basic-outfit';
22
22
  export * from './hands';
23
+ export * from './acting';
@@ -447,7 +447,14 @@ export interface PoseKey {
447
447
  expression?: ExpressionName | Partial<Expression>;
448
448
  /** Easing into this key */
449
449
  easing?: EasingType;
450
+ /** `false`: the acting pass (`actTracks`) takes the move into this key as written */
451
+ act?: boolean;
450
452
  }
453
+ /**
454
+ * The full pose at each key: a named pose, or the previous key's pose with
455
+ * the key's changes (the first builds on rest), with the key's face applied.
456
+ */
457
+ export declare function resolvePoseKeys(keys: PoseKey[]): StickPose[];
451
458
  /**
452
459
  * Keyframe tracks that move `target` through a sequence of poses. Each key is
453
460
  * a named pose or changes from the previous key (the first builds on rest),
@@ -42,3 +42,10 @@ export declare class Clock {
42
42
  private _scheduleFrame;
43
43
  private _onFrame;
44
44
  }
45
+ /**
46
+ * Time held to the last drawing: animating "on twos" (12 drawings a second
47
+ * against a 24 fps film) means each pose shows for two frames. Given a
48
+ * time in ms and the drawings per second, the time of the drawing on screen.
49
+ * A rate of 0 (or less) leaves time continuous.
50
+ */
51
+ export declare function heldTime(time: number, drawingsPerSecond: number): number;
@@ -9,3 +9,5 @@ export { morphPath, isPathData, clearMorphCache, MORPH_SAMPLES } from './path-mo
9
9
  export type { MorphOptions } from './path-morph';
10
10
  export { pointsToPath, shapeToPathData } from './path-builders';
11
11
  export type { PathPoint, PointsToPathOptions, SvgShape } from './path-builders';
12
+ export { trailSamples, ribbon, ribbonHeadCap } from './trail';
13
+ export type { TrailOptions, TrailSample, RibbonPoint, Ribbon } from './trail';
@@ -0,0 +1,79 @@
1
+ /**
2
+ * Trails: where something has been, as plain data.
3
+ *
4
+ * A trail is not a history of frames. It is the moving thing's position at
5
+ * earlier times, asked of a function of time (usually the timeline's state),
6
+ * so the same time always gives the same trail: seeking, scrubbing, frames
7
+ * rendered in any order and loops all draw it identically.
8
+ *
9
+ * The ribbon helper turns sampled points into a tapered band's two edges,
10
+ * for any renderer that fills polygons.
11
+ */
12
+ export interface TrailOptions {
13
+ /** How far back the trail reaches, ms */
14
+ length: number;
15
+ /** Points along it, head included (default 32; at least 2) */
16
+ samples?: number;
17
+ /**
18
+ * Motion that repeats every `period` ms: earlier times wrap into
19
+ * [0, period), so at the start of a loop the trail already shows the end
20
+ * of the previous lap.
21
+ */
22
+ period?: number;
23
+ /** Nothing before this time, ms (default: no limit). The trail is shorter until it has had time to grow. */
24
+ since?: number;
25
+ }
26
+ export interface TrailSample<P> {
27
+ /** Where it was */
28
+ at: P;
29
+ /** When, ms */
30
+ time: number;
31
+ /** 0 at the head (now) to 1 at the tail (`length` ago) */
32
+ age: number;
33
+ }
34
+ /**
35
+ * Sample a trail ending at `time`: oldest first, the head last.
36
+ *
37
+ * ```ts
38
+ * const trail = trailSamples((t) => pointOnOrbit(t), now, { length: 400 })
39
+ * ```
40
+ */
41
+ export declare function trailSamples<P>(positionAt: (time: number) => P, time: number, options: TrailOptions): TrailSample<P>[];
42
+ export interface RibbonPoint {
43
+ x: number;
44
+ y: number;
45
+ /** Full width here, in the points' units */
46
+ width: number;
47
+ }
48
+ export interface Ribbon {
49
+ /** One edge, a point per input point */
50
+ left: Array<{
51
+ x: number;
52
+ y: number;
53
+ }>;
54
+ /** The other edge, a point per input point */
55
+ right: Array<{
56
+ x: number;
57
+ y: number;
58
+ }>;
59
+ }
60
+ /**
61
+ * The two edges of a band along `points`, each point `width` wide. Joints
62
+ * are mitred, so neighbouring segments share their corners exactly (quads
63
+ * `left[i], left[i+1], right[i+1], right[i]` meet with no gap or overlap).
64
+ * Repeated points are skipped over when finding directions.
65
+ */
66
+ export declare function ribbon(points: RibbonPoint[]): Ribbon;
67
+ /**
68
+ * A round end for a band's last point: a half circle, `width / 2` across,
69
+ * bulging the way the band travels. Drawn as part of the last segment, it
70
+ * covers nothing the segment covers. Null when the band has no direction.
71
+ * Angles are canvas angles (radians, y down): the arc runs from `start`
72
+ * through the travel direction, decreasing, to `start - π`.
73
+ */
74
+ export declare function ribbonHeadCap(points: RibbonPoint[]): {
75
+ x: number;
76
+ y: number;
77
+ radius: number;
78
+ start: number;
79
+ } | null;
@@ -20,6 +20,13 @@ export interface VideoScene {
20
20
  height: number;
21
21
  /** Frames per second (default 30) */
22
22
  fps?: number;
23
+ /**
24
+ * Drawings per second for the timeline's animation: 12 holds every pose for
25
+ * two frames of 24 fps ("on twos"), 8 for three ("on threes"), as hand-drawn
26
+ * animation is timed. The frame rate (and `draw`, `background`) stays as set,
27
+ * so camera moves drawn there can stay smooth. Default: every frame.
28
+ */
29
+ drawingRate?: number;
23
30
  /** Length in ms (default: the timeline's duration) */
24
31
  duration?: number;
25
32
  /** Animation data; its markers drive stills and captions */
@@ -56,6 +63,8 @@ export interface FrameInfo {
56
63
  time: number;
57
64
  /** Timeline state at `time`, when the scene has a timeline */
58
65
  state?: AnimationState;
66
+ /** Timeline state at any other time (trails ask where things were), when the scene has a timeline */
67
+ stateAt?: (time: number) => AnimationState;
59
68
  /** Scene size in pixels (the logical size, before `scale`) */
60
69
  width: number;
61
70
  height: number;
@@ -14,6 +14,7 @@ import type { Drawable } from './object-kind';
14
14
  * `rotateZ` (degrees, YXZ) or `quaternion` (a slerp track); `scale` or
15
15
  * `scaleX` / `scaleY` / `scaleZ`; `visible` (0 or 1); `opacity`;
16
16
  * - meshes and lights: `color`; lights: `intensity`, `target`;
17
+ * - lines and trails: `color`, `width`, `opacity`; trails: `length`;
17
18
  * - cameras: `fov` (perspective), `height` (orthographic), `lookAt`;
18
19
  * - the scene itself, `<sceneId>`: `activeCamera` (a camera's id: a cut is one keyframe).
19
20
  */
@@ -117,6 +118,11 @@ export interface ResolveOptions {
117
118
  height: number;
118
119
  /** ms: the moment drawn, for looks that move with time (default 0) */
119
120
  time?: number;
121
+ /**
122
+ * The animated values at another moment (an `AnimationState`'s `values`):
123
+ * trails ask where what they follow was. Without it, trails draw nothing.
124
+ */
125
+ valuesAt?: (time: number) => SceneValues;
120
126
  }
121
127
  /** The frame at these animated values (an `AnimationState`'s `values`, or none for the scene as authored). */
122
128
  export declare function resolveScene3D(loaded: LoadedScene3D, values: SceneValues | undefined, options: ResolveOptions): ResolvedScene3D;
@@ -20,9 +20,12 @@ export declare class Scene3DAdapter {
20
20
  private height;
21
21
  private readonly scenes;
22
22
  private values;
23
+ private readonly valuesAt?;
24
+ /** `valuesAt`: the values at another time (`(t) => timeline.getStateAtTime(t).values`), for trails */
23
25
  constructor(renderer: Renderer3D, options: {
24
26
  width: number;
25
27
  height: number;
28
+ valuesAt?: (time: number) => SceneValues;
26
29
  });
27
30
  /** Add a scene; its tracks address `<scene.id>/<objectId>`. */
28
31
  registerScene(scene: LoadedScene3D): void;
@@ -37,10 +40,15 @@ export declare class Scene3DAdapter {
37
40
  /**
38
41
  * Draw a scene at these animated values in one call: for a headless video
39
42
  * scene's `draw(ctx, frame)` (`drawScene3D(ctx, scene, frame.state?.values, frame)`)
40
- * or a canvas target's custom draw.
43
+ * or a canvas target's custom draw. A video frame carries `stateAt`, so
44
+ * trails find where things were; elsewhere pass `valuesAt`.
41
45
  */
42
46
  export declare function drawScene3D(ctx: CanvasRenderingContext2D, scene: LoadedScene3D, values: SceneValues | undefined, size: {
43
47
  width: number;
44
48
  height: number;
45
49
  time?: number;
50
+ valuesAt?: (time: number) => SceneValues;
51
+ stateAt?: (time: number) => {
52
+ values: SceneValues;
53
+ };
46
54
  }): void;
@@ -134,7 +134,46 @@ export interface CharacterObject3D extends ObjectBase {
134
134
  } | false;
135
135
  };
136
136
  }
137
- export type Object3D = GroupObject | MeshObject | CameraObject | LightObject | CharacterObject3D;
137
+ /** How a line or trail looks: a flat band facing the camera, drawn among the meshes by depth. */
138
+ export interface StrokeStyle3D {
139
+ color: string;
140
+ /** Width, metres (default 0.05): it narrows with distance, like everything else */
141
+ width?: number;
142
+ /** How much it narrows toward its start (a line's first point, a trail's tail), 0..1 */
143
+ taper?: number;
144
+ /** How much it fades toward its start, 0..1 */
145
+ fade?: number;
146
+ /** 0..1, default 1 */
147
+ opacity?: number;
148
+ /** `normal` (default) paints over what is behind; `add` adds its light: glowing beams that feed bloom */
149
+ blend?: 'normal' | 'add';
150
+ }
151
+ /** A polyline through `points` (in its own space, so it moves with its transform and parent). */
152
+ export interface LineObject3D extends ObjectBase, StrokeStyle3D {
153
+ kind: 'line';
154
+ points: Vec3Tuple[];
155
+ /** Join the last point back to the first */
156
+ closed?: boolean;
157
+ }
158
+ /**
159
+ * Where another object has been: a band through its positions over the last
160
+ * `length` ms, narrowing and fading toward the tail (taper and fade default
161
+ * to 1). It needs the earlier moments, so the renderer is given a way to ask
162
+ * for them (`valuesAt` / `stateAt`); without one it draws nothing. Its own
163
+ * transform is not used.
164
+ */
165
+ export interface TrailObject3D extends ObjectBase, StrokeStyle3D {
166
+ kind: 'trail';
167
+ /** Id of the object it follows */
168
+ follow: string;
169
+ /** How far back it reaches, ms */
170
+ length: number;
171
+ /** Points along it (default 32) */
172
+ samples?: number;
173
+ /** Motion that repeats every `period` ms: the trail wraps, so a loop's first frame shows the last lap */
174
+ period?: number;
175
+ }
176
+ export type Object3D = GroupObject | MeshObject | CameraObject | LightObject | CharacterObject3D | LineObject3D | TrailObject3D;
138
177
  export type Geometry3D = {
139
178
  type: 'box';
140
179
  size: Vec3Tuple;
@@ -0,0 +1,30 @@
1
+ import { type Vec3 } from '../engine/math';
2
+ import type { Drawable } from './object-kind';
3
+ import type { ResolvedCamera, ResolvedScene3D, ScreenPoint } from './resolve-scene';
4
+ /**
5
+ * Lines and trails in a 3D scene: a band through world points, facing the
6
+ * camera, as many drawables as it has segments, so each sits at its own
7
+ * depth among the meshes' triangles (a trail can pass behind one shape and in
8
+ * front of another).
9
+ */
10
+ export interface StrokeLook {
11
+ color: string;
12
+ /** Metres */
13
+ width: number;
14
+ taper: number;
15
+ fade: number;
16
+ opacity: number;
17
+ additive: boolean;
18
+ }
19
+ export interface StrokeView {
20
+ camera: ResolvedCamera;
21
+ /** Canvas height, px */
22
+ height: number;
23
+ fog?: ResolvedScene3D['fog'];
24
+ toScreen(view: Vec3): ScreenPoint;
25
+ }
26
+ /**
27
+ * The band through `points` (world space), each with its age: 0 at the head,
28
+ * 1 at the tail, where taper and fade apply in full.
29
+ */
30
+ export declare function strokeDrawables(points: Vec3[], ages: number[], look: StrokeLook, view: StrokeView): Drawable[];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@algorisys/tinyfly",
3
- "version": "0.87.0",
3
+ "version": "0.89.0",
4
4
  "type": "module",
5
5
  "description": "Lightweight, API-driven animation engine and editor. The engine is framework-agnostic and runs in browsers, Web Workers, and Node.",
6
6
  "license": "MIT",