> 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/changelog.md).

# Changelog

## 1.0.2

* **NUI cursor not responding on first join (second round).** Causes left after 1.0.1: (1) the focus was re-asserted for 4 s from OUR call to `ShutdownLoadingScreenNui`, but the loadscreen (`loadscreen_cursor`) releases the focus when the engine really unmounts its frame, which on a first join (cold cache, long streaming) can happen later; (2) after that window the focus was re-applied only if `IsNuiFocused()` was false, but the cursor can disappear while the keyboard focus is still active (arrows work, mouse does not). Now, with one of our UIs open and the NUI `ready`, `SetNuiFocus` is re-applied every 150 ms for 10 s from every screen opening (`*:open`) and from the loadscreen shutdown, and then always every 1 s with no condition (idempotent). ESC (`escGuard` / `escGate`) is unchanged.
* The NUI `ready` handshake was a single fetch with no retry: on a cold start, if it reached Lua before the callbacks were registered it failed silently, `Nui.ready` stayed false and the focus was never applied. The UI now repeats it every 750 ms until it receives `init` (max 45 s; Lua is idempotent).

## 1.0.1

* **Cursor always visible on first join.** Cause: the NUI focus was given only once in `stage.enter`, while the loadscreen (`loadscreen_cursor`) was still active, and `ShutdownLoadingScreenNui` (on the scene reveal, later) releases the focus, cancelling ours: invisible pointer and arrow keys only. Now `Nui.focus` records the intent, applies it only after the `ready` handshake, forces it every cycle for 4 s after the loadscreen closes and re-asserts it if `IsNuiFocused()` is false; `SetNuiFocusKeepInput(false)` always. Selection, creation, spawn and pause all go through `Nui.focus`.
* **ESC only goes to the UI.** In selection, creation, spawn and the pause menu, ESC does the UI action (back / close; nothing in the main selection) and no longer opens the GTA map / pause menu: before, the pause thread let ESC through (`pass`) when the NUI had the focus. Now controls 199/200 are disabled every frame while the UI is open and for 500 ms after it closes (and while the key is held); if the pause opens anyway, `SetPauseMenuActive(false)`. The native pages opened from the pause (map, settings, keys) are untouched.
* **ESC closes only the UI that receives it, never our pause menu by mistake.** Cause: the pause thread opened the menu on the RELEASE of ESC; when another resource (HUD, weapon editor, OX, radio) closed its UI with ESC, the release arrived after `IsNuiFocused()` went back to false and opened our menu. Now the menu opens only if the PRESS also happened with no foreign UI (`L.escGate`), and for 500 ms after the last foreign UI (or after the ESC guard of `nui.lua`) ESC opens nothing. `DEBOUNCE_MS` raised from 250 to 500 ms (like the tail of the ESC guard) so the menu does not reopen right after closing. Test in `tests/t_pause.lua`.

## 1.0.0

First release for sale.

### Relog and pause menu

* **"Switch character" removed from the pause menu**: only `Relog` is left to go back to the selection. The entry, the C shortcut, the confirmation and the texts are removed from the NUI, along with the `pause:action(switch)` action and the `switch.request` RPC (the server refuses it as unknown: no client can go back to the selection without the relog countdown, which is server-side only). `Config.Pause.changeCharacter.enabled` is removed (the other rules - cooldown, dead, cuffed, damage, vehicle, ACE - stay and apply to the relog; an old `enabled` is ignored). `Config.Select.command` now starts the relog with the countdown. Forced logout by staff is unchanged.
* **`/relog`** (`Config.Relog`): command with a configurable name, optional key (`RegisterKeyMapping`, empty by default) and pause button. No confirmation to repeat: the server validates, the ped freezes (invincible, controls blocked) with a countdown of `countdownSec` seconds (5) **run by the server** (the client cannot shorten it), death or handcuffs cancel and release, at the end the server re-checks the rules, saves, logs out and goes back to the selection. `confirm` / `confirmSec` removed (old configs stay valid: the fields are ignored).
* **Transitions** (`Config.Transition`): relog, character change and forced logout fade out (750 ms), wait for the scene (at most 3.5 s) and fade in (700 ms) with a matching NUI veil; before, the screen went black at once.
* **Pause menu redone**: settings (scale, accent, language, contrast, audio...) apply instantly in the menu and in the whole UI from a single shared state, with a debounced KVP save written on close. Character card and server info with live data (money, job, hours, players, ping, time; `pause.live` every 5 s ONLY while open), quick actions with icons and shortcuts, full keyboard and gamepad support, blocked states explained under the entry, enter and exit animations with no flash.

