Qbox server pro FiveM: instalace, resources a pořadí načítání

Nejrychlejší cesta k fungujícímu Qbox serveru je oficiální recept pro txAdmin: spusť FXServer, otevři txAdmin, vyber Popular Recipes a pak QBox Framework, zadej databázi a nech ho stáhnout zhruba šedesát resources a naimportovat SQL. Pod povrchem všechno stojí na pěti resources - qbx_core, ox_lib, oxmysql, ox_inventory a ox_target - a na třech požadavcích, které lidé přehlížejí: zapnutý OneSync, aktuální build FXServeru a databáze MariaDB místo MySQL. Zbytek tohoto článku popisuje, jak do sebe tyto kousky zapadají, kde sehnat ostatní Qbox resources, které konvary mění chování jádra a co ti konzole říká, když server nenastartuje.

Pokud ještě nevíš, který framework zvolit, porovnání najdeš v článku ESX vs QBCore vs Qbox. Tento text počítá s tím, že už jsi se rozhodl.

Co Qbox potřebuje, než cokoli nainstaluješ#

Qbox je fork QBCore postavený na resources Overextended (ox_*). Na své prostředí je přísnější, než kdy byl QBCore, a většina neúspěšných prvních startů je problém prostředí, ne Qboxu.

Build serveru. Aktuální manifest qbx_core obsahuje závislost ve tvaru /server:10731, což znamená, že FXServer odmítne resource spustit na čemkoli starším. Číslo roste, jak Qbox přebírá novější nativní funkce, takže si přečti manifest verze, kterou jsi stáhl, a nevěř číslu z příspěvku na fóru, včetně tohoto. Pokud jsi pozadu, článek aktualizace artifactů FiveM serveru ukazuje, jak přejít na novější build, aniž by se rozbilo všechno ostatní.

OneSync. Bez něj Qbox neběží. Podle verze txAdminu je to buď volba na stránce nastavení FXServeru v txAdminu, nebo řádek set onesync on v server.cfg; soubor server.cfg z receptu pro Qbox žádný takový řádek nezapisuje, takže si ověř, co platí u tebe. Článek OneSync a sloty pro hráče vysvětluje, co přesně OneSync mění a proč na něm závisí každý moderní framework.

MariaDB, ne MySQL. Tohle lidi překvapí nejvíc. Instalační příručka Qboxu je přímočará: minimum je MariaDB 10.9.0, doporučuje se aktuální LTS verze, MySQL není podporováno a XAMPP se nemá používat nikdy. oxmysql se rád připojí k oběma databázím, takže server s MySQL ti obvykle první start dovolí - potíže přijdou později, u SQL, které spoléhá na chování MariaDB, u nesouladu collation mezi tabulkami a také proto, že ti s laděním nikdo v podpůrných kanálech Qboxu nepomůže. Pokud používáš hostovanou databázi a nevíš, o jaký engine jde, spusť v phpMyAdminu SELECT VERSION();. Server MariaDB to uvede ve verzi; holé číslo jako 8.4.x je MySQL.

Instalace přes recept pro txAdmin#

Recept je soubor YAML, který txAdmin provádí odshora dolů: stahuje repozitáře, rozbaluje je do složek, zapisuje konfigurační soubory a importuje SQL. Recept pro Qbox udržuje projekt Qbox a v aktuálním txAdminu ho najdeš v Popular Recipes.

1. Spusť FXServer s prázdnou datovou složkou. Otevře se txAdmin a dá ti PIN pro propojení účtu Cfx.re.
2. Vyber Popular Recipes a pak QBox Framework.
3. Na požádání vlož svůj licenční klíč Cfx.re. Klíč je tvůj, generuje se na portálu Cfx.re - odkud se bere, vysvětluje článek FiveM server a txAdmin.
4. Zadej údaje k databázi. txAdmin z nich sestaví connection string a spustí proti té databázi každý SQL soubor z receptu.
5. Nech instalaci doběhnout, projdi vygenerovaný server.cfg v editoru, který txAdmin ukáže, a spusť server.

