ESX, QBCore czy Qbox? Wybór i instalacja frameworka FiveM

Serwer roleplay jest zbudowany na frameworku: obsługuje on postacie, pieniądze, prace, ekwipunek i samochody. Porównamy trzy najczęściej używane (ESX Legacy, QBCore i Qbox), pomożemy wybrać i przeprowadzimy przez instalację z przepisu txAdmin, łącznie z konfiguracją adminów.

Czym jest framework#

Framework to zestaw zasobów, który daje serwerowi podstawową „grę RP”: tworzenie postaci, gotówkę i pieniądze w banku, prace i stopnie, ekwipunek, własność pojazdów i zapis do bazy danych. Pozostałe skrypty (prace, sklepy, telefon, garaże) budują na funkcjach frameworka.

Co to oznacza w praktyce:

• Skrypt jest pisany pod konkretny framework. Skrypt dla ESX nie zadziała na QBCore bez zmian i odwrotnie. Zawsze szukaj więc wersji skryptu dla swojego frameworka.
• Zmiana frameworka na działającym serwerze jest trudna. Przejście na inny oznacza nową bazę danych i wymianę skryptów. Wybieraj więc uważnie już na początku.
• Framework potrzebuje bazy danych i zasobu oxmysql.

Serwer bez frameworka (freeroam, drift, wyścigi) może działać na podstawowym przepisie txAdmin (FiveM Basic Server).

Podstawowe pojęcia#

Jeśli to rozumiesz, łatwiej znajdziesz problemy: gdy pieniądze lub samochód „znikną”, jest to rekord w bazie danych, który możesz odszukać i poprawić (na przykład w HeidiSQL).

Porównanie#

Jak wybrać#

• Chcesz najwięcej gotowych skryptów i poradników? ESX Legacy. Jest najbardziej rozpowszechniony i znajdziesz dla niego skrypty niemal do wszystkiego.
• Chcesz nowoczesną bazę i skrypty QBCore? Qbox. Używa bibliotek ox_lib, ox_inventory i ox_target, ma bardziej rygorystyczny kod i uruchamia większość skryptów QBCore przez bridge bez zmian.
• Masz konkretne płatne skrypty dla QBCore? QBCore albo Qbox (sprawdź u autora skryptu, czy działa na Qbox).
• Budujesz serwer z własnymi skryptami od zera? Wybierz ten, którego dokumentacja odpowiada Ci najbardziej. Dobra znajomość frameworka ma większe znaczenie niż to, który wybierzesz.

Najbezpieczniejsze podejście: wdróż framework próbnie, wypróbuj go w grze i dopiero potem kupuj skrypty.

Przed instalacją#

1. Utwórz pustą bazę danych w zakładce Baza danych (na przykład fivem, Dozwolone połączenia z %). Zostaw otwarte dane Nazwa bazy danych, Użytkownik, Host i Hasło.
2. Przygotuj klucz licencyjny (zaczyna się od cfxk_).
3. Zrób kopię zapasową, jeśli masz już coś na serwerze (zakładka Kopie zapasowe, poradnik), i wyeksportuj bazę danych (poradnik). Nowe wdrożenie zapisuje się do nowego folderu, ale przepis z włączonym Delete Database usunąłby bazę danych.
4. Sprawdź artefakty. Frameworki wymagają aktualnej wersji serwera. Stary serwer zaktualizuj według artykułu Aktualizacja artefaktów.

Instalacja z przepisu txAdmin#

Procedura jest taka sama dla wszystkich trzech frameworków; różni się tylko przepis i kilka ustawień po instalacji. Jeśli w txAdmin wdrożono już inny serwer, uruchom nowy kreator w Settings › FXServer przyciskiem Reset obok pola Server Data Folder. txAdmin wraca do strony Setup i nie usuwa istniejących plików.

