FiveM resources: instalace skriptů, ensure a pořadí načítání

Všechno, co na FiveM serveru „něco dělá“ (framework, práce, auta, mapy, HUD), je resource. Ukážeme, jak skript správně nahrát, zapnout ve správném pořadí a co dělat, když se nespustí.

Co je resource#

Resource je složka se skripty a soubory, kterou server umí spustit, zastavit a restartovat. Aby ji server poznal, musí v ní být soubor fxmanifest.lua (u velmi starých skriptů __resource.lua).

• Název složky je název resource. Složka ox_lib = resource ox_lib. Tento název píšete do ensure.
• Uvnitř bývají skripty pro server (server/), pro hráče (client/), sdílené (shared/), konfigurace (config.lua), webové rozhraní (html/, web/) a modely (stream/).
• Standalone skript funguje sám. Ostatní potřebují framework (ESX, QBCore, Qbox) nebo knihovnu (ox_lib, oxmysql). Co skript potřebuje, píše autor v návodu (README).

Složka resources a kategorie#

Server hledá resources ve složce resources vedle server.cfg. Složky v hranatých závorkách jsou kategorie: nejsou to resources, jen pořádek.

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

Tady existují resources oxmysql, ox_lib, es_extended a muj_skript. Celou kategorii spustíte jedním řádkem ensure [standalone]. Kategorie jdou i vnořovat.

U serveru s txAdminem je složka resources ve složce nasazení (txAdmin ji navrhuje jako txData/<NAZEV>_<KOD>.base).

Kde skripty brát#

• Oficiální zdroje: sekce Releases na fóru Cfx.re (otevře se v novém okně), Cfx Marketplace, GitHub autora (sekce Releases).
• Placené skripty kupujte jen přes Cfx Marketplace nebo Tebex. Jinde hrozí podvod.
• Nepoužívejte „leaky“ (kradené placené skripty). Často obsahují škodlivý kód, který „nakazí“ další resources nebo pošle cizím lidem přístup k serveru. FiveM takový kód hlásí jako prohibited logic.

Instalace skriptu krok za krokem#

Příprava v počítači#

1. Stáhněte skript. Pokud má na GitHubu sekci Releases, stáhněte archiv odtamtud, ne přes Code › Download ZIP. Release obsahuje sestavené webové rozhraní, zdrojový kód často ne.

2. Archiv rozbalte.

3. Najděte složku, ve které je přímo fxmanifest.lua. To je resource.

4. Složku přejmenujte na název, který uvádí autor. Typicky odstraňte příponu z GitHubu: ox_lib-main přejmenujte na ox_lib.

   Proč: jiné skripty se na resource odkazují jménem. ox_lib-main by pro ně neexistoval.

5. Přečtěte si README: jaké má skript závislosti (dependencies), jestli má soubor .sql a co nastavit v config.lua.

Nahrání na server#

1. V zákaznické zóně otevřete Moje služby, klikněte na server a přejděte na záložku Soubory.
2. Otevřete složku resources (případně kategorii, například [standalone]).
3. Klikněte na Nová složka a vytvořte složku s názvem resource, například muj_skript.
4. Otevřete ji a tlačítkem Nahrát nahrajte soubory. Podsložky (client, server, html …) vytvořte znovu tlačítkem Nová složka a nahrajte do nich jejich soubory.

Záložka Soubory nahrává jednotlivé soubory do 100 MB a archivy nerozbaluje. Velké resources (auta, oblečení, mapy, celý framework) nahrajte přes SFTP. Přístup vám zřídí podpora (kontakty), postup je v návodu Správa souborů.

Databáze a konfigurace#

1. Pokud skript obsahuje soubor .sql, naimportujte ho do databáze serveru. Postup s programem HeidiSQL je v návodu Databáze pro FiveM.