Recept toho stahuje hodně. V době psaní rozloží resources takto:

resources/  [ox]/          ox_lib, oxmysql, ox_target, ox_inventory, ox_doorlock, ox_fuel  [qbx]/         qbx_core, qbx_spawn, qbx_garages, qbx_police, qbx_ambulancejob...  [standalone]/  cfx defaults, illenium-appearance, Renewed-Banking, loadscreen...  [voice]/       pma-voice, mm_radio  [npwd]/        npwd (phone), qbx_npwd  [npwd-apps]/   phone apps  [assets]/      map assets

Do kořene serveru také zapíše pět konfiguračních souborů: server.cfg, permissions.cfg, ox.cfg, voice.cfg a misc.cfg. Rozdělení je záměrné - server.cfg zůstává čitelný a dlouhý seznam nastavení ox_inventory a ox_target je v ox.cfg.

Importované SQL není jeden soubor, ale několik: základní qbox.sql, potom qbx_core.sql, pak tabulky pro vozidla, prodejnu vozidel, prodej vozidel, trávu, závody na okruhu a drogy a nakonec vlastní import telefonu. Na tom záleží, když někdy budeš server skládat ručně, protože když jeden soubor vynecháš, resource nastartuje čistě a při prvním použití vyhodí ER_NO_SUCH_TABLE.

Recept ber jako výchozí bod. Instaluje joby, loupeže a telefon, které třeba nechceš, a každý z nich je něco, co se musí aktualizovat a co se může rozbít. Běžný a rozumný postup je nechat recept postavit server, jeden večer na něm hrát, abys viděl, jak Qbox vypadá, když funguje, a pak složku [qbx] zredukovat na to, o čem tvůj server skutečně je.

Základní resources a co dělá každý z nich#

Framework nesou pět resources. Všechno ostatní je volitelné, tyhle ne.

`qbx_core` je samotný framework: hráči a postavy, peníze, joby a gangy (s vestavěným multijobem), fronta při připojení, obrazovka výběru postavy a kompatibilní most, který odpovídá jako qb-core. Konfigurace je v qbx_core/config/ (client.lua, server.lua, shared.lua) a herní data - joby, gangy, vozidla, zbraně - jsou v qbx_core/shared/. Na rozdíl od QBCore nemá Qbox žádný objekt jádra. Exporty voláš přímo:

local player = exports.qbx_core:GetPlayer(source)if not player then return endplayer.Functions.AddMoney('bank', 500, 'weekly-wage')

`oxmysql` je most k databázi. Čte mysql_connection_string a všem ostatním resources poskytuje funkce pro dotazy. Connection string, import a práci s pomalými dotazy najdeš v článku databáze FiveM a oxmysql, takže je tu neopakuji.

`ox_lib` je sdílená knihovna: callbacky, oznámení, menu, progress bary, zóny, lokalizace. Skoro každý resource Qboxu ji načítá přes '@ox_lib/init.lua' ve svém manifestu. Oznámení v Qboxu procházejí přes ox_lib, a proto výměna za vlastní resource pro oznámení znamená upravovat ox_lib, ne qbx_core.

`ox_inventory` nahrazuje slotový inventář, který dodával QBCore. Itemy se definují v ox_inventory/data/items.lua, obchody a úschovny jsou datové soubory vedle něj a obrázky itemů jsou v ox_inventory/web/images. Musí se mu říct, pod jakým frameworkem běží, přes setr inventory:framework "qbx" - ox.cfg z receptu to nastavuje a ručně postavený server, který na to zapomene, dostane inventář, který nenajde žádné hráče.

`ox_target` je systém interakcí „třetího oka“: podržíš klávesu, podíváš se na věc a dostaneš možnosti. Většina jobů v Qboxu s ním registruje své interakce, takže server bez něj má policisty a mechaniky, kteří nemohou dělat vůbec nic.

