@algorisys/tinyfly 0.95.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 +5 -5
- package/docs/acting.md +165 -0
- 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 +24 -2
- package/docs/maps.md +2 -2
- package/docs/teaching.md +1 -1
- package/lib/addons/characters.js +4517 -3582
- package/lib/browser/tinyfly.iife.js +16 -14
- package/lib/browser/tinyfly.js +5788 -4853
- package/lib/browser/tinyfly.umd.js +16 -14
- 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 +5 -0
- package/lib/types/characters/chart.d.ts +108 -0
- package/lib/types/characters/code-panel.d.ts +21 -46
- package/lib/types/characters/index.d.ts +3 -0
- package/lib/types/characters/props/index.d.ts +1 -0
- package/lib/types/characters/props/prop-surface.d.ts +63 -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/llms-full.txt +279 -10
- package/llms.txt +28 -28
- package/package.json +1 -1
- package/skills/tinyfly/SKILL.md +29 -9
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
import type { Track } from '../../engine/types';
|
|
2
|
+
import type { StickStyle } from '../stick-figure';
|
|
3
|
+
import type { Surface } from '../surface/surface';
|
|
4
|
+
import { type BeatProblem } from './beat-check';
|
|
5
|
+
import { type Cast } from './custom';
|
|
6
|
+
import { type Beat, type BeatTarget, type ScriptOptions, type ScriptResult } from './script';
|
|
7
|
+
/**
|
|
8
|
+
* A figure acting on surfaces, written as plain data: beats name the places
|
|
9
|
+
* they act on (`{ surface: 'code', anchor: 'token:4:Println' }`) and say what
|
|
10
|
+
* the surface does in answer (`then`), at a moment of the beat.
|
|
11
|
+
*
|
|
12
|
+
* ```ts
|
|
13
|
+
* const result = surfaceScript('hero', { code }, [
|
|
14
|
+
* { do: 'leap', to: { surface: 'code', anchor: 'line:4' }, onto: { surface: 'code', anchor: 'line:5' } },
|
|
15
|
+
* { do: 'grab', target: { surface: 'code', anchor: 'token:4:Println' },
|
|
16
|
+
* then: { surface: 'code', edit: 'carry', anchor: 'token:4:Println', until: { beat: 2, at: 'release' } } },
|
|
17
|
+
* { do: 'throw', then: { surface: 'code', edit: 'fling', anchor: 'token:4:Println', at: 'release' } },
|
|
18
|
+
* ], { from: 600, ground: code.box.bottom })
|
|
19
|
+
* const timeline = { tracks: result.tracks } // the figure's tracks and every surface's
|
|
20
|
+
* ```
|
|
21
|
+
*
|
|
22
|
+
* It compiles to the same calls written by hand: the beats go to
|
|
23
|
+
* `scriptTracks` with each named place swapped for its box (as laid out,
|
|
24
|
+
* before any edit moves it), then each `then` runs `surface.edit()` at its
|
|
25
|
+
* beat's moment, in the order the beats are written. A `carry` makes the
|
|
26
|
+
* piece follow the figure's hand (`handPath`). Last, the figure is carried
|
|
27
|
+
* by any surface it stands on (`surface.ride()`), unless `ride: false`.
|
|
28
|
+
*/
|
|
29
|
+
/** A named place on one of the scene's surfaces (`surfaces[surface].anchor(anchor)`). */
|
|
30
|
+
export interface SurfaceRef {
|
|
31
|
+
surface: string;
|
|
32
|
+
anchor: string;
|
|
33
|
+
}
|
|
34
|
+
/** A moment of a beat: when it starts, when it touches its target, when it lets go, when it ends. */
|
|
35
|
+
export type BeatMoment = 'start' | 'contact' | 'release' | 'end';
|
|
36
|
+
export declare const BEAT_MOMENTS: readonly BeatMoment[];
|
|
37
|
+
/** A moment of this beat, or of a later one (`beat` is its index in the script). */
|
|
38
|
+
export type CueTime = BeatMoment | {
|
|
39
|
+
beat: number;
|
|
40
|
+
at?: BeatMoment;
|
|
41
|
+
};
|
|
42
|
+
/**
|
|
43
|
+
* What a surface does in answer to a beat: one of its edits (or `carry`),
|
|
44
|
+
* at one of its places. Every other field is the edit's own options (`text`,
|
|
45
|
+
* `into`, `to`, `style`…). Its time is a moment of the beat, not ms.
|
|
46
|
+
*/
|
|
47
|
+
export interface SurfaceCue {
|
|
48
|
+
surface: string;
|
|
49
|
+
/** One of the surface's edits, or `carry`: the piece at `anchor` follows the hand from `at` to `until` */
|
|
50
|
+
edit: string;
|
|
51
|
+
anchor: string | string[];
|
|
52
|
+
/** When it starts: a moment of the beat (default its contact, or its start when it has none) */
|
|
53
|
+
at?: BeatMoment;
|
|
54
|
+
/** When it ends: sets the edit's duration (`carry` needs it) */
|
|
55
|
+
until?: CueTime;
|
|
56
|
+
[option: string]: unknown;
|
|
57
|
+
}
|
|
58
|
+
/** A beat whose places can be named on a surface, and that a surface can answer. */
|
|
59
|
+
export interface SurfaceBeat extends Omit<Beat, 'target' | 'to' | 'onto'> {
|
|
60
|
+
/** What it acts on: a point or box, or a named place */
|
|
61
|
+
target?: BeatTarget | SurfaceRef;
|
|
62
|
+
/** Walking: where to, scene x, or a named place (its centre x) */
|
|
63
|
+
to?: number | SurfaceRef;
|
|
64
|
+
/** The floor it ends the beat on, scene y, or a named place (its top) */
|
|
65
|
+
onto?: number | SurfaceRef;
|
|
66
|
+
/** What the surfaces do in answer */
|
|
67
|
+
then?: SurfaceCue | SurfaceCue[];
|
|
68
|
+
}
|
|
69
|
+
export interface SurfaceScriptOptions extends ScriptOptions {
|
|
70
|
+
/** How the figure is drawn, for a `carry` to follow its hand (default: just its `height`) */
|
|
71
|
+
figureStyle?: StickStyle;
|
|
72
|
+
/** Carry the figure on the surfaces it stands on (default true) */
|
|
73
|
+
ride?: boolean;
|
|
74
|
+
}
|
|
75
|
+
export interface SurfaceScriptResult extends ScriptResult {
|
|
76
|
+
/** The figure's tracks (ridden), then every surface's tracks, keyed by its name in `surfaces` */
|
|
77
|
+
tracks: Track[];
|
|
78
|
+
/** Just the figure's tracks (ridden) */
|
|
79
|
+
figureTracks: Track[];
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Compile beats that act on surfaces into the figure's tracks and the
|
|
83
|
+
* surfaces' edits. Throws when a beat or a cue is wrong (see
|
|
84
|
+
* `checkSurfaceBeats`), naming the beat.
|
|
85
|
+
*/
|
|
86
|
+
export declare function surfaceScript(figure: string, surfaces: Record<string, Surface>, beats: SurfaceBeat[], options?: SurfaceScriptOptions): SurfaceScriptResult;
|
|
87
|
+
/**
|
|
88
|
+
* Problems in beats that act on surfaces: everything `checkBeats` finds,
|
|
89
|
+
* plus surfaces, places, edits and moments that do not exist (with the
|
|
90
|
+
* likely intended name). Errors make `surfaceScript` throw.
|
|
91
|
+
*/
|
|
92
|
+
export declare function checkSurfaceBeats(beats: unknown, surfaces: Record<string, Surface>, cast?: Cast): BeatProblem[];
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { type PropertyInfo } from '../adapters/canvas/target-properties';
|
|
2
|
+
import type { SurfaceAbout } from './surface/surface';
|
|
2
3
|
import type { Cast } from './acting/custom';
|
|
3
4
|
export interface Capabilities {
|
|
4
5
|
version?: string;
|
|
@@ -68,6 +69,10 @@ export interface Capabilities {
|
|
|
68
69
|
anchors: Record<string, string>;
|
|
69
70
|
edits: Record<string, string>;
|
|
70
71
|
};
|
|
72
|
+
/** Surfaces figures act on, by kind: their named anchors and edits (`surface.anchor(name)`, `surface.edit(name, anchor, options)`) */
|
|
73
|
+
surfaces: Record<string, SurfaceAbout>;
|
|
74
|
+
/** Beats that act on surfaces (`surfaceScript`): named places and the cues surfaces answer with */
|
|
75
|
+
surfaceScript: Record<string, string>;
|
|
71
76
|
cameraShots: Record<string, string>;
|
|
72
77
|
teach: Record<string, string>;
|
|
73
78
|
cli: Record<string, string>;
|
|
@@ -0,0 +1,108 @@
|
|
|
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 bar or line chart as a scene object figures act on: they point at a
|
|
9
|
+
* bar, highlight the dip, and stand on a bar as it grows.
|
|
10
|
+
*
|
|
11
|
+
* ```ts
|
|
12
|
+
* const sales = chart({
|
|
13
|
+
* x: 40, y: 30, width: 420, height: 280, kind: 'bar', title: 'Sales',
|
|
14
|
+
* data: [
|
|
15
|
+
* { id: 'q1', label: 'Q1', value: 40 },
|
|
16
|
+
* { id: 'q2', label: 'Q2', value: 25 },
|
|
17
|
+
* { id: 'q3', label: 'Q3', value: 55, hidden: true },
|
|
18
|
+
* ],
|
|
19
|
+
* })
|
|
20
|
+
* sales.edit('highlight', 'bar:q2', { at: 600 })
|
|
21
|
+
* sales.edit('show', 'bar:q3', { at: 1200 }) // grows in from the axis
|
|
22
|
+
* sales.edit('set', 'bar:q1', { at: 2000, value: 80 }) // and its value label counts up
|
|
23
|
+
* ```
|
|
24
|
+
*
|
|
25
|
+
* The data is declared up front; the scale (`max`) is fixed when it is made
|
|
26
|
+
* (from the data, or given), so a bar set past it grows out of the plot.
|
|
27
|
+
* Its places follow the values: `anchor('bar:q1', time)` is the bar as it
|
|
28
|
+
* stands at `time` (default: after every edit; a surface script aims beats
|
|
29
|
+
* at it as laid out). A figure standing on a bar's top is carried up and
|
|
30
|
+
* down with it (`ride()`). Edits are keys on its props: `bar.ID.value`,
|
|
31
|
+
* `bar.ID.show`, `bar.ID.highlight` (or `point.ID.…` on a line chart).
|
|
32
|
+
*/
|
|
33
|
+
export type ChartKind = 'bar' | 'line';
|
|
34
|
+
export declare const CHART_KINDS: readonly ChartKind[];
|
|
35
|
+
export type ChartThemeName = 'light' | 'dark';
|
|
36
|
+
export interface ChartTheme {
|
|
37
|
+
background: string;
|
|
38
|
+
text: string;
|
|
39
|
+
/** Axis and grid lines */
|
|
40
|
+
grid: string;
|
|
41
|
+
/** Bars, the line and its points */
|
|
42
|
+
color: string;
|
|
43
|
+
/** A highlighted bar or point */
|
|
44
|
+
highlight: string;
|
|
45
|
+
font: string;
|
|
46
|
+
}
|
|
47
|
+
export declare const CHART_THEMES: Record<ChartThemeName, ChartTheme>;
|
|
48
|
+
/** One bar or point. */
|
|
49
|
+
export interface ChartDatum {
|
|
50
|
+
id: string;
|
|
51
|
+
/** Under it, on the axis (default its id) */
|
|
52
|
+
label?: string;
|
|
53
|
+
value: number;
|
|
54
|
+
/** Start at nothing: a bar flat on the axis, a point the line has not reached; brought in with `show` */
|
|
55
|
+
hidden?: boolean;
|
|
56
|
+
}
|
|
57
|
+
export interface ChartOptions {
|
|
58
|
+
/** Top-left corner, scene px */
|
|
59
|
+
x: number;
|
|
60
|
+
y: number;
|
|
61
|
+
width: number;
|
|
62
|
+
height: number;
|
|
63
|
+
kind: ChartKind;
|
|
64
|
+
data: ChartDatum[];
|
|
65
|
+
/** The value at the top of the plot (default: a round number above the largest value) */
|
|
66
|
+
max?: number;
|
|
67
|
+
title?: string;
|
|
68
|
+
theme?: ChartThemeName | Partial<ChartTheme>;
|
|
69
|
+
/** Value labels: decimal places (default 0), and text before and after the number */
|
|
70
|
+
decimals?: number;
|
|
71
|
+
prefix?: string;
|
|
72
|
+
suffix?: string;
|
|
73
|
+
/** Show each value above its bar or point (default true) */
|
|
74
|
+
values?: boolean;
|
|
75
|
+
}
|
|
76
|
+
export interface Chart extends Surface {
|
|
77
|
+
readonly kind: 'chart';
|
|
78
|
+
readonly chartKind: ChartKind;
|
|
79
|
+
readonly target: CustomTarget;
|
|
80
|
+
readonly box: SurfaceBox;
|
|
81
|
+
/** The value at the top of the plot */
|
|
82
|
+
readonly max: number;
|
|
83
|
+
/** The box at a named place, as it stands at `time`: `box`, `bar:ID` or `point:ID`, `label:ID`, `value:ID` */
|
|
84
|
+
anchor(name: string, time?: number): SurfaceBox;
|
|
85
|
+
/** A chart has no pieces: this throws */
|
|
86
|
+
piece(anchor: string): SurfacePiece;
|
|
87
|
+
/** Change the chart at a time by name, at named places (see `CHART_SURFACE.edits`) */
|
|
88
|
+
edit(name: string, anchor: string | string[], options: SurfaceEditOptions): Chart;
|
|
89
|
+
follow(piece: SurfacePiece, path: TimedPoint[]): Chart;
|
|
90
|
+
fling(piece: SurfacePiece, options: FlingOptions): Chart;
|
|
91
|
+
move(piece: SurfacePiece, options: EditOptions & {
|
|
92
|
+
to: {
|
|
93
|
+
x: number;
|
|
94
|
+
y: number;
|
|
95
|
+
};
|
|
96
|
+
}): Chart;
|
|
97
|
+
/** A figure's tracks with it carried up and down by the bar it stands on */
|
|
98
|
+
ride(tracks: Track[], target: string, options: {
|
|
99
|
+
ground: number;
|
|
100
|
+
every?: number;
|
|
101
|
+
}): Track[];
|
|
102
|
+
tracks(target: string): Track[];
|
|
103
|
+
}
|
|
104
|
+
/** A chart's anchors and edits, as data: for its `about`, the capability catalog and the checks. */
|
|
105
|
+
export declare const CHART_SURFACE: SurfaceAbout;
|
|
106
|
+
export declare function chart(options: ChartOptions): Chart;
|
|
107
|
+
/** The smallest of 1, 2, 2.5, 5 × a power of ten at or above `value`. */
|
|
108
|
+
export declare function niceCeiling(value: number): number;
|
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
import type { CustomTarget } from '../adapters/canvas/canvas-adapter';
|
|
2
|
-
import type {
|
|
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';
|
|
3
7
|
/**
|
|
4
8
|
* A code listing as a scene object characters can act on: they stand on its
|
|
5
9
|
* lines, point at its tokens and swipe lines away.
|
|
@@ -66,23 +70,9 @@ export interface CodePanelOptions {
|
|
|
66
70
|
theme?: Partial<CodeTheme>;
|
|
67
71
|
}
|
|
68
72
|
/** A place on the panel, scene px. Stand on `top`; point at `x`, `y` (the centre). */
|
|
69
|
-
export
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
left: number;
|
|
73
|
-
right: number;
|
|
74
|
-
top: number;
|
|
75
|
-
bottom: number;
|
|
76
|
-
width: number;
|
|
77
|
-
height: number;
|
|
78
|
-
}
|
|
79
|
-
export interface CodeEditOptions {
|
|
80
|
-
/** When the edit starts, ms */
|
|
81
|
-
at: number;
|
|
82
|
-
/** ms (default 300) */
|
|
83
|
-
duration?: number;
|
|
84
|
-
easing?: EasingType;
|
|
85
|
-
}
|
|
73
|
+
export type CodeBox = SurfaceBox;
|
|
74
|
+
export type CodeEditOptions = EditOptions;
|
|
75
|
+
export type { TimedPoint };
|
|
86
76
|
/** How a removed line goes: wiped away, knocked off the panel, or out of focus. */
|
|
87
77
|
export type CodeRemoveStyle = 'wipe' | 'fly' | 'blur';
|
|
88
78
|
export declare const REMOVE_STYLES: readonly CodeRemoveStyle[];
|
|
@@ -94,38 +84,15 @@ export interface CodeRemoveOptions extends CodeEditOptions {
|
|
|
94
84
|
/** How long the lines below take to close the gap, ms (default 250) */
|
|
95
85
|
close?: number;
|
|
96
86
|
}
|
|
97
|
-
/** A word that can come loose from its line: made by `piece()`. */
|
|
98
|
-
export interface CodePiece {
|
|
99
|
-
/** Its key in the panel's props (`piece.K.x`…) */
|
|
100
|
-
readonly id: number;
|
|
87
|
+
/** A word that can come loose from its line: made by `piece()`. Its `home` is where it sits in its line. */
|
|
88
|
+
export interface CodePiece extends SurfacePiece {
|
|
101
89
|
readonly line: number;
|
|
102
90
|
readonly column: number;
|
|
103
91
|
readonly text: string;
|
|
104
|
-
/** Where it sits in its line */
|
|
105
|
-
readonly home: CodeBox;
|
|
106
|
-
}
|
|
107
|
-
/** A point at a time, scene px: a path for a piece to follow (see `handPath`). */
|
|
108
|
-
export interface TimedPoint {
|
|
109
|
-
time: number;
|
|
110
|
-
x: number;
|
|
111
|
-
y: number;
|
|
112
|
-
}
|
|
113
|
-
export interface CodeFlingOptions {
|
|
114
|
-
/** When it leaves, ms */
|
|
115
|
-
at: number;
|
|
116
|
-
/** px/ms (default: how fast it was moving along its `follow` path at `at`, or up and to the right) */
|
|
117
|
-
velocity?: {
|
|
118
|
-
x: number;
|
|
119
|
-
y: number;
|
|
120
|
-
};
|
|
121
|
-
/** Turns, degrees per ms (default 0.6, signed by the throw's direction) */
|
|
122
|
-
spin?: number;
|
|
123
|
-
/** px/ms² (default 0.0016) */
|
|
124
|
-
gravity?: number;
|
|
125
|
-
/** How long it flies before it is gone, ms (default 900) */
|
|
126
|
-
duration?: number;
|
|
127
92
|
}
|
|
128
|
-
export
|
|
93
|
+
export type CodeFlingOptions = FlingOptions;
|
|
94
|
+
export interface CodePanel extends Surface {
|
|
95
|
+
readonly kind: 'code';
|
|
129
96
|
/** The canvas target that draws the panel; put it in the scene's targets */
|
|
130
97
|
readonly target: CustomTarget;
|
|
131
98
|
readonly lines: readonly string[];
|
|
@@ -147,6 +114,12 @@ export interface CodePanel {
|
|
|
147
114
|
type(n: number, options: CodeEditOptions): CodePanel;
|
|
148
115
|
/** Make the `occurrence`th `text` on line `n` a piece that can come loose */
|
|
149
116
|
piece(n: number, text: string, occurrence?: number): CodePiece;
|
|
117
|
+
/** Make the word at a token anchor (`token:7:Println`) a piece that can come loose */
|
|
118
|
+
piece(anchor: string): CodePiece;
|
|
119
|
+
/** The box at a named place: `box`, `line:N`, `token:N:TEXT` (`token:N#K:TEXT` for the Kth), `spot:N:C` or `spot:N:C:W` */
|
|
120
|
+
anchor(name: string, time?: number): CodeBox;
|
|
121
|
+
/** Change the panel at a time by name, at named places (see `CODE_SURFACE.edits`): `edit('highlight', 'line:4', { at: 1200 })` */
|
|
122
|
+
edit(name: string, anchor: string | string[], options: SurfaceEditOptions): CodePanel;
|
|
150
123
|
/** Carry a piece along a path of scene points (its centre follows them) */
|
|
151
124
|
follow(piece: CodePiece, path: TimedPoint[]): CodePanel;
|
|
152
125
|
/** Throw or kick a piece away: it flies on a ballistic arc, spinning, and fades */
|
|
@@ -188,6 +161,8 @@ export interface CodePanel {
|
|
|
188
161
|
/** The recorded edits as tracks on `target` (the panel's key in the scene) */
|
|
189
162
|
tracks(target: string): Track[];
|
|
190
163
|
}
|
|
164
|
+
/** A code panel's anchors and edits, as data: for its `about`, the capability catalog and the checks. */
|
|
165
|
+
export declare const CODE_SURFACE: SurfaceAbout;
|
|
191
166
|
export declare function codePanel(options: CodePanelOptions): CodePanel;
|
|
192
167
|
/** What a code panel's methods do, for its `about` and the capability catalog. */
|
|
193
168
|
export declare const CODE_PANEL_EDITS: Record<string, string>;
|
|
@@ -17,6 +17,9 @@ export * from '../adapters/canvas/sketch';
|
|
|
17
17
|
export * from '../adapters/canvas/camera';
|
|
18
18
|
export * from './erase';
|
|
19
19
|
export * from './code-panel';
|
|
20
|
+
export * from './whiteboard';
|
|
21
|
+
export * from './chart';
|
|
22
|
+
export * from './surface';
|
|
20
23
|
export * from '../adapters/canvas/polyline';
|
|
21
24
|
export * from './hand';
|
|
22
25
|
export * from './character';
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import type { Track } from '../../engine/types';
|
|
2
|
+
import { type EditOptions } from '../surface/edit-log';
|
|
3
|
+
import { type FlingOptions, type SurfacePiece, type TimedPoint } from '../surface/pieces';
|
|
4
|
+
import { type Surface, type SurfaceAbout, type SurfaceEditOptions } from '../surface/surface';
|
|
5
|
+
import { type SurfaceBox } from '../surface/surface-box';
|
|
6
|
+
import { type PropTarget } from './target';
|
|
7
|
+
/**
|
|
8
|
+
* A prop as a surface: its state is something a figure changes. A figure
|
|
9
|
+
* opens the car's door, switches the house's lights on, shakes the tree.
|
|
10
|
+
*
|
|
11
|
+
* ```ts
|
|
12
|
+
* const car = propTarget({ x: 300, y: 380, prop: carPreset() })
|
|
13
|
+
* const carSurface = propSurface(car)
|
|
14
|
+
* carSurface.anchor('control:door') // where the door is
|
|
15
|
+
* carSurface.edit('switch', 'control:door', { at: 1200 }) // opens it
|
|
16
|
+
* carSurface.edit('switch', 'control:lights', { at: 2000, on: false })
|
|
17
|
+
*
|
|
18
|
+
* surfaceScript('hero', { car: carSurface }, [
|
|
19
|
+
* { do: 'grab', target: { surface: 'car', anchor: 'control:door' },
|
|
20
|
+
* then: { surface: 'car', edit: 'switch', anchor: 'control:door', until: 'end' } },
|
|
21
|
+
* ])
|
|
22
|
+
* ```
|
|
23
|
+
*
|
|
24
|
+
* Its places: `anchor:NAME` (one of the rig's anchors, as posed),
|
|
25
|
+
* `part:ID` (one of its parts, as seen: `window-1`, `wheel-0-left`),
|
|
26
|
+
* `control:NAME` (where the parts that control moves or lights are), and
|
|
27
|
+
* `box`. They are worked out at a time from the prop's values then: its
|
|
28
|
+
* starting values, the edits made here, and the prop's own tracks when it is
|
|
29
|
+
* scripted too (`tracks`, from its `propScript`), so the places follow a car
|
|
30
|
+
* that drives off. Edits are keys on its controls, written out by `tracks()`
|
|
31
|
+
* on the prop target's id. Do not key a control both here and in its own
|
|
32
|
+
* script: the later track wins.
|
|
33
|
+
*/
|
|
34
|
+
export interface PropSurfaceOptions {
|
|
35
|
+
/** The prop's own tracks (its `propScript` result), so its places follow it as it moves */
|
|
36
|
+
tracks?: Track[];
|
|
37
|
+
}
|
|
38
|
+
export interface PropSurface extends Surface {
|
|
39
|
+
readonly kind: 'prop';
|
|
40
|
+
readonly prop: PropTarget;
|
|
41
|
+
/** The box at a named place, at `time` (default: after every edit): `box`, `anchor:NAME`, `part:ID`, `control:NAME` */
|
|
42
|
+
anchor(name: string, time?: number): SurfaceBox;
|
|
43
|
+
/** A prop has no pieces: this throws */
|
|
44
|
+
piece(anchor: string): SurfacePiece;
|
|
45
|
+
/** Change the prop at a time: `set` a control to a value, or `switch` it on (open) or off (shut) */
|
|
46
|
+
edit(name: string, anchor: string | string[], options: SurfaceEditOptions): PropSurface;
|
|
47
|
+
follow(piece: SurfacePiece, path: TimedPoint[]): PropSurface;
|
|
48
|
+
fling(piece: SurfacePiece, options: FlingOptions): PropSurface;
|
|
49
|
+
move(piece: SurfacePiece, options: EditOptions & {
|
|
50
|
+
to: {
|
|
51
|
+
x: number;
|
|
52
|
+
y: number;
|
|
53
|
+
};
|
|
54
|
+
}): PropSurface;
|
|
55
|
+
/** Nothing on a prop carries a figure yet: the tracks come back as they are */
|
|
56
|
+
ride(tracks: Track[], target: string, options: {
|
|
57
|
+
ground: number;
|
|
58
|
+
every?: number;
|
|
59
|
+
}): Track[];
|
|
60
|
+
tracks(target: string): Track[];
|
|
61
|
+
}
|
|
62
|
+
export declare const PROP_SURFACE: SurfaceAbout;
|
|
63
|
+
export declare function propSurface(target: PropTarget, options?: PropSurfaceOptions): PropSurface;
|
|
@@ -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;
|