ESX, QBCore, nebo Qbox? Výběr a instalace frameworku pro FiveM

Roleplay server stojí na frameworku: ten řeší postavy, peníze, práce, inventář a auta. Porovnáme tři nejpoužívanější (ESX Legacy, QBCore a Qbox), poradíme s výběrem a provedeme vás instalací přes recept txAdminu včetně nastavení adminů.

Co je framework#

Framework je sada resources, která dává serveru základní „hru v RP“: vytvoření postavy, peníze v hotovosti a v bance, zaměstnání a hodnosti, inventář, vlastnictví aut, ukládání do databáze. Ostatní skripty (práce, obchody, telefon, garáže) pak stavějí na funkcích frameworku.

Důležité důsledky:

• Skript je napsaný pro konkrétní framework. Skript pro ESX bez úprav na QBCore nepoběží a naopak. U skriptu proto vždy hledejte verzi pro váš framework.
• Framework se špatně mění za běhu. Přechod na jiný znamená novou databázi a výměnu skriptů. Vyberte si proto dobře hned na začátku.
• Framework potřebuje databázi a resource oxmysql.

Server bez frameworku (freeroam, drift, závody) může běžet na základním receptu txAdminu (FiveM Basic Server).

Základní pojmy#

Kdo tomu rozumí, snáz najde chybu: když se „ztratí“ peníze nebo auto, je to záznam v databázi, který jde dohledat a opravit (třeba v HeidiSQL).

Srovnání#

Jak vybrat#

• Chcete nejvíc hotových skriptů a návodů? ESX Legacy. Je nejrozšířenější a skripty pro něj najdete skoro na všechno.
• Chcete moderní základ a skripty pro QBCore? Qbox. Používá knihovny ox_lib, ox_inventory a ox_target, má přísnější kód a většinu skriptů pro QBCore spustí přes most bez úprav.
• Máte konkrétní placené skripty pro QBCore? QBCore, nebo Qbox (ověřte u autora skriptu, že na Qboxu funguje).
• Stavíte server s vlastními skripty od nuly? Vyberte ten, jehož dokumentace vám nejvíc vyhovuje. Dobrá znalost frameworku je důležitější než jeho volba.

Nejjistější postup: nasaďte framework na zkoušku, projděte ho ve hře a teprve pak kupujte skripty.

Před instalací#

1. Vytvořte prázdnou databázi v záložce Databáze (například fivem, Povolený přístup z %). Údaje Název databáze, Uživatel, Server a Heslo si nechte otevřené.
2. Připravte license key (začíná cfxk_).
3. Udělejte zálohu, pokud na serveru už něco máte (záložka Zálohy, návod) a databázi vyexportujte (návod). Nové nasazení se ukládá do nové složky, ale databázi by recept se zapnutou volbou Delete Database smazal.
4. Zkontrolujte artefakty. Frameworky vyžadují aktuální verzi serveru. Starý server aktualizujte podle návodu Aktualizace artefaktů.

Instalace přes recept txAdminu#

Postup je u všech tří frameworků stejný, liší se jen recept a pár nastavení po instalaci. Pokud jste v txAdminu už jiný server nasadili, nový průvodce spustíte v Settings › FXServer tlačítkem Reset vedle pole Server Data Folder. txAdmin se vrátí na stránku Setup a stávající soubory nesmaže.

1. V txAdminu na stránce Setup zadejte Server Name a klikněte na Next.
2. U Deployment Type zvolte Popular Recipes.
3. Vyberte recept podle záložky níže.
4. Ponechte navrženou složku pro data, klikněte na Save a pak na Go to Recipe Deployer.
5. V kroku Step 1: Review Recipe klikněte na Next.
6. V kroku Step 2: Input Parameters vyplňte Server Registration Key a po kliknutí na Show/Hide Database options (advanced) i databázi: Database Host (IP z pole Server), Database Port (port z pole Server), Database Username, Database Password, Database Name. Přepínač Delete Database je ve výchozím stavu zapnutý, zkontrolujte, že je na Off. Každé pole podrobně vysvětluje návod k txAdminu.
7. Klikněte na Run Recipe a počkejte na dokončení. U velkých receptů to trvá několik minut.
8. V kroku Step 4: Configure server.cfg zkontrolujte, že endpoint_add_tcp a endpoint_add_udp mají port z řádku Adresa pro připojení v záložce Síť (recept může zapsat výchozí 30120). Pak upravte nastavení podle záložky níže a klikněte na Save & Run Server.

První kroky po instalaci: admin práva#

Admin v txAdminu a admin ve frameworku jsou dvě různé věci. txAdmin při nasazení přidá do server.cfg hlavního admina do skupiny group.admin (řádek add_principal identifier.fivem:<FIVEM_ID> group.admin). Frameworky na to navazují takto:

setgroup <ID_HRACE> admin

add_principal identifier.license:<LICENSE_HRACE> qbcore.god

add_principal identifier.license:<LICENSE_HRACE> group.admin

Po úpravě server.cfg nebo permissions.cfg restartujte server.

U Qboxu vyžadují admin příkazy jádra (například /addpermission, /setjob, /car) nejdřív zadat /optin. Vypíná se to volbou requireOptIn = false v qbx_core/config/server.lua.

Co nastavit jako první#

Každý framework má hlavní konfigurační soubor s ekonomikou, spawnem a postavami. Upravujte ho u vypnutého serveru, nebo v txAdminu po úpravě restartujte server. Soubory najdete ve složce nasazení v resources.