Kolem těchto pěti recept přidává věci, o kterých roleplay server předpokládá, že existují: qbx_spawn pro výběr místa spawnu, qbx_vehicles a qbx_garages pro vlastní auta, qbx_vehiclekeys, qbx_medical a qbx_ambulancejob, qbx_police, illenium-appearance pro oblečení, Renewed-Banking a pma-voice pro proximity voice.

Kde najít resources pro Qbox#

Všechno oficiální je v organizaci Qbox-project na GitHubu a každý oficiální resource má prefix qbx_. Dokumentace na docs.qbox.re má stránku pro každý základní resource s jeho exporty, eventy a konvary.

Tři pravidla ušetří většinu potíží:

• Stahuj releases, ne zelené tlačítko Code. ox_lib a ox_inventory mají webová rozhraní napsaná ve frontendovém frameworku a zdrojový strom neobsahuje sestavené soubory. Zip z releasu ano. Server, na kterém běží ox_inventory ze stažených zdrojáků, vypíše varování, že UI není sestavené, a hráči otevřou inventář, který tam není. Dokumentace Qboxu také doporučuje kvůli stabilitě provozovat jen vydané verze jejich vlastních resources.
• Čísla verzí pod 1.0.0 znamenají beta. Qbox to říká otevřeně. Použitelné jsou, ale mezi minor verzemi počítej s nekompatibilními změnami.
• Archivované repozitáře jsou dokončené, ne opuštěné. Několik starších resources Qboxu bylo archivováno, když jejich úkol převzalo něco jiného - obvykle qbx_core nebo některý resource ox_*. Když ti návod říká, ať nainstaluješ resource, jehož repozitář je archivovaný, zjisti před instalací, co ho nahradilo.

Resources třetích stran spadají do tří skupin. Resources psané pro Qbox fungují, jak bys čekal. Resources psané pro stack Overextended (s podporou ox_*) obvykle fungují, protože Qbox je na něm postavený. Resources psané pro QBCore běží přes most - ten je popsaný v další části - se skutečnými omezeními.

Když nějaký resource najdeš, přečti si před instalací jeho fxmanifest.lua: blok dependencies říká, co potřebuje, lua54 'yes' říká, že je aktuální, a cokoli, co volá os.execute nebo posílá HTTP požadavky na neznámou doménu, je důvod přestat. Delší argumentaci, proč to dělat pokaždé, najdeš v článku Jak udržet server s módy čistý.

Pořadí ensure a jak recept věci spouští#

Tady je startovní sekvence, kterou recept pro Qbox zapisuje, se zkrácenými komentáři:

exec voice.cfgexec ox.cfgensure mapmanagerensure chatensure spawnmanagerensure baseeventsensure ox_libensure qbx_coreensure ox_targetensure [ox]ensure [qbx]ensure [standalone]ensure [voice]ensure [assets]ensure [npwd-apps]ensure qbx_npwdensure npwdexec permissions.cfgexec misc.cfg

Dvě věci v něm vypadají špatně a nejsou.

Zaprvé, oxmysql se nikde nejmenuje před qbx_core. Nemusí, protože qbx_core uvádí oxmysql a ox_lib v dependencies svého manifestu a FXServer spouští závislosti resourcu dřív než resource samotný. Explicitní ensure ox_lib je tam kvůli přehlednosti; mechanismus závislostí by to udělal i tak. Proto také chybějící složka oxmysql způsobí hlasité selhání u qbx_core, a ne tiché selhání později.

Zadruhé, ensure [ox] běží až po qbx_core, i když je ve složce ox_inventory. To je správně: ox_inventory pod Qboxem chce, aby jádro už běželo a mohl číst hráče a jejich itemy. ensure složky v hranatých závorkách spustí všechny resources uvnitř, v pořadí, na které by ses neměl spoléhat, takže cokoli s pevným pořadím se uvádí na vlastním řádku před složkou.