### Loadscreen and editor

* **Customizable loadscreen** (`loadscreen/`): `loadscreen` + `loadscreen_manual_shutdown 'yes'` + `loadscreen_cursor 'yes'` in the manifest, a vanilla page separate from the NUI (gradient, image, slideshow or local video; logo and name; colors; music with volume and mute; tips; links; real progress bar from FiveM's messages). One config, `loadscreen/config.json` (curated ice-blue defaults, per-field fallback validation, warnings only in the console), assets in `loadscreen/media/`. Closed only by `Loading.shutdownNative` (also in passive mode and on error) with the `Config.Loadscreen.watchdogSec` watchdog. `gmc selftest` reports other loadscreens running (FiveM uses only one).
* **Local web editor** (`editor.bat` / `editor.sh`): 127.0.0.1 only, random token, Host / Origin / Sec-Fetch-Site checks, size limits, writes only inside `loadscreen/`; live preview of the real loadscreen, autosave with `config.prev.json` backup, upload with magic-byte checks, "Restore defaults".

### Selection

* **Single-scene selection, chosen with the mouse.** All the account's characters together (up to 10, `Config.Scenes.maxPeds`) on the LSIA hangar apron, in a staggered half circle, all different poses, golden hour and `CLEAR`, no DOF. Spots checked at runtime (flat ground, no wall / object / vehicle in the silhouette: moved or replaced), group camera computed from the number of characters and the real entities, verified with `IsEntityOnScreen` for each one (it widens if needed). Free slot = glowing placeholder (click = create). Hover = outline and name tag; click = card and "Play"; double click / Enter = play; arrows always active. The clickable boxes come from Lua. The other default scenes, the "Scene" button, the `solo` mode, the in-game editor and the share codes are gone (`/gmc scene` now lists the scenes; edit them in `data/scenes.json` + `/gmc reload`); `Config.Select.mode/sceneAssignment/scenes/jobScenes/allowSceneChoice` and `Config.Scenes.dof/shake/frostMs/ensembleMs/ensembleMaxPeds` are removed; `Config.Scenes.selectScene` and `maxPeds` are new. Smaller UI: compact card and a dot indicator in place of the slot strip.
* **Lively apron.** The characters are spread over the apron in 10 curated fixed spots (`ensemble.spots` in `data/scenes.json`: 3-6 m between neighbours, different depths, 3/4 or profile) and each does their own job with game props (wiping with a cloth, coffee, phone, cigarette, clipboard, welding, hammer, blower, broom, leaning, map, watch). The activity is stable per character (hash of name, surname, birth, sex), all different and suited to both sexes; it stays active when selected. Clickable boxes from the head and feet bones (corrected for profile or crouching peds); on cleanup `ClearPedTasksImmediately` and removal of orphan props.
* **Base slots = 1** (`Config.Slots.default`) for new accounts on ESX, QBCore and Qbox; ACE grants, `/gmc slots add` and Tebex unchanged. Drop-in on a running server: until staff sets the base, an account's base (plus any imported slots) covers at least its existing characters (even above `max`; ACE, `/gmc slots add` and Tebex stay on top), so the default never locks an existing character and gives no free slots. Locking stays an explicit staff action (`/gmc char lock`, or `/gmc slots remove|set` with confirmation). The ESX bridge reads characters up to slot 15 even with a lower `max`. In the selection only characters and free slots; with `showLocked` and `unlockUrl` at most ONE lock (before: a row up to `max`).
* `esx_skin`: the look is applied to local peds too (skinchanger format applied with natives, like `SkinChanger:ApplySkin`): with ESX every character is shown dressed together.
* Optimizations: the look of all characters in a single RPC (`select.looks`, cached in the session), cached `scene.list` response with only the two scenes in use, no server polling in the pause menu, per-frame lights precomputed, weather and time re-asserted 1/s, selection boxes sent only when they change, full cleanup also of outlines and the placeholder. UI: only the latin font subsets (`web/dist` from 670 KB to 550 KB), code of the multiple scenes and of the editor removed.

### Fixes

* Scene framing redone. Causes: identity set at z -99 (below the map of a missing qbox shell: camera on an underground object), default scenes with unverified coordinates / heading, FOGGY / XMAS weather and active DOF (with the ped out of focus the whole frame was blurred / grey), camera computed from scene numbers and not from the ped. Now: default scenes only from qb-spawn, esx\_multicharacter, qb-multicharacter and qbx\_core (file:line in `source`, `verified: true`), studio outdoors (qbx\_core defaultSpawn), the others optIn `verified: false`; validation that discards non-optIn scenes under z -50; ped placed on the ground with verified ground and made visible; camera from `GetOffsetFromEntityInWorldCoords` + `PointCamAtPedBone`, verified at runtime (IsEntityOnScreen, 1.2-8 m) with a safe framing; free slot at 4.5 m; DOF and breathing off by default; `/gmc camdebug`; spawn selector with streaming and camera centred on the real ground and a computed far clip.
* "Create character" fix: `shared/rules.lua` used `os.date` (the `os` library does not exist client-side in FiveM). Now civil date with arithmetic only (`Util.civil`); a static test forbids `os.`, `io.`, `debug.`, `require` and server-only / client-only APIs in the files loaded by the manifest.
* Frost no longer stays full screen: the transition always removes it (pcall) and the NUI releases it by itself after 6 s; transparency test also on semi-transparent layers (alpha > 0.05 outside the UI boxes).
* Scenes: penthouse, eclipse, casino and garage are `optIn` (they need IPL / DLC), no longer default; the default scene is an exterior. Support for `interior { ipl, coords, sets, pin }`: IPL, interior pinned in memory, wait for IsInteriorReady, fallback if it does not arrive. DOF and timecycle clamped in range.
* Spawn selector only on the first spawn of a new character (`Config.Spawn.onlyNewCharacter`, default true); later logins use the last saved position.
* Spawn selector: the aerial camera stays at 500 m (max 1500) and flies to the chosen point; before, with all points in frame, it climbed to about 12 km and the map was not drawn (only the pins).
* UI: no backdrop-filter or animated mask (white / black flicker in CEF on the frost transition); NUI transparency test in FiveM mode.
* Scenes: the camera does not get closer than 60 % of the framing and ignores obstacles under 0.6 m from the ped; `Config.Scenes.dof` and `debug`.

### Features

* Multicharacter, identity with photo, 3D spawn selector and pause menu for ESX Legacy, QBCore and Qbox (`Config.Modules`).
* `/gmc` staff commands (slots, lock, delete, wipe, backup, import, selftest), ACE for every action, Tebex integration from the console.
* Automatic backup before delete and wipe, audit log.
* Appearance adapters: illenium-appearance, fivem-appearance, rcore\_clothing, qb-clothing, esx\_skin, custom.
* Configurable client RPC timeout (`Config.Rpc.clientTimeoutMs`, default 25 s), checked by the selftest against `Config.ESX.joinTimeoutMs` + 5000.
* The appearance creator runs in the player's private routing bucket; bucket 0 on `appearance.done`, on `spawn.done` and on drop.
* Selection: idempotent opening when `forceSelect` and the state push arrive together (one scene, one `select:open`).
* `appearance.done` that fails: 3 attempts, then back to the selection with an error (never stuck in the `appearance` state).
* UI: the "Details" popover covers the whole width of the dossier, the name no longer sticks out.
* Complete Italian and English READMEs (installation per framework, Qbox: the two delete doors, adapters, config, commands, FAQ).


---

# 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/changelog.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.
