@algorisys/tinyfly 0.75.0 → 0.76.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.
@@ -919,7 +919,8 @@ class FrameRenderer {
919
919
  }
920
920
  /** Clear the context and draw the scene at `time` ms. */
921
921
  render(ctx, time, index = 0) {
922
- const state = this.timeline?.getStateAtTime(time);
922
+ const timelineState = this.timeline?.getStateAtTime(time);
923
+ const state = timelineState && { ...timelineState, currentTime: time };
923
924
  ctx.setTransform(1, 0, 0, 1, 0, 0);
924
925
  ctx.clearRect(0, 0, this.width, this.height);
925
926
  ctx.save();
@@ -1,6 +1,7 @@
1
1
  import type { CustomTarget } from '../adapters/canvas';
2
+ import type { FrameInfo } from '../headless/video-scene';
2
3
  import type { EasingType, Track } from '../engine/types';
3
- import { type Point, type SketchStyle } from '../adapters/canvas/sketch';
4
+ import { type Point, type SketchPen, type SketchStyle } from '../adapters/canvas/sketch';
4
5
  /**
5
6
  * A stick-figure rig: a pose is a handful of numbers, so poses blend, walk
6
7
  * cycles are functions of a phase, and every joint can be a timeline track.
@@ -53,6 +54,18 @@ export interface StickPose {
53
54
  * becomes an ellipse of the same area.
54
55
  */
55
56
  stretch: number;
57
+ /**
58
+ * How far the figure turns toward the way it faces: 0 front-on, 1 in
59
+ * profile. The face slides toward the facing side and narrows, and
60
+ * shoulders (with a `shoulderWidth`) close up. Turn walkers toward where they go.
61
+ */
62
+ turn: number;
63
+ /**
64
+ * 0 standing, 1 seated: the thighs swing forward to level, the shins hang
65
+ * straight down, and the hips drop to {@link seatHeight} above the feet. From
66
+ * 0.25 on, the lower foot rests on the ground.
67
+ */
68
+ sit: number;
56
69
  }
57
70
  export declare const REST_POSE: StickPose;
58
71
  /** A full pose from the fields that differ from rest. */
@@ -98,6 +111,7 @@ export declare const POSES: {
98
111
  sad: StickPose;
99
112
  surprised: StickPose;
100
113
  crouch: StickPose;
114
+ sit: StickPose;
101
115
  jump: StickPose;
102
116
  };
103
117
  export type PoseName = keyof typeof POSES;
