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

# Installation

> Requirements, start order and the first start.

## Requirements

* OneSync.
* [`ug-core`](https://ugcore.urging.ch/introduction) with the **characters** module enabled. The **accounts**, **jobs** and **gangs** modules are optional: without accounts everything is free, without jobs and gangs there are no job stores or uniforms.
* [`ug-lib`](https://ugcore.urging.ch/ug-lib/introduction), for store points, prompts, key bindings and the shared theme.
* `oxmysql`. The resource creates its tables, `ug_appearances` and `ug_outfits`, on the first start.

## Download

Download `ug-appearance-vX.Y.Z.zip` from the [releases](https://github.com/ugcore-project/ug-appearance/releases) and extract it into your resources folder, for example `resources/[ug]/ug-appearance`.

> [accordion] Building from source
>
> The repository does not contain the built page. Build it once with Node.js 20.19 or newer:
>
> ```bash theme={"dark"}
> cd resources/[ug]/ug-appearance/web
> npm ci
> npm run build
> ```
>
> The build goes to `web/dist`, which the manifest serves.

## Start order

```bash server.cfg theme={"dark"}
ensure oxmysql
ensure ug-lib
ensure ug-core
ensure ug-appearance
ensure ug-multicharacter
```

Start `ug-appearance` before `ug-multicharacter`. Character selection then uses the creator and shows every character in its own look. See [Character selection](https://ugcore.urging.ch/ug-appearance/integration.md#character-selection).

To let staff open the full editor on any player, grant the ACE:

```bash server.cfg theme={"dark"}
add_ace group.admin ug-appearance.admin allow
```

> [!WARNING]
>
> Run only one appearance resource. Others that set ped components, open clothing menus or save skins conflict with this one.

## First start

The server console prints:

```text theme={"dark"}
[INFO] Generated config.lua.
[ug-appearance] v1.0.0 ready: 28 stores, 2 models.
```

When a player opens a store or saves, their F8 console prints:

```text theme={"dark"}
[ug-appearance] Editor opened: clothing.
[ug-appearance] Saved clothing for 160.
```

When something is wrong, the resource logs every problem and stays idle instead of half working:

```text theme={"dark"}
[ERROR] config.lua: unknown key "maxOutfit". Did you mean "maxOutfits"?
[ERROR] Config invalid: 1 error(s). ug-appearance stays idle.
```

```text theme={"dark"}
[ERROR] ug-core's characters module is disabled. Enable it in ug-core's config/modules.lua.
[ERROR] ug-appearance stays idle.
```

> [!NOTE]
>
> The default store coordinates are the game's shop doors. Check each one on your server and move the ones your map changes. See [Stores and uniforms](https://ugcore.urging.ch/ug-appearance/stores.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.