Zasoby FiveM: instalacja skryptów, ensure i kolejność wczytywania

Wszystko, co na serwerze FiveM „coś robi” (framework, prace, samochody, mapy, HUD), jest zasobem (resource). Pokażemy, jak poprawnie przesłać skrypt, uruchomić go we właściwej kolejności i co zrobić, gdy nie chce wystartować.

Czym jest zasób#

Zasób to folder ze skryptami i plikami, który serwer może uruchomić, zatrzymać i zrestartować. Aby serwer go rozpoznał, musi zawierać plik fxmanifest.lua (__resource.lua w bardzo starych skryptach).

• Nazwa folderu to nazwa zasobu. Folder ox_lib = zasób ox_lib. Tę nazwę wpisujesz w ensure.
• W środku są zwykle skrypty dla serwera (server/), dla graczy (client/), współdzielone (shared/), konfiguracja (config.lua), interfejs WWW (html/, web/) i modele (stream/).
• Skrypt standalone działa samodzielnie. Inne potrzebują frameworka (ESX, QBCore, Qbox) lub biblioteki (ox_lib, oxmysql). Autor podaje, czego skrypt potrzebuje, w instrukcji (README).

Folder resources i kategorie#

Serwer szuka zasobów w folderze resources obok server.cfg. Foldery w nawiasach kwadratowych to kategorie: nie są zasobami, tylko sposobem na porządek.

server.cfg
resources/
├── [standalone]/
│   ├── oxmysql/
│   │   └── fxmanifest.lua
│   └── ox_lib/
│       └── fxmanifest.lua
├── [esx]/
│   └── es_extended/
│       └── fxmanifest.lua
└── muj_skript/
    └── fxmanifest.lua

To drzewo zawiera zasoby oxmysql, ox_lib, es_extended i muj_skript. Całą kategorię uruchamiasz jedną linią, ensure [standalone]. Kategorie można też zagnieżdżać.

Na serwerze z txAdmin folder resources znajduje się w folderze wdrożenia (txAdmin proponuje txData/<NAZWA>_<KOD>.base).

Skąd brać skrypty#

• Oficjalne źródła: sekcja Releases na forum Cfx.re (otwiera się w nowym oknie), Cfx Marketplace, GitHub autora (sekcja Releases).
• Płatne skrypty kupuj tylko przez Cfx Marketplace lub Tebex. Gdziekolwiek indziej ryzykujesz oszustwo.
• Nie używaj „leaków” (kradzionych płatnych skryptów). Często zawierają złośliwy kod, który „zaraża” inne zasoby albo daje obcym dostęp do Twojego serwera. FiveM zgłasza taki kod jako prohibited logic.

Instalacja skryptu krok po kroku#

Przygotowanie na komputerze#

1. Pobierz skrypt. Jeśli ma na GitHubie sekcję Releases, pobierz archiwum stamtąd, a nie przez Code › Download ZIP. Wydanie zawiera zbudowany interfejs WWW; kod źródłowy często nie.

2. Rozpakuj archiwum.

3. Znajdź folder, który bezpośrednio zawiera fxmanifest.lua. To jest zasób.

4. Zmień nazwę folderu na tę, którą podaje autor. Zazwyczaj usuń przyrostek z GitHuba: ox_lib-main zmień na ox_lib.

   Dlaczego: inne skrypty odwołują się do zasobu po nazwie. Dla nich ox_lib-main by nie istniał.

5. Przeczytaj README: jakie zależności ma skrypt, czy zawiera plik .sql i co ustawić w config.lua.

Przesyłanie na serwer#

1. W strefie klienta otwórz Moje usługi, kliknij swój serwer i przejdź do zakładki Pliki.
2. Otwórz folder resources (lub kategorię, na przykład [standalone]).
3. Kliknij Nowy folder i utwórz folder o nazwie zasobu, na przykład muj_skript.
4. Otwórz go i prześlij pliki przyciskiem Prześlij. Podfoldery (client, server, html …) odtwórz przez Nowy folder i prześlij do nich ich pliki.

Zakładka Pliki przesyła pojedyncze pliki do 100 MB i nie rozpakowuje archiwów. Duże zasoby (samochody, ubrania, mapy, cały framework) przesyłaj przez SFTP. Dostęp skonfiguruje dla Ciebie pomoc techniczna (kontakt); procedura jest w artykule Zarządzanie plikami.

Baza danych i konfiguracja#

1. Jeśli skrypt zawiera plik .sql, zaimportuj go do bazy danych serwera. Procedura z HeidiSQL jest w artykule Baza danych dla FiveM.

