@algorisys/tinyfly 0.94.0 → 0.95.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 (54) hide show
  1. package/README.md +6 -6
  2. package/docs/acting.md +5 -0
  3. package/docs/api-reference.md +3 -1
  4. package/docs/editor-guide.md +1 -1
  5. package/docs/examples.md +1 -1
  6. package/docs/getting-started.md +1 -1
  7. package/docs/gsap-compat.md +1 -1
  8. package/docs/llm-guide.md +17 -0
  9. package/docs/maps.md +2 -2
  10. package/docs/props.md +202 -0
  11. package/docs/scene-3d.md +141 -0
  12. package/docs/teaching.md +1 -1
  13. package/lib/addons/characters.js +5329 -2337
  14. package/lib/addons/scene-3d.js +140 -138
  15. package/lib/browser/tinyfly-scene-3d.iife.js +1 -1
  16. package/lib/browser/tinyfly.iife.js +15 -9
  17. package/lib/browser/tinyfly.js +7108 -4061
  18. package/lib/browser/tinyfly.umd.js +15 -9
  19. package/lib/engine/tinyfly-engine.js +612 -600
  20. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  21. package/lib/types/characters/capabilities.d.ts +17 -0
  22. package/lib/types/characters/character-script-3d.d.ts +80 -0
  23. package/lib/types/characters/character.d.ts +19 -0
  24. package/lib/types/characters/ground-path.d.ts +32 -0
  25. package/lib/types/characters/index.d.ts +3 -0
  26. package/lib/types/characters/props/clip.d.ts +5 -0
  27. package/lib/types/characters/props/draw.d.ts +60 -0
  28. package/lib/types/characters/props/effects.d.ts +12 -0
  29. package/lib/types/characters/props/families/aircraft.d.ts +37 -0
  30. package/lib/types/characters/props/families/animals.d.ts +156 -0
  31. package/lib/types/characters/props/families/birds.d.ts +86 -0
  32. package/lib/types/characters/props/families/environment.d.ts +71 -0
  33. package/lib/types/characters/props/families/vehicle.d.ts +129 -0
  34. package/lib/types/characters/props/hidden.d.ts +49 -0
  35. package/lib/types/characters/props/index.d.ts +23 -0
  36. package/lib/types/characters/props/mesh-3d.d.ts +24 -0
  37. package/lib/types/characters/props/presets.d.ts +34 -0
  38. package/lib/types/characters/props/ride-3d.d.ts +71 -0
  39. package/lib/types/characters/props/ride.d.ts +79 -0
  40. package/lib/types/characters/props/rig.d.ts +224 -0
  41. package/lib/types/characters/props/scene-objects.d.ts +2 -0
  42. package/lib/types/characters/props/script-3d.d.ts +85 -0
  43. package/lib/types/characters/props/script.d.ts +145 -0
  44. package/lib/types/characters/props/shapes.d.ts +96 -0
  45. package/lib/types/characters/props/slice.d.ts +66 -0
  46. package/lib/types/characters/props/target.d.ts +129 -0
  47. package/lib/types/engine/authoring/index.d.ts +1 -0
  48. package/lib/types/engine/authoring/spring-follow.d.ts +25 -0
  49. package/lib/types/scene-3d/object-kind.d.ts +4 -1
  50. package/lib/types/scene-3d/scene-types.d.ts +41 -1
  51. package/llms-full.txt +428 -9
  52. package/llms.txt +28 -27
  53. package/package.json +1 -1
  54. package/skills/tinyfly/SKILL.md +8 -0
