> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awokenlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Recorder

> awoken-recorder - bulk-capture the clothing/hair/prop thumbnails for image previews.

`awoken-recorder` is the companion tool that generates the thumbnails the appearance UI uses for [Image Previews](/resources/awoken-appearance/configuration/image-previews). It teleports your ped onto a built-in green screen, screenshots every drawable you select, removes the background, and writes the PNGs in the exact folder layout the appearance resource expects.

<Info>
  You only need the Recorder if you want the **image-preview UI**. If you're happy with number steppers (`Config.UseImagePreviews = false`), you can skip this entirely.
</Info>

## Installation

<Steps>
  <Step title="Add the dependency">
    The Recorder needs [screencapture](https://github.com/itschip/screencapture/releases). Make sure it's present and started before the Recorder.
  </Step>

  <Step title="Drop in the resource">
    Place `awoken-recorder` in your resources. **Keep the folder named `awoken-recorder`** - it self-checks its name and won't start if renamed.
  </Step>

  <Step title="Ensure it">
    Add `ensure awoken-recorder` to your `server.cfg` (after `screencapture`).
  </Step>
</Steps>

<Tip>
  Run captures on a quiet/empty server. The Recorder teleports and freezes your ped on the green screen for the duration, and a full clothing sweep takes a while.
</Tip>

## Capturing images

<Steps>
  <Step title="Open the tool">
    Run **`/recorder`**. The capture UI opens with your accent colour.
  </Step>

  <Step title="Pick gender + categories">
    Choose **male** or **female**, then the categories to capture - components (clothing), props, hair, head overlays - and the specific slots within them.
  </Step>

  <Step title="Start the capture">
    Begin the run. Your ped is moved to the green screen and each selected drawable is screenshotted in turn. A progress bar tracks it.
  </Step>

  <Step title="Stop early if needed">
    Press **F9** (or run `/stopscreenshot`) to abort. Your ped's model, clothes and position are restored automatically when a run ends or is stopped.
  </Step>
</Steps>

<Warning>
  Don't alt-tab away or interfere with the game mid-capture - moving the camera or ped will spoil the screenshots for that run.
</Warning>

## Output & moving the images

Captured PNGs are written to the Recorder's own folder, already in the right structure:

```text awoken-recorder/images/ theme={"dark"}
components/{gender}/{component_id}/{drawable}.png
props/{gender}/{prop_id}/{drawable}.png
hair/{gender}/{style}.png
headOverlays/{overlay_type}/{style}.png
```

To use them, copy the contents of `awoken-recorder/images/` into the appearance resource's `web/dist/images/` folder:

```text theme={"dark"}
awoken-recorder/images/*   →   illenium-appearance/web/dist/images/
```

Then make sure previews are enabled:

```lua shared/config.lua theme={"dark"}
Config.UseImagePreviews = true
Config.ImageBasePath    = "images"
```

## Reviewing captures

The Recorder UI includes a **gallery** so you can browse what's been captured for a category before moving the files - handy for spotting gaps.

## If you get stuck

* **Stuck with a cursor and no ped/control after a run** - run `/reloadskin` (from the appearance resource) to restore your character, or reconnect.
* **`server.js` errors on start** - confirm `screencapture` is started *before* `awoken-recorder`, and that the resource folder is named exactly `awoken-recorder`.