# CS SetCharName

**Преименувайте всеки онлайн герой от изчистен административен панел — промяната се прилага незабавно и се запазва трайно.**

Създадено от **illusion @ CodeStrike**

---

## Защо точно този?

Преименуването на герой звучи като сценарий от три реда, и точно затова
повечето от тях не работят. `SetCharInfo`актуализира данните на играча в реално време и
го изпраща на клиента си, така че новото име се показва веднага и всичко
изглежда правилно — но никога не се свързва с базата данни. Старото име идва директно
да се върне, когато този играч се свърже отново.

CS SetCharName изпълнява цялата задача: актуализация в реално време **и** проверено записване в
`players` таблица, в която се отчитат случаите на неуспех, вместо тези на поглъщане.

| | |
|---|---|
| **Незабавно** | Новото име влиза в сила за всеки ресурс веднага щом натиснете „Запази“. Няма нужда да се логвате отново, нито да се свързвате наново. |
| **Действително спестени** | Изрично записване в базата данни и отделно съобщение, ако това записване се провали. |
| **Няма зависимости** | Без ox_lib, без CDN, без SQL файл. Само Qbox. |
| **С правилно ограничен достъп** | При всяко мрежово обаждане ACE се проверява отново. Отварянето на панела не доказва нищо. |
| **Защита срещу XSS** | Измислено име в Steam не може да изпълнява код в играта на вашите администратори. |
| **Поддържа UTF-8** | Кирилица, гръцки, латиница с диакритични знаци — всичко се поддържа, като при желание можете да използвате режим „строга латиница“. |
| **Списък с възможност за търсене** | Филтрирайте едновременно по ID на сървъра, име на акаунта, име на персонажа и ID на гражданина. |
| **Влязъл** | Конзола и уебхук за Discord, с информация за персонала, целта, имената и лиценза. |
| **Локализирано** | Включени са английски и български език, по един файл за всеки език. |

---

## Предварителен преглед

<!--
Поставете екранните си снимки до този файл и ги посочете тук, например:
-->

---

## Изисквания

- **Qbox** (`qbx_core`) — този ресурс чете и записва `PlayerData.charinfo`
чрез официалните експорти на qbx_core.
- FiveM сървър, версия **6683** или по-нова.

