@algorisys/tinyfly 0.94.0 → 0.97.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 +6 -6
- package/docs/acting.md +170 -0
- package/docs/api-reference.md +3 -1
- package/docs/editor-guide.md +1 -1
- package/docs/examples.md +1 -1
- package/docs/getting-started.md +1 -1
- package/docs/gsap-compat.md +1 -1
- package/docs/llm-guide.md +41 -2
- package/docs/maps.md +2 -2
- package/docs/props.md +202 -0
- package/docs/scene-3d.md +141 -0
- package/docs/teaching.md +1 -1
- package/lib/addons/characters.js +6188 -2261
- package/lib/addons/scene-3d.js +140 -138
- package/lib/browser/tinyfly-scene-3d.iife.js +1 -1
- package/lib/browser/tinyfly.iife.js +17 -9
- package/lib/browser/tinyfly.js +8077 -4095
- package/lib/browser/tinyfly.umd.js +17 -9
- package/lib/engine/tinyfly-engine.js +612 -600
- package/lib/engine/tinyfly-engine.umd.cjs +2 -2
- package/lib/types/characters/acting/index.d.ts +1 -0
- package/lib/types/characters/acting/surface-script.d.ts +92 -0
- package/lib/types/characters/capabilities.d.ts +22 -0
- package/lib/types/characters/character-script-3d.d.ts +80 -0
- package/lib/types/characters/character.d.ts +19 -0
- package/lib/types/characters/chart.d.ts +108 -0
- package/lib/types/characters/code-panel.d.ts +21 -46
- package/lib/types/characters/ground-path.d.ts +32 -0
- package/lib/types/characters/index.d.ts +6 -0
- package/lib/types/characters/props/clip.d.ts +5 -0
- package/lib/types/characters/props/draw.d.ts +60 -0
- package/lib/types/characters/props/effects.d.ts +12 -0
- package/lib/types/characters/props/families/aircraft.d.ts +37 -0
- package/lib/types/characters/props/families/animals.d.ts +156 -0
- package/lib/types/characters/props/families/birds.d.ts +86 -0
- package/lib/types/characters/props/families/environment.d.ts +71 -0
- package/lib/types/characters/props/families/vehicle.d.ts +129 -0
- package/lib/types/characters/props/hidden.d.ts +49 -0
- package/lib/types/characters/props/index.d.ts +24 -0
- package/lib/types/characters/props/mesh-3d.d.ts +24 -0
- package/lib/types/characters/props/presets.d.ts +34 -0
- package/lib/types/characters/props/prop-surface.d.ts +63 -0
- package/lib/types/characters/props/ride-3d.d.ts +71 -0
- package/lib/types/characters/props/ride.d.ts +79 -0
- package/lib/types/characters/props/rig.d.ts +224 -0
- package/lib/types/characters/props/scene-objects.d.ts +2 -0
- package/lib/types/characters/props/script-3d.d.ts +85 -0
- package/lib/types/characters/props/script.d.ts +145 -0
- package/lib/types/characters/props/shapes.d.ts +96 -0
- package/lib/types/characters/props/slice.d.ts +66 -0
- package/lib/types/characters/props/target.d.ts +129 -0
- package/lib/types/characters/surface/edit-log.d.ts +47 -0
- package/lib/types/characters/surface/index.d.ts +11 -0
- package/lib/types/characters/surface/pieces.d.ts +61 -0
- package/lib/types/characters/surface/ride.d.ts +31 -0
- package/lib/types/characters/surface/surface-box.d.ts +18 -0
- package/lib/types/characters/surface/surface.d.ts +79 -0
- package/lib/types/characters/whiteboard.d.ts +131 -0
- package/lib/types/engine/authoring/index.d.ts +1 -0
- package/lib/types/engine/authoring/spring-follow.d.ts +25 -0
- package/lib/types/scene-3d/object-kind.d.ts +4 -1
- package/lib/types/scene-3d/scene-types.d.ts +41 -1
- package/llms-full.txt +699 -11
- package/llms.txt +28 -27
- package/package.json +1 -1
- package/skills/tinyfly/SKILL.md +37 -9
|
@@ -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;
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import type { EasingType, Track } from '../../engine/types';
|
|
2
|
+
/**
|
|
3
|
+
* The timed edits a surface records on its own props, written out as plain
|
|
4
|
+
* keyframes by `tracks()`. A surface's methods (highlight a line, grow a
|
|
5
|
+
* bar, fling a piece) only ever add keys here; nothing is applied until the
|
|
6
|
+
* timeline plays the tracks, so the same calls always give the same tracks.
|
|
7
|
+
*/
|
|
8
|
+
/** One recorded key on a prop. */
|
|
9
|
+
export type EditKey = {
|
|
10
|
+
time: number;
|
|
11
|
+
value: number;
|
|
12
|
+
easing?: EasingType;
|
|
13
|
+
};
|
|
14
|
+
/** When an edit happens. */
|
|
15
|
+
export interface EditOptions {
|
|
16
|
+
/** When the edit starts, ms */
|
|
17
|
+
at: number;
|
|
18
|
+
/** ms (default depends on the edit) */
|
|
19
|
+
duration?: number;
|
|
20
|
+
easing?: EasingType;
|
|
21
|
+
}
|
|
22
|
+
/** A span of time a prop is changing in, ms. */
|
|
23
|
+
export interface TimeWindow {
|
|
24
|
+
start: number;
|
|
25
|
+
end: number;
|
|
26
|
+
}
|
|
27
|
+
export interface EditLog {
|
|
28
|
+
/** The keys recorded on a prop so far (undefined when it has none) */
|
|
29
|
+
keys(prop: string): EditKey[] | undefined;
|
|
30
|
+
/** Add keys to a prop */
|
|
31
|
+
push(prop: string, ...keys: EditKey[]): void;
|
|
32
|
+
/** An edit from one value to another, as a start and an end key */
|
|
33
|
+
tween(prop: string, from: number, to: number, edit: EditOptions, defaultDuration?: number): void;
|
|
34
|
+
/** The value of a prop's latest key, or `fallback` when it has none */
|
|
35
|
+
last(prop: string, fallback: number): number;
|
|
36
|
+
/** A prop's recorded value at `time` (see `valueAt`) */
|
|
37
|
+
valueAt(prop: string, time: number): number;
|
|
38
|
+
/** Drop the keys after `time` on each prop (a later edit takes over from there) */
|
|
39
|
+
cutAfter(props: string[], time: number): void;
|
|
40
|
+
/** The recorded edits as tracks on `target` (the surface's key in the scene) */
|
|
41
|
+
tracks(target: string): Track[];
|
|
42
|
+
}
|
|
43
|
+
export declare function editLog(): EditLog;
|
|
44
|
+
/** A recorded prop's value at `time`: linear between its keys, held before the first and after the last (0 with none). */
|
|
45
|
+
export declare function valueAt(keys: EditKey[] | undefined, time: number): number;
|
|
46
|
+
/** When a prop's recorded value is changing: each pair of neighbouring keys with different values. */
|
|
47
|
+
export declare function changingWindows(keys: EditKey[] | undefined): TimeWindow[];
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Surfaces: scene objects figures act on (a code panel today; boards,
|
|
3
|
+
* charts and stateful props next). Each records timed edits on its own
|
|
4
|
+
* props, lets parts come loose as pieces, and carries a figure standing on
|
|
5
|
+
* it. These are the parts every surface shares.
|
|
6
|
+
*/
|
|
7
|
+
export * from './surface-box';
|
|
8
|
+
export * from './edit-log';
|
|
9
|
+
export * from './pieces';
|
|
10
|
+
export * from './ride';
|
|
11
|
+
export * from './surface';
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
import type { EditLog, EditOptions } from './edit-log';
|
|
2
|
+
import type { SurfaceBox } from './surface-box';
|
|
3
|
+
/**
|
|
4
|
+
* Parts of a surface that come loose: a word off a line of code, a note off
|
|
5
|
+
* a board, a slice out of a chart. A piece is drawn by its surface at its
|
|
6
|
+
* home plus the offsets recorded here, as `piece.K.x`, `.y` (px from home),
|
|
7
|
+
* `.rotate` (degrees) and `.opacity`. The surface makes its pieces (it knows
|
|
8
|
+
* what they look like); this moves them, the same way on every surface.
|
|
9
|
+
*/
|
|
10
|
+
/** A part of a surface that can come loose. */
|
|
11
|
+
export interface SurfacePiece {
|
|
12
|
+
/** Its key in the surface's props (`piece.K.x`…) */
|
|
13
|
+
readonly id: number;
|
|
14
|
+
/** Where it sits on the surface */
|
|
15
|
+
readonly home: SurfaceBox;
|
|
16
|
+
}
|
|
17
|
+
/** A point at a time, scene px: a path for a piece to follow (see `handPath`). */
|
|
18
|
+
export interface TimedPoint {
|
|
19
|
+
time: number;
|
|
20
|
+
x: number;
|
|
21
|
+
y: number;
|
|
22
|
+
}
|
|
23
|
+
export interface FlingOptions {
|
|
24
|
+
/** When it leaves, ms */
|
|
25
|
+
at: number;
|
|
26
|
+
/** px/ms (default: how fast it was moving along its `follow` path at `at`, or up and to the right) */
|
|
27
|
+
velocity?: {
|
|
28
|
+
x: number;
|
|
29
|
+
y: number;
|
|
30
|
+
};
|
|
31
|
+
/** Turns, degrees per ms (default 0.6, signed by the throw's direction) */
|
|
32
|
+
spin?: number;
|
|
33
|
+
/** px/ms² (default 0.0016) */
|
|
34
|
+
gravity?: number;
|
|
35
|
+
/** How long it flies before it is gone, ms (default 900) */
|
|
36
|
+
duration?: number;
|
|
37
|
+
}
|
|
38
|
+
/** How often a fling's arc (and a ride) is sampled, ms. */
|
|
39
|
+
export declare const SAMPLE_STEP = 33;
|
|
40
|
+
export interface PieceMotion {
|
|
41
|
+
/** Where a piece's centre is at `time`, scene px */
|
|
42
|
+
at(piece: SurfacePiece, time: number): {
|
|
43
|
+
x: number;
|
|
44
|
+
y: number;
|
|
45
|
+
};
|
|
46
|
+
/** Drop a piece's position and turn after `time` (a fling or a move takes over from there) */
|
|
47
|
+
cutAfter(piece: SurfacePiece, time: number): void;
|
|
48
|
+
/** Carry a piece along a path of scene points (its centre follows them) */
|
|
49
|
+
follow(piece: SurfacePiece, path: TimedPoint[]): void;
|
|
50
|
+
/** Throw or kick a piece away: it flies on a ballistic arc, spinning, and fades */
|
|
51
|
+
fling(piece: SurfacePiece, options: FlingOptions): void;
|
|
52
|
+
/** Move a piece's centre to a scene point (back home: its `home` centre) */
|
|
53
|
+
move(piece: SurfacePiece, options: EditOptions & {
|
|
54
|
+
to: {
|
|
55
|
+
x: number;
|
|
56
|
+
y: number;
|
|
57
|
+
};
|
|
58
|
+
}): void;
|
|
59
|
+
}
|
|
60
|
+
/** Moves pieces by recording their offsets in `log`. */
|
|
61
|
+
export declare function pieceMotion(log: EditLog): PieceMotion;
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import type { Track } from '../../engine/types';
|
|
2
|
+
import type { TimeWindow } from './edit-log';
|
|
3
|
+
/**
|
|
4
|
+
* A figure carried by what it stands on: a line of code moving up as the one
|
|
5
|
+
* above it is removed, a shelf sliding, a bar of a chart growing. A surface
|
|
6
|
+
* says where its floors are and how they move; `rideFloors` rewrites the
|
|
7
|
+
* figure's `y` track so its feet stay on them.
|
|
8
|
+
*/
|
|
9
|
+
/** Somewhere a figure can stand on a surface. */
|
|
10
|
+
export interface Floor {
|
|
11
|
+
/** Its top as laid out (before it has moved), scene y */
|
|
12
|
+
top: number;
|
|
13
|
+
/** How far it has moved at `time`, px (up is negative) */
|
|
14
|
+
offset(time: number): number;
|
|
15
|
+
/** When it is moving */
|
|
16
|
+
windows: TimeWindow[];
|
|
17
|
+
}
|
|
18
|
+
export interface RideOptions {
|
|
19
|
+
/** The script's ground, scene y (the figure's y track is measured from it) */
|
|
20
|
+
ground: number;
|
|
21
|
+
/** How often a moving stretch is sampled, ms */
|
|
22
|
+
every: number;
|
|
23
|
+
floors: Floor[];
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* `target`'s tracks with its `y` carried by the floor under its feet. Each
|
|
27
|
+
* segment of the `y` track keeps its keys (and easing) where what is under
|
|
28
|
+
* it does not move; where a floor under it moves (or it steps from one
|
|
29
|
+
* floor to another that has moved), the segment is sampled every `every` ms.
|
|
30
|
+
*/
|
|
31
|
+
export declare function rideFloors(tracks: Track[], target: string, { ground, every, floors }: RideOptions): Track[];
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A place on a surface, scene px: a line of code, a word, a bar of a chart,
|
|
3
|
+
* a note on a board. A figure stands on `top`, points at `x`, `y` (the
|
|
4
|
+
* centre) and swipes from `left` to `right`, so a box is a beat's target as
|
|
5
|
+
* it is.
|
|
6
|
+
*/
|
|
7
|
+
export interface SurfaceBox {
|
|
8
|
+
x: number;
|
|
9
|
+
y: number;
|
|
10
|
+
left: number;
|
|
11
|
+
right: number;
|
|
12
|
+
top: number;
|
|
13
|
+
bottom: number;
|
|
14
|
+
width: number;
|
|
15
|
+
height: number;
|
|
16
|
+
}
|
|
17
|
+
/** The box with this top-left corner and size. */
|
|
18
|
+
export declare function surfaceBox(left: number, top: number, width: number, height: number): SurfaceBox;
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import type { CustomTarget } from '../../adapters/canvas/canvas-adapter';
|
|
2
|
+
import type { Track } from '../../engine/types';
|
|
3
|
+
import type { EditOptions } from './edit-log';
|
|
4
|
+
import type { FlingOptions, SurfacePiece, TimedPoint } from './pieces';
|
|
5
|
+
import type { SurfaceBox } from './surface-box';
|
|
6
|
+
/**
|
|
7
|
+
* A surface: a scene object figures act on. A code panel is one; boards,
|
|
8
|
+
* charts and stateful props follow the same contract.
|
|
9
|
+
*
|
|
10
|
+
* Its places are named by strings, `kind:args`, so a beat can aim at one as
|
|
11
|
+
* plain data: `line:7` and `token:7:Println` on a code panel. `anchor(name)`
|
|
12
|
+
* gives the box there (stand on `top`, point at `x`, `y`), `piece(name)`
|
|
13
|
+
* makes the part there come loose, and `edit(name, anchor, options)` changes
|
|
14
|
+
* the surface at a time. Every edit is recorded as keys on the surface's own
|
|
15
|
+
* props and written out by `tracks()`, so the same calls always give the
|
|
16
|
+
* same tracks.
|
|
17
|
+
*
|
|
18
|
+
* ```ts
|
|
19
|
+
* const code = codePanel({ code: source, language: 'go', x: 40, y: 30 })
|
|
20
|
+
* code.anchor('token:4:Println') // where the word is
|
|
21
|
+
* code.edit('highlight', 'line:4', { at: 1200 })
|
|
22
|
+
* code.edit('fling', 'token:4:Println', { at: 2000 }) // knocked off the panel
|
|
23
|
+
* ```
|
|
24
|
+
*/
|
|
25
|
+
export interface Surface {
|
|
26
|
+
/** What it is: 'code', 'board', 'chart'… */
|
|
27
|
+
readonly kind: string;
|
|
28
|
+
/** The canvas target that draws it; put it in the scene's targets */
|
|
29
|
+
readonly target: CustomTarget;
|
|
30
|
+
/** The whole surface */
|
|
31
|
+
readonly box: SurfaceBox;
|
|
32
|
+
/** Its anchors and edits, said as data (for the capability catalog and the checks) */
|
|
33
|
+
readonly about: SurfaceAbout;
|
|
34
|
+
/** The box at a named place (see `about.anchors`), at `time` (default: after every edit) */
|
|
35
|
+
anchor(name: string, time?: number): SurfaceBox;
|
|
36
|
+
/** Make the part at a named place a piece that can come loose (the same piece each time it is asked for) */
|
|
37
|
+
piece(anchor: string): SurfacePiece;
|
|
38
|
+
/** Change the surface at a time: `name` is one of `about.edits`, `anchor` one place or several */
|
|
39
|
+
edit(name: string, anchor: string | string[], options: SurfaceEditOptions): Surface;
|
|
40
|
+
/** Carry a piece along a path of scene points (its centre follows them) */
|
|
41
|
+
follow(piece: SurfacePiece, path: TimedPoint[]): Surface;
|
|
42
|
+
/** Throw or kick a piece away: it flies on a ballistic arc, spinning, and fades */
|
|
43
|
+
fling(piece: SurfacePiece, options: FlingOptions): Surface;
|
|
44
|
+
/** Move a piece's centre to a scene point */
|
|
45
|
+
move(piece: SurfacePiece, options: EditOptions & {
|
|
46
|
+
to: {
|
|
47
|
+
x: number;
|
|
48
|
+
y: number;
|
|
49
|
+
};
|
|
50
|
+
}): Surface;
|
|
51
|
+
/** A figure's tracks with it carried along by what it stands on; `ground` is the script's `ground` */
|
|
52
|
+
ride(tracks: Track[], target: string, options: {
|
|
53
|
+
ground: number;
|
|
54
|
+
every?: number;
|
|
55
|
+
}): Track[];
|
|
56
|
+
/** The recorded edits as tracks on `target` (the surface's key in the scene) */
|
|
57
|
+
tracks(target: string): Track[];
|
|
58
|
+
}
|
|
59
|
+
/** An edit's options: when, plus what that edit takes (see `about.edits`). */
|
|
60
|
+
export type SurfaceEditOptions = EditOptions & Record<string, unknown>;
|
|
61
|
+
/** A surface's anchors and edits, as data. */
|
|
62
|
+
export interface SurfaceAbout {
|
|
63
|
+
kind: string;
|
|
64
|
+
/** How to make one */
|
|
65
|
+
create?: string;
|
|
66
|
+
/** Anchor patterns, such as `line:N`, and what each names */
|
|
67
|
+
anchors: Record<string, string>;
|
|
68
|
+
/** Edit names, with the anchors and options each takes */
|
|
69
|
+
edits: Record<string, string>;
|
|
70
|
+
}
|
|
71
|
+
/** An anchor name split into its kind and the rest: `token:7:Println` → `token`, `7:Println`. */
|
|
72
|
+
export declare function parseAnchor(name: string): {
|
|
73
|
+
kind: string;
|
|
74
|
+
rest: string;
|
|
75
|
+
};
|
|
76
|
+
/** The error for an anchor a surface does not have, naming the ones it does. */
|
|
77
|
+
export declare function anchorError(owner: string, name: string, about: SurfaceAbout, why?: string): Error;
|
|
78
|
+
/** The error for an edit a surface does not have. */
|
|
79
|
+
export declare function editError(owner: string, name: string, about: SurfaceAbout): Error;
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
import type { CustomTarget } from '../adapters/canvas/canvas-adapter';
|
|
2
|
+
import type { Track } from '../engine/types';
|
|
3
|
+
import { type EditOptions } from './surface/edit-log';
|
|
4
|
+
import { type FlingOptions, type SurfacePiece, type TimedPoint } from './surface/pieces';
|
|
5
|
+
import { type Surface, type SurfaceAbout, type SurfaceEditOptions } from './surface/surface';
|
|
6
|
+
import { type SurfaceBox } from './surface/surface-box';
|
|
7
|
+
/**
|
|
8
|
+
* A whiteboard (or a chalkboard) as a scene object figures act on: they
|
|
9
|
+
* write on it, circle and underline what matters, strike terms out, carry a
|
|
10
|
+
* term across the equals sign and erase it all.
|
|
11
|
+
*
|
|
12
|
+
* ```ts
|
|
13
|
+
* const board = whiteboard({
|
|
14
|
+
* x: 40, y: 30, width: 600, height: 340, theme: 'chalkboard',
|
|
15
|
+
* items: [
|
|
16
|
+
* { id: 'eq', text: '2x + 4 = 10', at: [60, 80] },
|
|
17
|
+
* { id: 'step', text: '2x = 6', at: [60, 160], hidden: true },
|
|
18
|
+
* { id: 'ring', mark: 'circle', around: 'term:eq:+ 4', hidden: true },
|
|
19
|
+
* ],
|
|
20
|
+
* })
|
|
21
|
+
* board.edit('draw', 'mark:ring', { at: 800 })
|
|
22
|
+
* board.edit('fling', 'term:eq:+ 4', { at: 1600 })
|
|
23
|
+
* board.edit('write', 'text:step', { at: 2400 })
|
|
24
|
+
* ```
|
|
25
|
+
*
|
|
26
|
+
* Everything on it is declared up front as plain data (`items`), so its
|
|
27
|
+
* places are known before anything plays. Text is laid out by arithmetic
|
|
28
|
+
* (each character a fixed `charWidth` em cell, drawn centred in it), never
|
|
29
|
+
* measured from a font, and marks get a hand-drawn wobble from a seed made
|
|
30
|
+
* of their id, so the same board is drawn the same everywhere. Items with
|
|
31
|
+
* `hidden: true` start unwritten (text) or undrawn (marks).
|
|
32
|
+
*
|
|
33
|
+
* Its places: `box`, `text:ID`, `term:ID:TEXT` (the first TEXT in that
|
|
34
|
+
* text; `term:ID#K:TEXT` for the Kth), `mark:ID`. A term can come loose as a
|
|
35
|
+
* piece. Edits are recorded as keys on its props (`text.ID.write`,
|
|
36
|
+
* `mark.ID.draw`, `strike.K.draw`, `piece.K.x`…) and written out by
|
|
37
|
+
* `tracks()`.
|
|
38
|
+
*/
|
|
39
|
+
export type BoardThemeName = 'whiteboard' | 'chalkboard';
|
|
40
|
+
export interface BoardTheme {
|
|
41
|
+
background: string;
|
|
42
|
+
frame: string;
|
|
43
|
+
/** The default colour of text and marks */
|
|
44
|
+
ink: string;
|
|
45
|
+
/** Named colours an item's `color` can use (any CSS colour works too) */
|
|
46
|
+
colors: Record<string, string>;
|
|
47
|
+
font: string;
|
|
48
|
+
/** Mark line width, as a fraction of the font size */
|
|
49
|
+
stroke: number;
|
|
50
|
+
/** Ink opacity (chalk is a little see-through) */
|
|
51
|
+
opacity: number;
|
|
52
|
+
}
|
|
53
|
+
export declare const BOARD_THEMES: Record<BoardThemeName, BoardTheme>;
|
|
54
|
+
/** The marks a board can draw. */
|
|
55
|
+
export type BoardMarkKind = 'circle' | 'box' | 'underline' | 'arrow';
|
|
56
|
+
export declare const BOARD_MARKS: readonly BoardMarkKind[];
|
|
57
|
+
/** Text on the board. */
|
|
58
|
+
export interface BoardText {
|
|
59
|
+
id: string;
|
|
60
|
+
text: string;
|
|
61
|
+
/** Its top-left corner, px from the board's top-left */
|
|
62
|
+
at: [number, number];
|
|
63
|
+
/** Font size, px (default the board's `fontSize`) */
|
|
64
|
+
size?: number;
|
|
65
|
+
/** A theme colour name (`red`, `blue`…) or any CSS colour (default the theme's ink) */
|
|
66
|
+
color?: string;
|
|
67
|
+
/** Start unwritten, to be written in with the `write` edit */
|
|
68
|
+
hidden?: boolean;
|
|
69
|
+
}
|
|
70
|
+
/** A hand-drawn mark: a circle, box or underline around a place, or an arrow from one place to another. */
|
|
71
|
+
export interface BoardMark {
|
|
72
|
+
id: string;
|
|
73
|
+
mark: BoardMarkKind;
|
|
74
|
+
/** `circle`, `box`, `underline`: the place it goes around (an item before it: `text:ID`, `term:ID:TEXT`, `mark:ID`) */
|
|
75
|
+
around?: string;
|
|
76
|
+
/** `arrow`: from one place to another */
|
|
77
|
+
from?: string;
|
|
78
|
+
to?: string;
|
|
79
|
+
color?: string;
|
|
80
|
+
/** Start undrawn, to be drawn in with the `draw` edit */
|
|
81
|
+
hidden?: boolean;
|
|
82
|
+
}
|
|
83
|
+
export type BoardItem = BoardText | BoardMark;
|
|
84
|
+
export interface WhiteboardOptions {
|
|
85
|
+
/** Top-left corner, scene px */
|
|
86
|
+
x: number;
|
|
87
|
+
y: number;
|
|
88
|
+
width: number;
|
|
89
|
+
height: number;
|
|
90
|
+
theme?: BoardThemeName | Partial<BoardTheme>;
|
|
91
|
+
/** px (default 28) */
|
|
92
|
+
fontSize?: number;
|
|
93
|
+
/** Width of a character cell, em (default 0.55) */
|
|
94
|
+
charWidth?: number;
|
|
95
|
+
items?: BoardItem[];
|
|
96
|
+
}
|
|
97
|
+
/** A term that can come loose from its text: made by `piece()`. */
|
|
98
|
+
export interface BoardPiece extends SurfacePiece {
|
|
99
|
+
readonly text: string;
|
|
100
|
+
/** The text item it is part of, and where in it */
|
|
101
|
+
readonly item: string;
|
|
102
|
+
readonly column: number;
|
|
103
|
+
}
|
|
104
|
+
export interface Whiteboard extends Surface {
|
|
105
|
+
readonly kind: 'board';
|
|
106
|
+
readonly target: CustomTarget;
|
|
107
|
+
readonly box: SurfaceBox;
|
|
108
|
+
/** The box at a named place: `box`, `text:ID`, `term:ID:TEXT` (`term:ID#K:TEXT` for the Kth), `mark:ID` */
|
|
109
|
+
anchor(name: string, time?: number): SurfaceBox;
|
|
110
|
+
/** Make the term at a `term:` place a piece that can come loose */
|
|
111
|
+
piece(anchor: string): BoardPiece;
|
|
112
|
+
/** Change the board at a time by name, at named places (see `WHITEBOARD_SURFACE.edits`) */
|
|
113
|
+
edit(name: string, anchor: string | string[], options: SurfaceEditOptions): Whiteboard;
|
|
114
|
+
follow(piece: SurfacePiece, path: TimedPoint[]): Whiteboard;
|
|
115
|
+
fling(piece: SurfacePiece, options: FlingOptions): Whiteboard;
|
|
116
|
+
move(piece: SurfacePiece, options: EditOptions & {
|
|
117
|
+
to: {
|
|
118
|
+
x: number;
|
|
119
|
+
y: number;
|
|
120
|
+
};
|
|
121
|
+
}): Whiteboard;
|
|
122
|
+
/** A board has nothing to stand on that moves: the tracks come back as they are */
|
|
123
|
+
ride(tracks: Track[], target: string, options: {
|
|
124
|
+
ground: number;
|
|
125
|
+
every?: number;
|
|
126
|
+
}): Track[];
|
|
127
|
+
tracks(target: string): Track[];
|
|
128
|
+
}
|
|
129
|
+
/** A board's anchors and edits, as data: for its `about`, the capability catalog and the checks. */
|
|
130
|
+
export declare const WHITEBOARD_SURFACE: SurfaceAbout;
|
|
131
|
+
export declare function whiteboard(options: WhiteboardOptions): Whiteboard;
|
|
@@ -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;
|