QBCore, ESX lub Standalone: jak Agency Scripts współpracują z Twoim frameworkiem

Problem kompatybilności frameworków

Większość skryptów FiveM jest dostarczana z jednym zaszytym na stałe frameworkiem. Jeśli używasz QBCore, korzystasz ze skryptów QBCore. Użytkownicy ESX są skazani na skrypty ESX. Użytkownicy wersji standalone najczęściej sztukują rozwiązania na własną rękę. Agency Scripts powstały w oparciu o przeciwną filozofię: framework jest adapterem, a nie założeniem.

Wzorzec adaptera

Każdy skrypt Agency udostępnia krótki zestaw funkcji wyszukiwania: getPlayerData, getInventory, addMoney, removeItem, getJob. Dostarczamy adaptery, które od razu mapują je na implementacje QBCore i ESX. W przypadku standalone implementujesz te cztery lub pięć funkcji samodzielnie, co zazwyczaj zajmuje jeden poranek, a każdy skrypt Agency jest kompatybilny.

Co to oznacza w praktyce

Gdy zmieniasz na swoim serwerze framework z QBCore na ESX (co zdarza się co kilka lat w miarę rozwoju frameworków), skrypty Agency nie wymagają ponownej instalacji ani rekonfiguracji. Podmieniasz adapter, a cała reszta nadal działa. To niezwykle rzadkie w ekosystemie FiveM i jest głównym powodem, dla którego właściciele serwerów stawiają na nasze narzędzia na dłuższą metę.

Co oznaczają poszczególne etykiety frameworków na naszych stronach produktów

Gdy strona produktu wymienia "QBCore, ESX", oznacza to, że dostarczamy gotowe adaptery dla obu z nich. Gdy mówi "Standalone", mamy na myśli to, że skrypt jest niezależny od frameworka, nie potrzebuje adaptera i działa na każdym serwerze. W praktyce niemal każdy skrypt Agency nadaje się do użytku na konfiguracjach standalone z małą warstwą zgodności (shim).

Kiedy pytać przed zakupem

Jeśli masz nietypową konfigurację, customowy framework, mocno zmodyfikowany QBCore lub coś dedykowanego, otwórz ticket na naszym Discordzie przed zakupem. Uczciwie powiemy ci, co zadziała, co wymaga drobnych poprawek, a czym nie warto zawracać sobie głowy. Bez presji sprzedażowej: wolimy, żebyś kupił jeden pasujący skrypt niż trzy, które nie zadziałają.

Jak wzorzec adaptera działa w praktyce

Po zainstalowaniu skryptu Agency folder zasobu zawiera framework podkatalog z co najmniej trzema plikami: qb.lua, esx.lua, oraz standalone.lua. Główny skrypt automatycznie wykrywa obecny framework, sprawdzając export QBCore lub ESX. Odpowiedni plik adaptera zostaje załadowany, pozostałe nie. Ta autodetekcja następuje przed uruchomieniem jakiejkolwiek logiki rozgrywki, więc wykrywanie frameworka nie powoduje żadnego narzutu podczas działania.

Każdy adapter implementuje ten sam wewnętrzny interfejs API. Jeśli skrypt musi dać graczowi pieniądze, wywołuje Framework.AddMoney(src, amount) wewnętrznie. Ta funkcja w qb.lua wywołuje export pieniędzy QBCore; w esx.lua wywołuje system kont ESX; w standalone.lua wywołuje dowolną funkcję zdefiniowaną w config.lua. Jedno wywołanie, trzy implementacje, zero zmian w skrypcie między frameworkami.

Instalacja na QBCore

W przypadku serwerów QBCore instalacja obejmuje zazwyczaj trzy kroki: pobierz zasób, wrzuć go do folderu resources i dodaj do server.cfg. Wykrywanie frameworka jest automatyczne. Jeśli używasz mocno zmodyfikowanego QBCore (własny system pieniędzy, własny ekwipunek, własne prace), może być konieczne nadpisanie określonych funkcji adaptera w config.lua zamiast edytować qb.lua bezpośrednio. Podejście z nadpisywaniem configu sprawia, że nie stracisz swoich zmian podczas aktualizacji zasobów.

Instalacja na ESX

Instalacja ESX przebiega według tego samego schematu. Jeden dodatkowy krok, który bywa czasem potrzebny: jeśli Twoja wersja ESX jest znacznie starsza (sprzed 1.7), niektóre funkcje adaptera odwołują się do nowszych nazw exportów ESX. Zasób zawiera flagę kompatybilności wstecznej (legacy) Config.ESXLegacy = true który przełącza na starsze wywołania API ESX we wszystkich skryptach Agency, które tego potrzebują.

