# CS SetCharName

**Redenumește orice personaj online dintr-un panou de administrare simplu — modificarea se aplică instantaneu și se salvează definitiv.**

Creat de **illusion @ CodeStrike**

---

## De ce tocmai acesta?

Schimbarea numelui unui personaj pare a fi un scenariu de trei rânduri, și tocmai de aceea
majoritatea sunt defecte. `SetCharInfo`actualizează datele în timp real ale jucătorului și
îl transmite clientului, astfel încât noul nume apare imediat și totul
pare corect — dar nu accesează deloc baza de date. Vechiul nume provine direct
se va reîncărca la următoarea conectare a jucătorului respectiv.

Funcția CS SetCharName se ocupă de tot: actualizare în timp real **și** o scriere verificată în
`players` tabel, în care se menționează că produsul a fost defect, nu că a fost înghițit.

| | |
|---|---|
| **Imediat** | Noua denumire se aplică imediat tuturor resurselor, în momentul în care apeși butonul „Salvare”. Nu este necesară o nouă autentificare sau o reconectare. |
| **Salvat efectiv** | O operațiune explicită de scriere în baza de date și un mesaj distinct în cazul în care această operațiune eșuează. |
| **Fără dependențe** | Fără ox_lib, fără CDN, fără fișier SQL. Doar Qbox. |
| **Accesul este restricționat în mod corespunzător** | Fiecare apel de rețea verifică din nou ACE. Deschiderea panoului nu dovedește nimic. |
| **Protejat împotriva atacurilor XSS** | Un nume Steam creat manual nu poate rula cod în jocul administratorilor tăi. |
| **Compatibil cu UTF-8** | Alfabetul chirilic, cel grecesc, alfabetul latin cu accente — toate sunt acceptate, cu un mod „latin strict” dacă doriți. |
| **Listă cu funcție de căutare** | Filtrează simultan după ID-ul serverului, numele contului, numele personajului și ID-ul de cetățean. |
| **Conectat** | Webhook pentru consolă și Discord, cu personalul, ținta, ambele denumiri și licența. |
| **Localizat** | Include limbile engleză și bulgară, câte un fișier pentru fiecare limbă. |

---

## Previzualizare

<!--
Puneți capturile de ecran lângă acest fișier și menționați-le aici, de exemplu:
-->

---

## Cerințe

- **Qbox** (`qbx_core`) — această resursă citește și scrie `PlayerData.charinfo`
prin intermediul exporturilor oficiale qbx_core.
- Server FiveM, versiunea **6683** sau o versiune mai recentă.