> QBCore (`qb-core`) **не** се поддържа по подразбиране. Двете рамки
> запазва се `charinfo`по същия начин, но пътят за запазване е различен — вижте
> [Приспособяване към друга рамка](#adapting-to-another-framework).

---

## Инсталиране

1. Копирайте `cs_setcharname`папката в вашата директория`resources`.
2. Започнете така:
```cfg
# server.cfg
ensure cs_setcharname
```
Ако го включите в някоя от категориите в скобите, вече започвате — `[staff-tools]`,
`[admin]`, каквото и да използвате — то се стартира автоматично и не ви е необходим
втори `ensure`ред.
3. Предоставете разрешението (следващия раздел).
4. Рестартирайте сървъра.

В конзолата трябва да видите следното:

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

Няма SQL файл за импортиране. Ресурсът записва данни в `players`таблицата, която
Qbox вече е създаден.

---

## Права за достъп

Играчът може да използва инструмента, ако премине **някоя** проверка за ACE в `Config.AllowedAces`.
Зададената по подразбиране стойност е:

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

Изберете този, който подхожда на вашата конфигурация, и го добавете към`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
```

Ако вашите групи се наследяват една от друга, правата се прехвърлят по веригата:

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

Да го предадеш и на подчинен:

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

Искате ли да го ограничите до един-единствен възел? Ограничете го до`Config.AllowedAces` само
`{ 'command.setcharname' }` и нищо друго няма да отвори панела.

> Промените в ACE се четат при стартиране`permissions.cfg`. След редактиране рестартирайте
> сървърът — самият`restart` ресурс не е достатъчен.

---

## Команди

| Команда | Резултат |
|---|---|
| `/setcharname` | Отваря панела |
| `/setcharname <id> <firstname> <lastname>` | Преименува директно, без графичен интерфейс |

Пряката форма допуска фамилии, състоящи се от няколко думи: `/setcharname 12 John Van Der Berg`
задава фамилията на `Van Der Berg`.

И двете форми работят и от конзолата на сървъра, където проверката на правата е
пропуснато.

---

## Конфигурация

Всичко се намира в `config.lua`.

### Общо

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

### Правила за имената

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

Допустимите символи са букви, интервали, тирета и апострофи, така че `O'Brien`
и се приема`Anne-Marie`. Всичко останало се отхвърля.

**Забележка`autoCapitalize`:** Използването на главни букви се отнася само за обикновени ASCII имена.
Lua работи`string.upper` с необработени байтове и би повредила многобайтовия UTF-8
последователност, така че имената, съдържащи не-ASCII символи, се съхраняват точно така, както са въведени.
Това е преднамерено, а не ограничение, което трябва да се заобикаля.

**За`strictLatin`:** оставете тази опция, `false`за да се разреши всеки скрипт. Настройте я, `true`ако вашият
Сървърът изисква имена на символи, съдържащи само латински букви.

### Поведение

```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
```

### Дърводобив

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

Всяка записка съдържа данни за служителя, целта, старото име, новото име и
шофьорската книжка на целта.

### Външен вид

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

> **Не добавяйте `backdrop-filter`към `web/style.css`.** FiveM преобразува NUI в
> своя собствена текстура и я наслагва върху играта чрез алфа-смесване, така че има`backdrop-filter`
> няма реален фон, от който да се вземе проба. Chromium преминава към непрозрачния черен основен слой
> и оцветява целия съставен слой — разширен с радиуса на замъгляването, така че става по-голям
> отколкото самият елемент — изцяло черно. Изглежда перфектно в браузъра и се показва
> черен правоъгълник в играта. Използвайте `Config.UI.opacity`вместо това.

---

## Управление чрез панел

| Вход | Действие |
|---|---|
| Кликнете върху един ред | Изберете този играч |
| Въведете текст в полето за търсене | Филтриране по идентификационен номер, акаунт, име на персонаж или граждански номер |
| `Enter` | Запази |
| `Esc` | Затвори |
| Кликнете извън панела | Затвори |

Бутонът „Запази“ остава деактивиран, докато и двете полета не бъдат попълнени правилно **и** не бъде въведено нещо
всъщност се е променило, така че не можеш да изразходваш време за презареждане за действие, което не води до нищо.

---

## Как се прилага преименуването

Струва си да се каже направо, защото това е елементът, който отличава един работещ инструмент от
такъв, който само на пръв поглед изглежда, че работи:

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

`SetCharInfo` актуализира го и`PlayerData` го изпраща към клиента чрез
`QBCore:Player:SetPlayerData`. Именно това прави новото име видимо
незабавно, навсякъде, без да се налага да влизаш отново.

**Не** записва в базата данни. стига само`charinfo` до `players`
таблицата чрез запазване, така че `Save`именно изричното действие прави промяната постоянна.
Ако операцията се провали, ще получите конкретно съобщение, в което се посочва, че името е било приложено, но не
запазено — а не празненство за успех, зад което се крие преименуване, което ще изчезне.

---

## Интеграция

Повечето ресурси не изискват нищо. Те четат това`PlayerData.charinfo`, което qbx_core притежава
вече е обновен, преди тези събития да се задействат.

Ако нещо в сървъра ви кешира името на героя при появата му — допълнителна натоварване
табелки с имена, лична карта, списък с телефонни номера — изберете едно от следните:

```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)
```

### Износ

```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
```

---

## Локализация

Копирайте`locales/en.lua`, преименувайте файла и ключа на таблицата, преведете стойностите,
след това го маркирайте`Config.Locale`:

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

При липса на ключ системата преминава към английски език, вместо да блокира панела, така че частичното
преводът може да бъде изпратен безпроблемно.

---

## Сигурност

Това е инструмент за администратори, затова е добре да се уточнят границите му.

- **При всяко събитие в мрежата се извършва повторна проверка на разрешението за ACE.** Отвореният панел доказва, че
нищо — всеки клиент може директно да задейства регистрирано мрежово събитие. Портата е
в `cs_setcharname:server:setName`, а не в потребителския интерфейс.
- **Цялата проверка се изпълнява отново на сървъра.** Същата проверка в панела
съществува единствено с цел незабавна обратна връзка и се разглежда като препоръка.
- **Неправилно форматираният UTF-8 се отхвърля.** Това блокира и байтовите последователности, използвани за
да промъкнат контролни символи през наивна проверка за дължина.
- **Панелът никога не използва `innerHTML`за данни на играчите.** Имена на акаунти, персонажи
имената и описанията на професиите се изписват с `textContent`, така че специално създадено име в Steam
не може да изпълнява код в играта на администратора.
- **Ограничение на броя на заявките** за всеки служител чрез `Config.Cooldown`.
- **Всичко е подробно записано**, включително и шофьорската книжка на целта.

---

## Адаптиране към друга рамка

Извикванията, специфични за фреймворка, са ограничени до и`server/main.lua` има
само четири от тях: `GetPlayer`, `SetCharInfo`, и`Save` `Notify`. За QBCore
еквивалентите са`QBCore.Functions.GetPlayer`: ,
`Player.Functions.SetPlayerData('charinfo', charinfo)`, `Player.Functions.Save()`
и събитието на клиента`QBCore:Notify`.

---

## Отстраняване на неизправности

**„Нямате право да използвате тази команда.“**
Липсва ACE. Добавете един от редовете от [„Permissions“](#permissions) и
рестартирайте **сървъра** — промените в ACE не се отразяват при рестартиране на ресурса.

**Името се възстановява след повторно влизане в системата.**
Записът в базата данни се провали. Панелът съобщава именно това, вместо
показва успех; проверете конзолата за грешка в MySQL и потвърдете, че е`oxmysql`
свързани.

**„Този играч все още не е завършил зареждането на своя герой.“**
Те са свързани, но все още са на екрана за избор на герой, така че няма
`PlayerData` за да ги промените. Изчакайте, докато се появят.

**В някои елементи на потребителския интерфейс все още се показва старото име.**
Този ресурс е запазил името в кеша при създаването. Включете се в`cs_setcharname:nameChanged` него,
или да го промените така, че да се чете „при`PlayerData.charinfo` поискване“.

**Зад панела се появява черна кутия.**
Нещо в `web/style.css`използва `backdrop-filter`. Премахнете го — вижте
бележка в раздела [„Външен вид](#appearance)“.

**Панелът не се отваря и нищо не се отпечатва.**
Проверете дали `qbx_core`е стартиран. Ресурсът извежда червено предупреждение при стартиране, ако
Не е така.

---

## Структура на файла

```
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
```

Валидирането се извършва целенасочено`shared/`: панелът и сървърът осигуряват спазването на правилата
правила, които са идентични байт по байт, така че потребителският интерфейс никога не може да приеме нещо, което сървърът
би отхвърлил.

---

## Списък с промените

### 1.0.0
- Първоначално издание

---

© CodeStrike — illusion. Преразпространението или препродажбата на изходния код не се разрешава