> For the complete documentation index, see [llms.txt](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/usage-guide.md).

# Usage guide

## Character selection

On join the player sees one scene with **every character of the account together** (up to `Config.Scenes.maxPeds`, 10), standing in a staggered half circle facing the camera, each with a different idle pose.

* **Hover** a character: it is highlighted (outline; on builds without the native the others dim) and a small name tag appears above the head.
* **Click** selects: the card appears at the bottom left with the **Play** button. **Double click** or **Enter** plays. The **arrow keys** cycle through the characters.
* The **free slot** is a glowing placeholder (column and ring in the accent colour): click it to create a character. With `showLocked` and an `unlockUrl` at most ONE locked slot is shown (the next one to unlock) with an "Unlock" button that opens the Tebex link.

The clickable areas are computed by Lua (feet and head of every ped projected to the screen, at most 25 Hz and only when they move): preview peds have no collision, so a raycast would not hit them.

## Creating a character (identity)

Choosing a free slot opens the identity step: first name, last name, sex, date of birth and, depending on `Config.Identity.fields`, nationality, height and backstory. The server validates everything again (limits, date format, unique name + surname, blocked words). The ID card with photo is shot in the identity photo set (`studio`).

After identity, `forceCreatorOnNew = true` opens the appearance creator of your appearance script. It runs in the player's private routing bucket. If saving the appearance fails it is retried 3 times, then the player goes back to the selection with an error message, and the creator restarts on re-entry: the player is never left stuck.

## Spawn

With `Config.Spawn.mode = 'ghiaccio'` the 3D selector shows an aerial camera that flies to the chosen point. By default (`onlyNewCharacter = true`) it only appears on the first spawn of a newly created character; later logins enter at the last saved position. Points can be restricted by job, gang or ACE.

## Pause menu

Esc opens the Multicharacter pause menu (`Config.Pause.keyP = 'menu'`): character card, server info with live data (money, job, hours, players, ping, time), quick actions with shortcuts (M map, I server, S settings, G GTA settings, K keys, R relog, D disconnect), keyboard and gamepad. Settings (scale, accent, language, audio...) apply instantly and are saved per player. Esc closes only the UI that has focus: it never opens the pause menu by mistake after another resource's UI closes.

The pause menu is not available in the situations of `Config.Pause.block` (dead and cuffed by default); the reason is shown below the entry.

## Going back to the selection

Players use `/relog` (or the **Relog** button, shortcut `R`). A countdown of 5 seconds runs on the server with the ped frozen; death or handcuffs cancel it. See [Commands & permissions](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/commands-and-permissions.md#relog). There is no immediate "Switch character" entry and players cannot delete characters.

## For staff

* `gmc info <target>` shows an account's characters and slots; `gmc log <target> [n]` its audit log.
* Add slots: `gmc slots add <target> 1` (timed with `--days 30`).
* Lock a character: `gmc char lock <target> <char>`.
* Delete or wipe: `gmc char delete|wipe ...`, then confirm with `/gmc confirm <code>`. A backup is made first and kept 14 days; `gmc backup list <target>` and `gmc backup restore <id>` bring it back.

Full table: [Commands & permissions](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/commands-and-permissions.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/multichar/usage-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
