@algorisys/tinyfly 0.75.0 → 0.77.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.
@@ -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,16 +161,151 @@ 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. Turned more than a quarter of the way
204
+ * (`turn` above 0.25), the back arm and its sleeve move behind the body:
205
+ *
206
+ * behind → legs → back arm → sleeve(back) → torso → body → front arm → …
207
+ */
208
+ export interface FigureLayers {
209
+ /** Before anything: long hair at the back, a cape, a shadow */
210
+ behind?: FigureLayer;
211
+ /** After the legs and torso, before the arms: a shirt, kurta, sari or trousers */
212
+ body?: FigureLayer;
213
+ /** Right after each arm, so each arm comes out of its own sleeve */
214
+ sleeve?: SleeveLayer;
215
+ /** After the arms, before the head: a bun, the root of a ponytail */
216
+ behindHead?: FigureLayer;
217
+ /** After the head and face: a hair cap, turban, crown, glasses, moustache */
218
+ overHead?: FigureLayer;
219
+ /** Last, before the label: a held prop in front of everything */
220
+ front?: FigureLayer;
145
221
  }
222
+ /** The head as drawn: an ellipse, turned with the lean and head tilt. */
223
+ export interface StickHead {
224
+ center: Point;
225
+ /** Radii across and along the head (they differ when the figure stretches) */
226
+ rx: number;
227
+ ry: number;
228
+ /** Rotation of the head, radians, as seen on screen (lean + head tilt, mirrored for facing) */
229
+ angle: number;
230
+ /**
231
+ * Face features in head units, for {@link headPoint}: 0 is the centre, -1
232
+ * the top, 1 the bottom. Hair fringes sit above `browTopY`, a moustache
233
+ * between `eyeY` and `mouthY`.
234
+ */
235
+ eyeY: number;
236
+ /** The highest point of either brow for this pose (brows rise with surprise) */
237
+ browTopY: number;
238
+ mouthY: number;
239
+ /** Across the head, where the face is centred: it sits toward the facing side */
240
+ faceX: number;
241
+ }
242
+ /**
243
+ * Where every part of a figure is, as {@link drawStickFigure} draws it. Points
244
+ * are in the figure's space (feet at 0, 0, up is -y) and already mirrored for
245
+ * facing, so no `ctx.scale(-1, 1)` is needed to draw at them (that would mirror
246
+ * text too). Use {@link jointsToScene} to move them to where the feet stand.
247
+ */
248
+ export interface StickJoints {
249
+ facing: 1 | -1;
250
+ /** The style's height */
251
+ height: number;
252
+ /** Squash and stretch as drawn (clamped to 0.3..3) */
253
+ stretch: number;
254
+ lineWidth: number;
255
+ /** The pelvis: legs hang from it and the body leans about it */
256
+ hip: Point;
257
+ /** Top of the spine, after the lean */
258
+ neck: Point;
259
+ /** Where the arms start: one point when `shoulderWidth` is 0 */
260
+ shoulders: Record<StickSide, Point>;
261
+ elbows: Record<StickSide, Point>;
262
+ hands: Record<StickSide, Point>;
263
+ knees: Record<StickSide, Point>;
264
+ feet: Record<StickSide, Point>;
265
+ /** Tips of the feet, pointing the way the figure faces (the ankles, in the classic look) */
266
+ toes: Record<StickSide, Point>;
267
+ /** The lower foot's y: where the ground is under a figure standing, walking or sitting */
268
+ feetY: number;
269
+ /** Which feet are on the ground: within 1% of the height of the lower foot */
270
+ grounded: Record<StickSide, boolean>;
271
+ /** Direction the hand points (the forearm, along its curve for rubber hose), radians: for holding props */
272
+ handAngle: Record<StickSide, number>;
273
+ /** Each limb as the polyline that is stroked (rubber-hose curves included), for sleeves and trousers */
274
+ limbs: {
275
+ leftArm: Point[];
276
+ rightArm: Point[];
277
+ leftLeg: Point[];
278
+ rightLeg: Point[];
279
+ spine: Point[];
280
+ };
281
+ head: StickHead;
282
+ }
283
+ /**
284
+ * Height of the hips above the feet when a figure `height` px tall is fully
285
+ * seated (`sit` 1): put the top of a bench, log or charpai here.
286
+ */
287
+ export declare function seatHeight(height: number, stretch?: number): number;
288
+ export { rubberLimb } from './look/curves';
146
289
  /**
147
- * Points along a limb, blending the jointed shape (two straight segments) into
148
- * a rubber-hose curve by `rubber` 0..1. The curve is the quadratic that passes
149
- * through the joint halfway along, so a bent limb keeps its bend, rounded.
290
+ * Where every joint of a figure is, without drawing it: the same numbers
291
+ * {@link drawStickFigure} draws with. `figure` is the pose as drawn (use
292
+ * {@link resolveStickPose} to fold a target's walk and talk in first).
150
293
  */
