# Viewer API

Everything createViewer accepts, and every command of the viewer it returns.

## createViewer options

The options `createViewer` takes. What the viewer shows can change afterwards through its commands.

- `container` (Default Required): The element the viewer fills. Give it a size.
- `key` (Default Required): Your publishable key.
- `weapon` (Default None): The weapon shown at start.
- `environment` (Default `showroom`): The environment at start: the showroom or a map.
- `background` (Default `environment`): The background at start, an object whose `type` is `environment` (the environment's backdrop), `none` (your page shows behind the item) or `custom`, with the `id` of one of your backdrops, from your [dashboard](https://render.vskin.gg/dashboard). A value the viewer cannot show leaves the environment's backdrop, which `viewer.state.background` then names.
- `watermark` (Default `vskin`): The watermark at start, an object whose `type` is `vskin` (the VSkin watermark tiled behind the item), `custom`, with the `id` of one of your watermarks, from your [dashboard](https://render.vskin.gg/dashboard), or `none` (no watermark). A value the viewer cannot show leaves the VSkin watermark, which `viewer.state.watermark` then names.
- `interactive` (Default `true`): `false` turns off rotation and zoom by the visitor.
- `autoplay` (Default Off): `true` plays the inspect animation on load.
- `locale` (Default `en`): Language of the viewer's messages and notices.

## The vskin-render-viewer element

The element takes the options of `createViewer` as these properties. One with an attribute beside it can also be written as that attribute. A boolean attribute turns its option on unless its value is `false`. An object goes through its property only.

- `viewerKey` (`viewer-key`): The `key` option of `createViewer`.
- `weapon`: The `weapon` option of `createViewer`, as a property only.
- `environment` (`environment`): The `environment` option of `createViewer`.
- `background`: The `background` option of `createViewer`, as a property only.
- `watermark`: The `watermark` option of `createViewer`, as a property only.
- `interactive` (`interactive`): The `interactive` option of `createViewer`.
- `autoplay` (`autoplay`): The `autoplay` option of `createViewer`.
- `locale` (`locale`): The `locale` option of `createViewer`.

What the element gives back: the handle, and two events.

- `viewer`: The viewer's handle once it answers, the one `createViewer` resolves with; `null` before, and once the element has left the page.
- `vskin-render-ready`: The viewer answered: its handle is in `detail.viewer`. Sent again when the element comes back to the page with a new viewer.
- `vskin-render-error`: The viewer could not start: the error is in `detail.error`, the one `createViewer` rejects with, family and code of a refusal included.

## Weapon fields

Name a weapon with `cert`, or with `defIndex` and `paintIndex` plus the fields you need, as in the URL options. Gloves take `cert`, or `defIndex`, `paintIndex`, `seed` and `float`; an agent takes `cert` or `defIndex`.

- `cert`: The item's certificate, returned for every item by Steam's public inventory API. Renders the exact item, cosmetics included. Recent inspect links end with it; older ones carry none.
- `defIndex`: Item definition index (defindex). Required with the paint kit index.
- `paintIndex`: Paint kit index. Required with the defindex; `0` for an agent or a weapon without a skin.
- `seed`: Pattern seed.
- `float`: Wear (float).
- `stattrak`: Adds a StatTrak™ counter.
- `kills`: The count on the StatTrak™ counter.
- `name`: Name tag text.

## Cosmetic fields

The fields of the cosmetics that `setStickers`, `setCharm` and `setPatches` take. The ids are the ones the URL options use.

### Sticker

- `id`: Sticker id.
- `slot`: The slot on the weapon, from 0 to 4.
- `wear`: Wear, from 0 (new) to 1 (scraped off).
- `rotation`: Rotation, in degrees.
- `offsetX`: Horizontal offset from the slot's default position.
- `offsetY`: Vertical offset from the slot's default position.

### Charm

- `id`: Charm id.
- `pattern`: Charm pattern.
- `wrappedSticker`: For a Sticker Slab, the id of the sticker inside.
- `offsetX`: Offset from the weapon's default charm attachment, in the weapon's model space (inches), along X.
- `offsetY`: The same offset, along Y.
- `offsetZ`: The same offset, along Z.

### Patch

- `id`: Patch id.
- `slot`: The patch slot on the agent. `state.patchSlots` says how many the agent has.

> Every command except `destroy` returns a promise: it resolves once the viewer has applied it, and rejects with an error code when it cannot.

## Items

- `setWeapon({ weapon })`: Shows a weapon, or clears it with `null`. A new seed, wear or name tag on the same weapon updates it in place.
- `setGloves({ gloves })`: Shows a pair of gloves, or clears them with `null`.
- `setAgent({ agent })`: Shows an agent, or clears it with `null`.
- `setSubject({ subject })`: With a weapon and gloves both shown, picks the one the free view presents.

## Cosmetics

- `setStickers({ stickers })`: Replaces the weapon's stickers, five at most.
- `setCharm({ charm })`: Attaches a charm, or removes it with `null`.
- `setPatches({ patches })`: Replaces the agent's patches.
- `armPlacement({ target })`: Arms free placement on a sticker or the charm: pressing it in the viewer moves it instead of rotating the item. `null` disarms.
- `forwardPointer({ x, y, phase })`: Hands a pointer from your page to the viewer, in viewport coordinates (`clientX`, `clientY`), so a drag that starts in your own HUD can land on the weapon. `phase` is `start`, `move` or `end`.

## View and camera

- `setView({ view })`: Switches between the free view, first person and third person.
- `setFirstPersonSettings({ fov, offsetX, offsetY, offsetZ, handedness })`: Sets the viewmodel in the game's units: field of view (`viewmodel_fov`), offsets (`viewmodel_offset_x`, `_y`, `_z`) and hand.
- `setFacing({ facing })`: Shows the front or the back of the weapon, pair of gloves or agent on stage. Asking for the current side recenters it. Not available in first person.
- `focus({ target })`: Flies the camera to a sticker, the charm or a patch. `null` flies back.
- `resetCamera()`: Flies the camera back from a focused sticker, charm or patch, like `focus` with `null`.

## Scene, sound and language

- `setEnvironment({ environment })`: Moves the item to another environment.
- `setBackground({ background })`: Shows the environment's backdrop (`environment`), your page behind the item (`none`), or one of your backdrops in place of any scenery, a map's included (`custom`, with its `id`). `custom` is refused with `not_entitled` without the Brand option, and with `invalid_argument` for an id that is not one of your backdrops.
- `setWatermark({ watermark })`: Shows the VSkin watermark tiled behind the item (`vskin`), one of your watermarks, covering the viewer from its center like a backdrop (`custom`, with its `id`), or removes it (`none`). It shows over a map's scenery too: set `none` when you switch to a map you want clear. `custom` is refused with `not_entitled` without the Brand option, and with `invalid_argument` for an id that is not one of your watermarks.
- `setSound({ muted })`: Mutes or unmutes the viewer.
- `setLocale({ locale })`: Changes the language of the viewer's messages and notices.

## Animations

- `play()`: Starts the inspect animation. A visitor's gesture pauses it.
- `pause()`: Pauses the inspect animation.
- `playAnimation({ name })`: Plays one animation by name, from `state.animations` or `state.agentAnimations`.
- `stopAnimation()`: Stops the running animation.
- `setSilentReload({ held })`: Holds or releases your reload key, as in the game: a quick press plays the normal reload, and a key still held just after the reload starts switches it to the weapon's slow, quieter reload.
- `startFire()`: Starts firing, until `stopFire`.
- `stopFire()`: Stops firing.

## Capture

- `capture()`: Returns a PNG of the viewer as a data URL, with the watermark as shown. It carries no VSkin signature, since Native includes the Brand option.

## Lifecycle

- `destroy()`: Removes the viewer and its iframe. Safe to call twice.

## Catalog

Lists to build your own pickers. Each resolves to an object with `total` and `values`, and needs the matching feature in your plan. The lists that take a query accept `search`, `limit` and `offset`.

- `catalog.weapons(query)`: Weapon and glove skins.
- `catalog.stickers(query)`: Stickers.
- `catalog.charms(query)`: Charms.
- `catalog.patches(query)`: Patches.
- `catalog.agents(query)`: Agents.
- `catalog.weaponModels()`: The factory weapons an agent can hold.
- `catalog.environments()`: Environments, with the ids `setEnvironment` takes.

## Inspect links

`buildInspectLink` turns a certificate into the item's in-game inspect link. It needs no viewer.

```ts
import { buildInspectLink } from '@vskin/sdk';

const link = buildInspectLink({
    cert: '80907B511F0241819887A01389A886B089B87A101E7583C05683C880D081E29988819074BD9D76A89CBFAD8080CCC2BD90C5B43DC58004723AE29988839074BD9D8A57A3BFAD80805842BDFAB6EDBEC5B01E1FBCE29988839074BD9DE6E6A6BFAD8080CCC2BD0D1D0BBEC5802E003AE29988839074BD9D1A1999BFAD80807042BD5D8024BEC560F02DBCE29988829073BD9D2EC7A1BFAD8080F0C1BDD01ADDBEC580ABBABBE81C82F0882281978880908CBD3DF845C1C5A99536BECDCFC895C0D05A1C85110C776A',
});
```
