# CS SetCharName

**Zmień nazwę dowolnej postaci w grze online za pomocą przejrzystego panelu administracyjnego — zmiana zostanie wprowadzona natychmiast i zapisana na stałe.**

Stworzone przez **illusion @ CodeStrike**

---

## Dlaczego akurat ten?

Zmiana imienia postaci brzmi jak scenariusz na trzy linijki, i właśnie dlatego
większość z nich jest uszkodzona. `SetCharInfo`aktualizuje dane na żywo gracza i
przesyła ją do klienta, dzięki czemu nowa nazwa pojawia się natychmiast i wszystko
wygląda poprawnie — ale nigdy nie nawiązuje połączenia z bazą danych. Stara nazwa pochodzi bezpośrednio
przywrócić, gdy ten gracz ponownie się zaloguje.

Funkcja CS SetCharName spełnia wszystkie wymagania: aktualizacja na żywo **oraz** zweryfikowany zapis do pliku
`players` tabela, w której zgłoszono ci awarię zamiast tego, by ją zignorować.

| | |
|---|---|
| **Natychmiast** | Nowa nazwa zaczyna obowiązywać dla wszystkich zasobów natychmiast po kliknięciu przycisku „Zapisz”. Nie trzeba się ponownie logować ani ponownie łączyć. |
| **Rzeczywiście zapisano** | Wyraźny zapis w bazie danych oraz odrębny komunikat w przypadku niepowodzenia tego zapisu. |
| **Brak zależności** | Bez ox_lib, bez CDN, bez pliku SQL. Tylko Qbox. |
| **Odpowiednio zabezpieczone hasłem** | Każde wywołanie sieciowe ponownie sprawdza reguły ACE. Otwarcie panelu niczego nie dowodzi. |
| **Zabezpieczone przed atakami XSS** | Wymyślona nazwa użytkownika na Steamie nie pozwala na uruchamianie kodu w grze prowadzonej przez administratorów. |
| **Obsługa kodowania UTF-8** | Alfabet cyryliczny, grecki, łaciński z akcentami — obsługujemy je wszystkie, a jeśli chcesz, dostępny jest też tryb ściśle łaciński. |
| **Lista z funkcją wyszukiwania** | Filtruj jednocześnie według identyfikatora serwera, nazwy konta, nazwy postaci i identyfikatora obywatela. |
| **Zalogowano się** | Webhook dla konsoli i serwisu Discord, zawierający informacje o pracowniku, celu, obu nazwach oraz licencji. |
| **Zlokalizowane** | W tym angielski i bułgarski – po jednym pliku dla każdego języka. |

---

## Podgląd

<!--
Umieść swoje zrzuty ekranu obok tego pliku i podaj do nich odniesienia w tym miejscu, np.
-->

---

## Wymagania

- **Qbox** (`qbx_core`) — ten zasób odczytuje i zapisuje `PlayerData.charinfo`
za pośrednictwem oficjalnych eksportów qbx_core.
- Serwer FiveM w wersji **6683** lub nowszej.

