# Agent API: controls, settings, state and glossary

This extends the page's agent API (`window.unrollView`, `window.unroll`). Everything a person can do with the
buttons, an agent can do here, by URL, or by keyboard. All controls are real `<button>`, `<select>`,
`<input>` elements with an `aria-label`, a stable `id` and a `data-action` (or `data-setting`).

## Actions

```js
unrollView.actions.list()          // [{ name, label, control, arg }]
unrollView.action('layer.gpu')     // same as unrollView.actions.run(name, arg)
unrollView.action('seek', 0.5)     // 0 rolled .. 1 unrolled
unrollView.action('destroy', true) // toggles take an optional boolean
```

| Action | Control id | Key | Argument |
| --- | --- | --- | --- |
| `play` | `play` | Space | optional boolean |
| `rollUp` | `btnRollUp` | U | |
| `seek` | `scrubIn` | Home, End, arrows | number 0 to 1 |
| `layer.xray`, `layer.ink`, `layer.gpu` | `.chip[data-layer]` | 1, 2, 3 | |
| `read` | `btnRead` | R | |
| `resetView` | `uiReset` | V | |
| `fullscreen` | `uiFull` | F | |
| `settings` | `btnSettings` | S | optional boolean |
| `help` | `btnHelp` | ? | |
| `about` | `btnInfo` | I | |
| `glossary` | `uiGlossOpen` | | optional term |
| `open` | `btnOpen` | | |
| `bench` | `btnBench` | | |
| `picture` | `btnShot` | | |
| `install` | `uiInstall` | | |
| `skipIntro` | `skipIntro` | Enter or Esc during the intro | |
| `destroy` | `btnTear` | T | optional boolean |
| `tool.tear`, `tool.crush`, `tool.burn`, `tool.water` | `toolTear`, `btnCrush`, `toolBurn`, `toolWater` | X, C, B, W | |
| `damage.reset` | `btnReset` | | |
| `crumble` | `btnCrumble` | K | |
| `sandbox` | `btnSandbox` | | optional boolean |
| `shake` | `btnShake` | | |
| `sound` | `btnSound` | | optional boolean |
| `prizeOnly` | `prizeOnly` | | optional boolean |
| `moreControls` | `uiFold` | | (small screens) |
| `scroll` | `scrollSel` | | scroll id |

Tool actions switch Destroy on first when needed.

## Settings

```js
unrollView.settings.list()                 // definitions with current values
unrollView.settings.get('quality')         // or get() for all
unrollView.settings.set('speed', 2)        // or set({ quality: 'low', hud: false })
unrollView.settings.reset()
unrollView.settings.open() / .close()
```

| Key | Values | Default |
| --- | --- | --- |
| `quality` | `low`, `medium`, `high` (pixel ratio; low also turns the glow off) | `high` (`medium` on touch) |
| `reducedMotion` | boolean | system setting |
| `speed` | 0.25 to 4 (intro, unroll and roll up) | 1 |
| `bloom` | 0 to 2 (glow) | 1 |
| `background` | `dark`, `black`, `slate`, `warm` | `dark` |
| `hud` | boolean (title, readout, credit) | true |
| `labels` | boolean (text under the View icons) | true |
| `sensitivity` | 0.25 to 3 (orbit, zoom and pan speed) | 1 |
| `inkBench` | boolean (show the Ink Bench button) | true |
| `units` | `metric`, `imperial` (readout) | `metric` |

Choices are saved in `localStorage` under `unroll.settings.v1`.

## URL parameters

Any setting: `?quality=low&speed=2&hud=0&units=imperial`. These apply for one visit and are not saved.
Actions: `?layer=gpu`, `?destroy=1`, `?tool=burn`, `?pos=0.5`, `?play=1`, `?panel=settings`.

## State

```js
unrollView.state()      // object
unrollView.stateJSON()  // the same as a JSON string
```

Fields: `scroll`, `layer`, `layers`, `position`, `playing`, `rollingUp`, `winding`, `destroy`, `tool`,
`sandbox`, `sound`, `panels` (settings, help, about, open, closeup, bench), `fullscreen`, `settings`, `actions`.

## Glossary

Plain language definitions of every term the page uses, alphabetical, in `glossary.json` and in the page:

```js
unrollView.glossary.list()          // [{ id, term, aliases, def }]
unrollView.glossary.get('patch')    // by id, term or alias
unrollView.glossary.search('scan')
unrollView.glossary.open('voxel')   // opens About at that entry
```

Jargon in the page text has a dotted underline that opens its entry.

## Intro and picking

`unrollView.introActive()`, `unrollView.skipIntro()`. `unrollView.pickMode()` is `gpu-float`, or `cpu` on GPUs
without float render targets, where Destroy picks the surface on the CPU (`unrollView.cpuPick(x, y)`).