# Figures

> Small 3D figures for your agents, saying what each is doing with two eyes and the way they move.

Source: https://cesarvenzac.com/figures

Package: [@cesarvenzac/figures](https://www.npmjs.com/package/@cesarvenzac/figures) 0.1.0 on npm, MIT licence. Source code: https://github.com/cesarvenzac/figures

```sh
npm install @cesarvenzac/figures
```

*Live example on the page: Make one. Click it to pet it, drag it to turn it round. Shuffle makes one from a word.* Its source:

```tsx
// A figure is four choices, kept as they are on the desk: its
// shape, its colourway, its energy, and what it does while it
// waits. No mouth, no hats, no arms or legs.
type Figure = {
  shape: "cube" | "sphere" | "pyramid" | "block" | "cloud";
  palette: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
  energy: "calm" | "lively" | "bouncy";
  habit: "look" | "hum" | "nap" | "spin" | "wave" | "morph";
};

// Made from a word, the same every time: a hash of it seeds a
// small generator, which picks each part.
const figure = figureFor("Filmmaker");

// Drawn in 3D by one shader for the whole page. Clicked, it's
// petted; dragged, it turns round and springs home.
<AgentFigure figure={figure} size={168} grab />
```

Figures are small characters for the agents in your interface: a cube, a sphere, a pyramid, a block or a cloud, in 3D, with two eyes painted on its face. No mouth, no arms, no hats: they say what the agent is doing with their eyes and the way they move, waiting, thinking, at work, done, in trouble or asleep, and they react as that changes.

## Use

```tsx
import { figureFor } from "@cesarvenzac/figures";
import { AgentFigure } from "@cesarvenzac/figures/react";

<AgentFigure figure={figureFor("Ada")} mood="thinking" />;
```

`figureFor` makes a figure from any word, an agent's name say, the same word the same figure every time. Give it a mood and it acts it out.

## What it does

- **Real 3D, one shader.** Five solids found by raymarching in a fragment shader, one WebGL 2 context for every figure on the page, in an iridescent material in eight colourways or colours of your own.
- **Eyes that say it.** Fourteen expressions: lids cut into the eyes, or the eyes become a shape, ^ ^, stars, hearts, × ×, morphing from one into the next.
- **Moods it acts out.** Waiting, thinking, at work, done, in trouble, asleep, each shape its own way: the cube solves itself like a Rubik's cube while it thinks. As the mood changes, it reacts.
- **Alive on the page.** They follow the pointer on a desktop, turn to look when another celebrates or fails, are petted when clicked, and have a habit while they wait.
- **Quiet when it should be.** Still under reduced motion and off screen, a flat drawing where there's no WebGL 2, hidden from assistive tech, and no stylesheet to load.

How they're made, from the shader to the faces, is in [Figures](https://cesarvenzac.com/lab/figures) in the Lab.

## Docs

- [Getting started](https://cesarvenzac.com/figures/docs/getting-started.md): Install Figures, put a figure beside an agent's name, and keep the four choices a figure is made of.
- [Moods and moves](https://cesarvenzac.com/figures/docs/moods.md): What a figure shows for each mood, how it reacts as one changes, its fourteen faces, and the moves it makes on demand.
- [Colours and stills](https://cesarvenzac.com/figures/docs/colours.md): Its eight colourways or colours of your own, your design tokens included, a dot of its colours, and a still for anywhere a live figure can't go.
- [API reference](https://cesarvenzac.com/figures/docs/api.md): Everything the package exports, entry by entry: the figures as data, and the React components with every prop.