ESX, QBCore of Qbox? Een framework voor FiveM kiezen en installeren

Een roleplayserver draait op een framework: dat regelt personages, geld, banen, inventaris en auto's. We vergelijken de drie meestgebruikte (ESX Legacy, QBCore en Qbox), helpen je kiezen en nemen je mee door de installatie via een txAdmin-recept, inclusief het instellen van admins.

Wat een framework is#

Een framework is een set resources die de server de basis van “het RP-spel” geeft: een personage aanmaken, contant geld en geld op de bank, banen en rangen, een inventaris, het bezit van auto's en het opslaan in de database. Andere scripts (banen, winkels, telefoon, garages) bouwen daarna voort op de functies van het framework.

Belangrijke gevolgen:

• Een script is geschreven voor een specifiek framework. Een script voor ESX draait niet zonder aanpassingen op QBCore, en andersom. Zoek bij een script daarom altijd de versie voor jouw framework.
• Een framework wissel je niet makkelijk als de server eenmaal draait. Overstappen op een ander framework betekent een nieuwe database en andere scripts. Kies daarom meteen aan het begin goed.
• Een framework heeft een database en de resource oxmysql nodig.

Een server zonder framework (freeroam, drift, races) kan draaien op het basisrecept van txAdmin (FiveM Basic Server).

Basisbegrippen#

Wie dit begrijpt, vindt een fout sneller: als geld of een auto “verdwijnt”, gaat het om een record in de database dat je kunt opzoeken en herstellen (bijvoorbeeld in HeidiSQL).

Vergelijking#

Hoe je kiest#

• Wil je de meeste kant-en-klare scripts en handleidingen? ESX Legacy. Het wordt het meest gebruikt en je vindt er scripts voor bijna alles.
• Wil je een moderne basis en scripts voor QBCore? Qbox. Het gebruikt de bibliotheken ox_lib, ox_inventory en ox_target, heeft strengere code en draait de meeste scripts voor QBCore zonder aanpassingen via de bridge.
• Heb je specifieke betaalde scripts voor QBCore? QBCore, of Qbox (controleer bij de auteur van het script of het op Qbox werkt).
• Bouw je een server met eigen scripts vanaf nul? Kies het framework waarvan de documentatie je het best ligt. Een goede kennis van het framework is belangrijker dan de keuze zelf.

De veiligste aanpak: deploy het framework op proef, loop het in het spel door en koop pas daarna scripts.

Vóór de installatie#

1. Maak een lege database aan op het tabblad Databases (bijvoorbeeld fivem, Toegang toegestaan vanaf %). Laat de gegevens Databasenaam, Gebruiker, Host en Wachtwoord openstaan.
2. Leg je license key klaar (begint met cfxk_).
3. Maak een back-up als er al iets op de server staat (tabblad Back-ups, handleiding) en exporteer de database (handleiding). Een nieuwe deployment wordt in een nieuwe map opgeslagen, maar een recept met de optie Delete Database ingeschakeld zou de database verwijderen.
4. Controleer de artifacts. Frameworks vereisen een actuele serverversie. Update een oude server volgens de handleiding Artifacts updaten.

Installatie via een txAdmin-recept#

De stappen zijn bij alle drie de frameworks hetzelfde, alleen het recept en een paar instellingen na de installatie verschillen. Heb je in txAdmin al een andere server gedeployd, dan start je een nieuwe wizard via Settings › FXServer met de knop Reset naast het veld Server Data Folder. txAdmin keert terug naar de pagina Setup en verwijdert de bestaande bestanden niet.

