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

# Changelog

## 1.0.2

* **Cursore NUI che non risponde al primo ingresso (secondo giro).** Cause residue dopo 1.0.1: (1) la riaffermazione del focus durava 4 s dalla NOSTRA chiamata a `ShutdownLoadingScreenNui`, ma il loadscreen (`loadscreen_cursor`) rilascia il focus quando il motore smonta davvero il suo frame, che al primo ingresso (cache a freddo, streaming lungo) può avvenire dopo; (2) dopo la finestra il focus era riapplicato solo se `IsNuiFocused()` era falso, ma il cursore può sparire con il focus tastiera ancora attivo (frecce sì, mouse no). Ora, con una UI nostra aperta e la NUI `ready`, `SetNuiFocus` è riapplicato ogni 150 ms per 10 s da ogni apertura di schermata (`*:open`) e dallo shutdown del loadscreen, e poi sempre ogni 1 s senza condizioni (idempotente). ESC (`escGuard`/`escGate`) invariato. (3) L'handshake `ready` della NUI era un solo fetch senza ritentativo: se su un avvio a freddo arrivava a Lua prima della registrazione dei callback falliva in silenzio, `Nui.ready` restava falso e il focus non veniva mai applicato; ora la UI lo ripete ogni 750 ms fino a ricevere `init` (max 45 s; Lua è idempotente).

## 1.0.1

* **Cursore sempre visibile al primo ingresso.** Causa: il focus NUI veniva dato una sola volta in `stage.enter`, mentre il loadscreen (`loadscreen_cursor`) era ancora attivo, e `ShutdownLoadingScreenNui` (al reveal della scena, dopo) rilascia il focus cancellando il nostro: puntatore invisibile e solo frecce. Ora `Nui.focus` registra l'intenzione, la applica solo a handshake `ready` fatto, la forza a ogni ciclo per 4 s dopo la chiusura del loadscreen e la riaffermata se `IsNuiFocused()` è falso; `SetNuiFocusKeepInput(false)` sempre. Selezione, creazione, spawn e pause passano tutti da `Nui.focus`.
* **ESC solo alla UI.** In selezione, creazione, spawn e pause menu ESC fa l'azione della UI (indietro/chiudi; nella selezione principale niente) e non apre più la mappa/pausa di GTA: prima il thread del pause lasciava passare ESC (`pass`) quando la NUI aveva il focus. Ora 199/200 sono disabilitati ogni frame finché la UI è aperta e per 500 ms dopo la chiusura (e finché il tasto è premuto); se la pausa si apre comunque `SetPauseMenuActive(false)`. Le pagine native aperte dal pause (mappa, impostazioni, tasti) non sono toccate.
* **ESC chiude solo la UI che la riceve, mai il nostro pause menu per errore.** Causa: il thread del pause apriva il menu sul RILASCIO di ESC; quando un'altra risorsa (HUD, editor armi, OX, radio) chiudeva la sua UI con ESC, il rilascio arrivava dopo il ritorno di `IsNuiFocused()` a falso e apriva il nostro menu. Ora il menu si apre solo se anche la PRESSIONE è avvenuta senza UI altrui (`L.escGate`), e per 500 ms dopo l'ultima UI altrui (o dopo la guardia ESC di `nui.lua`) ESC non apre nulla. `DEBOUNCE_MS` portato da 250 a 500 ms (come la coda della guardia ESC) per non riaprire il menu appena chiuso. Test in `tests/t_pause.lua`.

## 1.0.0

Prima versione per la vendita.