@@ -0,0 +1,66 @@
1
+ import { type Mat4, type Vec3 } from '../../engine/math';
2
+ import type { Mesh } from './shapes';
3
+ /**
4
+ * Cutting a prop into columns, for sorting by depth among other things.
5
+ *
6
+ * A 3D scene draws pen-drawn things back to front, each whole, at one depth.
7
+ * A long prop (a bus) has one depth for all of it, so a figure standing by
8
+ * its far end and one by its near end can't both sort right against it.
9
+ * Cut on a grid into columns about a metre across (along the prop's length
10
+ * and width; up stays whole), each column sorts at its own depth. Columns
11
+ * don't overlap, so for anything outside the prop the order is right; inside
12
+ * a column the prop's parts keep their own order (a cabin over its body).
13
+ * Big shapes are cut at the column walls, and those cuts are joins, not
14
+ * outlines (`walls`), so the prop still draws as one. Small parts (a wheel,
15
+ * an eye, a tube) go whole into the column their middle is in.
16
+ */
17
+ export type Cell = readonly [number, number];
18
+ /** Where to cut along an axis: columns about `size` across, or none when it is not much longer than that. */
19
+ export declare function gridCuts(min: number, max: number, size: number): number[];
20
+ /** The column a point is in. */
21
+ export declare function cellOf(xs: number[], zs: number[], point: Vec3): Cell;
22
+ /** A mesh moved into its prop's space: its points by the part's matrix, its normals turned with it. */
23
+ export declare function meshInSpace(mesh: Mesh, m: Mat4): Mesh;
24
+ /** A mesh (in its prop's space) cut at the grid's column walls: one joined piece per column it reaches. */
25
+ export declare function cutMesh(mesh: Mesh, xs: number[], zs: number[]): Array<{
26
+ cell: Cell;
27
+ mesh: Mesh;
28
+ }>;
29
+ /** A part placed for cutting: its mesh, and its matrix into the prop's rest space. */
30
+ export interface PlacedPart<P> {
31
+ part: P;
32
+ mesh: Mesh;
33
+ local: Mat4;
34
+ /** Never cut (a tube: it is drawn along its centre line in line art) */
35
+ whole?: boolean;
36
+ }
37
+ export interface ColumnPiece<P> {
38
+ part: P;
39
+ /** Its own mesh (placed by `local`), or a piece cut from it (already in rest space) */
40
+ mesh: Mesh;
41
+ cut: boolean;
42
+ cell: Cell;
43
+ }
44
+ /** A mesh in rest space, with its bounds, cached by the matrix that put it there (most parts don't move). */
45
+ interface Placed {
46
+ /** The matrix's key */
47
+ key: string;
48
+ inSpace: Mesh;
49
+ low: Vec3;
50
+ high: Vec3;
51
+ }
52
+ /** A matrix as a cache key. */
53
+ export declare const matrixKey: (m: Mat4) => string;
54
+ /** A part's mesh in rest space, with its bounds. */
55
+ export declare function placedMesh(mesh: Mesh, local: Mat4): Placed;
56
+ /**
57
+ * A prop's parts placed in columns about `size` across, in its rest space
58
+ * (before its pitch, lift and squash, so the columns move with it): small
59
+ * parts whole in the column their middle is in, big ones cut at the column
60
+ * walls. Cuts are cached, so only parts that move are cut again.
61
+ */
62
+ export declare function propColumns<P>(parts: Array<PlacedPart<P>>, size: number): {
63
+ pieces: Array<ColumnPiece<P>>;
64
+ middle: (cell: Cell) => Vec3;
65
+ };
66
+ export {};
@@ -0,0 +1,129 @@
1
+ import type { CustomTarget } from '../../adapters/canvas/canvas-adapter';
2
+ import type { PropertyInfo } from '../../adapters/canvas/target-properties';
3
+ import type { FrameInfo } from '../../headless/video-scene';
4
+ import type { ActingRig } from '../acting/acting';
5
+ import { type PropRig, type SolvedProp } from './rig';
6
+ import { type PropDrawOptions } from './draw';
7
+ import type { PropAction } from './script';
8
+ /**
9
+ * A prop: what it is, its rig, what it can do and how it acts. Families
10
+ * (`vehicle()`, …) make them; presets (`car()`) are families with settings.
11
+ */
12
+ export interface Prop {
13
+ /** What it is: car, tree, helicopter */
14
+ kind: string;
15
+ /** The family it comes from: vehicle, plant, building, aircraft */
16
+ family: string;
17
+ summary: string;
18
+ rig: PropRig;
19
+ /** What its beats can do (see `propScript`) */
20
+ actions: Record<string, PropAction>;
21
+ /** How its controls act: which lead, which follow, which wind up and overshoot (see `actKeyframes`) */
22
+ acting: ActingRig;
23
+ /** Its colours, for effects drawn with it */
24
+ colors?: {
25
+ body?: string;
26
+ ink?: string;
27
+ };
28
+ /**
29
+ * Follow-through: controls that trail another on a spring (an antenna
30
+ * behind the car's motion). The control is how far the follower lags,
31
+ * along the way the prop faces, × `per`, capped at ± `limit`.
32
+ */
33
+ follow?: PropFollow[];
34
+ /** A wheeled prop's reference wheel radius, metres: `wheelSpin` is that wheel's turn (see `propTow`) */
35
+ wheelRadius?: number;
36
+ /**
37
+ * How it gets about, for beats in world metres (`propScript3D`): each way
38
+ * of moving with its speed and the controls keyed as it goes, so wheels
39
+ * roll and feet step exactly the distance covered.
40
+ */
41
+ moves?: Record<string, PropMove>;
42
+ }
43
+ /** One way a prop moves over the ground (or through the air), as plain data. */
44
+ export interface PropMove {
45
+ /** Its usual speed, metres per second */
46
+ speed: number;
47
+ /** Controls set as it sets off (a gait's number) */
48
+ set?: Record<string, number>;
49
+ /** Controls eased in as it sets off and out as it stops (`walking: 1`, `flapping: 1`) */
50
+ hold?: Record<string, number>;
51
+ /** Controls advanced in step with the distance, per metre (`wheelSpin` in degrees, a stride's phase in cycles) */
52
+ perMetre?: Record<string, number>;
53
+ /** Controls advanced with time, per second (a wingbeat, a rotor) */
54
+ perSecond?: Record<string, number>;
55
+ /** It flies: a beat's `height` (metres) is how high, as its `lift` */
56
+ flies?: boolean;
57
+ }
58
+ export interface PropFollow {
59
+ /** The control it drives */
60
+ control: string;
61
+ /** What it follows: a directly keyed control, usually `x` */
62
+ of: string;
63
+ /** Control units per px of lag */
64
+ per: number;
65
+ stiffness?: number;
66
+ damping?: number;
67
+ /** The most it bends either way */
68
+ limit?: number;
69
+ }
70
+ export interface PropTargetOptions {
71
+ /** Where its middle stands on the ground, scene px */
72
+ x: number;
73
+ y: number;
74
+ prop: Prop;
75
+ /** px per metre (default 60, which makes a 1.7 m figure about 100 px tall) */
76
+ scale?: number;
77
+ /** Starting control values (default each control's default) */
78
+ values?: Record<string, number>;
79
+ look?: PropDrawOptions['look'];
80
+ ink?: string;
81
+ lineWidth?: number;
82
+ pencil?: PropDrawOptions['pencil'];
83
+ seed?: number;
84
+ /** `solid` (default) or `stick`: line art to go with stick figures */
85
+ style?: PropDrawOptions['style'];
86
+ /** The paper colour a stick prop is filled with */
87
+ paper?: string;
88
+ }
89
+ /** A `custom` target made by {@link propTarget}. */
90
+ export interface PropTarget extends CustomTarget {
91
+ readonly prop: Prop;
92
+ /** px per metre */
93
+ readonly propScale: number;
94
+ readonly propDraw: Omit<PropDrawOptions, 'time' | 'rider'>;
95
+ }
96
+ /** Every control a prop has, described: the common ones and its own. */
97
+ export declare function propControls(prop: Prop): Record<string, PropertyInfo & {
98
+ default?: number;
99
+ }>;
100
+ /**
101
+ * A `custom` canvas target that draws a prop, its middle standing at x, y.
102
+ * Its props are the prop's controls, so tracks turn it, squash it, spin its
103
+ * wheels; `describeTarget` lists them with what the prop can do.
104
+ */
105
+ export declare function propTarget(options: PropTargetOptions): PropTarget;
106
+ /** The prop solved for control values, in its own space (its middle on the ground at 0, 0). */
107
+ export declare function solveAt(prop: Prop, values: Record<string, number>, scale: number): SolvedProp;
108
+ export interface PropFrame {
109
+ /** Its control values in this frame */
110
+ values: Record<string, number>;
111
+ /** Where its middle stands, scene px */
112
+ origin: {
113
+ x: number;
114
+ y: number;
115
+ };
116
+ solved: SolvedProp;
117
+ /** An anchor in scene px, with its depth (nearer is larger) */
118
+ anchor(name: string): {
119
+ x: number;
120
+ y: number;
121
+ depth: number;
122
+ };
123
+ }
124
+ /** A prop target in a frame: its values from the timeline's state, where it stands, and its anchors in scene px. */
125
+ export declare function propAt(target: PropTarget, frame: Pick<FrameInfo, 'time' | 'state'>, id: string): PropFrame;
126
+ /** Draw a prop target as it is in a frame, for immediate-mode drawing; `rider` draws a figure seated in it. */
127
+ export declare function drawProp(ctx: CanvasRenderingContext2D, target: PropTarget, frame: Pick<FrameInfo, 'time' | 'state'>, id: string, options?: {
128
+ rider?: (ctx: CanvasRenderingContext2D) => void;
129
+ }): PropFrame;
@@ -5,3 +5,4 @@ export * from './narration';
5
5
  export * from './beats';
