@cesarvenzac/figures 0.0.0-stage → 0.1.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 +145 -2
- package/dist/figure-acts.d.ts +55 -0
- package/dist/figure-acts.js +616 -0
- package/dist/figure-curves.d.ts +30 -0
- package/dist/figure-curves.js +44 -0
- package/dist/figure-gl.d.ts +33 -0
- package/dist/figure-gl.js +875 -0
- package/dist/figure-loop.d.ts +3 -0
- package/dist/figure-loop.js +21 -0
- package/dist/figure-motion.d.ts +76 -0
- package/dist/figure-motion.js +260 -0
- package/dist/figure-peers.d.ts +36 -0
- package/dist/figure-peers.js +37 -0
- package/dist/figure-pose.d.ts +77 -0
- package/dist/figure-pose.js +108 -0
- package/dist/figure-scene.d.ts +65 -0
- package/dist/figure-scene.js +210 -0
- package/dist/figure-space.d.ts +233 -0
- package/dist/figure-space.js +151 -0
- package/dist/figure.d.ts +204 -0
- package/dist/figure.js +277 -0
- package/dist/index.d.ts +19 -0
- package/dist/index.js +19 -0
- package/dist/react.d.ts +69 -0
- package/dist/react.js +775 -0
- package/dist/rubik.d.ts +34 -0
- package/dist/rubik.js +54 -0
- package/package.json +73 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 César Venzac
|
|
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,146 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @cesarvenzac/figures
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Small figures for the agents in your interface: a cube, a sphere, a pyramid, a block or a cloud,
|
|
4
|
+
really in 3D, with two eyes painted on its face.
|
|
5
|
+
|
|
6
|
+
They have no mouth, arms or hats. They say everything with their eyes and the way they move, as
|
|
7
|
+
Anki's Cozmo does: lids cut into the eyes for each expression, or the eyes become a shape (^ ^,
|
|
8
|
+
stars, hearts, × ×), the head turning and tipping with them. Each shape has acts of its own: the
|
|
9
|
+
cube solves itself like a Rubik's cube while it thinks, the block turns its dials like a cryptex,
|
|
10
|
+
the pyramid's capstone floats, the sphere has moons, the cloud rains while it works. Give one a
|
|
11
|
+
mood and it shows it, and reacts as it changes: it celebrates a finished run, loses its colour at
|
|
12
|
+
a failed one, yawns when it's switched off.
|
|
13
|
+
|
|
14
|
+
The docs are at [cesarvenzac.com/figures](https://cesarvenzac.com/figures), and the figures to
|
|
15
|
+
make, pet and watch in [the Lab](https://cesarvenzac.com/lab/figures).
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
npm install @cesarvenzac/figures
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Use
|
|
22
|
+
|
|
23
|
+
```tsx
|
|
24
|
+
import { figureFor } from "@cesarvenzac/figures";
|
|
25
|
+
import { AgentFigure } from "@cesarvenzac/figures/react";
|
|
26
|
+
|
|
27
|
+
const ada = figureFor("Ada"); // { shape: "sphere", energy: "calm", habit: "wave", palette: 6 }
|
|
28
|
+
|
|
29
|
+
<AgentFigure figure={ada} mood="thinking" size={48} />;
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
A figure is four choices, plain data you can store: its `shape` (`cube`, `sphere`, `pyramid`,
|
|
33
|
+
`block`, `cloud`), its `energy` (`calm`, `lively`, `bouncy`: how big and quick it moves), its
|
|
34
|
+
`habit` (what it does while it waits: `look`, `hum`, `nap`, `spin`, `wave`, `morph`) and its
|
|
35
|
+
`palette` (a colourway, 1 to 8). `figureFor(word)` makes one from any word, the same word the same
|
|
36
|
+
figure every time, so an agent's name is enough. `readFigure(value)` reads a stored one back,
|
|
37
|
+
filling in anything missing or unknown; `isFigure(value)` says whether a value is a whole figure.
|
|
38
|
+
|
|
39
|
+
## Moods
|
|
40
|
+
|
|
41
|
+
What the agent it stands for is doing. Each mood has its expression and its loop:
|
|
42
|
+
|
|
43
|
+
| Mood | Shows |
|
|
44
|
+
| --- | --- |
|
|
45
|
+
| `idle` | Waiting: breathing, blinking, doing its habit now and then |
|
|
46
|
+
| `thinking` | Setting up: looking up and aside, the cube scrambling and solving itself |
|
|
47
|
+
| `working` | At work: eyes narrowed and scanning, each shape busy its own way |
|
|
48
|
+
| `happy` | Done, something to look at: happy eyes, turning into a star now and then |
|
|
49
|
+
| `trouble` | In trouble: squeezed eyes, worrying, shaking now and then |
|
|
50
|
+
| `sleep` | Switched off: eyes shut, grey and dim, z's |
|
|
51
|
+
|
|
52
|
+
As the mood changes it reacts (`reactionTo(from, to)` says which): to `happy`, it celebrates (the
|
|
53
|
+
cube bursts and snaps back, the sphere splashes, the pyramid launches its capstone, the block
|
|
54
|
+
spins its dials like a slot machine, the cloud gets a rainbow); to `trouble`, it fails; into work,
|
|
55
|
+
it gets going; to `sleep`, it dozes off, and back, it wakes.
|
|
56
|
+
|
|
57
|
+
## `AgentFigure`
|
|
58
|
+
|
|
59
|
+
```tsx
|
|
60
|
+
<AgentFigure
|
|
61
|
+
figure={ada}
|
|
62
|
+
mood="working"
|
|
63
|
+
size={48} // its box, in pixels; the canvas overhangs it for its halo, shadow and hops
|
|
64
|
+
look // turns toward the pointer on a desktop (default true)
|
|
65
|
+
react // smiles and bounces when the link or button it's in is hovered (default true)
|
|
66
|
+
pet // clicked, it's petted, and the link it's in doesn't open (default true)
|
|
67
|
+
grab={false} // dragged, it turns, springing home when let go
|
|
68
|
+
still={false} // drawn once, never moving
|
|
69
|
+
drain={0} // 0 to 1: greys it, for an agent running out of budget, say
|
|
70
|
+
/>
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
To set it outright rather than by mood: `expression` (one of `EXPRESSIONS`: `neutral`, `happy`,
|
|
74
|
+
`sad`, `tired`, `thinking`, `working`, `listening`, `speaking`, `sleeping`, `surprised`,
|
|
75
|
+
`trouble`, `love`, `excited`, `failed`) and `motion` (a loop to move in, one of `LOOPS`). `play`
|
|
76
|
+
makes a move now, again whenever its `at` changes:
|
|
77
|
+
|
|
78
|
+
```tsx
|
|
79
|
+
<AgentFigure figure={ada} play={{ motion: "spin", at: Date.now() }} />
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
The moves are `MOVES` (`hop`, `bounce`, `spin`, `turn`, `flip`, `nod`, `shake`, `wave`, `pop`,
|
|
83
|
+
`melt`, `love`) and the reactions `REACTIONS` (`pet`, `celebrate`, `fail`, `start`, `doze`,
|
|
84
|
+
`wake`). `aim` (`{ x, y }`, −1 to 1 each way, right and down) says where it looks, in place of the
|
|
85
|
+
pointer; `lift` (a function of the frame's time, 0 to 1) hops it off the ground as it walks, its
|
|
86
|
+
shadow staying put. Both are read every frame. `className` and `style` go on its box, after its own
|
|
87
|
+
styles.
|
|
88
|
+
|
|
89
|
+
Every figure on a page notices the others: when one is petted, finishes or fails, the rest turn
|
|
90
|
+
to look, and now and then one glances at whichever is busy. A hover on a link or button the
|
|
91
|
+
figure is in makes it smile; to react to another element's hover, mark it `data-figure-host`.
|
|
92
|
+
|
|
93
|
+
It's a drawing, hidden from assistive tech: put words beside it saying who it is and what it's
|
|
94
|
+
doing. It holds still under reduced motion and while it's off screen, and where there's no WebGL 2
|
|
95
|
+
it's a flat drawing instead.
|
|
96
|
+
|
|
97
|
+
## Colours
|
|
98
|
+
|
|
99
|
+
Each colourway is three colours, `main`, `light` and `deep`, which its material flows through
|
|
100
|
+
(`COLOURWAYS`: blue, green, sun, pink, violet, teal, orange, red). Give one your own with
|
|
101
|
+
`colours`, and the eyes theirs with `ink` (`INK`, a near black, unless you do). Any CSS colour
|
|
102
|
+
works, and a custom property is read from the page's root, so your tokens stay the one place
|
|
103
|
+
they're said:
|
|
104
|
+
|
|
105
|
+
```tsx
|
|
106
|
+
<AgentFigure figure={ada} colours={{ main: "var(--brand)", light: "var(--brand-light)", deep: "var(--brand-deep)" }} ink="var(--ink)" />
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
`AgentDot` is a figure's colours alone, as a dot, where a whole figure wouldn't read (a table's
|
|
110
|
+
row): `<AgentDot figure={ada} size={8} />`, with `colours` too.
|
|
111
|
+
|
|
112
|
+
## A still
|
|
113
|
+
|
|
114
|
+
`svgOf(figure, expression?, colours?, size?, id?)` writes a figure as an SVG file, seen from the
|
|
115
|
+
front: for an email, a social card, anywhere a live figure can't go. It runs anywhere, Node
|
|
116
|
+
included.
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
import { figureFor, svgOf } from "@cesarvenzac/figures";
|
|
120
|
+
|
|
121
|
+
svgOf(figureFor("Ada"), "happy", {}, 128); // '<svg xmlns="http://www.w3.org/2000/svg" …'
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## Cost
|
|
125
|
+
|
|
126
|
+
Every figure on a page is drawn by one WebGL 2 context, raymarching the shapes in a fragment
|
|
127
|
+
shader, and copied onto its own canvas; the canvas is at most 512 device pixels across, and a
|
|
128
|
+
figure is drawn every frame only while something happens, every other frame while it only
|
|
129
|
+
breathes, and not at all off screen. They all share one frame loop and one pointer listener.
|
|
130
|
+
|
|
131
|
+
## Development
|
|
132
|
+
|
|
133
|
+
```sh
|
|
134
|
+
npm ci
|
|
135
|
+
npm test
|
|
136
|
+
npm run typecheck
|
|
137
|
+
npm run check # packed as npm publishes it, then installed and run as a user's would be
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
This repository is a copy. The package is developed inside the site it was made for, whose
|
|
141
|
+
repository is private, and every release copies it here and publishes it to npm from here, with
|
|
142
|
+
provenance. Issues are welcome; pull requests are read, and their changes made at the source.
|
|
143
|
+
|
|
144
|
+
## Licence
|
|
145
|
+
|
|
146
|
+
MIT. The material is the one the site's Aura experiment drew, on MaterialX's Perlin noise.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import type { Loop, Reaction, Shape } from "./figure.ts";
|
|
2
|
+
import { type Bit, type Pose, REST } from "./figure-pose.ts";
|
|
3
|
+
/**
|
|
4
|
+
* What each shape does its own way, as the cube solves itself like a Rubik's cube while it thinks:
|
|
5
|
+
* pure functions of time, giving a pose (figure-pose.ts) with the shape's own parts.
|
|
6
|
+
*
|
|
7
|
+
* Reactions, once, `p` from 0 to 1 (`actAt`):
|
|
8
|
+
* - Petted: heart eyes and hearts floating up; the cube twirls its top layer, the sphere dents and
|
|
9
|
+
* ripples like jelly, the pyramid leans like jelly, the block's dials rock as it purrs, the
|
|
10
|
+
* cloud's puffs bounce one after another.
|
|
11
|
+
* - A run finished: starry eyes and sparks; the cube bursts into its cubelets, twisting, and snaps
|
|
12
|
+
* back; the sphere splashes into droplets that fly out and run back together; the pyramid
|
|
13
|
+
* launches its capstone, spinning, and catches it; the block spins its dials like a slot machine,
|
|
14
|
+
* the eyes coming round last; the cloud's puffs pop and a rainbow sweeps over it.
|
|
15
|
+
* - A run failed: × × eyes and drained colour; the cube's layers glitch and it slumps; the sphere
|
|
16
|
+
* deflates, wrinkled, and fills again; the pyramid's slabs slip sideways and back; the block's
|
|
17
|
+
* dials jam and jerk; the cloud storms, rain and lightning.
|
|
18
|
+
* - Work starting, switched off, switched on: a determined nod, a yawn as the eyes close, a
|
|
19
|
+
* stretch as they open wide; each shape turning a layer, a capstone or its dials its own way.
|
|
20
|
+
*
|
|
21
|
+
* Loops, at `t` seconds, as strong as `env` (0 to 1: how far it has come in, or gone out)
|
|
22
|
+
* (`actLoopAt`): thinking, the sphere's moons orbit, the pyramid's capstone floats and turns, the
|
|
23
|
+
* block's dials turn like a cryptex's, the cloud boils (the cube's Rubik's turns are
|
|
24
|
+
* rubik.ts); at work, the cube's layers tick like clockwork, the sphere's colour rolls
|
|
25
|
+
* with a moon going round, the capstone stamps, the block's side dials roll like wheels, the cloud
|
|
26
|
+
* rains; asleep, z's rise and the cube's cubelets loosen; worried, goosebumps, a rattle, a grey
|
|
27
|
+
* drizzle. A loop that turns something (`QUANTUM`) comes back to where it started every so many
|
|
28
|
+
* seconds, so it can stop there.
|
|
29
|
+
*/
|
|
30
|
+
/** Where in the picture a shape's top is, as it rests (world units from the picture's middle). */
|
|
31
|
+
export declare const topOf: (shape: Shape) => number;
|
|
32
|
+
/** Where in the picture its middle is. */
|
|
33
|
+
export declare const middleOf: (shape: Shape) => number;
|
|
34
|
+
/** Hearts floating up from above its head, one after another from `from`, each living `life` of the move. */
|
|
35
|
+
export declare function hearts(p: number, shape: Shape, from: number, every: number, life: number, count: number): Bit[];
|
|
36
|
+
/** Sparks round it, popping one after another from `from`, each living `life`. */
|
|
37
|
+
export declare function sparks(p: number, shape: Shape, from: number, life: number): Bit[];
|
|
38
|
+
/** Z's asleep: one rising every 2.2 seconds, each for 3.3, the first once it has had time to doze off. */
|
|
39
|
+
export declare function zs(t: number, shape: Shape, strength?: number): Bit[];
|
|
40
|
+
/** Where a reaction has got to `p` of the way through (0 to 1), for a shape, at an energy's amplitude. */
|
|
41
|
+
export declare function actAt(act: Reaction, p: number, shape: Shape, amp?: number): Pose;
|
|
42
|
+
/**
|
|
43
|
+
* How often each shape's loop comes back to where it started, in seconds at lively energy: a
|
|
44
|
+
* loop that turns its parts stops only then, so nothing jumps. 0 is any time. The thinking cube's
|
|
45
|
+
* Rubik's turns finish their own round (figure-motion.ts).
|
|
46
|
+
*/
|
|
47
|
+
export declare const QUANTUM: Record<Loop, Record<Shape, number>>;
|
|
48
|
+
/** How long a loop's own act takes to come in and to go out, in seconds. */
|
|
49
|
+
export declare const ENVELOPE: {
|
|
50
|
+
readonly in: 0.6;
|
|
51
|
+
readonly out: 0.5;
|
|
52
|
+
};
|
|
53
|
+
/** Where a shape's own loop act is at `t` seconds, as strong as `env`. */
|
|
54
|
+
export declare function actLoopAt(loop: Loop, t: number, shape: Shape, amp?: number, env?: number): Pose;
|
|
55
|
+
export { REST };
|