2. Otwórz config.lua (lub config/*.lua) w edytorze zakładki Pliki i przejrzyj ustawienia. Typowe opcje:

   Opcja (przykład)	Co zwykle robi
   Config.Framework = 'esx'	Pod jaki framework skrypt jest ustawiony (esx, qb, qbx). Musi pasować do Twojego serwera.
   Config.Locale = 'cs'	Język tekstów (tutaj czeski), jeśli skrypt zawiera ten język.
   Config.Debug = false	Wyjście diagnostyczne. Na działającym serwerze zostaw false.

   Nazwy opcji różnią się między skryptami. Autor wyjaśnia dokładnie ich działanie w komentarzach w pliku.

Włączanie skryptu#

1. Dodaj tę linię do server.cfg (w CFG Editor, jeśli używasz txAdmin):

   ensure muj_skript

   • ensure – uruchamia zasób (i restartuje go, jeśli już działa).
   • muj_skript – nazwa folderu zasobu.

   Umieść linię pod wszystkimi zależnościami skryptu (framework, oxmysql, ox_lib). Jeśli skrypt jest w kategorii, którą już uruchamiasz (ensure [standalone]), linii nie musisz dodawać.

2. Zrestartuj serwer. Albo uruchom skrypt bez restartu, poleceniami w konsoli (strefa klienta albo Live Console w txAdmin):

   refresh
   ensure muj_skript

   • refresh – serwer ponownie skanuje folder resources i znajduje nowe zasoby. Bez tego serwer nie wie o nowym skrypcie.
   • ensure muj_skript – uruchamia go.

Skrypty, które zmieniają dane graczy lub dodają przedmioty do ekwipunków, lepiej uruchamiać restartem całego serwera, a nie w trakcie jego działania.

fxmanifest.lua: co w nim jest#

fx_version 'cerulean'
game 'gta5'

author 'Jan'
description 'Przykładowy skrypt'
version '1.0.0'

shared_script 'config.lua'
client_scripts {
    'client/*.lua'
}
server_scripts {
    '@oxmysql/lib/MySQL.lua',
    'server/*.lua'
}

ui_page 'html/index.html'
files {
    'html/index.html',
    'html/app.js'
}

dependencies {
    'oxmysql',
    'ox_lib'
}

Starszy wpis lua54 'yes' nie jest już potrzebny: od czerwca 2025 wszystkie skrypty działają na Lua 5.4.

Zależności i kolejność wczytywania#

• Zasoby startują w kolejności linii ensure w server.cfg.
• Zwykła kolejność: standardowe zasoby FiveM › oxmysql › ox_lib › rdzeń frameworka › skrypty frameworka › Twoje skrypty.
• Wpis dependencies w manifeście może też wymagać warunków serwera, na przykład '/onesync' (włączony OneSync), '/server:4500' (minimalny build serwera) lub '/gameBuild:h4' (minimalny game build). Jeśli warunek nie jest spełniony, skrypt nie wystartuje.

Płatne skrypty i Asset Escrow#

Płatne skrypty z Cfx Marketplace lub Tebex są zwykle chronione przez Asset Escrow: kod jest zaszyfrowany i działa tylko na serwerach kupującego.

• Skrypt działa tylko na serwerze, którego klucz licencyjny należy do tego samego konta Cfx.re, z którego kupiono skrypt. Pobierz go z Cfx.re Portal (otwiera się w nowym oknie) albo z linku w e-mailu od Tebex.
• Zaszyfrowanych plików nie da się edytować. Autor zwykle zostawia pliki konfiguracyjne (config.lua) otwarte i te możesz edytować.
• Zasób zawiera plik .fxap. Musi zostać przesłany na serwer razem z resztą, inaczej skryptu nie da się zweryfikować.

Samochody, ubrania i mapy (pliki streamowane)#

Modele i tekstury są „streamowane” do graczy: pobierają je z serwera przy łączeniu. Taki zasób ma zwykle folder stream i odwołania do plików danych gry w manifeście.

fx_version 'cerulean'
game 'gta5'

files {
    'data/vehicles.meta',
    'data/carvariations.meta',
    'data/handling.meta'
}

data_file 'VEHICLE_METADATA_FILE' 'data/vehicles.meta'
data_file 'VEHICLE_VARIATION_FILE' 'data/carvariations.meta'
data_file 'HANDLING_FILE' 'data/handling.meta'

Praktyczne wskazówki:

• Każdy samochód lub mapa zwiększa pobieranie przy pierwszym połączeniu. Dziesiątki samochodów z teksturami w wysokiej rozdzielczości oznaczają długie wczytywanie.
• Wnętrza (MLO) często wymagają określonego game buildu (sv_enforceGameBuild) albo innego zasobu z danymi bazowymi. Przeczytaj README.
• Duże paczki samochodów i map przesyłaj przez SFTP; pliki często mają ponad 100 MB.

Sprawdzenie skryptu przed instalacją#

Skrypt działa na serwerze z pełnym dostępem do jego danych, bazy danych i graczy. Zanim go uruchomisz, sprawdź przynajmniej:

• Źródło: oficjalny GitHub autora, forum Cfx.re, Cfx Marketplace lub Tebex. Nie przypadkowe linki z Discorda.
• Nieczytelny kod w skądinąd otwartym skrypcie (długie ciągi bezsensownych znaków, load( z pobranym tekstem). Płatne skrypty szyfruje Asset Escrow, ale swobodnie dostępny skrypt nie powinien zawierać takiego kodu.
• Wysyłanie danych gdzie indziej: wywołania PerformHttpRequest na adresy niezwiązane ze skryptem.
• Nowe polecenia admina, o których README nie wspomina.

Jeśli FiveM zgłasza dla zasobu prohibited logic, zasób prawdopodobnie zawiera złośliwy kod, który mógł zarazić także inne zasoby. Usuń go i sprawdź pozostałe skrypty.

Wydajność zasobów#

• Serwer wypisuje w konsoli server thread hitch warning: timer interval of … milliseconds, gdy jeden tick serwera trwał dłużej niż 150 ms. Sporadyczny komunikat przy starcie jest w porządku. Częste komunikaty podczas pracy oznaczają, że jakiś skrypt przeciąża serwer.
• Winowajcę znajdziesz wbudowanym profilerem: w konsoli serwera wpisz profiler record 500 (nagrywa 500 klatek), poczekaj, a potem profiler saveJSON profil.json. Plik zapisuje się w folderze, z którego uruchamiany jest serwer. Pobierz go w zakładce Pliki i otwórz w narzędziach deweloperskich Chrome (zakładka Performance › wczytaj profil).
• Po stronie gracza polecenie resmon w konsoli F8 pokazuje obciążenie poszczególnych zasobów. Działa tylko w trybie deweloperskim klienta (w przeciwnym razie zgłasza Access denied for command resmon).

Polecenia do pracy z zasobami#

Polecenia wpisuj w konsoli serwera bez ukośnika. W txAdmin to samo znajdziesz w formie graficznej na stronie Resources.

Weryfikacja#

• Po restarcie lub ensure konsola pokazuje linię Started resource muj_skript.
• W txAdmin strona Resources pokazuje zasób jako uruchomiony.
• Skrypt działa w grze, a w konsoli klienta (F8) nie ma czerwonych błędów.

Rozwiązywanie problemów#

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

Couldn't find resource muj_skript.#

Serwer nie zna zasobu o tej nazwie.

• Nazwa w ensure nie zgadza się z nazwą folderu (wielkość liter ma znaczenie; uważaj na -main).
• fxmanifest.lua nie jest bezpośrednio w folderze (podwojony folder po rozpakowaniu).
• Skrypt przesłano przy działającym serwerze bez uruchomienia refresh.
• Folder jest poza resources albo w innym resources, niż używa serwer (z txAdmin jest to folder wdrożenia).

Could not find dependency ox_lib for resource muj_skript.#

Brakuje zależności. Zainstaluj zasób wymieniony w komunikacie (tutaj ox_lib) i umieść jego ensure nad skryptem. Komunikat Could not start dependency … oznacza, że zależność istnieje, ale sama nie wystartowała. Poszukaj jej błędu w konsoli.

Couldn't start resource muj_skript.#

Zasób istnieje, ale się nie uruchomił. Prawdziwy powód jest zwykle tuż nad tym komunikatem w konsoli: brakująca zależność, błąd manifestu, niespełniony warunek (OneSync, game build) albo błąd licencji.

Ostrzeżenie, że zasób nie ma manifestu#

W folderze brakuje fxmanifest.lua (albo plik ma inną nazwę, na przykład fxmanifest.lua.txt z Windows). Sprawdź nazwę pliku i poszukaj podwojonego folderu.

SCRIPT ERROR: @muj_skript/server/main.lua:25: …#

Błąd bezpośrednio w kodzie skryptu. Po dwukropku są plik, numer linii i opis. Najczęstsze przyczyny: błędne ustawienie frameworka w config.lua, brakująca tabela w bazie danych (nie zaimportowano .sql), niezgodna wersja frameworka. Błędy po stronie gracza zobaczysz w konsoli F8.

You lack the required entitlement to use muj_skript#

Płatny skrypt kupiono na innym koncie Cfx.re niż to, do którego należy klucz licencyjny serwera. Użyj klucza licencyjnego z tego samego konta albo przenieś skrypt na właściwe konto w Portalu. Spróbuj też zrestartować serwer.

Failed to verify protected resource muj_skript#

Pliki zaszyfrowanego skryptu są uszkodzone albo któregoś brakuje, zwykle .fxap. Prześlij cały zasób ponownie, łącznie z plikiem .fxap. Niektóre programy SFTP nie przesyłają plików ukrytych (zaczynających się od kropki); włącz w nich pokazywanie plików ukrytych.

Error parsing script lub Failed to load script#

Skrypt używa funkcji nowszej wersji serwera. Zaktualizuj artefakty (poradnik).

Interfejs skryptu (menu, telefon, HUD) się nie pokazuje#

Brakuje zbudowanego interfejsu WWW. Pobierz skrypt z sekcji Releases zamiast kodu źródłowego albo zbuduj interfejs według README (npm install i npm run build na komputerze) i prześlij wynikowy folder.

Dalsza lektura#

• FiveM: Introduction to Resources (otwiera się w nowym oknie)
• FiveM: Resource Manifest (otwiera się w nowym oknie)
• FiveM: Server Commands (start, stop, ensure, refresh) (otwiera się w nowym oknie)
• FiveM: Asset Escrow (otwiera się w nowym oknie)