Pravidla pro tvoje vlastní doplňky z toho plynou. Resource, který používá exporty Qboxu, patří za qbx_core. Resource, který používá itemy z ox_inventory, patří za [ox]. Pokud svoje resources dáš do složky, třeba [custom], přidej ensure [custom] na konec seznamu, za [qbx]. A řádek exec ox.cfg musí být před řádky ensure, protože hodnoty setr se čtou při startu resourcu - konvar nastavený poté, co jeho resource už běží, nedělá nic až do dalšího restartu. Každá direktiva v souboru je vysvětlená v článku FiveM server.cfg krok za krokem.

Konvary qbx_core#

Qbox přesunul spoustu toho, co bývalo konfigurací v Lua, do konvarů, takže chování jádra měníš v server.cfg a ne úpravou souborů, které příští aktualizace přepíše. Tohle jsou zdokumentované konvary s výchozími hodnotami:

Některé si zaslouží aspoň větu.

Multijob. Když zvýšíš qbx:max_jobs_per_player na 3 a nastavíš qbx:setjob_replaces na false, dostaneš multijob bez dalšího resourcu: /setjob job přidá místo přepsání aktuálního a hráč mezi nimi přepíná. To je nejčastější důvod, proč lidé na QBCore instalovali samostatný multijob skript.

`cleanPlayerGroups`. Při startu jádro odstraní z player_groups řádky, které odkazují na joby nebo gangy, jež už nejsou definované v qbx_core/shared/. To chceš po smazání jobu - a nepříjemné překvapení, když jsi job v jobs.lua přejmenoval a čekal jsi, že ho všichni zachovají. Přejmenování udělej tak, že přidáš nový job, přesuneš na něj lidi a teprve pak odstraníš starý.

Perzistence vozidel. FiveM občas smaže entity, které by neměl, a zmizelé vlastní auto uprostřed jízdy je to, čeho si hráči všimnou. qbx:enableVehiclePersistence ho znovu spawnuje s jeho vlastnostmi. Recept ho zapisuje přes setr místo set, stejně jako qbx:enableBridge, protože tyto hodnoty čte i klientská strana. Když je měníš, ponech stejné sloveso.

`bucketLockdownMode`. relaxed a strict brání klientům vytvářet síťové entity ve výchozím routing bucketu, což je hlavní cesta cheatů, které spamují spawn. strict rozbije každý resource, který spawnuje entity z klienta, takže ho nejdřív vyzkoušej na stagingové kopii.

Pamatuj na pravidlo set versus sets z každého jiného návodu pro FiveM: sets zveřejní hodnotu v seznamu serverů. Žádná z těchto hodnot není tajná, ale návyk psát set je důležitý u jediného řádku, který tajný je - mysql_connection_string.

Resources z QBCore na Qboxu: most#

Se zapnutým qbx:enableBridge qbx_core deklaruje provide 'qb-core', takže resource, který uvádí qb-core jako závislost, je spokojený, a exports['qb-core']:GetCoreObject() vrací objekt, který se chová jako ten z QBCore. Většina dobře napsaných resources z QBCore běží beze změn.

Co přes most nepřežije:

• Přímý přístup k tabulkám. Resource, který zapisuje do sloupců players z QBCore sám místo přes funkce hráče, obchází Qbox a může zapisovat do sloupců, které jsou nyní strukturované jinak.
• Kód inventáře. Cokoli, co volá exporty qb-inventory nebo čeká formát itemů z QBCore, potřebuje přepsat volání inventáře pro ox_inventory.
• Neveřejné vnitřnosti. Resources, které čtou soubory přímo z qb-core/ nebo spoléhají na chování, které QBCore nikdy nezdokumentovalo, se rozbíjejí způsobem, který se špatně dohledává.
• Multijob skripty s vlastními tabulkami. Kolidují s vestavěným multijobem; dokumentace Qboxu říká, že mohou fungovat jen tehdy, když jdou přes exporty qbx_core.

Itemy jsou jediné místo, kde most funguje oběma směry. Item přidaný do qbx_core/shared/items.lua se automaticky předá do ox_inventory, což udrží spokojené resources z QBCore běžící přes most. Chování itemu, které potřebuje exporty na klientu nebo serveru - například použití itemu - se ale pořád musí ručně napsat do ox_inventory/data/items.lua. U nového itemu, který používají jen resources znající Qbox, ho definuj rovnou v ox_inventory a items.lua úplně přeskoč.

