# CS SetCharName

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

Создано **illusion @ CodeStrike**

---

## Почему именно этот?

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

Функция CS SetCharName решает задачу полностью: обеспечивает обновление в режиме реального времени **и** проверенную запись в
`players` таблица, в которой о сбое сообщается вам, а не скрывается.

| | |
|---|---|
| **Мгновенно** | Новое имя вступает в силу для всех ресурсов сразу же после нажатия кнопки «Сохранить». Не требуется ни перезахода, ни повторного подключения. |
| **Фактически сэкономлено** | Явная запись в базу данных и отдельное сообщение в случае сбоя этой записи. |
| **Отсутствие зависимостей** | Никаких ox_lib, никаких CDN, никаких SQL-файлов. Только Qbox. |
| **Надлежащая проверка прав доступа** | При каждом сетевом вызове происходит повторная проверка ACE. Открытие панели ничего не доказывает. |
| **Защита от XSS** | Под вымышленным именем в Steam нельзя запускать код в игре ваших администраторов. |
| **Поддержка кодировки UTF-8** | Кириллица, греческий алфавит, латинский алфавит с диакритическими знаками — всё поддерживается, а при необходимости можно включить режим строгого латинского алфавита. |
| **Список с возможностью поиска** | Фильтруйте сразу по 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, сохраняются в точности так, как они введены.
Это сделано намеренно, и это не ограничение, которое нужно обходить.

**Параметр «On`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`Вместо этого используйте .

---

## Панель управления

| Ввод | Действие |
|---|---|
| Нажмите на строку | Выберите этого игрока |
| Введите текст в поле поиска | Фильтрация по ID, учетной записи, имени персонажа или идентификационному номеру гражданина |
| `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) и
Перезапустите **сервер** — изменения в 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. Перераспространение или перепродажа исходного кода запрещены