Instalacja na Standalone

Standalone to obszar, w którym większość właścicieli serwerów napotykała dotąd problemy przy innych skryptach. Ścieżka standalone w Agency Scripts jest jednoznaczna i dobrze udokumentowana. Dla każdego skryptu plik adaptera standalone dokładnie wymienia funkcje, które musisz zaimplementować. Większość skryptów wymaga od czterech do ośmiu funkcji. Każda funkcja posiada komentarz wyjaśniający, co powinna zwracać. Typowa implementacja standalone zajmuje od jednej do trzech godzin w zależności od tego, jak złożony jest twój własny system danych graczy.

Gdy zaimplementujesz adapter dla jednego skryptu Agency, kolejne skrypty zajmują znacznie mniej czasu, te same niestandardowe funkcje często mają zastosowanie w wielu resource'ach.

Dlaczego ma to znaczenie dla długoterminowego działania serwera

Frameworki FiveM nie są wieczne. Serwery działające od trzech lub więcej lat prawdopodobnie przeszły już przynajmniej jedną poważną zmianę frameworka, być może migrację ze społecznościowego forka ESX do głównej wersji ESX albo ze starszego QBCore do aktualnej wersji. Serwery polegające na skryptach ściśle powiązanych z frameworkiem płacą wysoki koszt migracji: każdy skrypt wymaga aktualizacji lub wymiany, gdy framework znacząco się zmienia.

Architektura adapterów Agency Scripts oznacza, że migracja frameworka wpływa tylko na warstwę adaptera. Twoje dane z Agency-Phone, logi Agency-Admin, historia transakcji Agency-Blackmarket i postępy graczy w Agency-Minerjob pozostają w nienaruszonym stanie. Podmieniasz pliki adaptera, aktualizujesz config.lua, a skrypty działają dalej. To jest rzeczywista, długoterminowa wartość podejścia opartego na kompatybilności: nie tylko wspieranie wielu frameworków, ale także izolowanie Twojego serwera od ewolucji frameworków.

Często zadawane pytania

Czy wszystkie skrypty Agency używają tego samego wzorca adaptera?

Tak. Każdy płatny skrypt Agency i większość darmowych korzysta z tego wzorca. Jedynymi wyjątkami są zasoby czysto interfejsowe, takie jak Agency-Loadingscreen i Agency-Notify, które nie wchodzą w żadną interakcję z frameworkiem i działają wszędzie identycznie.

Czy mogę mieszać adaptery frameworków? Na przykład używać pieniędzy z QBCore, ale ekwipunku standalone?

Tak, za pomocą nadpisań w konfiguracji. Ustaw wykrywanie frameworka na QBCore, a następnie nadpisz określone funkcje adaptera w config.lua, aby wywoływały twój niestandardowy system ekwipunku zamiast systemu QBCore. System nadpisywania istnieje właśnie dla serwerów z konfiguracjami hybrydowymi.

Co jeśli nowy framework zyska popularność i nie jest jeszcze obsługiwany?

Otwórz ticket wsparcia na Discord. Oceniamy prośby o wsparcie nowych frameworków na podstawie ich popularności w społeczności. W przypadku frameworków ze znaczącą społecznością historycznie dodawaliśmy wsparcie w ciągu 2-4 tygodni. W międzyczasie ścieżka adaptera standalone działa dla każdego frameworka jako rozwiązanie tymczasowe.

Czy adaptery frameworka są aktualizowane, gdy sam framework jest aktualizowany?

Tak. Gdy QBCore lub ESX wprowadza zmiany powodujące brak kompatybilności wstecznej, publikujemy aktualizacje adaptera w ciągu kilku dni od wydania frameworka. Aktywni subskrybenci otrzymują powiadomienia o aktualizacjach przez Tebex. To jeden z powodów istnienia modelu subskrypcyjnego: utrzymanie adaptera to ciągła praca, a nie jednorazowy koszt.

Podsumowanie wymagań według frameworka

• QBCore, dowolna najnowsza wersja QBCore. Wykrywana automatycznie, zerowa konfiguracja dla standardowych instalacji.
• ESX, ESX Legacy 1.7+ lub główna linia ESX. Ustaw flagę legacy dla starszych wersji.
• Standalone, zaimplementuj od 4 do 8 funkcji na skrypt w config.lua. Jednorazowa konfiguracja, do wielokrotnego użytku we wszystkich skryptach Agency.
• Wszystkie konfiguracje, konto cfx.re z ważną licencją, zalecany serwer FiveM z Artifacts 5181 lub nowszym.