1. Vul in txAdmin op de pagina Setup de Server Name in en klik op Next.
2. Kies bij Deployment Type voor Popular Recipes.
3. Kies het recept volgens het tabblad hieronder.
4. Laat de voorgestelde map voor de data staan, klik op Save en daarna op Go to Recipe Deployer.
5. Klik in de stap Step 1: Review Recipe op Next.
6. Vul in de stap Step 2: Input Parameters de Server Registration Key in en, nadat je op Show/Hide Database options (advanced) hebt geklikt, ook de database: Database Host (het IP-adres uit het veld Host), Database Port (de poort uit het veld Host), Database Username, Database Password, Database Name. De schakelaar Delete Database staat standaard aan, controleer of hij op Off staat. Elk veld wordt uitgebreid uitgelegd in de handleiding voor txAdmin.
7. Klik op Run Recipe en wacht tot het recept klaar is. Bij grote recepten duurt dat enkele minuten.
8. Controleer in de stap Step 4: Configure server.cfg of endpoint_add_tcp en endpoint_add_udp de poort hebben uit de regel Verbindingsadres op het tabblad Netwerk (het recept kan de standaardpoort 30120 invullen). Pas daarna de instellingen aan volgens het tabblad hieronder en klik op Save & Run Server.

Eerste stappen na de installatie: adminrechten#

Een admin in txAdmin en een admin in het framework zijn twee verschillende dingen. txAdmin voegt bij het deployen in server.cfg de hoofdadmin toe aan de groep group.admin (de regel add_principal identifier.fivem:<FIVEM_ID> group.admin). De frameworks sluiten daar als volgt op aan:

setgroup <PLAYER_ID> admin

add_principal identifier.license:<PLAYER_LICENSE> qbcore.god

add_principal identifier.license:<PLAYER_LICENSE> group.admin

Herstart de server nadat je server.cfg of permissions.cfg hebt aangepast.

Bij Qbox moet je voor de admincommando's van de kern (bijvoorbeeld /addpermission, /setjob, /car) eerst /optin invoeren. Dat schakel je uit met de optie requireOptIn = false in qbx_core/config/server.lua.

Wat je als eerste instelt#

Elk framework heeft een hoofdconfiguratiebestand met de economie, de spawn en de personages. Bewerk het terwijl de server uit staat, of herstart de server in txAdmin na het bewerken. De bestanden vind je in de deploymentmap onder resources.

Geld en voorwerpen worden in de database opgeslagen. Een wijziging van de startwaarden geldt alleen voor nieuw aangemaakte personages, voor bestaande personages verandert er niets.

Compatibele scripts#