6
6
  export * from './camera-shots';
7
7
  export * from './did-you-mean';
8
+ export * from './spring-follow';
@@ -0,0 +1,25 @@
1
+ import type { Keyframe } from '../types';
2
+ /**
3
+ * Follow-through as keyframes: a value that chases another on a spring, so a
4
+ * secondary part lags behind and overshoots a primary one — a car's antenna
5
+ * after the car, leaves after a branch, a load on a truck.
6
+ *
7
+ * const chase = springFollow((t) => valueOf(xTrack, t), { start: 0, end: 4000 })
8
+ * // the antenna's bend is how far the follower is behind: (chase − x) × k
9
+ *
10
+ * The spring is stepped in fixed 1 ms steps from `start`, so the same input
11
+ * always gives the same keys. It starts at rest on the primary's value.
12
+ */
13
+ export interface SpringFollowOptions {
14
+ /** From and to, ms */
15
+ start: number;
16
+ end: number;
17
+ /** Key spacing, ms (default 33) */
18
+ step?: number;
19
+ /** Spring stiffness (default 120): higher follows more tightly */
20
+ stiffness?: number;
21
+ /** Damping (default 9): lower wobbles longer */
22
+ damping?: number;
23
+ mass?: number;
24
+ }
25
+ export declare function springFollow(primary: (time: number) => number, options: SpringFollowOptions): Keyframe<number>[];
@@ -2,7 +2,7 @@ import type { Mat4, Vec3 } from '../engine/math';
2
2
  import type { AnimatableValue } from '../engine/types';