Admini a oprávnění#

permissions.cfg z receptu obsahuje nastavení ACE. txAdmin do něj při instalaci zapíše tvůj vlastní identifikátor jako hlavního admina, jako řádek ve tvaru add_principal identifier.fivem:1234567 group.admin. Admin příkazy Qboxu - /setjob, /setgang a další - jsou omezené příkazy kontrolované proti skupinám ACE, takže každý, kdo je má používat, potřebuje řádek s principalem. Soubor se čte, když ho server.cfg spustí, takže po úpravě restartuj server nebo v živé konzoli spusť exec permissions.cfg.

Seznam adminů drž v permissions.cfg a nikde jinde. Oprávnění udělené z Lua uvnitř resourcu není při kontrole souboru vidět a přesně tohle dělá resource s backdoorem. Napojení těchto skupin na role na Discordu místo ručního psaní identifikátorů popisuje článek Discord oprávnění a whitelist pro FiveM.

Běžné startovní chyby a co znamenají#

Čti konzoli odshora, ne odspodu. První červený řádek je obvykle příčina a padesát řádků za ním jsou resources, které selhaly, protože selhal ten první. Obecnou metodu popisuje článek Jak číst konzoli.

`qbx_core` odmítne nastartovat kvůli nesplněné závislosti na `/onesync` nebo `/server:`. OneSync je vypnutý, nebo je build FXServeru starší, než žádá manifest. Zapni OneSync v nastavení txAdminu nebo aktualizuj artifacty. Žádné upravování qbx_core to nespraví.

„No such export GetCoreObject in resource qbx_core“. Nějaký resource z QBCore žádá qbx_core o objekt jádra, který Qbox nemá. Oprava je v tom resourcu: měl by volat exports['qb-core']:GetCoreObject(), na což most odpoví. Zkontroluj také, že most není vypnutý.

„This resource is still using the deprecated qbx_core utils“. Varování, ne chyba. Uvedený resource je stará verze; stáhni jeho nejnovější verzi.

Hráči uvázlí na načítací obrazovce. Na čisté instalaci je to téměř vždy výběr postavy, který nikdy nezavře načítací obrazovku, typicky po výměně vestavěného multicharacteru. Buď nastav loadscreen:externalShutdown na false v server.cfg, nebo ať tvůj resource pro postavy volá ShutdownLoadingScreen() a ShutdownLoadingScreenNui(). Pokud jsi nic nenahrazoval, hledej v konzoli výš resource, který nenastartoval - stejný příznak způsobí selhání qbx_spawn nebo oxmysql.

„Can't create table ... (Foreign Key Constraint is incorrectly formed)“. Nesoulad collation mezi vytvářenou tabulkou a tou, na kterou odkazuje - běžné, když bylo SQL z různých resources psané s odlišnými výchozími hodnotami, a ještě běžnější na MySQL. Oprava podle Qboxu je ukončit příkazy CREATE TABLE explicitní znakovou sadou a collation a pak tabulku zahodit a vytvořit znovu:

CREATE TABLE IF NOT EXISTS example_table (  id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,  citizenid VARCHAR(50) NOT NULL) DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

„SCRIPT ERROR: failed to load model“. Model se nenačetl v časovém limitu, obvykle na pomalém klientovi. Pokud chyba pochází z qbx_core, zvyš loadingModelsTimeout v qbx_core/config/client.lua.

Inventář se otevře prázdný nebo vůbec. Buď je ox_inventory stažený ze zdrojáků bez sestaveného UI, nebo není inventory:framework nastavený na qbx, protože se ox.cfg nikdy nespustil. Zkontroluj exec ox.cfg nad řádky ensure.

