procedural-bot-animations 0.0.0-stage → 0.2.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 (47) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +202 -2
  3. package/dist/animation.d.ts +90 -0
  4. package/dist/animation.js +396 -0
  5. package/dist/brain.d.ts +198 -0
  6. package/dist/brain.js +581 -0
  7. package/dist/character.d.ts +123 -0
  8. package/dist/character.js +916 -0
  9. package/dist/characters/berry.d.ts +2 -0
  10. package/dist/characters/berry.js +38 -0
  11. package/dist/characters/flame.d.ts +2 -0
  12. package/dist/characters/flame.js +46 -0
  13. package/dist/delta.d.ts +16 -0
  14. package/dist/delta.js +146 -0
  15. package/dist/examples.d.ts +4 -0
  16. package/dist/examples.js +208 -0
  17. package/dist/focus.d.ts +46 -0
  18. package/dist/focus.js +284 -0
  19. package/dist/gaze.d.ts +48 -0
  20. package/dist/gaze.js +133 -0
  21. package/dist/index.d.ts +21 -0
  22. package/dist/index.js +21 -0
  23. package/dist/interactions.d.ts +30 -0
  24. package/dist/interactions.js +100 -0
  25. package/dist/library.d.ts +18 -0
  26. package/dist/library.js +14 -0
  27. package/dist/moods.d.ts +80 -0
  28. package/dist/moods.js +51 -0
  29. package/dist/motion.d.ts +93 -0
  30. package/dist/motion.js +167 -0
  31. package/dist/mount.d.ts +90 -0
  32. package/dist/mount.js +707 -0
  33. package/dist/parts.d.ts +36 -0
  34. package/dist/parts.js +131 -0
  35. package/dist/reactions.d.ts +184 -0
  36. package/dist/reactions.js +1855 -0
  37. package/dist/rig.d.ts +119 -0
  38. package/dist/rig.js +59 -0
  39. package/dist/scroll-traveler.d.ts +41 -0
  40. package/dist/scroll-traveler.js +43 -0
  41. package/dist/state-machine.d.ts +49 -0
  42. package/dist/state-machine.js +68 -0
  43. package/dist/ticker.d.ts +10 -0
  44. package/dist/ticker.js +42 -0
  45. package/dist/transformations.d.ts +21 -0
  46. package/dist/transformations.js +306 -0
  47. package/package.json +51 -4
