Jak Przenieść Serwer z ESX na QBCore? Poradnik Techniczny FiveM

Migracja serwera FiveM z frameworka ESX na QBCore to jedno z największych wyzwań technicznych, przed jakimi mogą stanąć właściciele serwerów. Choć proces jest złożony, przejście na QBCore często przynosi znaczące korzyści w postaci lepszej optymalizacji, nowocześniejszej struktury kodu i aktywnego wsparcia społeczności. Ten poradnik krok po kroku przeprowadzi Cię przez kluczowe etapy migracji, minimalizując ryzyko utraty danych i przestojów.

Celem tego artykułu jest przedstawienie ustrukturyzowanego planu działania, który pozwoli na przeniesienie kluczowych danych graczy, takich jak konta, postacie czy pojazdy, oraz pomoże zrozumieć, jak podejść do konwersji skryptów. Po przeczytaniu tego poradnika będziesz gotowy, aby świadomie zaplanować i rozpocząć proces migracji swojego serwera na QBCore.

Wymagania Wstępne

• Pełen dostęp do plików serwera (np. przez FTP, SFTP lub panel hostingowy).
• Dostęp do bazy danych serwera (np. przez phpMyAdmin lub HeidiSQL).
• Edytor kodu, taki jak Visual Studio Code, do edycji plików konfiguracyjnych i skryptów.
• Podstawowa znajomość struktury serwera FiveM oraz języka LUA i zapytań SQL.
• Świeża, czysta instalacja serwera z QBCore Framework.
• Kompletna kopia zapasowa (backup) starego serwera opartego na ESX (pliki i baza danych).

Przewodnik Krok po Kroku

1. Krok 1: Wykonaj pełną kopię zapasową

   Zanim zaczniesz cokolwiek zmieniać, wykonaj pełny backup swojego serwera ESX. Obejmuje to wszystkie pliki z folderu resources oraz zrzut (dump) całej bazy danych. To absolutnie kluczowy krok, który zabezpieczy Cię przed utratą danych w razie niepowodzenia.

2. Krok 2: Przygotuj czystą instalację QBCore

   Bezpośrednia „aktualizacja” z ESX na QBCore nie jest możliwa. Najlepszym i najbezpieczniejszym podejściem jest rozpoczęcie od nowa. Zainstaluj świeży serwer FiveM z najnowszą wersją QBCore Framework zgodnie z oficjalną dokumentacją. Upewnij się, że serwer uruchamia się poprawnie bez żadnych błędów, zanim przejdziesz dalej.

3. Krok 3: Migracja bazy danych

   To najbardziej krytyczna część procesu. Struktury baz danych ESX i QBCore różnią się. Musisz przenieść dane ręcznie lub za pomocą skryptu migracyjnego. Skup się na najważniejszych tabelach:

   • Użytkownicy (users): W ESX dane takie jak pieniądze, praca czy ekwipunek często są przechowywane w tabeli users w formacie JSON. W QBCore dane te znajdują się w tabeli players i mają inną strukturę. Będziesz musiał napisać skrypt (np. w LUA lub Pythonie) lub serię zapytań SQL, aby przenieść identyfikatory graczy (np. `license`), pieniądze i inne podstawowe informacje.
   • Pojazdy (owned_vehicles): Podobnie, tabela z pojazdami graczy (w ESX często owned_vehicles) musi zostać zmapowana na strukturę tabeli player_vehicles w QBCore. Zwróć uwagę na format zapisu modyfikacji i danych pojazdu.
   • Inne dane: Przeanalizuj, jakie inne dane są dla Ciebie kluczowe (np. gangi, nieruchomości) i zaplanuj ich migrację.
4. Krok 4: Konwersja lub wymiana skryptów

   Skrypty napisane dla ESX nie będą działać na QBCore. Każdy skrypt musi zostać zastąpiony jego odpowiednikiem dla QBCore lub przepisany od zera. Wiele popularnych skryptów ma swoje wersje dla obu frameworków. Kluczowe różnice, na które trzeba zwrócić uwagę, to sposób odwoływania się do gracza, obsługa eventów oraz funkcje frameworka (np. pokazywanie powiadomień, zarządzanie pieniędzmi).

5. Krok 5: Konfiguracja i uruchomienie

   Po przeniesieniu bazy danych i przygotowaniu skryptów dla QBCore, zaktualizuj swój plik server.cfg. Upewnij się, że uruchamiasz wszystkie niezbędne zasoby QBCore (qb-core, qb-menu, itd.), a wszystkie stare zasoby ESX są usunięte lub wyłączone. Uruchom serwer i dokładnie przeanalizuj konsolę w poszukiwaniu błędów.

6. Krok 6: Intensywne testy

   Przed publicznym udostępnieniem serwera, przeprowadź gruntowne testy. Sprawdź logowanie, tworzenie postaci, działanie prac, systemów ekonomicznych i wszystkich kluczowych funkcji. Poproś zaufanych graczy o pomoc w znalezieniu błędów. Ten etap może zająć nawet kilka dni, ale jest niezbędny do zapewnienia stabilności.

Przykładowy Kod / Konfiguracja

Poniżej znajduje się prosty przykład pokazujący różnicę w wywoływaniu funkcji powiadomienia w skrypcie po stronie klienta między ESX a QBCore. To ilustruje, dlaczego skrypty wymagają przepisania.

Powiadomienie w ESX:

-- Plik client.lua w skrypcie ESX

-- Rejestracja eventu z serwera
RegisterNetEvent('esx:showNotification')
AddEventHandler('esx:showNotification', function(message)
  ESX.ShowNotification(message)
end)

Powiadomienie w QBCore:

-- Plik client.lua w skrypcie QBCore

-- Rejestracja eventu z serwera
RegisterNetEvent('QBCore:Notify', function(message, type)
  QBCore.Functions.Notify(message, type)
end)

-- Przykład użycia:
-- QBCore.Functions.Notify("Witaj na serwerze!", "success", 5000)

Jak widać, mimo że cel jest ten sam, nazwy funkcji, eventów i przekazywane argumenty są zupełnie inne. Ta fundamentalna różnica dotyczy niemal każdej interakcji z frameworkiem, od pobierania danych gracza po zarządzanie przedmiotami.

Podsumowanie

Migracja serwera z ESX na QBCore to maraton, a nie sprint. Proces wymaga starannego planowania, cierpliwości i podstawowej wiedzy technicznej. Kluczem do sukcesu jest metodyczne podejście: solidny backup, czysta instalacja, przemyślana migracja bazy danych i skrupulatne testowanie. Choć początkowy wysiłek jest duży, nagrodą jest serwer działający na nowoczesnym, wydajnym i dobrze wspieranym frameworku.

Nie spiesz się i nie bój się prosić o pomoc na forach deweloperskich QBCore. Pamiętaj, że lepiej poświęcić więcej czasu na przygotowania, niż zmagać się z błędami i utraconymi danymi po nieudanej próbie migracji na „żywym” serwerze.