151
- export declare function rubberLimb(root: Point, joint: Point, end: Point, rubber: number, samples?: number): Point[];
294
+ export declare function stickFigureJoints(figure: StickPose, style?: StickStyle): StickJoints;
152
295
  /**
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.
296
+ * A point on the head from head units: (0, 0) is the centre and ±1 the edges,
297
+ * x to the right on screen and y down, both turned with the head. For
298
+ * example, `headPoint(head, head.faceX, head.browTopY - 0.1)` is just above
299
+ * the brows.
300
+ */
301
+ export declare function headPoint(head: StickHead, x: number, y: number): Point;
302
+ /** Joints moved from the figure's space to a scene where its feet stand at (x, y). */
303
+ export declare function jointsToScene(joints: StickJoints, x: number, y: number): StickJoints;
304
+ export { taperedLine, taperedOutline } from './look/tapered-line';
305
+ /**
306
+ * Draw a figure with its feet at (0, 0). `time` (ms) matters for a sketched
307
+ * style (it picks which boil frame of the wobble shows) and is passed to any
308
+ * `layers` hooks.
155
309
  */
156
310
  export declare function drawStickFigure(ctx: CanvasRenderingContext2D, figure: StickPose, style?: StickStyle, time?: number): void;
157
311
  /** Values a stick-figure target's tracks can animate, besides x/y/opacity/…. */
@@ -165,6 +319,11 @@ export interface StickFigureProps extends StickPose {
165
319
  /** Limbs from jointed (0) to rubber hose (1); starts at the style's `rubber` */
166
320
  rubber: number;
167
321
  }
322
+ /**
323
+ * The pose a stick-figure target draws at `time` ms: its props with the walk
324
+ * cycle (by `walking`) and the chatter of `talk` folded in.
325
+ */
326
+ export declare function resolveStickPose(props: StickFigureProps, time: number): StickPose;
168
327
  export interface StickFigureTargetOptions {
169
328
  /** Where the feet stand */
170
329
  x: number;
@@ -173,13 +332,31 @@ export interface StickFigureTargetOptions {
173
332
  pose?: Partial<StickPose>;
174
333
  style?: StickStyle;
175
334
  }
335
+ /** A `custom` target made by {@link stickFigureTarget}. */
336
+ export interface StickFigureTarget extends CustomTarget {
337
+ /** The style it draws with, so {@link stickFigureAt} can find its joints */
338
+ readonly figureStyle: StickStyle;
339
+ }
176
340
  /**
177
341
  * A `custom` canvas target that draws a stick figure. Its props are the pose
178
342
  * plus `walk`, `walking`, `talk` and `rubber`, so the timeline can pose, walk,
179
343
  * voice and loosen it. `x`/`y` here are the feet; the target's own box sits
180
344
  * above them (a stretched figure reaches above its box).
181
345
  */
182
- export declare function stickFigureTarget(options: StickFigureTargetOptions): CustomTarget;
346
+ export declare function stickFigureTarget(options: StickFigureTargetOptions): StickFigureTarget;
347
+ /**
348
+ * The pose and scene-space joints of a {@link stickFigureTarget} in a frame, for
349
+ * immediate-mode drawing that follows it (a speech-bubble tail at the head, a
350
+ * pot carried on it). `id` is the target's key in the scene's `targets`, which
351
+ * is how the timeline's tracks address it.
352
+ *
353
+ * The figure's `x`/`y` tracks are followed; a `rotate` or `scale` on the
354
+ * target itself is not.
355
+ */
356
+ export declare function stickFigureAt(target: CustomTarget, frame: Pick<FrameInfo, 'time' | 'state'>, id: string): {
357
+ pose: StickPose;
358
+ joints: StickJoints;
359
+ };
183
360
  export interface PoseKey {
184
361
  time: number;
185
362
  /** The pose here: a name, or joints to change from the previous key (default: no change) */
@@ -0,0 +1,14 @@
1
+ import type { CharacterLayers } from '../character';
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.
7
+ */
8
+ export interface BasicOutfitOptions {
9
+ /** Shirt colour (default red) */
10
+ shirt?: string;
11
+ /** Trouser colour (default navy) */
12
+ trousers?: string;
13
+ }
14
+ export declare function basicOutfit(options?: BasicOutfitOptions): CharacterLayers;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@algorisys/tinyfly",
3
- "version": "0.75.0",
3
+ "version": "0.77.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",