• Download de versie voor jouw framework. Veel auteurs bieden één script aan voor meerdere frameworks, met een keuze in config.lua (bijvoorbeeld Config.Framework = 'esx', 'qb' of 'qbx').
• De ox-bibliotheken (ox_lib, ox_inventory, ox_target) werken met zowel ESX als Qbox. Zorg dat je vóór het installeren van een tweede inventaris weet welke je gebruikt. Twee inventarissen tegelijk werken niet.
• Scripts voor QBCore op Qbox draaien via de bridge, zolang ze qb-core op de gedocumenteerde manier gebruiken. Scripts die rechtstreeks in de databasetabellen van QBCore werken, functioneren niet.
• Conflicten: twee scripts met dezelfde functie (twee HUD's, twee garages, twee telefoons) zitten elkaar meestal in de weg. Schakel het oorspronkelijke script uit (commentarieer de ensure ervan uit of verplaats het uit de categorie).

De installatie van afzonderlijke scripts staat beschreven in de handleiding FiveM resources.

Handmatige installatie (voor gevorderden)#

Een recept doet automatisch wat je anders met de hand zou doen:

1. Het downloadt de kern van het framework en de afhankelijkheden ervan (oxmysql, ox_lib …) in specifieke versies.
2. Het importeert het SQL-bestand van het framework in de database.
3. Het bereidt server.cfg voor met de juiste volgorde van ensure, de ACE-rechten en de connection string.

Kies alleen voor een handmatige installatie als je elke versie zelf in de hand wilt hebben. Volg de officiële documentatie van het framework en houd de volgorde aan: oxmysql › bibliotheken › kern › scripts. Op een server bij ons is het recept een stuk sneller, honderden bestanden handmatig uploaden via het tabblad Bestanden kost veel tijd (voor grote bestanden regelt support toegang via SFTP).

Het framework updaten#

1. Maak een back-up van de bestanden (tabblad Back-ups) en exporteer de database (HeidiSQL, handleiding).
2. Lees de release notes (changelog) op de GitHub-pagina van het framework. Let vooral op wijzigingen in de database (.sql-bestanden met migraties) en wijzigingen in de configuratie.
3. Zet de server uit.
4. Vervang de mappen van de bijgewerkte resources door de nieuwe. Download je eigen config.lua-bestanden vooraf en vergelijk ze na de update met de nieuwe (nieuwe opties kunnen ontbreken).
5. Voer de migratie-SQL uit als de release die bevat.
6. Start de server en houd de console in de gaten. Controleer daarna in het spel je personage, geld en inventaris.

Update niet alleen de kern zonder de andere onderdelen van het framework. De versies van es_extended en van de scripts in [esx_addons] (of van qb-core en qb-*) horen bij elkaar te passen.

Controle#

• In de console (of in Live Console in txAdmin) staat Database server connection established! en de kern van het framework wordt zonder rode fouten geladen.
• Na het verbinden verschijnt in het spel het aanmaken of kiezen van een personage.
• Het commando /group (ESX) of het openen van het adminmenu /admin (QBCore, Qbox) bevestigt dat je adminrechten hebt.

Als iets niet werkt#

Meldingen die je hier niet vindt, zoek je op in het overzicht Veelvoorkomende fouten van een FiveM-server.

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

Het recept downloadt tientallen repository's van GitHub en GitHub heeft het aantal verzoeken tijdelijk beperkt. Wacht ongeveer een uur en start de deployment opnieuw.

De deployment eindigt met een databasefout#

De gegevens komen niet overeen met het tabblad Databases (de host uit het veld Host, niet localhost; de databasenaam exact zoals in de lijst). Typische meldingen en hun oplossing vind je in de handleiding Database voor FiveM.

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

Het script heeft geen toegang tot ESX: het start eerder dan es_extended, of het gebruikt de oude manier om ESX te laden. Zet de ensure ervan onder es_extended en update zowel es_extended als het script naar de actuele versie.

No such export GetCoreObject in resource qbx_core#

Een script voor QBCore roept de kern van Qbox rechtstreeks aan. Op Qbox hoort het exports['qb-core']:GetCoreObject() aan te roepen (via de bridge). Controleer of de bridge aan staat (setr qbx:enableBridge "true") en pas het script aan of download de versie voor Qbox.

Native … is not supported#

Het framework of een script gebruikt een functie die jouw serverversie nog niet kent. Update de artifacts naar de nieuwste versie (handleiding).

Een speler blijft hangen op het laadscherm#

• Meestal een fout in de multicharacter of in de database. Kijk in de console van de server en in de clientconsole F8.
• Qbox met een eigen multicharacter: stel setr loadscreen:externalShutdown false in.
• QBCore na de eerste deployment: wacht tot het bouwen van de resources (yarn) klaar is.

ESX Multicharacter couldn't connect to the database#

De verbinding met de database werkt niet. Controleer set mysql_connection_string in server.cfg en de regel Database server connection established! in de console.

Admincommando's werken niet#

• QBCore en Qbox: de regel add_principal … met de juiste identifier ontbreekt, of je hebt hem toegevoegd zonder de server te herstarten.
• ESX: de speler heeft de groep admin niet. Controleer dat met het commando /group en stel de groep in met setgroup.

Meer bronnen#

• ESX Legacy: documentatie (opent in een nieuw venster)
• QBCore: documentatie (opent in een nieuw venster)
• Qbox: documentatie (opent in een nieuw venster)
• FiveM: Frameworks (opent in een nieuw venster)
• Lijst met txAdmin-recepten (Popular Recipes) (opent in een nieuw venster)