package/dist/rig.d.ts ADDED
@@ -0,0 +1,119 @@
1
+ export type Point = {
2
+ x: number;
3
+ y: number;
4
+ };
5
+ /** Role of the appendage: the middle one (C), the left one (L) and the right one (R). */
6
+ export type Role = "C" | "L" | "R";
7
+ /** A leaf or a flame tongue: a piece attached to the body that rotates and bends. */
8
+ export type Appendage = {
9
+ role: Role;
10
+ path: string;
11
+ pivot: Point;
12
+ tip: Point;
13
+ };
14
+ export type EyeStyle = "classic" | "pumpy" | "big";
15
+ export declare const EYE_STYLES: EyeStyle[];
16
+ /**
17
+ * Resting shape of the eye: a `w × h` pill (fully rounded corners), tilted
18
+ * `tilt` degrees (the same direction on both eyes, like italics) and shifted
19
+ * `dx`/`dy` from the base point. `dx` is mirrored: positive brings the eyes closer.
20
+ */
21
+ export type EyeShape = {
22
+ w: number;
23
+ h: number;
24
+ tilt: number;
25
+ dx: number;
26
+ dy: number;
27
+ };
28
+ export type Rig = {
29
+ id: string;
30
+ body: string;
31
+ appendages: Appendage[];
32
+ eyes: {
33
+ left: Point;
34
+ right: Point;
35
+ };
36
+ eyeStyles: Record<EyeStyle, EyeShape>;
37
+ ground: Point;
38
+ center: Point;
39
+ shadow: {
40
+ x: number;
41
+ y: number;
42
+ rx: number;
43
+ ry: number;
44
+ };
45
+ accessory: Point;
46
+ /**
47
+ * Center of the transformations: the body becomes a circle of radius
48
+ * `ROUND_RADIUS` around it (resting on the ground) and objects are born there.
49
+ */
50
+ anchor: Point;
51
+ /** Distance from the ground to the base of the appendages (for the tip physics). */
52
+ baseHeight: number;
53
+ /** Idle sway of the appendages: multiplies amplitude and frequency. */
54
+ idleAppendage: {
55
+ amp: number;
56
+ freq: number;
57
+ };
58
+ /** 0 = firm body; 1 = the body flickers like fire. */
59
+ flicker: number;
60
+ /** Optional light core (the 1000-day flame). */
61
+ core?: string;
62
+ };
63
+ export declare const VIEWBOX: {
64
+ readonly x: 190;
65
+ readonly y: 60;
66
+ readonly w: 880;
67
+ readonly h: 990;
68
+ };
69
+ export declare const VIEWBOX_ATTR: string;
70
+ export declare const ASPECT: number;
71
+ /** Happy arc-shaped eye (^), for an eye of width 80 centered at (0,0). */
72
+ export declare const HAPPY_EYE_PATH = "M-50,26 C-36,-38 36,-38 50,26 C34,4 -34,4 -50,26 Z";
73
+ /** Sparks of a hit: 8 directions, alternating distance and color. */
74
+ export declare const SPARKS: {
75
+ dx: number;
76
+ dy: number;
77
+ alt: boolean;
78
+ }[];
79
+ export declare const SPARK_PATH = "M0,-20 L7,-7 L20,0 L7,7 L0,20 L-7,7 L-20,0 L-7,-7Z";
80
+ /** Radius of the circle the body turns into (ground at y = 960, anchor at 660). */
81
+ export declare const ROUND_RADIUS = 300;
82
+ /** Radius of the bubble the body shrinks into and objects are born from. */
83
+ export declare const DOT_R = 36;
84
+ /** Scale of the round body when its radius is exactly the bubble's. */
85
+ export declare const DOT_SCALE: number;
86
+ /** Loading ring: outer radius and hole (46 px stroke). */
87
+ export declare const RING: {
88
+ readonly R: 133;
89
+ readonly hole: 87;
90
+ };
91
+ /**
92
+ * Check mark, relative to the anchor. The stroke is as wide as the bubble, so
93
+ * the start of the round-capped check is the bubble itself.
94
+ */
95
+ export declare const CHECK: {
96
+ readonly start: {
97
+ readonly x: -130;
98
+ readonly y: -10;
99
+ };
100
+ readonly path: "M-130,-10 L-45,75 L135,-105";
101
+ readonly length: number;
102
+ readonly width: number;
103
+ };
104
+ /**
105
+ * `</>`: each stroke is born at one of the three dots (the vertex of the <,
106
+ * the middle of the slash, the vertex of the >). Width 50 = the dots' diameter
107
+ * at that moment.
108
+ */
109
+ export declare const CODE: {
110
+ readonly dist: 170;
111
+ readonly radius: 25;
112
+ readonly strokes: readonly ["M-170,0 L-95,-75", "M-170,0 L-95,75", "M0,0 L38,-105", "M0,0 L-38,105", "M170,0 L95,-75", "M170,0 L95,75"];
113
+ readonly lengths: readonly [106.1, 106.1, 111.7, 111.7, 106.1, 106.1];
114
+ };
115
+ /** Energy orbit: full radius and radius of each dot. */
116
+ export declare const ORBIT: {
117
+ readonly R: 300;
118
+ readonly radii: readonly [26, 18, 26, 18, 26, 18, 26, 18];
119
+ };
package/dist/rig.js ADDED
@@ -0,0 +1,59 @@
1
+ /*
2
+ * Rigs: the geometry of each character, separate from the motion engine. All
3
+ * characters share one coordinate system (ground at y = 960, center at
4
+ * x ≈ 627) and one viewBox, so reactions, accessories and objects work for
5
+ * every one of them.
6
+ */
7
+ export const EYE_STYLES = ["classic", "pumpy", "big"];
8
+ export const VIEWBOX = { x: 190, y: 60, w: 880, h: 990 };
9
+ export const VIEWBOX_ATTR = `${VIEWBOX.x} ${VIEWBOX.y} ${VIEWBOX.w} ${VIEWBOX.h}`;
10
+ export const ASPECT = VIEWBOX.h / VIEWBOX.w;
11
+ /** Happy arc-shaped eye (^), for an eye of width 80 centered at (0,0). */
12
+ export const HAPPY_EYE_PATH = "M-50,26 C-36,-38 36,-38 50,26 C34,4 -34,4 -50,26 Z";
13
+ /* ---------- effects ---------- */
14
+ /** Sparks of a hit: 8 directions, alternating distance and color. */
15
+ export const SPARKS = Array.from({ length: 8 }, (_, i) => {
16
+ const a = (i * Math.PI) / 4 + Math.PI / 8;
17
+ const r = i % 2 ? 300 : 370;
18
+ return { dx: Math.round(Math.cos(a) * r), dy: Math.round(Math.sin(a) * r), alt: i % 2 === 1 };
19
+ });
20
+ export const SPARK_PATH = "M0,-20 L7,-7 L20,0 L7,7 L0,20 L-7,7 L-20,0 L-7,-7Z";
21
+ /* ---------- transformations ---------- */
22
+ /** Radius of the circle the body turns into (ground at y = 960, anchor at 660). */
23
+ export const ROUND_RADIUS = 300;
24
+ /** Radius of the bubble the body shrinks into and objects are born from. */
25
+ export const DOT_R = 36;
26
+ /** Scale of the round body when its radius is exactly the bubble's. */
27
+ export const DOT_SCALE = DOT_R / ROUND_RADIUS;
28
+ /** Loading ring: outer radius and hole (46 px stroke). */
29
+ export const RING = { R: 133, hole: 87 };
30
+ /**
31
+ * Check mark, relative to the anchor. The stroke is as wide as the bubble, so
32
+ * the start of the round-capped check is the bubble itself.
33
+ */
34
+ export const CHECK = {
35
+ start: { x: -130, y: -10 },
36
+ path: "M-130,-10 L-45,75 L135,-105",
37
+ length: Math.hypot(85, 85) + Math.hypot(180, 180),
38
+ width: DOT_R * 2,
39
+ };
40
+ /**
41
+ * `</>`: each stroke is born at one of the three dots (the vertex of the <,
42
+ * the middle of the slash, the vertex of the >). Width 50 = the dots' diameter
43
+ * at that moment.
44
+ */
45
+ export const CODE = {
46
+ dist: 170,
47
+ radius: 25,
48
+ strokes: [
49
+ "M-170,0 L-95,-75",
50
+ "M-170,0 L-95,75",
51
+ "M0,0 L38,-105",
52
+ "M0,0 L-38,105",
53
+ "M170,0 L95,-75",
54
+ "M170,0 L95,75",
55
+ ],
56
+ lengths: [106.1, 106.1, 111.7, 111.7, 106.1, 106.1],
57
+ };
58
+ /** Energy orbit: full radius and radius of each dot. */
59
+ export const ORBIT = { R: 300, radii: [26, 18, 26, 18, 26, 18, 26, 18] };
@@ -0,0 +1,41 @@
1
+ export interface Slot {
2
+ name: string;
3
+ mood?: string;
4
+ /** Document-relative coordinates (`getBoundingClientRect()` plus `window.scrollY`/`scrollX`), not viewport-relative. */
5
+ rect: {
6
+ x: number;
7
+ y: number;
8
+ width: number;
9
+ height: number;
10
+ };
11
+ }
12
+ export interface TravelerFrame {
13
+ x: number;
14
+ y: number;
15
+ scale: number;
16
+ /** -1..1, which way the character is heading; feed into gaze/lean. */
17
+ directionX: number;
18
+ mood?: string;
19
+ /** 0 at rest near a slot, up to 1 mid-flight between two slots. */
20
+ flight: number;
21
+ }
22
+ export interface TravelerOptions {
23
+ /** Shrink at the midpoint of a flight, 0..1 of the slot size. Default 0.12. */
24
+ flightShrink?: number;
25
+ /** Upward arc at the midpoint of a flight, in the same units as the slots. Default 40. */
26
+ flightArc?: number;
27
+ /** Portion of each leg spent "parked" vs. flying, via smoothstep easing. Default [0.2, 0.8]. */
28
+ easeWindow?: [number, number];
29
+ }
30
+ /**
31
+ * Computes one frame of the "character that travels between landing-page
32
+ * slots on scroll" pattern. Caller supplies the slots (e.g. from
33
+ * `getBoundingClientRect()` on `.slot[data-name]` elements, already
34
+ * ordered top to bottom) and which one is "active" (e.g. the last slot
35
+ * whose center has crossed above the viewport's midline) plus a 0..1
36
+ * progress toward the next one. This function has no DOM dependency so it
37
+ * is easy to unit test; wire the DOM reads yourself.
38
+ */
39
+ export declare function travelerFrame(slots: Slot[], activeIndex: number, progress: number, opts?: TravelerOptions): TravelerFrame;
40
+ /** Finds the index of the last slot whose vertical center is above `viewportFraction` of `viewportHeight`. */
41
+ export declare function findActiveSlot(slots: Slot[], scrollY: number, viewportHeight: number, viewportFraction?: number): number;
@@ -0,0 +1,43 @@
1
+ import { clamp, smooth } from "./motion.js";
2
+ /**
3
+ * Computes one frame of the "character that travels between landing-page
4
+ * slots on scroll" pattern. Caller supplies the slots (e.g. from
5
+ * `getBoundingClientRect()` on `.slot[data-name]` elements, already
6
+ * ordered top to bottom) and which one is "active" (e.g. the last slot
7
+ * whose center has crossed above the viewport's midline) plus a 0..1
8
+ * progress toward the next one. This function has no DOM dependency so it
9
+ * is easy to unit test; wire the DOM reads yourself.
10
+ */
11
+ export function travelerFrame(slots, activeIndex, progress, opts = {}) {
12
+ const { flightShrink = 0.12, flightArc = 40, easeWindow = [0.2, 0.8] } = opts;
13
+ const current = slots[clamp(activeIndex, 0, slots.length - 1)];
14
+ const next = slots[clamp(activeIndex + 1, 0, slots.length - 1)];
15
+ const p = clamp(progress, 0, 1);
16
+ const eased = smooth(easeWindow[0], easeWindow[1], p);
17
+ const cx = current.rect.x + current.rect.width / 2;
18
+ const cy = current.rect.y + current.rect.height / 2;
19
+ const nx = next.rect.x + next.rect.width / 2;
20
+ const ny = next.rect.y + next.rect.height / 2;
21
+ const flight = Math.sin(p * Math.PI); // 0 at both ends, 1 at the midpoint
22
+ const arc = -flightArc * flight;
23
+ const scaleBase = current.rect.width / 2 + (next.rect.width / 2 - current.rect.width / 2) * eased;
24
+ return {
25
+ x: cx + (nx - cx) * eased,
26
+ y: cy + (ny - cy) * eased + arc,
27
+ scale: (scaleBase / (current.rect.width / 2)) * (1 - flightShrink * flight),
28
+ directionX: clamp((nx - cx) / 200, -1, 1),
29
+ mood: p > 0.5 ? next.mood : current.mood,
30
+ flight,
31
+ };
32
+ }
33
+ /** Finds the index of the last slot whose vertical center is above `viewportFraction` of `viewportHeight`. */
34
+ export function findActiveSlot(slots, scrollY, viewportHeight, viewportFraction = 0.5) {
35
+ const line = scrollY + viewportHeight * viewportFraction;
36
+ let active = 0;
37
+ for (let i = 0; i < slots.length; i++) {
38
+ const center = slots[i].rect.y + slots[i].rect.height / 2;
39
+ if (center <= line)
40
+ active = i;
41
+ }
42
+ return active;
43
+ }
@@ -0,0 +1,49 @@
1
+ export interface StateDef<S extends string, Ctx> {
2
+ id: S;
3
+ /** Called once when the machine enters this state. */
4
+ onEnter?(ctx: Ctx): void;
5
+ /** Called once when the machine leaves this state. */
6
+ onExit?(ctx: Ctx): void;
7
+ /** Transition to `to` automatically after `ms` of being in this state, unless interrupted. */
8
+ after?: {
9
+ ms: number;
10
+ to: S;
11
+ };
12
+ /** States that may interrupt this one even mid-timer/mid-animation. Default: all. */
13
+ interruptibleBy?: S[] | "*";
14
+ /** Arbitrary data a binder (e.g. an avatar renderer) reads to decide mood/motion for this state. */
15
+ data?: Record<string, unknown>;
16
+ }
17
+ export interface TransitionDef<S extends string, E extends string, Ctx> {
18
+ from: S | "*";
19
+ event: E;
20
+ to: S;
21
+ guard?(ctx: Ctx): boolean;
22
+ }
23
+ export interface StateMachineConfig<S extends string, E extends string, Ctx> {
24
+ initial: S;
25
+ states: Record<S, StateDef<S, Ctx>>;
26
+ transitions: TransitionDef<S, E, Ctx>[];
27
+ context?: Ctx;
28
+ }
29
+ export interface BotStateMachine<S extends string, E extends string, Ctx> {
30
+ getState(): S;
31
+ getContext(): Ctx;
32
+ /** Fires `event`; returns true if a transition matched and ran. */
33
+ send(event: E): boolean;
34
+ /** Force a transition, bypassing `transitions` (still runs onExit/onEnter and schedules `after`). */
35
+ goto(state: S): void;
36
+ /** Advance internal timers (the `after` auto-transitions). Call every frame with a delta in ms. */
37
+ tick(dtMs: number): void;
38
+ /** Subscribe to state changes. Returns an unsubscribe function. */
39
+ subscribe(fn: (state: S, previous: S) => void): () => void;
40
+ }
41
+ /**
42
+ * A small typed finite state machine for bot/mascot behavior (idle,
43
+ * thinking, success, error, loading, sleeping, or any custom set). Framework-
44
+ * and renderer-agnostic: it only tracks state and timers, you decide in
45
+ * `onEnter`/`onExit` or in a `bind*` helper what that means visually.
46
+ */
47
+ export declare function createStateMachine<S extends string, E extends string, Ctx = Record<string, never>>(config: StateMachineConfig<S, E, Ctx>): BotStateMachine<S, E, Ctx>;
48
+ /** Common bot states, free to use as-is or as a starting point for your own `S` union. */
49
+ export type CommonBotState = "idle" | "thinking" | "success" | "error" | "loading" | "sleeping";
@@ -0,0 +1,68 @@
1
+ /**
2
+ * A small typed finite state machine for bot/mascot behavior (idle,
3
+ * thinking, success, error, loading, sleeping, or any custom set). Framework-
4
+ * and renderer-agnostic: it only tracks state and timers, you decide in
5
+ * `onEnter`/`onExit` or in a `bind*` helper what that means visually.
6
+ */
7
+ export function createStateMachine(config) {
8
+ let current = config.initial;
9
+ let timerMs = null;
10
+ let timerTarget = null;
11
+ const context = (config.context ?? {});
12
+ const listeners = new Set();
13
+ function enter(state) {
14
+ const def = config.states[state];
15
+ timerMs = def.after ? def.after.ms : null;
16
+ timerTarget = def.after ? def.after.to : null;
17
+ }
18
+ function transitionTo(next) {
19
+ if (next === current)
20
+ return;
21
+ const previous = current;
22
+ const prevDef = config.states[previous];
23
+ prevDef.onExit?.(context);
24
+ current = next;
25
+ enter(next);
26
+ config.states[next].onEnter?.(context);
27
+ for (const fn of listeners)
28
+ fn(current, previous);
29
+ }
30
+ enter(current);
31
+ config.states[current].onEnter?.(context);
32
+ return {
33
+ getState: () => current,
34
+ getContext: () => context,
35
+ send(event) {
36
+ const currentDef = config.states[current];
37
+ for (const t of config.transitions) {
38
+ if ((t.from === "*" || t.from === current) && t.event === event) {
39
+ if (t.guard && !t.guard(context))
40
+ continue;
41
+ if (currentDef.interruptibleBy &&
42
+ currentDef.interruptibleBy !== "*" &&
43
+ !currentDef.interruptibleBy.includes(t.to)) {
44
+ continue;
45
+ }
46
+ transitionTo(t.to);
47
+ return true;
48
+ }
49
+ }
50
+ return false;
51
+ },
52
+ goto(state) {
53
+ transitionTo(state);
54
+ },
55
+ tick(dtMs) {
56
+ if (timerMs === null || timerTarget === null)
57
+ return;
58
+ timerMs -= dtMs;
59
+ if (timerMs <= 0) {
60
+ transitionTo(timerTarget);
61
+ }
62
+ },
63
+ subscribe(fn) {
64
+ listeners.add(fn);
65
+ return () => listeners.delete(fn);
66
+ },
67
+ };
68
+ }
@@ -0,0 +1,10 @@
1
+ type Subscriber = (now: number) => void;
2
+ /** Last pointer position in the window and when it last moved. */
3
+ export declare const pointer: {
4
+ x: number;
5
+ y: number;
6
+ last: number;
7
+ inside: boolean;
8
+ };
9
+ export declare function subscribe(f: Subscriber): () => void;
10
+ export {};
package/dist/ticker.js ADDED
@@ -0,0 +1,42 @@
1
+ /*
2
+ * A single requestAnimationFrame for every character on the page, and a single
3
+ * pointer listener. Whoever subscribes receives the frame time; when nobody is
4
+ * left, the loop stops. With the tab hidden, the browser already pauses rAF.
5
+ */
6
+ const subscribers = new Set();
7
+ let frame = 0;
8
+ /** Last pointer position in the window and when it last moved. */
9
+ export const pointer = { x: 0, y: 0, last: -Infinity, inside: true };
10
+ function run(now) {
11
+ for (const f of subscribers)
12
+ f(now);
13
+ frame = subscribers.size ? requestAnimationFrame(run) : 0;
14
+ }
15
+ function onMove(e) {
16
+ pointer.x = e.clientX;
17
+ pointer.y = e.clientY;
18
+ pointer.last = performance.now();
19
+ pointer.inside = true;
20
+ }
21
+ function onLeave(e) {
22
+ if (!e.relatedTarget)
23
+ pointer.inside = false;
24
+ }
25
+ export function subscribe(f) {
26
+ if (subscribers.size === 0) {
27
+ window.addEventListener("pointermove", onMove, { passive: true });
28
+ document.documentElement.addEventListener("pointerleave", onLeave);
29
+ }
30
+ subscribers.add(f);
31
+ if (!frame)
32
+ frame = requestAnimationFrame(run);
33
+ return () => {
34
+ subscribers.delete(f);
35
+ if (subscribers.size === 0) {
36
+ window.removeEventListener("pointermove", onMove);
37
+ document.documentElement.removeEventListener("pointerleave", onLeave);
38
+ cancelAnimationFrame(frame);
39
+ frame = 0;
40
+ }
41
+ };
42
+ }
@@ -0,0 +1,21 @@
1
+ import type { PartialDelta } from './delta.js';
2
+ export declare const TRANSFORMATIONS: {
3
+ morphLoading: {
4
+ duration: number;
5
+ sample: (t: number) => PartialDelta;
6
+ };
7
+ morphCheck: {
8
+ duration: number;
9
+ sample: (t: number) => PartialDelta;
10
+ };
11
+ morphCode: {
12
+ duration: number;
13
+ sample: (t: number) => PartialDelta;
14
+ };
15
+ energy: {
16
+ duration: number;
17
+ sample: (t: number) => PartialDelta;
18
+ };
19
+ };
20
+ /** Reactions that cannot be interrupted: in the middle of them the body does not even exist. */
21
+ export declare const EXCLUSIVE: ReadonlySet<string>;