# Figures: API reference

> Everything the package exports, entry by entry: the figures as data, and the React components with every prop.

Source: https://cesarvenzac.com/figures/docs/api

Two entries: the main one, which runs anywhere, Node included, and `@cesarvenzac/figures/react`.

## The main entry

### figureFor(seed)

A figure made from any word: the same word, the same figure.

```typescript
function figureFor(seed: string): Figure;
```

### readFigure(value), isFigure(value)

A stored figure read back, any part missing or unknown taken from `DEFAULT_FIGURE`; and whether a value is a whole figure.

```typescript
function readFigure(value: unknown): Figure;
function isFigure(value: unknown): value is Figure;
```

### reactionTo(from, to)

The reaction a figure plays as its mood changes from one to the other, or `null`.

```typescript
function reactionTo(from: Mood, to: Mood): Once | null;
```

### svgOf(figure, expression?, colours?, size?, id?)

A figure as an SVG file, seen from the front.

```typescript
function svgOf(
  figure: Figure,
  expression?: Expression, // "neutral"
  colours?: Partial<Colourway & { ink: string }>,
  size?: number, // 100
  id?: string, // "figure", its gradient's name
): string;
```

### Types

```typescript
type Shape = "cube" | "sphere" | "pyramid" | "block" | "cloud";
type Energy = "calm" | "lively" | "bouncy";
type Habit = "look" | "hum" | "nap" | "spin" | "wave" | "morph";
type Palette = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
type Figure = {
  shape: Shape;
  energy: Energy;
  habit: Habit;
  palette: Palette;
};
type Mood =
  | "idle" | "thinking" | "working"
  | "happy" | "trouble" | "sleep";
type Expression = (typeof EXPRESSIONS)[number];
type Loop = (typeof LOOPS)[number];
type Reaction = (typeof REACTIONS)[number];
type Once = (typeof ONCE)[number]; // a move or a reaction
type Motion = Loop | Once;
type Colourway = { main: string; light: string; deep: string };
```

### Constants

- `SHAPES`, `ENERGIES`, `HABITS`, `PALETTES`, `MOODS`: every value of each.
- `EXPRESSIONS`: the fourteen faces.
- `LOOPS`: how a figure moves while it stays in a mood: breathe, work, think, float, rest, worry.
- `MOVES` and `REACTIONS`, both in `ONCE`, and every loop and move in `MOTIONS`.
- `COLOURWAYS`: the eight colourways, by number. `INK`: the eyes' near black.
- `DEFAULT_FIGURE`: what `readFigure` fills in from, a lively sphere in blue that looks around.

## @cesarvenzac/figures/react

### AgentFigure

A live figure, drawn with WebGL 2. [Moods and moves](https://cesarvenzac.com/figures/docs/moods) says what each prop does.

```typescript
function AgentFigure(props: {
  figure: Figure;
  mood?: Mood; // "idle"
  expression?: Expression; // in place of its mood's
  motion?: Motion; // a loop, in place of its mood's
  play?: { motion: Motion; at: number }; // a move, now
  size?: number; // its box, in pixels: 48
  look?: boolean; // follows the pointer: true
  react?: boolean; // smiles when what it's in is hovered: true
  pet?: boolean; // petted when clicked: true
  still?: boolean; // drawn once: false
  grab?: boolean; // turned by dragging: false
  drain?: number; // 0 to 1, greys it: 0
  aim?: { x: number; y: number }; // where it looks, −1 to 1
  lift?: (now: number) => number; // off the ground, 0 to 1
  colours?: Colourway; // its colourway's
  ink?: string; // INK
  className?: string;
  style?: CSSProperties; // after its own
}): JSX.Element;
```

### AgentDot

A figure's colours alone, as a dot.

```typescript
function AgentDot(props: {
  figure: Figure;
  colours?: Colourway; // its colourway's
  size?: number; // 8
  className?: string;
  style?: CSSProperties;
}): JSX.Element;
```

## 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.