> QBCore (`qb-core`) **nu** este acceptat în mod implicit. Cele două framework-uri
> se salvează `charinfo`în același mod, dar calea de salvare este diferită — vezi
> [Adaptarea la un alt cadru](#adapting-to-another-framework).

---

## Instalare

1. Copiați `cs_setcharname`folderul în `resources`directorul dumneavoastră.
2. Pornește-l:
```cfg
# server.cfg
ensure cs_setcharname
```
Dacă o încadrezi într-o categorie marcată între paranteze, ai deja un început — `[staff-tools]`,
`[admin]`, indiferent ce folosești — se pornește automat și nu ai nevoie de un
a doua linie`ensure`.
3. Acordați permisiunea (secțiunea următoare).
4. Reporniți serverul.

Ar trebui să vezi următorul mesaj în consolă:

```
[cs_setcharname] v1.0.0 loaded - /setcharname (illusion @ CodeStrike)
```

Nu există niciun fișier SQL de importat. Resursa scrie în `players`tabelul care
Qbox-ul a fost deja creat.

---

## Permisiuni

Un jucător poate folosi instrumentul dacă trece **orice** verificare ACE din `Config.AllowedAces`.
Valoarea implicită livrată este:

```lua
Config.AllowedAces = {
'command.setcharname',
'admin',
'owner',
}
```

Alegeți varianta care se potrivește configurației dvs. și adăugați-o la`permissions.cfg`:

```cfg
# Dedicated permission — recommended, keeps this tool independent
add_ace group.admin command.setcharname allow

# Or reuse an existing staff permission you already grant
add_ace group.admin admin allow
```

Dacă grupurile tale se moștenesc unele de la altele, permisiunea se transmite de-a lungul lanțului:

```cfg
add_principal group.owner group.admin # owners now have it too
```

De asemenea, pentru a o încredința unui subordonat:

```cfg
add_ace group.mod command.setcharname allow
```

Vrei să-l limitezi la un singur nod? Redu-l la`Config.AllowedAces` doar
`{ 'command.setcharname' }` și nimic altceva nu va deschide panoul.

> Modificările din fișierul ACE sunt citite la pornire. După editare`permissions.cfg`, reporniți
> serverul — o singură`restart` resursă nu este suficientă.

---

## Comenzi

| Comandă | Rezultat |
|---|---|
| `/setcharname` | Deschide panoul |
| `/setcharname <id> <firstname> <lastname>` | Redenumește direct, fără interfață de utilizator |

Forma directă acceptă nume de familie formate din mai multe cuvinte: `/setcharname 12 John Van Der Berg`
setează numele de familie la `Van Der Berg`.

Ambele forme funcționează și din consola serverului, unde verificarea permisiunilor se face
omise.

---

## Configurare

Totul trăiește în `config.lua`.

### Generalități

```lua
Config.Locale = 'en' -- 'en' or 'bg'
Config.Command = 'setcharname' -- rename the command if you like
```

### Reguli privind denumirile

```lua
Config.Name = {
minLength = 2,
maxLength = 24,
strictLatin = false, -- true = ASCII letters only
allowDigits = false,
autoCapitalize = true, -- "john doe" -> "John Doe"
}
```

Caracterele permise sunt literele, spațiile, cratimele și apostrofele, deci `O'Brien`
și `Anne-Marie`se acceptă. Tot restul este respins.

**Notă`autoCapitalize`:** scrierea cu majuscule se aplică numai numelor în format ASCII simplu.
Lua `string.upper`operează cu octeți neprelucrați și ar corupe un caracter UTF-8 multibyte
secvență, astfel încât numele care conțin caractere non-ASCII sunt stocate exact așa cum au fost tastate.
Este o măsură intenționată, nu o limitare pe care trebuie să o ocolești.

**La`strictLatin`:** lăsați această opțiune activată `false`pentru a permite orice script. Setați-o `true`dacă
Serverul acceptă numai nume de caractere în alfabetul latin.

### Comportament

```lua
Config.NotifyTarget = true -- tell the renamed player what happened
Config.ShowCitizenId = true -- set false to keep it off screen while streaming
Config.Cooldown = 2 -- seconds between renames, per staff member
```

### Exploatarea forestieră

```lua
Config.Logs = {
console = true,
webhook = '', -- Discord webhook URL, empty to disable
botName = 'SetCharName',
}
```

Fiecare înregistrare conține informații despre angajat, țintă, numele vechi, numele nou și
permisul persoanei vizate.

### Aspect

```lua
Config.UI = {
accent = '#5b8cff',
opacity = 0.97, -- panel background opacity, 0.0 - 1.0
}
```

> **Nu adăugați `backdrop-filter`la `web/style.css`.** FiveM redă NUI în
> are propria textură și o suprapune prin alfa peste joc, astfel încât a are`backdrop-filter`
> nu există un fundal real din care să se preleveze o probă. Chromium revine la stratul de bază negru opac
> și colorează întregul strat compus — extins cu raza de estompare, deci mai mare
> decât elementul în sine — negru uniform. Arată perfect într-un browser și afișează
> un dreptunghi negru în joc. Folosește `Config.UI.opacity`în schimb.

---

## Comenzi de pe panou

| Intrare | Acțiune |
|---|---|
| Faceți clic pe un rând | Selectează jucătorul respectiv |
| Tastați în câmpul de căutare | Filtrează după ID, cont, numele personajului sau numărul de identificare al cetățeanului |
| `Enter` | Salvare |
| `Esc` | Închide |
| Faceți clic în afara panoului | Închide |

Butonul „Salvare” rămâne dezactivat până când ambele câmpuri sunt completate corect **și** s-a efectuat o acțiune
s-a modificat efectiv, așa că nu poți consuma un timp de reîncărcare pentru o acțiune fără efect.

---

## Cum se aplică redenumirea

Merită spus clar, pentru că aceasta este partea care face diferența între un instrument funcțional și
una care pare doar că funcționează:

```lua
exports.qbx_core:SetCharInfo(id, 'firstname', firstname)
exports.qbx_core:SetCharInfo(id, 'lastname', lastname)
exports.qbx_core:Save(id)
```

`SetCharInfo` actualizează și`PlayerData` îl transmite clientului prin intermediul
`QBCore:Player:SetPlayerData`. Asta este ceea ce face ca noua denumire să fie vizibilă
imediat, oriunde, fără a fi nevoie să te reconectezi.

**Nu** scrie în baza de date. Ajunge doar`charinfo` până la `players`
tabelul printr-o operație de salvare, astfel încât comanda explicită este`Save` cea care face ca modificarea să devină permanentă.
Dacă operațiunea eșuează, vei primi un mesaj specific care îți va indica că numele a fost aplicat, dar nu
salvat — în loc de un toast de succes care ascunde o redenumire ce se va evapora.

---

## Integrare

Majoritatea resurselor nu au nevoie de nimic. Ele citesc `PlayerData.charinfo`ce conține qbx_core
a fost deja actualizată înainte ca aceste evenimente să se declanșeze.

Dacă ceva pe serverul tău stochează în cache numele personajului la apariție — suprasolicitare
plăcuțe cu nume, un card de identitate, o listă de contacte din telefon — alege una dintre acestea:

```lua
-- Server: fires for every rename
AddEventHandler('cs_setcharname:server:nameChanged', function(source, oldName, newName)
print(('%s is now %s'):format(oldName, newName))
end)
```

```lua
-- Client: fires on the renamed player only
AddEventHandler('cs_setcharname:nameChanged', function(oldName, newName)
-- refresh whatever holds a copy of the name
end)
```

### Exporturi

```lua
-- Server. Runs with console authority, so it bypasses the ACE check.
-- Use it from your own admin menu, a Discord bot bridge, an application system.
local ok, message = exports.cs_setcharname:SetName(targetId, 'John', 'Doe')

-- Server. Ask whether a player is allowed to use the tool.
exports.cs_setcharname:CanUse(source) --> boolean

-- Client.
exports.cs_setcharname:IsOpen() --> boolean
```

---

## Localizare

Copiați`locales/en.lua`, redenumiți fișierul și cheia tabelului, traduceți valorile,
apoi indică `Config.Locale`spre el:

```lua
-- locales/de.lua
Locales = Locales or {}
Locales['de'] = {
['title'] = 'Charakternamen',
-- ...
}
```

O cheie lipsă revine la limba engleză în loc să blocheze panoul, astfel încât o soluție parțială
traducerea poate fi expediată în condiții de siguranță.

---

## Securitate

Acesta este un instrument de administrare, așa că merită să precizăm clar limitele sale.

- **La fiecare eveniment de rețea se verifică din nou permisiunea ACE.** Faptul că panoul este deschis dovedește
nimic — orice client poate declanșa direct un eveniment de rețea înregistrat. Poarta este
în `cs_setcharname:server:setName`, nu în interfața utilizatorului.
- **Toate procesele de validare se execută din nou pe server.** Aceeași verificare în panou
există exclusiv pentru a oferi un feedback imediat și are caracter orientativ.
- **UTF-8 cu format incorect este respins.** Aceasta blochează, de asemenea, secvențele de octeți utilizate pentru a
să strecoare caractere de control printr-o verificare simplistă a lungimii.
- **Panoul nu utilizează niciodată `innerHTML`pentru datele jucătorilor.** Numele conturilor, personajele
numele și denumirile funcțiilor sunt scrise cu `textContent`, așa că un nume Steam creat special
nu se poate executa cod în jocul unui administrator.
- **Limita de rate** pe angajat prin intermediul `Config.Cooldown`.
- **Sunt înregistrate toate datele**, inclusiv permisul țintei.

---

## Adaptarea la un alt cadru

Apelurile specifice cadrului se limitează la și`server/main.lua` există
doar patru dintre ele: `GetPlayer`, `SetCharInfo`, `Save`și `Notify`. Pentru QBCore
echivalentele sunt`QBCore.Functions.GetPlayer`: ,
`Player.Functions.SetPlayerData('charinfo', charinfo)`, `Player.Functions.Save()`
și evenimentul clientului`QBCore:Notify`.

---

## Depanare

**„Nu ai permisiunea de a folosi această comandă.”**
Lipsește ACE. Adăugați una dintre liniile din secțiunea [„Permisiuni”](#permissions) și
repornirea serverului — modificările aduse ACE nu sunt preluate la repornirea resursei.

**Numele revine la starea inițială după o reconectare.**
Scrierea în baza de date a eșuat. Panoul afișează această eroare în mod specific, în loc de
care indică succesul; verificați consola pentru a vedea dacă există o eroare MySQL și confirmați că este`oxmysql`
conectat.

**„Jucătorul respectiv nu a terminat încă de încărcat personajul.”**
Sunt conectați, dar se află încă pe ecranul de selectare a personajului, așa că nu există
`PlayerData` pentru a modifica. Așteaptă până când apar.

**Unele elemente ale interfeței de utilizare afișează încă denumirea veche.**
Resursa respectivă a stocat numele în cache la apariție. Conectează-te la`cs_setcharname:nameChanged` ea,
sau modificați-o astfel încât să se citească „la`PlayerData.charinfo` cerere”.

**În spatele panoului apare o cutie neagră.**
Ceva din `web/style.css`folosește `backdrop-filter`. Eliminați-l — consultați
notă din secțiunea [„Aspect](#appearance)”.

**Panoul nu se deschide și nu se imprimă nimic.**
Verificați dacă `qbx_core`este pornit. Resursa afișează un mesaj de avertizare roșu la pornire dacă
Nu este așa.

---

## Structura fișierului

```
cs_setcharname/
├── fxmanifest.lua
├── config.lua all settings
├── shared/main.lua locale helper + name validation
├── locales/
│ ├── en.lua
│ └── bg.lua
├── client/main.lua NUI bridge, focus handling
├── server/main.lua permissions, validation, rename, logging
└── web/
├── index.html
├── style.css
└── script.js
```

Validarea este integrată în `shared/`mod intenționat: panoul și serverul asigură respectarea
reguli identice la nivel de octet, astfel încât interfața utilizatorului nu poate accepta niciodată ceva ce serverul
ar respinge.

---

## Istoric modificări

### 1.0.0
- Versiunea inițială

---

© CodeStrike — iluzie. Redistribuirea sau revânzarea codului sursă nu este permisă