2. Otevřete config.lua (nebo config/*.lua) v editoru záložky Soubory a projděte nastavení. Typické volby:

   Volba (příklad)	Co obvykle dělá
   Config.Framework = 'esx'	Pro jaký framework se skript nastaví (esx, qb, qbx). Musí odpovídat vašemu serveru.
   Config.Locale = 'cs'	Jazyk textů, pokud skript češtinu má.
   Config.Debug = false	Ladicí výpisy. Na ostrém serveru nechte false.

   Názvy voleb se liší skript od skriptu. Co přesně dělají, píše autor v komentářích souboru.

Zapnutí skriptu#

1. Do server.cfg (u txAdminu v CFG Editoru) přidejte řádek:

   ensure muj_skript

   • ensure – spustí resource (a když už běží, restartuje ho).
   • muj_skript – název složky resource.

   Řádek dejte pod všechny závislosti skriptu (framework, oxmysql, ox_lib). Pokud je skript v kategorii, kterou už spouštíte (ensure [standalone]), řádek přidávat nemusíte.

2. Restartujte server. Nebo skript spusťte bez restartu, příkazy v konzoli (zákaznická zóna, nebo Live Console v txAdminu):

   refresh
   ensure muj_skript

   • refresh – server znovu projde složku resources a najde nové resources. Bez něj nový skript nezná.
   • ensure muj_skript – spustí ho.

Skripty, které mění data hráčů nebo přidávají věci do inventáře, raději spouštějte restartem celého serveru, ne za běhu.

fxmanifest.lua: co v něm je#

fx_version 'cerulean'
game 'gta5'

author 'Jan'
description 'Ukázkový skript'
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'
}

Starší položka lua54 'yes' už není potřeba: od června 2025 běží všechny skripty v Lua 5.4.

Závislosti a pořadí načítání#

• Resources se spouštějí v pořadí řádků ensure v server.cfg.
• Obvyklé pořadí: standardní resources FiveM › oxmysql › ox_lib › jádro frameworku › skripty frameworku › vaše skripty.
• Řádek dependencies v manifestu může vyžadovat i podmínky serveru, například '/onesync' (zapnutý OneSync), '/server:4500' (minimální build serveru) nebo '/gameBuild:h4' (minimální game build). Když podmínka neplatí, skript se nespustí.

Placené skripty a Asset Escrow#

Placené skripty z Cfx Marketplace nebo Tebexu bývají chráněné systémem Asset Escrow: kód je zašifrovaný a běží jen na serverech kupujícího.

• Skript poběží jen na serveru, jehož license key patří stejnému účtu Cfx.re, na kterém jste skript koupili. Stáhnete ho z Cfx.re Portalu (otevře se v novém okně) nebo z odkazu v e-mailu od Tebexu.
• Zašifrované soubory upravit nejde. Autor obvykle nechává otevřené konfigurační soubory (config.lua), ty upravovat můžete.
• V resource je soubor .fxap. Musí se na server nahrát spolu s ostatními, jinak skript nepůjde ověřit.

Auta, oblečení a mapy (streamované soubory)#

Modely a textury se hráčům „streamují“: při připojení si je stáhnou ze serveru. Takový resource má obvykle složku stream a v manifestu odkazy na herní datové soubory.

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'

Praktické rady:

• Každé auto nebo mapa zvětšuje stahování při prvním připojení. Desítky aut s vysokým rozlišením textur znamenají dlouhé načítání.
• Interiéry (MLO) často vyžadují určitý game build (sv_enforceGameBuild) nebo jiný resource se základními daty. Čtěte README.
• Velké balíčky aut a map nahrávejte přes SFTP, soubory bývají větší než 100 MB.

Kontrola skriptu před instalací#

Skript běží na serveru s plným přístupem k jeho datům, databázi a hráčům. Než ho spustíte, projděte aspoň:

• Zdroj: oficiální GitHub autora, fórum Cfx.re, Cfx Marketplace nebo Tebex. Ne náhodné odkazy z Discordu.
• Nečitelný kód v jinak otevřeném skriptu (dlouhé řetězce nesmyslných znaků, load( se staženým textem). Placené skripty jsou šifrované přes Asset Escrow, ale zdarma dostupný skript by takový kód mít neměl.
• Odesílání dat jinam: volání PerformHttpRequest na adresy, které se skriptem nesouvisejí.
• Nové admin příkazy, o kterých README neříká.

Když FiveM u resource ohlásí prohibited logic, resource pravděpodobně obsahuje škodlivý kód, který mohl nakazit i jiné resources. Odstraňte ho a zkontrolujte ostatní skripty.

Výkon resources#

• Server hlásí v konzoli server thread hitch warning: timer interval of … milliseconds, když jedno kolo serveru trvalo déle než 150 ms. Občasná hláška při startu nevadí. Časté hlášky za běhu znamenají, že některý skript zatěžuje server.
• Viníka najdete vestavěným profilerem: v konzoli serveru zadejte profiler record 500 (nahraje 500 snímků), počkejte, pak profiler saveJSON profil.json. Soubor se uloží do složky, ze které se server spouští. Stáhněte si ho v záložce Soubory a otevřete v prohlížeči Chrome v nástrojích pro vývojáře (záložka Performance › načíst profil).
• Na straně hráče ukazuje zátěž jednotlivých resources příkaz resmon v konzoli F8. Funguje jen ve vývojářském režimu klienta (jinak hlásí Access denied for command resmon).

Příkazy pro práci s resources#

Příkazy píšete do konzole serveru bez lomítka. V txAdminu najdete totéž graficky na stránce Resources.

Ověření#

• Po restartu nebo ensure je v konzoli řádek Started resource muj_skript.
• V txAdminu na stránce Resources je resource ve stavu spuštěný.
• Ve hře skript funguje a v klientské konzoli (F8) nejsou červené chyby.

Když něco nefunguje#

Hlášky, které tu nenajdete, hledejte v přehledu Časté chyby FiveM serveru.

Couldn't find resource muj_skript.#

Server resource s tímto názvem nezná.

• Název v ensure nesedí s názvem složky (velká a malá písmena se rozlišují, pozor na -main).
• fxmanifest.lua není přímo ve složce (zdvojená složka po rozbalení).
• Skript jste nahráli za běhu a nezadali refresh.
• Složka je mimo resources, nebo v jiném resources, než který server používá (u txAdminu je to složka nasazení).

Could not find dependency ox_lib for resource muj_skript.#

Chybí závislost. Nainstalujte resource uvedený v hlášce (tady ox_lib) a dejte jeho ensure nad skript. Hláška Could not start dependency … znamená, že závislost existuje, ale sama se nespustila. Hledejte v konzoli její chybu.

Couldn't start resource muj_skript.#

Resource existuje, ale nespustil se. Nad touto hláškou v konzoli bývá skutečný důvod: chybějící závislost, chyba v manifestu, nesplněná podmínka (OneSync, game build) nebo chyba licence.

Varování, že resource nemá manifest#

Ve složce chybí fxmanifest.lua (nebo má jiný název, třeba fxmanifest.lua.txt z Windows). Zkontrolujte název souboru a zdvojenou složku.

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

Chyba přímo v kódu skriptu. Za dvojtečkou je soubor, číslo řádku a popis. Nejčastější příčiny: špatné nastavení frameworku v config.lua, chybějící tabulka v databázi (neimportovali jste .sql), nekompatibilní verze frameworku. Chyby u hráče uvidíte v konzoli F8.

You lack the required entitlement to use muj_skript#

Placený skript je koupený na jiném účtu Cfx.re, než ke kterému patří license key serveru. Použijte license key ze stejného účtu, nebo skript převeďte na Portalu na správný účet. Zkuste také server restartovat.

Failed to verify protected resource muj_skript#

Soubory zašifrovaného skriptu se poškodily nebo některý chybí, typicky .fxap. Nahrajte resource znovu celý, včetně souboru .fxap. Některé SFTP programy skryté soubory (začínající tečkou) nepřenášejí, zapněte v nich zobrazení skrytých souborů.

Error parsing script nebo Failed to load script#

Skript používá funkce novější verze serveru. Aktualizujte artefakty (návod).

Rozhraní skriptu (menu, telefon, HUD) se nezobrazí#

Chybí sestavené webové rozhraní. Stáhněte skript ze sekce Releases místo zdrojového kódu, nebo podle README rozhraní sestavte (npm install a npm run build v počítači) a nahrajte výslednou složku.

Další zdroje#

• FiveM: Introduction to Resources (otevře se v novém okně)
• FiveM: Resource Manifest (otevře se v novém okně)
• FiveM: Server Commands (start, stop, ensure, refresh) (otevře se v novém okně)
• FiveM: Asset Escrow (otevře se v novém okně)