Peníze a předměty se ukládají do databáze. Změna startovních hodnot se týká jen nově vytvořených postav, stávajícím nic nezmění.

Kompatibilní skripty#

• Stahujte verzi pro svůj framework. Mnoho autorů nabízí jeden skript pro více frameworků a volbu v config.lua (například Config.Framework = 'esx', 'qb' nebo 'qbx').
• Knihovny ox (ox_lib, ox_inventory, ox_target) fungují s ESX i Qboxem. Před instalací druhého inventáře si ujasněte, který používáte. Dva inventáře najednou nefungují.
• Skripty pro QBCore na Qboxu běží přes most, pokud používají qb-core dokumentovaným způsobem. Nefungují skripty, které sahají přímo do databázových tabulek QBCore.
• Konflikty: dva skripty se stejnou funkcí (dva HUDy, dvě garáže, dva telefony) si obvykle překážejí. Původní vypněte (zakomentujte jeho ensure nebo ho přesuňte z kategorie).

Instalaci jednotlivých skriptů popisuje návod FiveM resources.

Ruční instalace (pro pokročilé)#

Recept dělá automaticky to, co byste jinak dělali ručně:

1. Stáhne jádro frameworku a jeho závislosti (oxmysql, ox_lib …) v konkrétních verzích.
2. Naimportuje SQL soubor frameworku do databáze.
3. Připraví server.cfg se správným pořadím ensure, právy ACE a connection stringem.

Ruční instalaci volte jen tehdy, když chcete mít každou verzi pod kontrolou. Postupujte podle oficiální dokumentace frameworku a dodržte pořadí: oxmysql › knihovny › jádro › skripty. Na serveru u nás je recept výrazně rychlejší, ruční nahrávání stovek souborů přes záložku Soubory je zdlouhavé (velké soubory přes SFTP zřídí podpora).

Aktualizace frameworku#

1. Zálohujte soubory (záložka Zálohy) a vyexportujte databázi (HeidiSQL, návod).
2. Přečtěte si poznámky k vydání (changelog) na GitHubu frameworku. Hledejte hlavně změny databáze (soubory .sql s migracemi) a změny konfigurace.
3. Vypněte server.
4. Nahraďte složky aktualizovaných resources novými. Svoje config.lua si předem stáhněte a po aktualizaci porovnejte s novými (nové volby mohou chybět).
5. Spusťte migrační SQL, pokud ho vydání obsahuje.
6. Spusťte server a sledujte konzoli. Pak zkontrolujte ve hře postavu, peníze a inventář.

Neaktualizujte jen jádro bez ostatních částí frameworku. Verze es_extended a skriptů [esx_addons] (nebo qb-core a qb-*) mají jít spolu.

Ověření#

• V konzoli (nebo Live Console v txAdminu) je Database server connection established! a bez červených chyb se načte jádro frameworku.
• Po připojení ve hře se objeví vytvoření nebo výběr postavy.
• Příkaz /group (ESX) nebo otevření admin menu /admin (QBCore, Qbox) potvrdí, že máte admin práva.

Když něco nefunguje#

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

Task Failed: Response code 403 (rate limit exceeded)#

Recept stahuje desítky repozitářů z GitHubu a GitHub dočasně omezil počet požadavků. Počkejte zhruba hodinu a nasazení spusťte znovu.

Nasazení skončí chybou databáze#

Údaje se neshodují se záložkou Databáze (host z pole Server, ne localhost; název databáze přesně podle seznamu). Typické hlášky a jejich řešení najdete v návodu Databáze pro FiveM.

ESX = nil (nebo attempt to index a nil value (global 'ESX'))#

Skript nemá přístup k ESX: buď startuje dřív než es_extended, nebo používá starý způsob načtení ESX. Dejte jeho ensure pod es_extended a aktualizujte es_extended i skript na aktuální verzi.

No such export GetCoreObject in resource qbx_core#

Skript pro QBCore volá jádro Qboxu napřímo. Na Qboxu má volat exports['qb-core']:GetCoreObject() (přes most). Zkontrolujte, že je most zapnutý (setr qbx:enableBridge "true"), a skript upravte nebo stáhněte verzi pro Qbox.

Native … is not supported#

Framework nebo skript používá funkci, kterou vaše verze serveru ještě nezná. Aktualizujte artefakty na nejnovější verzi (návod).

Hráč visí na načítací obrazovce#

• Nejčastěji chyba v multicharacteru nebo databázi. Podívejte se do konzole serveru a do klientské konzole F8.
• Qbox s vlastním multicharacterem: nastavte setr loadscreen:externalShutdown false.
• QBCore po prvním nasazení: počkejte, než doběhne sestavení resources (yarn).

ESX Multicharacter couldn't connect to the database#

Nefunguje připojení k databázi. Zkontrolujte set mysql_connection_string v server.cfg a řádek Database server connection established! v konzoli.

Admin příkazy nefungují#

• QBCore a Qbox: chybí řádek add_principal … se správným identifikátorem, nebo jste ho přidali a nerestartovali server.
• ESX: hráč nemá skupinu admin. Ověřte příkazem /group a nastavte ji setgroup.

Další zdroje#

• ESX Legacy: dokumentace (otevře se v novém okně)
• QBCore: dokumentace (otevře se v novém okně)
• Qbox: dokumentace (otevře se v novém okně)
• FiveM: Frameworks (otevře se v novém okně)
• Seznam receptů txAdminu (Popular Recipes) (otevře se v novém okně)