1. Na stronie Setup w txAdmin wpisz Server Name i kliknij Next.
2. W Deployment Type wybierz Popular Recipes.
3. Wybierz przepis zgodnie z zakładką niżej.
4. Zostaw proponowany folder danych, kliknij Save, a potem Go to Recipe Deployer.
5. W Step 1: Review Recipe kliknij Next.
6. W Step 2: Input Parameters wypełnij Server Registration Key, a po kliknięciu Show/Hide Database options (advanced) także bazę danych: Database Host (IP z pola Host), Database Port (port z pola Host), Database Username, Database Password, Database Name. Przełącznik Delete Database jest domyślnie włączony; upewnij się, że jest ustawiony na Off. Każde pole szczegółowo objaśnia poradnik txAdmin.
7. Kliknij Run Recipe i poczekaj na zakończenie. Duże przepisy trwają kilka minut.
8. W Step 4: Configure server.cfg sprawdź, czy endpoint_add_tcp i endpoint_add_udp mają port z linii Adres połączenia w zakładce Sieć (przepis może wpisać domyślny 30120). Następnie dostosuj ustawienia według zakładki niżej i kliknij Save & Run Server.

Pierwsze kroki po instalacji: uprawnienia admina#

Admin w txAdmin i admin we frameworku to dwie różne rzeczy. Podczas wdrożenia txAdmin dodaje głównego admina do grupy group.admin w server.cfg (linia add_principal identifier.fivem:<FIVEM_ID> group.admin). Frameworki budują na tym następująco:

setgroup <PLAYER_ID> admin

add_principal identifier.license:<PLAYER_LICENSE> qbcore.god

add_principal identifier.license:<PLAYER_LICENSE> group.admin

Po edycji server.cfg lub permissions.cfg zrestartuj serwer.

Na Qbox polecenia admina z rdzenia (na przykład /addpermission, /setjob, /car) wymagają najpierw wpisania /optin. Wyłączysz to opcją requireOptIn = false w qbx_core/config/server.lua.

Co ustawić najpierw#

Każdy framework ma główny plik konfiguracyjny z ekonomią, spawnem i postaciami. Edytuj go przy zatrzymanym serwerze albo zrestartuj serwer w txAdmin po edycji. Pliki znajdziesz w folderze wdrożenia w resources.

Pieniądze i przedmioty są przechowywane w bazie danych. Zmiana wartości startowych dotyczy tylko nowo utworzonych postaci; istniejące pozostają bez zmian.

Kompatybilne skrypty#

• Pobieraj wersję dla swojego frameworka. Wielu autorów oferuje jeden skrypt dla kilku frameworków z opcją w config.lua (na przykład Config.Framework = 'esx', 'qb' lub 'qbx').
• Biblioteki ox (ox_lib, ox_inventory, ox_target) działają zarówno z ESX, jak i z Qbox. Przed instalacją drugiego ekwipunku ustal jasno, którego używasz. Dwa ekwipunki naraz nie działają.
• Skrypty QBCore na Qbox działają przez bridge, jeśli używają qb-core w udokumentowany sposób. Skrypty, które bezpośrednio sięgają do tabel bazy danych QBCore, nie działają.
• Konflikty: dwa skrypty o tej samej funkcji (dwa HUD-y, dwa garaże, dwa telefony) zwykle sobie przeszkadzają. Wyłącz pierwotny (zakomentuj jego ensure albo przenieś go poza kategorię).

Instalację pojedynczych skryptów opisuje artykuł Zasoby FiveM.

Instalacja ręczna (dla zaawansowanych)#

Przepis automatycznie robi to, co inaczej trzeba zrobić ręcznie:

1. Pobiera rdzeń frameworka i jego zależności (oxmysql, ox_lib …) w konkretnych wersjach.
2. Importuje plik SQL frameworka do bazy danych.
3. Przygotowuje server.cfg z właściwą kolejnością ensure, uprawnieniami ACE i connection stringiem.

Instalację ręczną wybierz tylko wtedy, gdy chcesz mieć każdą wersję pod kontrolą. Postępuj według oficjalnej dokumentacji frameworka i zachowaj kolejność: oxmysql › biblioteki › rdzeń › skrypty. Na serwerze StormHost przepis jest znacznie szybszy; ręczne przesyłanie setek plików przez zakładkę Pliki jest żmudne (pomoc techniczna może skonfigurować SFTP do dużych plików).

Aktualizacja frameworka#