* **Via "Cambia personaggio" dal pause menu**: resta solo `Relog` per tornare alla selezione. Rimossi voce, scorciatoia C, conferma e testi dalla NUI, l'azione `pause:action(switch)`, la RPC `switch.request` (il server la rifiuta come sconosciuta: nessun client può più tornare alla selezione senza il countdown del relog, che è solo lato server), i campi `changeCharacter` di `pause:open`/`pause:update` e `change` di `pause.info`/`pause.live`, `Config.Pause.changeCharacter.enabled` (le altre regole - cooldown, morto, ammanettato, danni, veicolo, ACE - restano e valgono per il relog; un vecchio `enabled` è ignorato). `Config.Select.command` ora avvia il relog con countdown. Il logout forzato dello staff non cambia. Test anti-bypass in `tests/t_relog.lua`.
* **`/relog`** (`Config.Relog`): comando con nome configurabile, tasto opzionale (`RegisterKeyMapping`, vuoto di default) e pulsante del pause. Nessuna conferma da ripetere: il server valida, il ped si congela (invincibile, controlli bloccati) con un conto alla rovescia di `countdownSec` secondi (5) **gestito dal server** (il client non lo accorcia), morte o manette annullano e sbloccano, a fine tempo il server ricontrolla le regole, salva, fa il logout e torna alla selezione. `confirm`/`confirmSec` rimossi (le vecchie config restano valide: i campi sono ignorati).
* **Transizioni** (`Config.Transition`, `client/transition.lua`): relog, cambio personaggio e logout forzato fanno dissolvenza in uscita (750 ms), attesa della scena (al massimo 3.5 s) e dissolvenza in entrata (700 ms) con il velo NUI coerente; prima lo schermo diventava nero di colpo (e il cleanup dello stage lo riaccendeva un istante per un lampo).
* **Pause menu rifatto**: le impostazioni (scala, accento, lingua, contrasto, audio...) si applicano subito nel menu e in tutta la UI da un solo stato condiviso (prima il menu leggeva una copia presa all'apertura: cursori ed etichette non cambiavano finché non lo si richiudeva), con salvataggio in KVP ritardato (debounce) e scritto alla chiusura. Scheda del personaggio e info server con dati vivi (soldi, lavoro, ore, giocatori, ping, ora; `pause.live` ogni 5 s SOLO a menu aperto), azioni rapide con icone e scorciatoie (M, I, S, G, K, C, R, D), tastiera e gamepad completi, stati di blocco spiegati sotto la voce, animazioni di ingresso e uscita senza flash. Nuovi: RPC `pause.live` e `relog.cancel`, messaggi NUI `pause:update` e `relog`, evento `relog` (solo aggiunte al contratto).
* **Loadscreen personalizzabile** (`loadscreen/`): `loadscreen` + `loadscreen_manual_shutdown 'yes'` + `loadscreen_cursor 'yes'` nel manifest, pagina vanilla separata dalla NUI (gradiente, immagine, slideshow o video locale; logo e nome; colori; musica con volume e muto; consigli; link; barra di progresso reale dai messaggi di FiveM). Una sola config, `loadscreen/config.json` (default curati in blu ghiaccio, validazione con ripiego per campo e avvisi solo in console), asset in `loadscreen/media/`. Chiusura solo da `Loading.shutdownNative` (anche in modalità passiva e in caso di errore) con watchdog `Config.Loadscreen.watchdogSec`. `gmc selftest` segnala gli altri loadscreen in esecuzione (FiveM ne usa uno solo).
* **Editor web locale** (`editor.bat` / `editor.sh`, `tools/editor-server.ps1` / `.py`): solo 127.0.0.1, token casuale, controllo di Host/Origin/Sec-Fetch-Site, limiti di dimensione, scrive solo in `loadscreen/`; anteprima dal vivo della loadscreen vera, salvataggio automatico con backup `config.prev.json`, upload con controllo dei magic bytes, "Ripristina default".
* **Selezione in una sola scena, scelta col mouse.** Tutti i personaggi dell'account insieme (fino a 10, `Config.Scenes.maxPeds`) sul piazzale dell'hangar di LSIA (qb-garages `config.lua:323`, piano e aperto), a semicerchio scalato verso la camera, pose tutte diverse, ora d'oro e `CLEAR`, niente DOF. Posti controllati a runtime (suolo piano, nessun muro/oggetto/veicolo nella sagoma: spostati o sostituiti), camera di gruppo calcolata sul numero di personaggi e sulle entità reali, verificata con `IsEntityOnScreen` per ognuno (si allarga se serve). Slot libero = segnaposto luminoso (click = crea). Hover = contorno (`SetEntityDrawOutline`, ripiego alpha) e tag col nome; click = scheda e "Gioca"; doppio click/Invio = gioca; frecce sempre attive. Le box cliccabili arrivano dal Lua (piedi e testa proiettati, max 25 Hz e solo se cambiano). Via le altre scene di default, il pulsante "Scena", la modalità `solo`, l'editor in gioco e i codici di condivisione (`/gmc scene` ora elenca le scene; si modificano in `data/scenes.json` + `/gmc reload`); via `Config.Select.mode/sceneAssignment/scenes/jobScenes/allowSceneChoice` e `Config.Scenes.dof/shake/frostMs/ensembleMs/ensembleMaxPeds`; nuovi `Config.Scenes.selectScene` e `maxPeds`. UI più piccola: scheda compatta e indicatore a punti al posto della striscia di slot.
* **Piazzale vivo.** I personaggi sono sparsi sul piazzale in 10 posti fissi curati (`ensemble.spots` in `data/scenes.json`: 3-6 m fra vicini, profondità diverse, 3/4 o profilo) e ognuno fa il suo lavoro con prop del gioco (pulire col panno, caffè, telefono, sigaretta, clipboard, saldare, martello, soffiatore, scopa, appoggiato, mappa, orologio). L'attività è stabile per personaggio (hash di nome, cognome, nascita, sesso), tutte diverse e adatte a entrambi i sessi; resta attiva anche selezionato. Box cliccabili dai bone di testa e piedi (corrette con ped di profilo o accovacciati); al cleanup `ClearPedTasksImmediately` e rimozione dei prop orfani.
* **Slot base = 1** (`Config.Slots.default`) per gli account nuovi su ESX, QBCore e Qbox; grant ACE, `/gmc slots add` e Tebex invariati. Drop-in su un server già avviato: finché lo staff non fissa la base, la base di un account (più gli eventuali slot importati) copre almeno i suoi personaggi esistenti (anche oltre `max`; ACE, `/gmc slots add` e Tebex restano sopra), quindi il default non blocca mai un PG esistente e non regala slot (un buco tra gli slot non diventa uno slot libero; la capacità conta i personaggi, non il numero dello slot). Il blocco resta un'azione esplicita dello staff (`/gmc char lock`, oppure `/gmc slots remove|set` con conferma). Il bridge ESX legge i PG fino allo slot 15 anche con `max` più basso. In selezione solo personaggi e slot liberi; con `showLocked` e `unlockUrl` al massimo UN lucchetto (prima: una fila fino a `max`).
* `esx_skin`: l'aspetto si applica anche a ped locali (formato skinchanger applicato con le native, come `SkinChanger:ApplySkin`): con ESX tutti i personaggi si vedono vestiti insieme.
* Ottimizzazioni: aspetto di tutti i personaggi in una sola RPC (`select.looks`, in cache nella sessione), risposta di `scene.list` in cache e con le sole due scene usate, nessun polling del server nel pause menu (via `pause:server`), luci per frame precalcolate (nessuna tabella creata per frame), meteo e ora riaffermati 1/s, box della selezione inviate solo se cambiano, cleanup completo anche dei contorni e del segnaposto. UI: solo i sottoinsiemi latin dei font (`web/dist` da 670 KB a 550 KB), codice delle scene multiple e dell'editor rimosso.
* Inquadrature delle scene rifatte. Cause: set dell'identity a z -99 (spazio sotto la mappa di uno shell qbox assente: camera su un oggetto sotto terra), scene di default con coordinate/heading non verificati, meteo FOGGY/XMAS e DOF attivo (con il ped fuori fuoco tutto il quadro sfocato/grigio), camera calcolata da numeri della scena e non dal ped. Ora: scene di default solo da qb-spawn, esx\_multicharacter, qb-multicharacter e qbx\_core (file:riga in `source`, `verified: true`), studio all'esterno (qbx\_core defaultSpawn), le altre optIn `verified: false`; validazione che scarta le scene non optIn sotto z -50; ped messo a terra con suolo verificato e reso visibile; camera da `GetOffsetFromEntityInWorldCoords` + `PointCamAtPedBone`, verificata a runtime (IsEntityOnScreen, 1.2-8 m) con inquadratura di sicurezza; slot libero da 4.5 m; DOF e respiro spenti di default; `/gmc camdebug`; selettore di spawn con streaming e camera centrati sul suolo vero e far clip calcolato.
* Fix "Crea personaggio": `shared/rules.lua` usava `os.date` (la libreria `os` non esiste lato client FiveM). Ora data civile con sola aritmetica (`Util.civil`); test statico che vieta `os.`/`io.`/`debug.`/`require` e API solo-server/solo-client nei file caricati dal manifest.
* La brina (frost) non resta più a schermo intero: la transizione la toglie sempre (pcall) e la NUI la rilascia da sola dopo 6 s; test di trasparenza anche sui layer semitrasparenti (alpha > 0.05 fuori dai box UI).
* Scene: attico, eclipse, casino e garage sono `optIn` (servono IPL/DLC), non più di default; la scena di default è un esterno. Supporto `interior { ipl, coords, sets, pin }`: IPL, interno fissato in memoria, attesa di IsInteriorReady, ripiego se non arriva. DOF e timecycle clampati in range.
* Selettore di spawn solo al primo spawn di un personaggio nuovo (`Config.Spawn.onlyNewCharacter`, default true); nei login successivi ultima posizione salvata.
* Selettore di spawn: la camera aerea resta a 500 m (max 1500) e vola sul punto scelto; prima, con tutti i punti nel quadro, saliva a \~12 km e la mappa non veniva disegnata (solo i pin).
* UI: niente backdrop-filter né mask animata (sfarfallio bianco/nero in CEF su transizione brina); test di trasparenza della NUI in modalità FiveM.
* Scene: la camera non si avvicina oltre il 60 % dell'inquadratura e ignora ostacoli a meno di 0.6 m dal ped; `Config.Scenes.dof` e `debug`.
* Multicharacter, identity con foto, selettore di spawn 3D e pause menu per ESX Legacy, QBCore e Qbox (`Config.Modules`).
* Scene cinematiche di selezione ed editor in gioco `/gmc scene`.
* Comandi staff `/gmc` (slot, lock, delete, wipe, backup, import, selftest), ACE per ogni azione, integrazione Tebex da console.
* Backup automatico prima di delete e wipe, log di audit.
* Adapter di aspetto: illenium-appearance, fivem-appearance, rcore\_clothing, qb-clothing, esx\_skin, custom.
* Timeout RPC del client configurabile (`Config.Rpc.clientTimeoutMs`, default 25 s) e controllato dal selftest contro `Config.ESX.joinTimeoutMs` + 5000.
* Il creatore d'aspetto gira nel routing bucket privato del giocatore; bucket 0 a `appearance.done`, a `spawn.done` e al drop.
* Selezione: apertura idempotente quando `forceSelect` e push di stato arrivano insieme (una sola scena, un solo `select:open`).
* `appearance.done` che fallisce: 3 tentativi, poi ritorno alla selezione con errore (mai fermo nello stato `appearance`).
* UI: il popover "Dettagli" copre l'intera larghezza del dossier, il nome non sporge più.
* README italiano e inglese completi (installazione per framework, Qbox: le due porte di delete, adapter, config, comandi, 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/it/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.