> QBCore (`qb-core`) **nie** jest obsługiwane w standardzie. Te dwa frameworki
> zapisuje się to `charinfo`w ten sam sposób, ale ścieżka zapisu jest inna — zobacz
> [Dostosowanie się do innego systemu](#adapting-to-another-framework).

---

## Instalacja

1. Skopiuj ten `cs_setcharname`folder do swojego `resources`katalogu.
2. Zacznij:
```cfg
# server.cfg
ensure cs_setcharname
```
Jeśli przypiszesz to do jednej z kategorii w nawiasach, to już zaczynasz — `[staff-tools]`,
`[admin]`, niezależnie od tego, czego używasz — uruchamia się automatycznie i nie musisz
drugi `ensure`wiersz.
3. Przyznaj uprawnienie (w następnej sekcji).
4. Uruchom ponownie serwer.

W konsoli powinno pojawić się następujące komunikaty:

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

Nie ma pliku SQL do zaimportowania. Zasób zapisuje dane do tabeli`players`, która
Qbox został już utworzony.

---

## Uprawnienia

Gracz może skorzystać z tego narzędzia, jeśli zda **dowolny** test ACE w `Config.AllowedAces`.
Domyślna wartość to:

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

Wybierz opcję, która pasuje do Twojej konfiguracji, i dodaj ją do`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
```

Jeśli grupy dziedziczą uprawnienia jedna po drugiej, uprawnienia są przekazywane wzdłuż łańcucha:

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

Aby przekazać to również osobie o niższym stopniu:

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

Chcesz, żeby działało wyłącznie na jednym węźle? Ogranicz to tylko do`Config.AllowedAces`
`{ 'command.setcharname' }` i nic innego nie spowoduje otwarcia panelu.

> Zmiany w pliku ACE są odczytywane podczas uruchamiania. Po wprowadzeniu zmian `permissions.cfg`należy ponownie uruchomić
> serwer — sam`restart` w sobie nie wystarczy.

---

## Polecenia

| Polecenie | Wynik |
|---|---|
| `/setcharname` | Otwiera panel |
| `/setcharname <id> <firstname> <lastname>` | Zmienia nazwę bezpośrednio, bez interfejsu użytkownika |

W formie bezpośredniej dopuszczalne są nazwiska składające się z kilku słów: `/setcharname 12 John Van Der Berg`
ustawia nazwisko na `Van Der Berg`.

Obie formy działają również z konsoli serwera, gdzie sprawdzanie uprawnień odbywa się
pominięto.

---

## Konfiguracja

Wszystko znajduje się w `config.lua`.

### Ogólne informacje

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

### Zasady dotyczące nazw

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

Dopuszczalne znaki to litery, spacje, łączniki i apostrofy, więc `O'Brien`
i przechodzi`Anne-Marie`. Wszystko inne zostaje odrzucone.

**Uwaga`autoCapitalize`:** wielkie litery stosuje się wyłącznie w przypadku nazw zapisanych w standardowym kodzie ASCII.
Lua `string.upper`operuje na surowych bajtach i mogłaby uszkodzić wielobajtowe dane w formacie UTF-8
kolejności, więc nazwy zawierające znaki spoza zestawu ASCII są zapisywane dokładnie tak, jak zostały wpisane.
Jest to zamierzone działanie, a nie ograniczenie, które należy obejść.

**Opcja „On`strictLatin`”:** pozostaw tę opcję włączoną, `false`aby zezwolić na uruchamianie dowolnych skryptów. Ustaw tę opcję, `true`jeśli twój
Serwer wymaga, aby nazwy znaków zawierały wyłącznie znaki łacińskie.

### Zachowanie

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

### Wycinka drzew

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

Każdy wpis zawiera informacje o pracowniku, osobie, której dotyczy zmiana, poprzednim imieniu, nowym imieniu oraz
prawo jazdy osoby, której to dotyczy.

### Wygląd

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

> **Nie dodawaj `backdrop-filter`do `web/style.css`.** FiveM renderuje NUI jako
> własną teksturę i nakłada ją metodą alfa-blendingu na obraz gry, więc a ma`backdrop-filter`
> brak prawdziwego tła do próbkowania. Chromium przechodzi na nieprzezroczystą czarną warstwę podstawową
> i maluje całą warstwę złożoną — powiększoną o promień rozmycia, a więc większą
> niż sam element — jednolita czerń. Wygląda idealnie w przeglądarce i wyświetla się
> czarny prostokąt w grze. `Config.UI.opacity`Zamiast tego użyj .

---

## Elementy sterujące na panelu

| Dane wejściowe | Akcja |
|---|---|
| Kliknij wiersz | Wybierz tego gracza |
| Wpisz tekst w polu wyszukiwania | Filtruj według identyfikatora, konta, nazwy postaci lub numeru identyfikacyjnego obywatela |
| `Enter` | Zapisz |
| `Esc` | Zamknij |
| Kliknij poza panelem | Zamknij |

Przycisk „Zapisz” pozostaje nieaktywny, dopóki oba pola nie zostaną poprawnie wypełnione **i** nie zostanie wykonana jakaś czynność
faktycznie uległo zmianie, więc nie można wykorzystać czasu odnowienia na czynność, która nic nie daje.

---

## Jak przebiega zmiana nazwy

Warto to jasno podkreślić, ponieważ właśnie ta cecha odróżnia narzędzie robocze od
taki, który tylko pozornie działa:

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

`SetCharInfo` aktualizuje `PlayerData`i przesyła do klienta za pośrednictwem
`QBCore:Player:SetPlayerData`. To właśnie sprawia, że nowa nazwa jest widoczna
natychmiast, wszędzie, bez konieczności ponownego logowania.

**Nie** zapisuje danych w bazie danych. dociera jedynie`charinfo` do `players`
tabela jest zapisywana, więc to właśnie jawne zapisanie sprawia`Save`, że zmiana staje się trwała.
Jeśli operacja się nie powiedzie, pojawi się konkretny komunikat informujący, że nazwa została zastosowana, ale nie
zapisane — a nie toast z okazji sukcesu, za którym kryje się zmiana nazwy, która wkrótce zniknie.

---

## Integracja

Większość zasobów nie wymaga niczego. Odczytują one to`PlayerData.charinfo`, co zawiera qbx_core
zostały już odświeżone przed uruchomieniem tych zdarzeń.

Jeśli jakiś element serwera buforuje nazwę postaci w momencie jej pojawienia się — obciążenie
tabliczki z nazwiskiem, legitymacja, lista kontaktów w telefonie — wybierz jedną z tych opcji:

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

### Eksport

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

---

## Lokalizacja

Skopiuj`locales/en.lua`, zmień nazwę pliku i klucza tabeli, przetłumacz wartości,
następnie wskaż to`Config.Locale`:

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

W przypadku braku klucza system przełącza się na język angielski, zamiast wyłączać panel, więc częściowe
przesyłka jest bezpieczna.

---

## Bezpieczeństwo

Jest to narzędzie administracyjne, dlatego warto jasno określić jego ograniczenia.

- **Przy każdym zdarzeniu sieciowym ponownie sprawdzane jest uprawnienie ACE.** Otwarty panel świadczy o tym, że
nic — każdy klient może bezpośrednio wywołać zarejestrowane zdarzenie sieciowe. Bramka jest
w `cs_setcharname:server:setName`…, a nie w interfejsie użytkownika.
- **Wszystkie operacje walidacyjne ponownie odbywają się na serwerze.** Ta sama kontrola w panelu
ma na celu wyłącznie zapewnienie natychmiastowej informacji zwrotnej i ma charakter wyłącznie doradczy.
- **Nieprawidłowo sformułowane dane UTF-8 są odrzucane.** Blokuje to również sekwencje bajtów używane do
przekazać znaki kontrolne pomimo prostej kontroli długości.
- **Panel nigdy nie wykorzystuje `innerHTML`do przechowywania danych graczy.** Nazwy kont, postacie
nazwy i etykiety stanowisk są zapisywane za pomocą znaku „,”`textContent`, więc specjalnie spreparowana nazwa w serwisie Steam
nie można uruchomić kodu w grze administratora.
- **Ograniczenie liczby operacji** na pracownika za pośrednictwem `Config.Cooldown`.
- **Wszystko zostało dokładnie odnotowane**, łącznie z prawem jazdy osoby, której to dotyczy.

---

## Dostosowanie się do innego systemu

Wywołania specyficzne dla danego frameworka ograniczają się do `server/main.lua`i istnieje
tylko cztery z nich: `GetPlayer`, `SetCharInfo`, `Save`i `Notify`. Dla QBCore
odpowiedniki to`QBCore.Functions.GetPlayer`: ,
`Player.Functions.SetPlayerData('charinfo', charinfo)`, `Player.Functions.Save()`
oraz zdarzenie klienta`QBCore:Notify`.

---

## Rozwiązywanie problemów

**„Nie masz uprawnień do użycia tego polecenia.”**
Brakuje ACE. Dodaj jedną z linii z sekcji [„Uprawnienia”](#permissions) i
uruchom ponownie **serwer** — zmiany w ACE nie są uwzględniane po ponownym uruchomieniu zasobu.

**Nazwa wraca do poprzedniej postaci po ponownym zalogowaniu się.**
Wystąpił błąd zapisu w bazie danych. Panel zgłasza to konkretnie, zamiast
wskazujące na powodzenie; sprawdź konsolę pod kątem błędu MySQL i upewnij się`oxmysql`, że
połączone.

**„Ten gracz nie zakończył jeszcze wczytywania swojej postaci.”**
Są połączeni, ale wciąż znajdują się na ekranie wyboru postaci, więc nie ma
`PlayerData` aby je zmodyfikować. Poczekaj, aż się pojawią.

**W niektórych elementach interfejsu użytkownika nadal widoczna jest stara nazwa.**
Ten zasób zapisał nazwę w pamięci podręcznej w momencie pojawienia się. Podłącz się do`cs_setcharname:nameChanged` niego,
lub zmienić to na „na`PlayerData.charinfo` żądanie”.

**Za panelem pojawia się czarna skrzynka.**
Coś w `web/style.css`korzysta z `backdrop-filter`. Usuń to — zobacz
uwaga w sekcji [„Wygląd](#appearance)”.

**Panel się nie otwiera i nic nie jest drukowane.**
Sprawdź, czy `qbx_core`został uruchomiony. Zasób wyświetla czerwone ostrzeżenie podczas uruchamiania, jeśli
Nie jest.

---

## Układ pliku

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

Walidacja jest celowo`shared/` wbudowana: panel i serwer zapewniają jej przestrzeganie
zasady identyczne bajt po bajcie, więc interfejs użytkownika nigdy nie może zaakceptować czegoś, co serwer
odrzuciłby.

---

## Lista zmian

### 1.0.0
- Pierwsze wydanie

---

© CodeStrike — illusion. Zabrania się dalszego rozpowszechniania lub odsprzedaży kodu źródłowego