1. Zarchiwizuj pliki (zakładka Kopie zapasowe) i wyeksportuj bazę danych (HeidiSQL, poradnik).
2. Przeczytaj informacje o wydaniu (changelog) na GitHubie frameworka. Szukaj głównie zmian w bazie danych (pliki migracji .sql) i zmian konfiguracji.
3. Zatrzymaj serwer.
4. Zastąp foldery aktualizowanych zasobów nowymi. Wcześniej pobierz swoje pliki config.lua i po aktualizacji porównaj je z nowymi (mogą brakować nowe opcje).
5. Uruchom migrację SQL, jeśli wydanie ją zawiera.
6. Uruchom serwer i obserwuj konsolę. Potem sprawdź w grze swoją postać, pieniądze i ekwipunek.

Nie aktualizuj samego rdzenia bez pozostałych części frameworka. Wersje es_extended i skryptów [esx_addons] (albo qb-core i qb-*) powinny iść w parze.

Weryfikacja#

• Konsola (lub Live Console w txAdmin) pokazuje Database server connection established!, a rdzeń frameworka wczytuje się bez czerwonych błędów.
• Po połączeniu w grze pojawia się tworzenie lub wybór postaci.
• Polecenie /group (ESX) albo otwarcie menu /admin (QBCore, Qbox) potwierdza, że masz uprawnienia admina.

Rozwiązywanie problemów#

Komunikatów, których tu nie znajdziesz, szukaj w artykule Częste błędy serwera FiveM.

Task Failed: Response code 403 (rate limit exceeded)#

Przepis pobiera dziesiątki repozytoriów z GitHuba, a GitHub tymczasowo ograniczył liczbę żądań. Poczekaj około godziny i uruchom wdrożenie ponownie.

Wdrożenie kończy się błędem bazy danych#

Dane nie zgadzają się z zakładką Baza danych (host z pola Host, nie localhost; nazwa bazy dokładnie jak na liście). Typowe komunikaty i ich naprawę opisuje artykuł Baza danych dla FiveM.

ESX = nil (lub attempt to index a nil value (global 'ESX'))#

Skrypt nie ma dostępu do ESX: albo startuje przed es_extended, albo używa starego sposobu wczytywania ESX. Umieść jego ensure pod es_extended i zaktualizuj zarówno es_extended, jak i skrypt do aktualnej wersji.

No such export GetCoreObject in resource qbx_core#

Skrypt QBCore wywołuje rdzeń Qbox bezpośrednio. Na Qbox powinien wywoływać exports['qb-core']:GetCoreObject() (przez bridge). Sprawdź, czy bridge jest włączony (setr qbx:enableBridge "true"), i popraw skrypt albo pobierz wersję dla Qbox.

Native … is not supported#

Framework lub skrypt używa funkcji, której Twoja wersja serwera jeszcze nie zna. Zaktualizuj artefakty do najnowszej wersji (poradnik).

Gracz wisi na ekranie wczytywania#

• Najczęściej błąd w skrypcie multicharacter albo w bazie danych. Sprawdź konsolę serwera i konsolę klienta (F8).
• Qbox z własnym multicharacter: ustaw setr loadscreen:externalShutdown false.
• QBCore po pierwszym wdrożeniu: poczekaj na zakończenie budowania zasobów (yarn).

ESX Multicharacter couldn't connect to the database#

Połączenie z bazą danych nie działa. Sprawdź set mysql_connection_string w server.cfg i linię Database server connection established! w konsoli.

Polecenia admina nie działają#

• QBCore i Qbox: brakuje linii add_principal … z poprawnym identyfikatorem albo dodano ją bez restartu serwera.
• ESX: gracz nie ma grupy admin. Sprawdź przez /group i ustaw przez setgroup.

Dalsza lektura#

• ESX Legacy: dokumentacja (otwiera się w nowym oknie)
• QBCore: dokumentacja (otwiera się w nowym oknie)
• Qbox: dokumentacja (otwiera się w nowym oknie)
• FiveM: Frameworks (otwiera się w nowym oknie)
• Lista przepisów txAdmin (Popular Recipes) (otwiera się w nowym oknie)