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.
- package/LICENSE +21 -0
- package/README.md +202 -2
- package/dist/animation.d.ts +90 -0
- package/dist/animation.js +396 -0
- package/dist/brain.d.ts +198 -0
- package/dist/brain.js +581 -0
- package/dist/character.d.ts +123 -0
- package/dist/character.js +916 -0
- package/dist/characters/berry.d.ts +2 -0
- package/dist/characters/berry.js +38 -0
- package/dist/characters/flame.d.ts +2 -0
- package/dist/characters/flame.js +46 -0
- package/dist/delta.d.ts +16 -0
- package/dist/delta.js +146 -0
- package/dist/examples.d.ts +4 -0
- package/dist/examples.js +208 -0
- package/dist/focus.d.ts +46 -0
- package/dist/focus.js +284 -0
- package/dist/gaze.d.ts +48 -0
- package/dist/gaze.js +133 -0
- package/dist/index.d.ts +21 -0
- package/dist/index.js +21 -0
- package/dist/interactions.d.ts +30 -0
- package/dist/interactions.js +100 -0
- package/dist/library.d.ts +18 -0
- package/dist/library.js +14 -0
- package/dist/moods.d.ts +80 -0
- package/dist/moods.js +51 -0
- package/dist/motion.d.ts +93 -0
- package/dist/motion.js +167 -0
- package/dist/mount.d.ts +90 -0
- package/dist/mount.js +707 -0
- package/dist/parts.d.ts +36 -0
- package/dist/parts.js +131 -0
- package/dist/reactions.d.ts +184 -0
- package/dist/reactions.js +1855 -0
- package/dist/rig.d.ts +119 -0
- package/dist/rig.js +59 -0
- package/dist/scroll-traveler.d.ts +41 -0
- package/dist/scroll-traveler.js +43 -0
- package/dist/state-machine.d.ts +49 -0
- package/dist/state-machine.js +68 -0
- package/dist/ticker.d.ts +10 -0
- package/dist/ticker.js +42 -0
- package/dist/transformations.d.ts +21 -0
- package/dist/transformations.js +306 -0
- package/package.json +51 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Jp-mainieri
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,203 @@
|
|
|
1
|
-
#
|
|
1
|
+
# procedural-bot-animations
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/procedural-bot-animations)
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
A procedural animation engine for 2D SVG mascots and bot avatars. A character is a body outline, two eyes and up to three moving parts. The engine adds one pose per frame on top of that: an idle that never repeats, blended moods, looping activities, one-shot reactions, eyes that look, blink and react, and parts that sway and bend on springs. It renders plain DOM (one SVG, no framework). The part that computes the pose does not touch the DOM, so you can draw it yourself.
|
|
8
|
+
|
|
9
|
+
Characters and animations are plain JSON, so you can write them by hand or generate them with an LLM. The package also contains a typed state machine and a scroll traveler.
|
|
10
|
+
|
|
11
|
+
The cover image was made with an earlier version of the engine. It shows Berry, one of the two built-in characters.
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
Package page: [npmjs.com/package/procedural-bot-animations](https://www.npmjs.com/package/procedural-bot-animations)
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npm install procedural-bot-animations
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
The package is ESM only, needs a DOM for `mountCharacter`, and has no runtime dependencies.
|
|
22
|
+
|
|
23
|
+
## Quick start
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
import { mountCharacter, RIG_BERRY } from "procedural-bot-animations";
|
|
27
|
+
|
|
28
|
+
const host = document.querySelector<HTMLElement>("#bot")!;
|
|
29
|
+
|
|
30
|
+
const bot = mountCharacter(host, {
|
|
31
|
+
rig: RIG_BERRY,
|
|
32
|
+
size: 200,
|
|
33
|
+
color: "#e11d2e",
|
|
34
|
+
label: "Berry, the assistant",
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
bot.update({ mood: "curious" }); // a held expression
|
|
38
|
+
bot.update({ mood: { curious: 0.6, focused: 0.4 }, activity: "thinking" }); // a blend, plus a loop
|
|
39
|
+
bot.react("success"); // a one-shot reaction
|
|
40
|
+
// bot.destroy(); // removes the SVG and the listeners
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
By default the character looks at the pointer, reacts when the pointer enters it or it is clicked, and follows `prefers-reduced-motion`. The built-in moods, activities and reactions are listed in [`skills/procedural-bot-animations/references/motion-cookbook.md`](skills/procedural-bot-animations/references/motion-cookbook.md) and exported as `MOODS`, `ACTIVITIES` and `REACTIONS`.
|
|
44
|
+
|
|
45
|
+
A minimal page is in [`examples/minimal.html`](examples/minimal.html).
|
|
46
|
+
|
|
47
|
+
## The Studio
|
|
48
|
+
|
|
49
|
+
The Studio is a static demo in [`site/`](site), served from GitHub Pages at <https://jp-mainieri.github.io/procedural-bot-animations/>. It shows a character on a stage, lets you import your own character and animation JSON, and has prompts you can copy into an LLM to generate them. [`examples/README.md`](examples/README.md) says how to run it locally.
|
|
50
|
+
|
|
51
|
+
## Bring your own character
|
|
52
|
+
|
|
53
|
+
A character is one JSON object in a 0..100 box. Its core keys (`version`, `id`, `name`, `body.path`, `eyes`) are an [Open Bot Avatar](https://github.com/dominikscholz/open-bot-avatar) definition, so any valid Open Bot Avatar definition is accepted unchanged. An optional `rig` key adds moving parts, eye styles, idle sway and flicker.
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
import { mountCharacter, parseCharacter } from "procedural-bot-animations";
|
|
57
|
+
|
|
58
|
+
const parsed = parseCharacter(jsonText); // never throws
|
|
59
|
+
if (!parsed.ok) throw new Error(parsed.errors.join("\n")); // every problem, each starting with its JSON path
|
|
60
|
+
|
|
61
|
+
mountCharacter(host, {
|
|
62
|
+
rig: parsed.value.rig,
|
|
63
|
+
color: parsed.value.definition.rig?.color, // the format's suggested colour; you pass it on yourself
|
|
64
|
+
});
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The full contract, with every limit and a worked example, is in [`docs/character-format.md`](docs/character-format.md). `parseCharacter` runs `validateCharacter` and then `characterToRig`; both are exported too.
|
|
68
|
+
|
|
69
|
+
## Bring your own animations
|
|
70
|
+
|
|
71
|
+
An animation is one JSON object of kind `reaction` (plays once), `activity` (loops) or `mood` (a held pose). It is a set of keyframe tracks over named fields such as `bodySy`, `partL`, `lidTop` or `eyeX`. Every value is an offset from the resting pose.
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
import {
|
|
75
|
+
RIG_BERRY,
|
|
76
|
+
addToLibrary,
|
|
77
|
+
createLibrary,
|
|
78
|
+
mountCharacter,
|
|
79
|
+
parseAnimation,
|
|
80
|
+
} from "procedural-bot-animations";
|
|
81
|
+
|
|
82
|
+
const library = createLibrary(); // a copy of the built-ins that is safe to extend
|
|
83
|
+
|
|
84
|
+
const result = parseAnimation(jsonText); // never throws
|
|
85
|
+
if (!result.ok) throw new Error(result.errors.join("\n"));
|
|
86
|
+
addToLibrary(library, result.value.compiled);
|
|
87
|
+
|
|
88
|
+
const bot = mountCharacter(host, { rig: RIG_BERRY, library });
|
|
89
|
+
// or, on a character that is already mounted: bot.update({ library });
|
|
90
|
+
|
|
91
|
+
const { kind, id } = result.value.definition;
|
|
92
|
+
if (kind === "reaction") bot.react(id);
|
|
93
|
+
if (kind === "activity") bot.update({ activity: id });
|
|
94
|
+
if (kind === "mood") bot.update({ mood: id });
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
The full contract, the field list with ranges and a house style for good motion are in [`docs/animation-format.md`](docs/animation-format.md). `describeAnimation(definition)` returns a one-paragraph summary of what an animation does.
|
|
98
|
+
|
|
99
|
+
## Generate them with an LLM
|
|
100
|
+
|
|
101
|
+
Both format documents end with a **Prompt** section: a self-contained block you copy into any LLM, followed by a description of what you want.
|
|
102
|
+
|
|
103
|
+
- Characters: [Prompt in `docs/character-format.md`](docs/character-format.md#prompt)
|
|
104
|
+
- Animations: [Prompt in `docs/animation-format.md`](docs/animation-format.md#prompt)
|
|
105
|
+
|
|
106
|
+
Paste the model's JSON into `parseCharacter` or `parseAnimation`. Each error starts with the JSON path of the problem, so you can paste the errors back to the model and ask for a fix. The Studio offers the same prompts. If you use Claude Code, the skill in [`skills/procedural-bot-animations/`](skills/procedural-bot-animations) teaches an agent to generate and self-check both formats.
|
|
107
|
+
|
|
108
|
+
## What's in this repo
|
|
109
|
+
|
|
110
|
+
| Path | What |
|
|
111
|
+
|---|---|
|
|
112
|
+
| [`src/mount.ts`](src/mount.ts), [`src/ticker.ts`](src/ticker.ts) | `mountCharacter`, the plain-DOM SVG renderer, and the shared `requestAnimationFrame` loop |
|
|
113
|
+
| [`src/brain.ts`](src/brain.ts) | `Brain`: computes one `Pose` per frame. No DOM |
|
|
114
|
+
| [`src/gaze.ts`](src/gaze.ts), [`src/focus.ts`](src/focus.ts) | Eye movement (saccade, pursuit, microsaccades, attention, boredom) and the gaze modes (`free`, `focus`, `data-bot-focus` anchors) |
|
|
115
|
+
| [`src/moods.ts`](src/moods.ts), [`src/reactions.ts`](src/reactions.ts), [`src/interactions.ts`](src/interactions.ts), [`src/transformations.ts`](src/transformations.ts) | 9 moods, 5 activities, 36 reactions, the hover and click gestures, and the body-to-object transformations |
|
|
116
|
+
| [`src/parts.ts`](src/parts.ts), [`src/motion.ts`](src/motion.ts), [`src/delta.ts`](src/delta.ts) | Part physics and path bending, springs, keyframe tracks, blink, jump, and the list of animatable fields |
|
|
117
|
+
| [`src/rig.ts`](src/rig.ts), [`src/characters/`](src/characters) | The `Rig` type, and the built-in characters Berry and Flame |
|
|
118
|
+
| [`src/character.ts`](src/character.ts), [`src/animation.ts`](src/animation.ts), [`src/library.ts`](src/library.ts), [`src/examples.ts`](src/examples.ts) | The two JSON formats (validate, compile, parse), the per-instance library, and original example characters and animations written as data |
|
|
119
|
+
| [`src/state-machine.ts`](src/state-machine.ts), [`src/scroll-traveler.ts`](src/scroll-traveler.ts) | A typed state machine and a scroll traveler. Both are DOM-free |
|
|
120
|
+
| [`docs/`](docs) | [`architecture.md`](docs/architecture.md), [`character-format.md`](docs/character-format.md), [`animation-format.md`](docs/animation-format.md) |
|
|
121
|
+
| [`skills/procedural-bot-animations/`](skills/procedural-bot-animations) | A [Claude Code](https://claude.com/claude-code) skill: mount a character, generate character and animation JSON, tune motion |
|
|
122
|
+
| [`site/`](site) | The Studio |
|
|
123
|
+
| [`examples/`](examples) | A minimal page |
|
|
124
|
+
| [`tests/`](tests) | Vitest tests. They run in Node, with no DOM |
|
|
125
|
+
|
|
126
|
+
## The eyes
|
|
127
|
+
|
|
128
|
+
The eyes are most of why a character feels alive. What the engine does, all of it in `src/gaze.ts`, `src/brain.ts` and `src/mount.ts`:
|
|
129
|
+
|
|
130
|
+
- **Saccades.** When the target jumps, the eye hops there on a slightly underdamped spring, aims a little short and settles. It does not glide in a straight line.
|
|
131
|
+
- **Pursuit.** When the target moves slowly, such as a cursor, the eye follows it smoothly. A fast cursor is followed firmly instead of with a chain of hops.
|
|
132
|
+
- **Microsaccades.** At rest, the eye makes tiny random shifts every 0.5 to 1.6 s, so it is never perfectly still.
|
|
133
|
+
- **Blinks.** A random interval of 1.8 to 6 s. One blink in five is a double blink. A large saccade can trigger a blink. There are no blinks while the character sleeps.
|
|
134
|
+
- **Attention and boredom.** Big saccades, a fast cursor and a close cursor raise attention: the eyes grow and the lids open. When nothing happens for a few seconds, boredom rises and the lids get heavy.
|
|
135
|
+
- **Shape follows movement.** During a fast saccade the eyes stretch along the movement and tilt toward it, then relax. Looking up enlarges the eye. Looking down lowers the eyelid.
|
|
136
|
+
- **Cross-eyed look.** With the cursor right on top of the character, the eyes move closer together.
|
|
137
|
+
- **Real eyelids.** The upper and lower lids are clip paths with an adjustable tilt, so a mood can frown or squint instead of only scaling the eye. A happy eye crossfades into an arc.
|
|
138
|
+
- **Fake 3D turn.** The `turn` field slides the eyes sideways and shrinks the far one. Past 1, the face turns to a profile where one eye vanishes.
|
|
139
|
+
- **Where to look.** `gaze: "pointer"` follows the cursor. `"free"` wanders across the page and gets drawn to page events. `"focus"` looks at what matters: focused fields, typing, clicks, scrolling and elements with `data-bot-focus`. You can also pass a point or a function.
|
|
140
|
+
|
|
141
|
+
The numbers are in [`skills/procedural-bot-animations/references/motion-cookbook.md`](skills/procedural-bot-animations/references/motion-cookbook.md). How the pieces connect is in [`docs/architecture.md`](docs/architecture.md).
|
|
142
|
+
|
|
143
|
+
## State machine and scroll traveler
|
|
144
|
+
|
|
145
|
+
`createStateMachine` is a small typed state machine with timed transitions (`after`), interrupt rules (`interruptibleBy`) and subscribers. It does not know about characters: you connect a state to `update({ mood, activity })` or `react(...)` yourself. Call `tick(dtMs)` every frame to advance the `after` timers. See [`skills/procedural-bot-animations/references/state-machine-guide.md`](skills/procedural-bot-animations/references/state-machine-guide.md).
|
|
146
|
+
|
|
147
|
+
`travelerFrame` and `findActiveSlot` compute where a character should be as the page scrolls between sections. They take numbers (slot rectangles that you read yourself) and return numbers.
|
|
148
|
+
|
|
149
|
+
## Accessibility
|
|
150
|
+
|
|
151
|
+
- **Reduced motion.** `reducedMotion` is `"auto"` by default and follows `prefers-reduced-motion`. You can force it with `true` or ignore it with `false`. When it applies, the character stops idling, jumping, squashing and blinking, and the idle sway of the parts stops. Reactions lose their movement fields (position, rotation, scale, turn, sparks, embers, smoke and transformations). The gaze follows its target with simple smoothing instead of saccades. Changes of expression (eyelids, eye shape, happy eyes, accessories such as `!` and `?`) still show.
|
|
152
|
+
- **Screen readers.** With the `label` option the SVG gets `role="img"` and `aria-label`. Without it the SVG is `aria-hidden="true"`.
|
|
153
|
+
- **Decorative mode.** `interactive: false` turns off hover and click reactions.
|
|
154
|
+
- The SVG has no tab stop and no keyboard handlers. If a click on the character does something in your app, give that action a real button.
|
|
155
|
+
|
|
156
|
+
## Relationship to Open Bot Avatar and DevBerry
|
|
157
|
+
|
|
158
|
+
**Open Bot Avatar.** This project is independent and unofficial. It is not affiliated with Open Bot Avatar or published by its author, Dominik Scholz. Open Bot Avatar is MIT-licensed. From it, this project uses only the shape of its JSON definition (`version`, `id`, `name`, `body.path`, `eyes`), and it adapts its path grammar. It has no runtime dependency on the `open-bot-avatar` package and never calls its renderer.
|
|
159
|
+
|
|
160
|
+
**DevBerry.** The engine is a TypeScript port of the mascot engine behind [DevBerry](https://devberry.app), made generic: the rig, the brain, the gaze, the moods, the reactions and the transformations come from there. Berry and the Flame are DevBerry's characters, included with the owner's permission.
|
|
161
|
+
|
|
162
|
+
## Migrating from 0.1
|
|
163
|
+
|
|
164
|
+
0.2.0 replaces the whole engine. It is a breaking change, with no compatibility layer.
|
|
165
|
+
|
|
166
|
+
0.1 was a small engine for one silhouette with two pill eyes. These 0.1 exports no longer exist:
|
|
167
|
+
|
|
168
|
+
| 0.1 export | Use instead |
|
|
169
|
+
|---|---|
|
|
170
|
+
| `bindBrain`, `BoundBot`, `BindOptions` | `mountCharacter(host, { rig })`, which returns `{ brain, svg, update, react, jump, currentReaction, getGazeState, destroy }` |
|
|
171
|
+
| `mountRig`, `MountedRig`, `RenderOptions`, `Bounds` | `mountCharacter` |
|
|
172
|
+
| `AvatarDefinitionLike` | `CharacterDefinition` and `parseCharacter(json)`, which also returns a `Rig`. Open Bot Avatar definitions are accepted unchanged |
|
|
173
|
+
| `brain.setMood({...})` | `bot.update({ mood: "curious" })` or `{ mood: { curious: 0.6, focused: 0.4 } }`. The new `mood` replaces the previous one; it does not merge |
|
|
174
|
+
| `brain.react("bounce")` | `bot.react("success")` or another name from `REACTIONS`. The 0.1 reactions `bounce`, `doubleBlink` and `nod` are gone. `fright` still exists but is a new, different reaction |
|
|
175
|
+
| `ReactionPlayer`, `ReactionDefinition`, `builtinReactions`, `bounce`, `fright`, `doubleBlink`, `nod` | `REACTIONS`, `ReactionDef`, a `Library`, and `Brain.react(name, now)`. Write your own with the animation JSON format |
|
|
176
|
+
| `MoodBlender`, `MoodBlenderOptions`, `blendMoods`, `builtinMoods`, `MoodDefinition` | `MOODS`. The `Brain` blends the mood weights itself. Custom moods go through a `Library` |
|
|
177
|
+
| `GazeEngine`, `GazeEngineOptions`, `Point2D`, `ArrivalStyle` | `Gaze` (used by the `Brain`), or the `gaze` option of `mountCharacter` (`"pointer"`, `"free"`, `"focus"`, a point, a function, or `null`) |
|
|
178
|
+
| `BlinkScheduler`, `BlinkOptions` | Blinking is built into the `Brain` (`newBlink` and `stepBlink` in `src/motion.ts`) |
|
|
179
|
+
| `fakeTurn`, `FakeTurnOptions` | The `turn` field, handled by the `Brain` |
|
|
180
|
+
| `neverRepeating`, `breathing`, `BreathingOptions` | Built into the `Brain` |
|
|
181
|
+
| `mulberry32`, `randRange`, `chance` | Removed. `Brain` takes an `rng` option, and the `Rng` type is still exported |
|
|
182
|
+
| `safeDt` | Removed. The `Brain` limits `dt` itself |
|
|
183
|
+
| `neutralPose`, `neutralEyePose`, `neutralBodyPose`, `addPose`, `addEyePose`, `addBodyPose`, `PoseDelta`, `resolveDelta`, `BodyPose` | Removed. `Pose` and `EyePose` still exist but are different types. Animations use the `Delta` fields in `src/delta.ts` |
|
|
184
|
+
| `Brain`, `BrainOptions` | Same names, new API: `new Brain(rig, options)` and `brain.step(now, input)` |
|
|
185
|
+
| `SpringState` (`value`, `velocity`) | `Spring` (`a`, `v`). `spring(m, target, k, c, dt)` mutates `m` and returns nothing |
|
|
186
|
+
|
|
187
|
+
`clamp`, `lerp`, `smooth` and `damp` are still exported with the same signatures, now from `src/motion.ts`. `createStateMachine` and the scroll traveler are unchanged. The optional `peerDependencies` entry for `open-bot-avatar` is gone.
|
|
188
|
+
|
|
189
|
+
## Development
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
npm install
|
|
193
|
+
npm run typecheck # tsc --noEmit
|
|
194
|
+
npm test # vitest run
|
|
195
|
+
npm run build # tsc -p tsconfig.build.json, into dist/
|
|
196
|
+
npm run check # all three, as CI runs them
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
CI runs on Node 20 and 22. See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
200
|
+
|
|
201
|
+
## License
|
|
202
|
+
|
|
203
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import type { DeltaField, PartialDelta } from "./delta.js";
|
|
2
|
+
import type { CurveName } from "./motion.js";
|
|
3
|
+
import type { ActivityDef, ReactionDef } from "./reactions.js";
|
|
4
|
+
import type { ValidationResult } from "./character.js";
|
|
5
|
+
export type { ValidationResult };
|
|
6
|
+
export type FieldGroup = "body" | "parts" | "eyes" | "lids" | "accessories" | "flame" | "morph";
|
|
7
|
+
export type FieldUnit = "px" | "deg" | "scale" | "0..1" | "-1..1";
|
|
8
|
+
export interface FieldInfo {
|
|
9
|
+
group: FieldGroup;
|
|
10
|
+
/** `px`: drawing pixels; `deg`: degrees; `scale`: increment over 1 (-0.5 = half); `0..1` / `-1..1`: plain amounts. */
|
|
11
|
+
unit: FieldUnit;
|
|
12
|
+
min: number;
|
|
13
|
+
max: number;
|
|
14
|
+
rest: 0;
|
|
15
|
+
description: string;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* One entry per delta field. The hard ranges come from the extreme values the
|
|
19
|
+
* built-in reactions, activities and moods actually reach, widened about 1.5×.
|
|
20
|
+
* 0 is always the character at rest.
|
|
21
|
+
*/
|
|
22
|
+
export declare const FIELD_INFO: Record<DeltaField, FieldInfo>;
|
|
23
|
+
/** Group of every field, in the order of `FIELDS`. */
|
|
24
|
+
export declare const FIELD_GROUPS: readonly FieldGroup[];
|
|
25
|
+
export declare const CURVE_NAMES: CurveName[];
|
|
26
|
+
export type AnimationKeyframe = [number, number] | [number, number, CurveName];
|
|
27
|
+
export type AnimationTracks = Partial<Record<DeltaField, AnimationKeyframe[]>>;
|
|
28
|
+
export type AnimationDefinition = {
|
|
29
|
+
version: 1;
|
|
30
|
+
kind: "reaction";
|
|
31
|
+
id: string;
|
|
32
|
+
name: string;
|
|
33
|
+
duration: number;
|
|
34
|
+
tracks: AnimationTracks;
|
|
35
|
+
} | {
|
|
36
|
+
version: 1;
|
|
37
|
+
kind: "activity";
|
|
38
|
+
id: string;
|
|
39
|
+
name: string;
|
|
40
|
+
period: number;
|
|
41
|
+
tracks: AnimationTracks;
|
|
42
|
+
} | {
|
|
43
|
+
version: 1;
|
|
44
|
+
kind: "mood";
|
|
45
|
+
id: string;
|
|
46
|
+
name: string;
|
|
47
|
+
pose: Partial<Record<DeltaField, number>>;
|
|
48
|
+
};
|
|
49
|
+
export type CompiledAnimation = {
|
|
50
|
+
kind: "reaction";
|
|
51
|
+
id: string;
|
|
52
|
+
name: string;
|
|
53
|
+
def: ReactionDef;
|
|
54
|
+
} | {
|
|
55
|
+
kind: "activity";
|
|
56
|
+
id: string;
|
|
57
|
+
name: string;
|
|
58
|
+
def: ActivityDef;
|
|
59
|
+
} | {
|
|
60
|
+
kind: "mood";
|
|
61
|
+
id: string;
|
|
62
|
+
name: string;
|
|
63
|
+
def: PartialDelta;
|
|
64
|
+
};
|
|
65
|
+
export declare const ANIMATION_LIMITS: {
|
|
66
|
+
readonly reactionDuration: readonly [0.2, 10];
|
|
67
|
+
readonly activityPeriod: readonly [0.3, 20];
|
|
68
|
+
readonly maxTracks: 24;
|
|
69
|
+
readonly maxKeyframes: 40;
|
|
70
|
+
readonly nameMax: 60;
|
|
71
|
+
};
|
|
72
|
+
/** The valid field names closest to `name` (case-insensitive edit distance, substring matches first). */
|
|
73
|
+
export declare function closestFields(name: string, count?: number): DeltaField[];
|
|
74
|
+
/** Checks any JSON value as an animation definition. Collects every problem; warnings never block. */
|
|
75
|
+
export declare function validateAnimation(input: unknown): ValidationResult<AnimationDefinition>;
|
|
76
|
+
/** Turns a validated definition into what the library stores. */
|
|
77
|
+
export declare function compileAnimation(def: AnimationDefinition): CompiledAnimation;
|
|
78
|
+
/** JSON text → validated definition plus compiled entry. Never throws. */
|
|
79
|
+
export declare function parseAnimation(json: string): ValidationResult<{
|
|
80
|
+
definition: AnimationDefinition;
|
|
81
|
+
compiled: CompiledAnimation;
|
|
82
|
+
}>;
|
|
83
|
+
/** Structural type so this file does not depend on library.ts. */
|
|
84
|
+
export declare function addToLibrary(lib: {
|
|
85
|
+
reactions: Record<string, ReactionDef>;
|
|
86
|
+
activities: Record<string, ActivityDef>;
|
|
87
|
+
moods: Record<string, PartialDelta>;
|
|
88
|
+
}, a: CompiledAnimation): void;
|
|
89
|
+
/** One-paragraph plain-English summary: length, which groups move and the peak values. */
|
|
90
|
+
export declare function describeAnimation(def: AnimationDefinition): string;
|