@@ -130,6 +144,11 @@ export interface StickStyle {
130
144
  color?: string;
131
145
  /** Line width (default 2.5% of the height) */
132
146
  lineWidth?: number;
147
+ /**
148
+ * Head diameter as a fraction of the height (default 0.24). A bigger head
149
+ * takes its room from the torso: the feet and hips stay where they are.
150
+ */
151
+ headSize?: number;
133
152
  /** Head fill; `none` leaves it see-through (default white) */
134
153
  headFill?: string;
135
154
  /** 1 faces right, -1 faces left: mirrors the figure and turns the eyes */
@@ -142,7 +161,127 @@ export interface StickStyle {
142
161
  sketch?: SketchStyle;
143
162
  /** Limbs: 0 straight segments jointed at elbows and knees (default), 1 smooth rubber-hose curves */
144
163
  rubber?: number;
164
+ /**
165
+ * Half the shoulder width, as a fraction of the height (default 0: both arms
166
+ * come from one point on the spine). The shoulders sit either side of the
167
+ * spine and square to it, so they tilt with `lean`; a line joins them.
168
+ */
169
+ shoulderWidth?: number;
170
+ /**
171
+ * The 0.75 look: even straight-stroked lines, sharp elbows and knees, no
172
+ * hands or feet, and the hips held at a fixed height (feet can float off the
173
+ * ground mid-stride). Off by default: limbs taper, elbows and knees are
174
+ * always a little rounded (as `rubber` 0.3), hands and feet are drawn, the
175
+ * lower foot always rests on the ground (so a walk bobs), and the body leans
176
+ * into sitting down and standing up.
177
+ */
178
+ classic?: boolean;
179
+ /** Drawing hooks that put costumes, hair and props inside the figure's z-order */
180
+ layers?: FigureLayers;
181
+ }
182
+ export type StickSide = 'left' | 'right';
183
+ /**
184
+ * Draws part of a figure: a costume, hair, a held prop. The context is in the
185
+ * figure's own space (feet at 0, 0, not mirrored), saved and restored around
186
+ * the call, with the figure's line colour and width set. `joints` are already
187
+ * mirrored for facing, so the hook draws at them directly. `pen` is given when
188
+ * the figure is sketched, so a costume boils with the line work; it is not the
189
+ * figure's own pen, so adding a costume does not change how the figure wobbles.
190
+ */
191
+ export type FigureLayer = (ctx: CanvasRenderingContext2D, joints: StickJoints, time: number, pen?: SketchPen) => void;
192
+ /** A {@link FigureLayer} for one arm's sleeve. */
193
+ export type SleeveLayer = (ctx: CanvasRenderingContext2D, joints: StickJoints, side: StickSide, time: number, pen?: SketchPen) => void;
194
+ /**
195
+ * Hooks called while a figure draws, so what they draw sits at the right depth.
196
+ * The order is:
197
+ *
198
+ * behind → legs → torso → body → back arm → sleeve(back) → front arm →
199
+ * sleeve(front) → behindHead → head and face → overHead → front → label
200
+ *
201
+ * The left arm is always the back arm, drawn first. The figure faces the
202
+ * viewer and is mirrored as a whole for `facing`, so its left side is always
203
+ * the one away from the way it looks.
204
+ */
205
+ export interface FigureLayers {
206
+ /** Before anything: long hair at the back, a cape, a shadow */
207
+ behind?: FigureLayer;
208
+ /** After the legs and torso, before the arms: a shirt, kurta, sari or trousers */
209
+ body?: FigureLayer;
210
+ /** Right after each arm, so each arm comes out of its own sleeve */
211
+ sleeve?: SleeveLayer;
212
+ /** After the arms, before the head: a bun, the root of a ponytail */
213
+ behindHead?: FigureLayer;
214
+ /** After the head and face: a hair cap, turban, crown, glasses, moustache */
215
+ overHead?: FigureLayer;
216
+ /** Last, before the label: a held prop in front of everything */
217
+ front?: FigureLayer;
218
+ }
219
+ /** The head as drawn: an ellipse, turned with the lean and head tilt. */
220
+ export interface StickHead {
221
+ center: Point;
222
+ /** Radii across and along the head (they differ when the figure stretches) */
223
+ rx: number;
224
+ ry: number;
225
+ /** Rotation of the head, radians, as seen on screen (lean + head tilt, mirrored for facing) */
226
+ angle: number;
227
+ /**
228
+ * Face features in head units, for {@link headPoint}: 0 is the centre, -1
229
+ * the top, 1 the bottom. Hair fringes sit above `browTopY`, a moustache
230
+ * between `eyeY` and `mouthY`.
231
+ */
232
+ eyeY: number;
233
+ /** The highest point of either brow for this pose (brows rise with surprise) */
234
+ browTopY: number;
235
+ mouthY: number;
236
+ /** Across the head, where the face is centred: it sits toward the facing side */
237
+ faceX: number;
145
238
  }
239
+ /**
240
+ * Where every part of a figure is, as {@link drawStickFigure} draws it. Points
241
+ * are in the figure's space (feet at 0, 0, up is -y) and already mirrored for
242
+ * facing, so no `ctx.scale(-1, 1)` is needed to draw at them (that would mirror
243
+ * text too). Use {@link jointsToScene} to move them to where the feet stand.
244
+ */
245
+ export interface StickJoints {
246
+ facing: 1 | -1;
247
+ /** The style's height */
248
+ height: number;
249
+ /** Squash and stretch as drawn (clamped to 0.3..3) */
250
+ stretch: number;
251
+ lineWidth: number;
252
+ /** The pelvis: legs hang from it and the body leans about it */
253
+ hip: Point;
254
+ /** Top of the spine, after the lean */
255
+ neck: Point;
256
+ /** Where the arms start: one point when `shoulderWidth` is 0 */
257
+ shoulders: Record<StickSide, Point>;
258
+ elbows: Record<StickSide, Point>;
259
+ hands: Record<StickSide, Point>;
260
+ knees: Record<StickSide, Point>;
261
+ feet: Record<StickSide, Point>;
262
+ /** Tips of the feet, pointing the way the figure faces (the ankles, in the classic look) */
263
+ toes: Record<StickSide, Point>;
264
+ /** The lower foot's y: where the ground is under a figure standing, walking or sitting */
265
+ feetY: number;
266
+ /** Which feet are on the ground: within 1% of the height of the lower foot */
267
+ grounded: Record<StickSide, boolean>;
268
+ /** Direction the hand points (the forearm, along its curve for rubber hose), radians: for holding props */
269
+ handAngle: Record<StickSide, number>;
270
+ /** Each limb as the polyline that is stroked (rubber-hose curves included), for sleeves and trousers */
271
+ limbs: {
272
+ leftArm: Point[];
273
+ rightArm: Point[];
274
+ leftLeg: Point[];
275
+ rightLeg: Point[];
276
+ spine: Point[];
277
+ };
278
+ head: StickHead;
279
+ }
280
+ /**
281
+ * Height of the hips above the feet when a figure `height` px tall is fully
282
+ * seated (`sit` 1): put the top of a bench, log or charpai here.
283
+ */
284
+ export declare function seatHeight(height: number, stretch?: number): number;
146
285
  /**
147
286
  * Points along a limb, blending the jointed shape (two straight segments) into
148
287
  * a rubber-hose curve by `rubber` 0..1. The curve is the quadratic that passes
@@ -150,8 +289,30 @@ export interface StickStyle {
150
289
  */
151
290
  export declare function rubberLimb(root: Point, joint: Point, end: Point, rubber: number, samples?: number): Point[];
152
291
  /**
153
- * Draw a figure with its feet at (0, 0). `time` (ms) only matters for a
154
- * sketched style: it picks which boil frame of the wobble shows.
292
+ * Where every joint of a figure is, without drawing it: the same numbers
293
+ * {@link drawStickFigure} draws with. `figure` is the pose as drawn (use
294
+ * {@link resolveStickPose} to fold a target's walk and talk in first).
295
+ */
296
+ export declare function stickFigureJoints(figure: StickPose, style?: StickStyle): StickJoints;
297
+ /**
298
+ * A point on the head from head units: (0, 0) is the centre and ±1 the edges,
299
+ * x to the right on screen and y down, both turned with the head. For
300
+ * example, `headPoint(head, head.faceX, head.browTopY - 0.1)` is just above
301
+ * the brows.
302
+ */
303
+ export declare function headPoint(head: StickHead, x: number, y: number): Point;
304
+ /** Joints moved from the figure's space to a scene where its feet stand at (x, y). */
305
+ export declare function jointsToScene(joints: StickJoints, x: number, y: number): StickJoints;
306
+ /**
307
+ * Fill a line through `points` whose width runs from `startWidth` to
308
+ * `endWidth`, with round ends: a limb that tapers, or a sleeve or trouser leg
309
+ * along a joint polyline. Uses the context's fill style.
310
+ */
311
+ export declare function taperedLine(ctx: CanvasRenderingContext2D, points: Point[], startWidth: number, endWidth: number): void;
312
+ /**
313
+ * Draw a figure with its feet at (0, 0). `time` (ms) matters for a sketched
314
+ * style (it picks which boil frame of the wobble shows) and is passed to any
315
+ * `layers` hooks.
155
316
  */
156
317
  export declare function drawStickFigure(ctx: CanvasRenderingContext2D, figure: StickPose, style?: StickStyle, time?: number): void;
157
318
  /** Values a stick-figure target's tracks can animate, besides x/y/opacity/…. */
@@ -165,6 +326,11 @@ export interface StickFigureProps extends StickPose {
165
326
  /** Limbs from jointed (0) to rubber hose (1); starts at the style's `rubber` */
166
327
  rubber: number;
167
328
  }
329
+ /**
330
+ * The pose a stick-figure target draws at `time` ms: its props with the walk
331
+ * cycle (by `walking`) and the chatter of `talk` folded in.
332
+ */
333
+ export declare function resolveStickPose(props: StickFigureProps, time: number): StickPose;
168
334
  export interface StickFigureTargetOptions {
169
335
  /** Where the feet stand */
170
336
  x: number;
@@ -173,13 +339,31 @@ export interface StickFigureTargetOptions {
173
339
  pose?: Partial<StickPose>;
174
340
  style?: StickStyle;
175
341
  }
342
+ /** A `custom` target made by {@link stickFigureTarget}. */
343
+ export interface StickFigureTarget extends CustomTarget {
344
+ /** The style it draws with, so {@link stickFigureAt} can find its joints */
345
+ readonly figureStyle: StickStyle;
346
+ }
176
347
  /**
177
348
  * A `custom` canvas target that draws a stick figure. Its props are the pose
178
349
  * plus `walk`, `walking`, `talk` and `rubber`, so the timeline can pose, walk,
179
350
  * voice and loosen it. `x`/`y` here are the feet; the target's own box sits
180
351
  * above them (a stretched figure reaches above its box).
181
352
  */
182
- export declare function stickFigureTarget(options: StickFigureTargetOptions): CustomTarget;
353
+ export declare function stickFigureTarget(options: StickFigureTargetOptions): StickFigureTarget;
354
+ /**
355
+ * The pose and scene-space joints of a {@link stickFigureTarget} in a frame, for
356
+ * immediate-mode drawing that follows it (a speech-bubble tail at the head, a
357
+ * pot carried on it). `id` is the target's key in the scene's `targets`, which
358
+ * is how the timeline's tracks address it.
359
+ *
360
+ * The figure's `x`/`y` tracks are followed; a `rotate` or `scale` on the
361
+ * target itself is not.
362
+ */
363
+ export declare function stickFigureAt(target: CustomTarget, frame: Pick<FrameInfo, 'time' | 'state'>, id: string): {
364
+ pose: StickPose;
365
+ joints: StickJoints;
366
+ };
183
367
  export interface PoseKey {
184
368
  time: number;
185
369
  /** The pose here: a name, or joints to change from the previous key (default: no change) */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@algorisys/tinyfly",
3
- "version": "0.75.0",
3
+ "version": "0.76.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",