# Figures: Getting started

> Install Figures, put a figure beside an agent's name, and keep the four choices a figure is made of.

Source: https://cesarvenzac.com/figures/docs/getting-started

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

Plain TypeScript, published as ES modules with their types, and no dependencies. The main entry runs anywhere, Node included; the live figure is `@cesarvenzac/figures/react`, with React 18 or later as a peer.

## A first figure

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

export function Agent({ name, busy }: Props) {
  return (
    <span className="agent">
      <AgentFigure
        figure={figureFor(name)}
        mood={busy ? "working" : "idle"}
        size={40}
      />
      {name}
    </span>
  );
}
```

`size` is its box in pixels, 48 unless said. Its canvas is half as big again, overhanging the box on every side for its halo, its shadow and its hops, and lets the pointer through. A figure is a drawing, hidden from assistive tech, so put words beside it: who it is and what it's doing.

## Four choices

A figure is plain data, to keep wherever you keep the agent:

```typescript
type Figure = {
  shape: "cube" | "sphere" | "pyramid" | "block" | "cloud";
  energy: "calm" | "lively" | "bouncy";
  habit: "look" | "hum" | "nap" | "spin" | "wave" | "morph";
  palette: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
};
```

- **Shape**: a cube, a sphere, a pyramid, a block or a cloud, each with acts of its own.
- **Energy**: how big and quick it moves. Calm is smaller and slower, bouncy bigger and quicker.
- **Habit**: what it does while it waits: looks around, hums, naps, spins, wobbles or changes shape for a beat.
- **Palette**: its colourway, blue, green, sun, pink, violet, teal, orange or red ([Colours](https://cesarvenzac.com/figures/docs/colours)).

`figureFor(word)` picks all four from a word, the same word always the same figure. `readFigure(value)` reads a stored one back, taking any part missing or unknown from `DEFAULT_FIGURE`, and `isFigure(value)` says whether a value is a whole figure, for a form to check before it saves.

```typescript
import { figureFor, readFigure } from "@cesarvenzac/figures";

figureFor("Ada");
// { shape: "sphere", energy: "calm", habit: "wave", palette: 6 }
readFigure(JSON.parse(stored)); // never throws
```

## On a server

`AgentFigure` is a client component (`"use client"`): a server draws its box and canvas, and it draws itself once the page runs, fading in. Elsewhere it's a component like any other.

## Figures's docs

- [Overview](https://cesarvenzac.com/figures.md): Small 3D figures for your agents, saying what each is doing with two eyes and the way they move.
- [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.