`ER_NO_SUCH_TABLE` u jedné funkce. Jeden ze SQL souborů receptu se neimportoval. Najdi soubor .sql toho resourcu a naimportuj ho přes phpMyAdmin - velké soubory řeší návod na import do phpMyAdmin - poté, co si přečteš jeho první řádky kvůli případnému DROP TABLE.

Qbox na hostovaném serveru#

Na RE:NODE má FiveM server k dispozici txAdmin, takže postup s receptem výše funguje tak, jak je napsaný: server nastartuje do txAdminu, propojíš účet Cfx.re a vložíš svůj vlastní licenční klíč. Tarif zahrnuje slot pro databázi vytvořený z panelu s vygenerovaným hostem, uživatelem a heslem a tlačítko Open in phpMyAdmin, které tě přihlásí jednorázovým tokenem. Panel nejmenuje engine za tím slotem, takže před nasazením Qboxu spusť SELECT VERSION(); a pokud to není MariaDB, rozhodni se s otevřenýma očima, jestli se smíříš s nepodporovanou databází.

Správce souborů rozbaluje zip z releasů na místě, čímž vyměníš resource za novější verzi bez lokální kopie serveru, a SFTP zvládne hromadné nahrávání, například celé složky [qbx]. Limitem tarifu je paměť: celý recept s telefonem, mapovými assety a každým jobem je těžší než okleštěný seznam, takže stojí za to přečíst si kolik RAM potřebuje FiveM server, než vybereš tarif. Když server dosáhne limitu, zastaví se a čistě se restartuje místo swapování, takže server, který se pod zátěží pořád restartuje, je problém s dimenzováním, na který se podívej pomocí resmonu a monitoru txAdminu, ne záhada.

Před aktualizací jakéhokoli resourcu Qboxu udělej backup a exportuj databázi. Releasy Qboxu mění schémata ochotněji, než to dělal QBCore, a stagingový server s kopií databáze - viz staging a produkce na jednom účtu - je místo, kde by se aktualizace měla poprvé potkat s tvým seznamem resources.

FAQ#

Je Qbox kompatibilní se skripty pro QBCore?

Většinou. Most odpovídá jako qb-core a zvládá jeho zdokumentované exporty a eventy. Skripty, které sahají přímo do tabulek QBCore, používají starý inventář nebo spoléhají na nezdokumentované vnitřnosti, potřebují úpravy. Každý otestuj, nepředpokládej.

Musím používat recept pro txAdmin?

Ne, ale je to nejrychlejší cesta ke známému funkčnímu výchozímu bodu. Ručně potřebuješ pět základních resources z jejich releasů, SQL z qbx_core a z každého resourcu s funkcí, ox.cfg nebo ekvivalentní řádky setr, zapnutý OneSync a pořadí ensure uvedené výše.

Můžu odebrat resources, které recept nainstaloval?

Ano. Smaž složku a pokud byl uvedený na vlastním řádku ensure, odstraň ten řádek. Nejdřív zkontroluj, že ho neuvádí v dependencies svého manifestu nic jiného. Základní pětici nech být a buď opatrný u všeho, co patří do procesu vytváření postavy - výběr spawnu a oblečení - protože jejich odstranění se projeví hráči, kteří nemohou dokončit vytvoření postavy.

Kam přidám nový job?

Do qbx_core/shared/jobs.lua, jako položku tabulky s jejími grady, a pak restart. Resource pro job mu pak dá nějakou náplň. Hráči se přiřazují přes /setjob, který podle qbx:setjob_replaces buď přidává, nebo nahrazuje.

Proč Qbox trvá na MariaDB?

Jeho dokumentace uvádí jako minimum MariaDB 10.9 a píše, že MySQL není podporováno, takže jeho SQL i podpora jsou psané pro MariaDB. Server s MySQL často v praxi funguje, ale problémy na něm musíš řešit sám.

Kolik hráčů zvládne Qbox server?

To závisí na OneSync a tvé licenční úrovni, ne na Qboxu. Samotný framework stojí na tick velmi málo; hardware určuje seznam resources, který na něm postavíš, a streamované assety.