Notatki operatora
Jak dodać skrypty do serwera FiveM (resources, ensure)
Dodawanie skryptów to codzienność każdego admina FiveM, a jednocześnie źródło połowy problemów ze startem serwera. Ten poradnik przechodzi przez cały proces: folder resources, plik fxmanifest.lua, wpis ensure w server.cfg, kolejność zależności, restart pojedynczego zasobu bez restartu serwera i najczęstsze błędy.
W skrócie: Skrypt (zasób) to folder z plikiem fxmanifest.lua. Wgrywasz go do katalogu resources, dodajesz w server.cfg linię ensure nazwa_folderu i restartujesz serwer albo wykonujesz w konsoli refresh + ensure nazwa. Nazwa w ensure musi zgadzać się co do znaku z nazwą folderu: bez spacji, bez polskich znaków. Zależności startują przed skryptami, które z nich korzystają.
Jak FiveM widzi skrypty: zasób, manifest, ensure
W nomenklaturze FiveM skrypt to zasób (resource). Zasób to po prostu folder, który zawiera plik fxmanifest.lua, czyli manifest opisujący, co serwer ma załadować: pliki Lua lub JavaScript po stronie serwera i klienta, interfejs, zależności. Bez manifestu folder jest dla serwera niewidzialny.
Serwer nie uruchamia niczego sam z siebie. O tym, które zasoby wystartują, decyduje lista w server.cfg: każda linia ensure nazwa_zasobu to jeden uruchamiany zasób. Ta trójka, folder w resources, manifest w środku i linia ensure, to cały mechanizm.
Krok 1: wgraj folder do resources
Pobrany skrypt (z forum Cfx, GitHuba czy sklepu) rozpakuj i wgraj cały folder do katalogu resources na serwerze, przez SFTP, panel hostingu albo menedżer plików. Dwie pułapki, które załatwiają większość zgłoszeń na Discordach pomocowych:
- Folder w folderze. Po rozpakowaniu zipa często dostajesz
nazwa_skryptu/nazwa_skryptu/fxmanifest.lua. Serwer szuka manifestu na pierwszym poziomie, więc wgraj ten wewnętrzny folder, nie opakowanie. - Nazwa folderu. Bez spacji, bez polskich znaków, najlepiej małe litery i podkreślenia. Nazwa folderu to jednocześnie nazwa, której użyjesz w
ensure.
Z doświadczenia: od razu po pobraniu zajrzyj do środka folderu i sprawdź, czy widzisz fxmanifest.lua (w bardzo starych skryptach: __resource.lua). Jeśli go nie ma na pierwszym poziomie, masz albo zagnieżdżony folder, albo paczkę, która w środku zawiera kilka osobnych zasobów do wgrania osobno.
Krok 2: foldery kategorii w nawiasach kwadratowych
Przy kilkudziesięciu zasobach płaska lista robi się nieczytelna, więc FiveM pozwala grupować zasoby w folderach ujętych w nawiasy kwadratowe, na przykład [mapy], [pojazdy], [framework]. Serwer nie traktuje takiego folderu jako zasobu, tylko zagląda do środka i szuka tam właściwych zasobów.
Uwaga na częsty błąd: zasób może leżeć w folderze kategorii, ale nie w zwykłym folderze bez nawiasów. Ścieżka resources/[pojazdy]/moj_samochod/fxmanifest.lua zadziała, a resources/pojazdy/moj_samochod/... już nie.
Krok 3: dodaj ensure w server.cfg
Otwórz server.cfg i dodaj linię z nazwą folderu zasobu:
# framework i biblioteki najpierw
ensure ox_lib
ensure es_extended
# potem skrypty, które z nich korzystają
ensure moj_hud
ensure moj_samochodDo wpisu ensure podajesz samą nazwę zasobu, bez nazwy folderu kategorii. Serwer sam znajdzie zasób wewnątrz [pojazdy] czy [mapy].
Różnica między start a ensure: obie komendy uruchamiają zasób, ale ensure restartuje go, jeśli już działa. Dzięki temu ta sama linia działa przy starcie serwera i przy ręcznym przeładowaniu, dlatego w praktyce używa się dziś niemal wyłącznie ensure.
Krok 4: kolejność ma znaczenie
Duża część skryptów zależy od innych zasobów: frameworka (ESX, QBCore), biblioteki interfejsu, systemu baz danych. Zasób zależny musi wystartować po tym, od którego zależy, inaczej wysypie się przy starcie z błędami w konsoli.
| Kolejność w server.cfg | Co tu trafia |
|---|---|
| 1. Biblioteki bazowe | Łącznik z bazą danych, biblioteki pomocnicze (na przykład ox_lib) |
| 2. Framework | es_extended (ESX) albo qb-core (QBCore) i jego moduły |
| 3. Skrypty rozgrywki | Prace, HUD-y, sklepy, garaże, wszystko co korzysta z frameworka |
| 4. Mapy i pojazdy | Dodatkowe mapy (MLO) i paczki pojazdów, zwykle niezależne |
Autorzy skryptów podają zależności w opisie lub pliku README. Jeśli konsola przy starcie wypisuje, że jakiś obiekt frameworka nie istnieje, w dziewięciu przypadkach na dziesięć zasób wystartował przed swoją zależnością.
Krok 5: uruchom bez restartu całego serwera
Nowo wgrany zasób możesz uruchomić na działającym serwerze, z konsoli (bezpośrednio albo przez txAdmin):
refresh # przeskanuj katalog resources na nowo
ensure moj_hud # uruchom (lub zrestartuj) zasóbrefresh jest potrzebny tylko wtedy, gdy folder pojawił się w resources już po starcie serwera. Do samego przeładowania działającego zasobu po zmianie configu wystarczy restart nazwa_zasobu. Pamiętaj przy tym, że linia ensure w server.cfg i tak musi istnieć, inaczej zasób nie wstanie po kolejnym restarcie serwera.
Jeśli zarządzasz serwerem przez panel, wygodnie zrobisz to samo z zakładki zasobów w txAdmin. Cały panel opisaliśmy w osobnym wpisie o txAdmin na serwerze FiveM.
Skrypty płatne i assety escrow
Skrypty kupione w sklepach (w tym oficjalnym systemem asset escrow Cfx) wgrywa się identycznie: folder do resources, linia ensure. Różnica polega na tym, że część plików jest zaszyfrowana i weryfikowana licencyjnie po kluczu serwera, więc taki zasób zadziała tylko na serwerze z kluczem przypisanym do konta, na którym dokonano zakupu. Jeśli po wgraniu płatnego skryptu konsola zgłasza błąd uprawnień do assetu, sprawdź, czy klucz licencyjny w server.cfg pochodzi z tego samego konta Cfx co zakup.
Najczęstsze błędy
| Objaw | Przyczyna i ratunek |
|---|---|
couldn't find resource | Nazwa w ensure różni się od nazwy folderu, folder jest zagnieżdżony o poziom za głęboko albo brakuje fxmanifest.lua. Popraw i wykonaj refresh. |
| Zasób startuje, ale sypie błędami frameworka | Zła kolejność: zasób wystartował przed swoją zależnością. Przenieś ensure zależności wyżej w server.cfg. |
| Folder wgrany, serwer go nie widzi | Folder dodany po starcie serwera bez refresh, albo leży w zwykłym (nienawiasowym) podfolderze. |
| Po restarcie serwera skrypt znika | Zasób uruchomiony ręcznie komendą, ale bez linii ensure w server.cfg. Dopisz linię. |
| Błąd licencji przy płatnym zasobie | Klucz serwera z innego konta Cfx niż zakup skryptu. Wygeneruj klucz na właściwym koncie. |
Z doświadczenia: dodawaj skrypty pojedynczo albo małymi partiami i patrz w konsolę po każdym ensure. Wgranie dwudziestu zasobów naraz i restart to przepis na wieczór spędzony na zgadywaniu, który z nich położył serwer. Po jednym na raz diagnoza trwa sekundy.
Najczęstsze pytania
Jak dodać skrypt do serwera FiveM?
Wgraj folder skryptu (z plikiem fxmanifest.lua w środku) do katalogu resources, dodaj w server.cfg linię ensure nazwa_folderu i zrestartuj serwer albo wykonaj refresh + ensure z konsoli.
Czym różni się ensure od start?
Obie uruchamiają zasób, ale ensure restartuje go, jeśli już działa. W praktyce w server.cfg używa się dziś prawie wyłącznie ensure.
Dlaczego widzę couldn't find resource?
Nazwa w ensure nie zgadza się z nazwą folderu, folder jest zagnieżdżony o poziom za głęboko, brakuje manifestu albo kategoria nie jest w nawiasach kwadratowych.
Czy mogę zrestartować jeden skrypt bez restartu serwera?
Tak: restart nazwa_zasobu w konsoli lub w txAdmin. Nowy folder wymaga wcześniej komendy refresh.
Po co foldery w nawiasach kwadratowych?
To katalogi grupujące, na przykład [mapy] czy [pojazdy]. Serwer nie traktuje ich jako zasobów, tylko szuka zasobów w ich wnętrzu.
Powiązane
- Serwer FiveM: kompletny przewodnik po stawianiu serwera - artifacts, server.cfg, klucz licencyjny i porty.
- txAdmin na serwerze FiveM - panel, w którym zasoby restartujesz jednym kliknięciem.
- Dobór sprzętu pod serwer gry - ile mocy potrzebuje serwer z większą paczką skryptów.
- Hosting serwera Minecraft: na co zwrócić uwagę - jeśli obok FiveM prowadzisz też serwer Minecraft.
- Oficjalna dokumentacja: wprowadzenie do zasobów na docs.fivem.net.