3
3
  import type { Material3D, Object3D } from './scene-types';
4
4
  import type { PreparedMesh } from './load-scene';
5
- import type { ResolvedCamera, ResolvedScene3D, ScreenPoint } from './resolve-scene';
5
+ import type { ResolvedCamera, ResolvedLight, ResolvedScene3D, ScreenPoint } from './resolve-scene';
6
6
  /**
7
7
  * A kind of scene object beyond the built-in meshes, lights and cameras,
8
8
  * added when a scene is loaded: characters come this way, from the
@@ -40,6 +40,9 @@ export interface ObjectContext {
40
40
  /** Its world matrix */
41
41
  world: Mat4;
42
42
  camera: ResolvedCamera;
43
+ /** The scene's lights (empty when it brings none), and its fog: for kinds that light what they draw as the meshes are */
44
+ lights: ResolvedLight[];
45
+ fog?: ResolvedScene3D['fog'];
43
46
  /** Canvas size, px */
44
47
  width: number;
45
48
  height: number;
@@ -117,6 +117,10 @@ export interface CharacterObject3D extends ObjectBase {
117
117
  pose?: Record<string, number>;
118
118
  /** A soft shadow on the ground under it (default true) */
119
119
  shadow?: boolean;
120
+ /** The gait it walks in when walking (`walk`, `run`, `sneak`, `strut`, `tired`, `bouncy`…; default walk); a `gait` track can change it */
121
+ gait?: string;
122
+ /** How much of its gait is applied, 0..1 (default 0); its `walk` track (the gait's phase, in cycles) steps it — see `characterScript3D` */
123
+ walking?: number;
120
124
  /**
121
125
  * `pen` (default): drawn by its pens, in its 2D look (clean, pencil,
122
126
  * silhouette) seen in perspective. `solid`: built of shaded capsules and an
@@ -134,6 +138,40 @@ export interface CharacterObject3D extends ObjectBase {
134
138
  } | false;
135
139
  };
136
140
  }
141
+ /**
142
+ * A prop (a car, a tree, a house, a horse, a bird…) named by its preset,
143
+ * drawn with the characters' pens in its look. Like characters, it needs the
144
+ * characters add-on: `loadScene3D(scene, { kinds: [characterObjects, propObjects] })`
145
+ * with both from `@algorisys/tinyfly/characters`. It stands on its object's
146
+ * ground and faces +z; `rotateY` turns it. Its controls (`door`, `wheelSpin`,
147
+ * `spread`, …) are tracks on the object too.
148
+ */
149
+ export interface PropObject3D extends ObjectBase {
150
+ kind: 'prop';
151
+ /** The preset: car, truck, bus, tractor, cart, trainCar, bike, motorbike, tree, house, helicopter, airplane, horse, dog, cat, cow, songbird, crow, chicken */
152
+ prop: string;
153
+ /** The preset's options (colours, sizes) */
154
+ options?: Record<string, unknown>;
155
+ /** Its control values as placed (`door: 1`, `lights: 1`); tracks animate them */
156
+ values?: Record<string, number>;
157
+ /** clean (default), pencil or silhouette, as the figures */
158
+ /**
159
+ * clean (default), pencil or silhouette: drawn with the figures' pens. `mesh`: built of the scene's own
160
+ * meshes, lit, outlined and depth-sorted with them (exact with the WebGL2 renderer); glass is see-through
161
+ */
162
+ look?: 'clean' | 'pencil' | 'silhouette' | 'mesh';
163
+ /** The mesh look's shading (default toon) and outline width in px (default 2) */
164
+ shading?: 'unlit' | 'flat' | 'lambert' | 'toon';
165
+ outline?: number;
166
+ /** solid (default) or stick (line art) */
167
+ style?: 'solid' | 'stick';
168
+ /** Outline colour */
169
+ ink?: string;
170
+ /** The paper a stick prop's shapes are filled with */
171
+ paper?: string;
172
+ /** A contact shadow on the ground under it (default true) */
173
+ shadow?: boolean;
174
+ }
137
175
  /** How a line or trail looks: a flat band facing the camera, drawn among the meshes by depth. */
138
176
  export interface StrokeStyle3D {
139
177
  color: string;
@@ -173,7 +211,7 @@ export interface TrailObject3D extends ObjectBase, StrokeStyle3D {
173
211
  /** Motion that repeats every `period` ms: the trail wraps, so a loop's first frame shows the last lap */
174
212
  period?: number;
175
213
  }
176
- export type Object3D = GroupObject | MeshObject | CameraObject | LightObject | CharacterObject3D | LineObject3D | TrailObject3D;
214
+ export type Object3D = GroupObject | MeshObject | CameraObject | LightObject | CharacterObject3D | PropObject3D | LineObject3D | TrailObject3D;
177
215
  export type Geometry3D = {
178
216
  type: 'box';
179
217
  size: Vec3Tuple;
@@ -219,6 +257,8 @@ export interface Material3D {
219
257
  shading?: 'unlit' | 'flat' | 'lambert' | 'toon';
220
258
  /** Toon: number of light bands (default 3) */
221
259
  bands?: number;
260
+ /** Inked creases too, where faces meet at a sharp angle (default true); false for smooth surfaces built of facets: only their silhouettes */
261
+ creases?: boolean;
222
262
  /** Ink outline along silhouettes and creases, px */
223
263
  outline?: {
224
264
  width: number;