v-core - a roleplay framework built for FiveM Enhanced

v-core is a complete, self-contained roleplay framework for FiveM Enhanced - the GTA V Enhanced next-gen edition. 39 modules, one shared design system, one database, no external framework dependency. It is not an ESX or QBCore add-on pack, it is the framework.

Why a new framework rather than a port? ESX and QBCore were written for the Legacy branch, and the differences are not cosmetic: the Enhanced binary is cfx-server.exe and rejects Legacy stream assets outright; sv_enforceGameBuild takes Legacy build numbers that lock Enhanced clients out entirely; and CEF 140 dropped nui:// as a secure context and renders backdrop-filter as an opaque black box, which breaks most existing NUI. Every one of those is designed around here rather than patched over.

Built and tested on cfx-server.exe, OneSync, MariaDB via oxmysql.

git clone https://github.com/laforetbrut/v-core-framework-fivem.git

Then follow Installation - five steps, no build toolchain.

Status: in active development on main.

Document	What it is
API.md	Every export, callback and event - the reference
DEVELOPERS.md	Write a script for v-core: the V helper, conventions, gotchas
ARCHITECTURE.md	What each module does today, and the roadmap
CHANGELOG.md	What shipped
CONTRIBUTING.md	How to contribute, and what gets sent back

Why it exists

Most FiveM frameworks are a core plus fifty third-party scripts that each bring their own UI, their own config format and their own idea of who is allowed to do what. v-core is the opposite bet: one codebase, one look, one permission model, and everything an operator needs to tune is editable in-game - never by editing Lua on a live server.

Features

• FiveM Enhanced native - runs on cfx-server.exe, gamename: gta5enhanced. No sv_enforceGameBuild (those are Legacy build numbers and lock Enhanced clients out). CEF 140-safe NUI (https://cfx-nui-…).
• v-core - DB-persistent players, server/client callback system, permission tiers, structured audit log, multi-character selection. Every module goes through it.
• v-ui design system, fully themeable - one canonical stylesheet every NUI page shares, driven by v-ui/config.lua: 6 colour presets, an accent override the whole highlight family is derived from, corner roundness, density, animation speed (0 disables motion), panel opacity and font scale. Changing any of it in Admin -> Settings -> Interface restyles every module at once - no module hardcodes a colour.
• Animated loading screen - v-loadscreen/config.js: a background slideshow of looping videos and stills, an in-screen music player, rotating tips, a keybinds strip and a live player count, all in one file. It closes on the framework's own player-loaded signal, with a failsafe so nobody is stranded on it.
• In-game content editor - 30 domains the admin panel creates, edits and deletes without a restart: map blips, store locations, shops, jobs & grades, gangs & ranks, items, craft recipes, clothing stores & wearable slots, garages, rental points, fuel stations, mechanic shops, dealerships, the vehicle catalogue, licence types, gang territories, the penal code, substances, radio channels, faction treasuries and per-module themes. All backed by v-world, all applied live.
• Built to be extended - a script somebody else writes plugs in with one manifest line. Services (V.Service('banking')) so it asks for a capability rather than a resource name; hooks it can veto or rewrite, which plain events cannot do; and a registry listing every module, service, hook, event and command, because that is the question an integrator starts with. See DEVELOPERS.md.
• Module registry & settings - every module declares its tunables to v-core; the admin panel's Settings tab renders whatever it is handed, so it never needs changing. A third-party script adds v_module 'yes' to its manifest and appears there too - see DEVELOPERS.md.
• NPC police off by default - no ambient cruisers, no wanted stars, no dispatch helicopter, because none of it is played by anyone. Every piece is its own switch in the admin panel.
• No player chat commands - the interaction surface is the target eye, keybinds and NUI, by design.
• Bilingual out of the box - every player-facing string exists in English and French; players pick their language on first join.
• Server-authoritative by default - proximity, funds, ownership and permissions are re-derived server-side on every action. Client-side gates are treated as UX, not security.
• On-demand local MariaDB - never runs as a Windows service, never starts with Windows.

Gameplay modules

• v-inventory - grid inventory (weight, use/drop/give), 302-item catalogue, functional weapons (ammo, serial, durability/jamming, attachments), backpacks & armor, a hidden pocket, vehicle trunks & shared/gang stashes, and player frisk/steal + hands-up.
• v-world - the admin-editable world content layer (blips, store locations, jobs, items, recipes).
• v-admin - in-game panel (F10): dashboard, players, scripts, world, logs, Editor, and tools (noclip, god, invisible, player blips, spectate, open a player's inventory).
• v-appearance / v-spawn - appearance engine with stable clothing identity, multi-character selection, barber / plastic surgeon / tattoo parlour.
• v-crafting - 105 recipes across 6 stations (workbench, reloading, kitchen, electronics, recycling/refining, hidden drug lab), server-authoritative, recipes editable in-game.
• v-gathering - resource nodes (mining, salvage, textile, hidden cannabis grows) feeding the crafting tier.
• v-shops - stores with buy & sell, vending machines, a scrap dealer, and an illegal dealer / launderer (dirty money). Store positions editable in-game.
• v-target - universal interaction eye (hold Left-Alt): entity/zone options filtered by permission & job.
• v-jobs - jobs, grades, on-duty salaries; the source of truth for every job gate.
• v-vehicles / v-garages - owned-vehicle persistence (mods, fuel, damage), server-minted plates, a key system, a 3D showroom preview, and 9 garages incl. an impound lot and job motor pools - all editable in-game.
• v-fuel - four fuel types (regular / premium / diesel / electric), load-based consumption, 18 stations incl. EV charging points with connector levels and a charge curve, jerry cans; stations and prices editable in-game.
• v-mechanic - 20-part wear model (12 for an EV) driven by distance, abuse and crashes, a real odometer, 27 craftable parts, roadside repair kits and job-locked shops - all editable in-game.
• v-vehicleshop - 6 dealerships, a 56-vehicle catalogue with a 3D showroom preview, test drives, licence-gated purchases and sell-back; dealers and catalogue editable in-game.
• v-licenses - 12 licences & permits (ID, driving, HGV, boat, pilot, weapon…) with suspension, revocation, expiry and demerit points; the single source of truth for character capabilities.
• v-cityhall - the city hall job desk: apply for any position an admin has left open, or resign. Whitelisted jobs (police, EMS, …) never show up here - they are handed out by their own chain of command.
• v-rentals - short-term hire at four counters: a deposit and a fee up front, a temporary RENT### plate and a timer. Return it in time and the deposit comes back. A rental never creates an ownership row, which is the single rule that separates a hire from a free car.
• v-factions - one engine for legal factions and illegal ones: they differ by which table holds their definition, jobs or gangs, and by nothing else. Membership, ranks, and a treasury that is a real account with its own audit trail rather than a number in a config. Salaries can be paid out of it.
• v-bossmenu (F6) - the panel a faction leader needs: members, ranks, hiring, dismissal, treasury and payroll. Gated on rank, not on admin permission - staff are not bosses.
• v-gangs - territory with capture and influence. Influence belongs to whoever holds the turf and a rival wears it down rather than taking it, so a contested turf is a fight instead of a race. Unheld influence decays: a turf has to be held, not taken once.
• v-police - cuffs, escort, search, seizure, charges, fines, jail and an MDT (record, warrants, licences, vehicles). Police is a job, not a permission. The penal code is data - 21 charges with fine, jail time and licence points, all editable in-game.
• v-banking (Fleeca ATM) · v-status (hunger/thirst/stress/bleed) · v-hud (five themes, ten speedometers, twenty-one dashboard tell-tales, a compass, a round minimap and a per-player settings menu) · v-sport (gym training: strength, breath and stamina, with a rhythm QTE) · v-notify · v-clothing (16 wearable slots, 10 stores, slots & stores editable in-game) · v-loadscreen.
• v-music (F4) - boomboxes, jukeboxes and the car stereo, positional and synced by timestamp so a late arrival joins mid-track. Host allow-list, because arbitrary URL playback is a moderation problem rather than a technical one.
• v-radio (F3) - the handheld: monitor several channels at once, talk on one, presets on a keypad. It decides no permission - it asks v-voice, which asks the job and gang gates.
• v-3dsound - a positional sound primitive other modules call: a name, a place and a range go on the wire, never audio, and only listeners in range are told.
• v-anticheat - server-side checks on movement, health, explosions, client entity creation, money and weapon damage. Logs by default rather than kicking, because an anticheat that kicks legitimate players is worse than none.
• v-voice - proximity voice in three steps, radio channels gated on job or gang rank, and a separate channel for phone calls. Bleeding narrows your range, cuffs kill the radio, and leaving a job leaves its channel.
• v-drugs - plantations a player places and can lose, and street dealing that pushes back: demand decays per district as you sell into it, and heat drives both refusals and the chance of a bust. Sales pay dirty money, which has to go through the launderer.
• Economy loops - legal: gather → craft → sell. Illegal: grow → process → deal → launder.

Installation

1. Artifacts - the server binaries live in artifacts/ (not tracked by git). Download cfx-server_win_x64.zip (Windows) or cfx-server_linux_x64.tar.xz (Linux) from the cfx.re artifacts and extract it into artifacts/. It must contain cfx-server.exe - server.zip / FXServer.exe is the Legacy branch and will reject Enhanced clients with bad_request.
2. License key - get a free key at keymaster.fivem.net and set sv_licenseKey in server.cfg.
3. Database - point mysql_connection_string in server.cfg at your MySQL/MariaDB, then import database/schema.sql.
4. Run - ./start.ps1.
5. Connect - in FiveM press F8 and type connect localhost:30120.

The core: v-core

resources/[local]/v-core is the framework. Other resources use it via exports:

local Core = exports['v-core']:GetCore()

To add a feature resource:

1. Create resources/[local]/<your-resource>/ with an fxmanifest.lua.
2. Grab the core with exports['v-core']:GetCore() and build on Core.GetPlayer, Core.Notify, etc.
3. Add ensure <your-resource> in server.cfg after v-core.
4. Ship a permission-gated management UI in v-admin for anything an operator will want to tune - see the v-world pattern in ARCHITECTURE.md §7.
5. In the server console: refresh then ensure <your-resource>.

Database (on-demand)

Any MySQL or MariaDB instance works - the framework only talks to it through oxmysql, so how you run it is your call (a service, Docker, or an on-demand local install).

Set the connection in server.cfg:

set mysql_connection_string "mysql://user:password@localhost:3306/your_database?charset=utf8mb4"

Then import database/schema.sql (24 tables). Migrations run automatically at boot.

Dependencies

• FiveM / cfx.re · FiveM natives · Server manual · MariaDB · oxmysql · screenshot-basic - clothing catalogue thumbnails

Checks

Four scripts under tools/ answer questions whose wrong answer is silent in game. Each reads the repository, changes nothing, and exits non-zero when it finds something, so a hook or a CI step can fail on it. Run them from the repository root:

python tools/lua-syntax.py        # every Lua file compiles, client ones included
python tools/privacy-sweep.py     # anything that must never be committed
python tools/locale-check.py      # keys defined once, on both sides, and every key asked for exists
python tools/manifest-check.py    # every asset a NUI page loads is one the resource serves

lua-syntax is the one that answers a question starting the server cannot. A broken CLIENT script is never read by the server: the resource reports "Started", registers its settings and logs nothing, and the file simply does not run when a player connects. That was measured, not assumed - a deliberately broken client file produced a completely clean boot.

A fifth needs a database, which is why it is listed apart. The four above read the repository and need nothing else. sql-check asks the database whether every SQL statement in the framework is one it would accept, which a boot test cannot: booting only ever runs the queries that run at boot, and a SELECT behind a shop or a phone app is not seen until a player walks into it.

database\start-db.bat
set VCORE_DB=mysql://user:password@host:port/database
python tools/sql-check.py --client "C:/Program Files/MariaDB 12.3/bin/mariadb.exe"

PREPARE runs the parser and the name resolver and stops: nothing is read, nothing is written. Over 903 complete statements it currently reports none the database refuses. It says out loud what it does not judge rather than counting it as passing - 66 queries assembled at runtime, and the handful written in qb-core's or ox_core's schema behind a Bridge.framework == 'qb' branch, which never run here and are listed apart so a permanent failure does not teach everybody to ignore the check.

A module can carry its own, and the phone does. v-phone/tools/test-all.py runs twenty-two of them in the order that fails cheapest first, from a Lua compile through its own static checks to a probe that drives a real mouse through the compositor and reports every control reachable across all 37 apps. It has to be run from the resource's own directory, because it globs relatively:

cd "resources/[local]/v-phone" && python tools/test-all.py --fast

--fast skips the 71 screenshots; without it they are rebuilt. One of its checks is a selftest that shows every other check a fault it is supposed to catch, which is the property that stops a green light meaning nobody looked.

locale-check reads the NUI JavaScript as well as the Lua, which for a module whose interface is a web page is where nearly all of its text lives: v-phone asks for 591 keys from app.js and four from Lua. Reading only Lua validated four keys out of 852 and reported success. The phone resolves a key with S[k] || k, so a missing one is rendered to the player as its own name. The interfaces do not agree on a name for that resolver - v-phone calls it L, v-appearance and v-inventory call it t, v-hud reaches it as S.t - and all four are read, which is what brought v-hud's 118 menu strings and v-inventory's 13 under the check.

Each was written because the thing it looks for had already happened at least once here: a live connection string in a tracked file, a key defined twice where the second silently won, and a script the page loaded that the manifest did not list, which 404s and leaves a feature doing nothing.

Two of the three are silent today. privacy-sweep still reports one line - the database URL in server.cfg, credentials and all, in a tracked file. It is root:root against a local MariaDB in a private repository, so the exposure is small, but the fix is the pattern the same file already uses for its licence key: move the line into a gitignored database.cfg and exec it, at the cost of one setup step on every new machine. That trade is the operator's to make, which is why the checker reports it rather than anything having changed it.

Two modules carry their own deeper checks, which validate balance, locales, NUI callbacks and manifest against that module's own rules. They find their resource from their own location, so they run from the repository root like the rest:

python "resources/[local]/v-sport/tools/check.py"
python "resources/[local]/v-phone/tools/check.py"

Credits

Author: vyrriox

---

v-core - un framework roleplay pour FiveM Enhanced (Version Française)

v-core est un framework roleplay complet et autonome pour FiveM Enhanced (l'édition next-gen de GTA V). 39 modules, un seul design system, une seule base de données, aucune dépendance à un framework externe - ce n'est pas un pack d'add-ons pour ESX ou QBCore, c'est le framework.

Développé et testé sur le binaire serveur Enhanced (cfx-server.exe), OneSync, MariaDB via oxmysql.

État : en développement actif sur main.

Document	Contenu
API.md	Tous les exports, callbacks et événements - la référence
DEVELOPERS.md	Écrire un script pour v-core : le helper V, conventions, pièges
ARCHITECTURE.md	Ce que fait chaque module, et la roadmap
CHANGELOG.md	Ce qui est livré
CONTRIBUTING.md	Comment contribuer

Pourquoi

La plupart des frameworks FiveM, c'est un core plus cinquante scripts tiers qui apportent chacun leur UI, leur format de config et leur propre idée de qui a le droit de faire quoi. v-core fait le pari inverse : une seule base de code, un seul look, un seul modèle de permissions, et tout ce qu'un opérateur doit régler est modifiable en jeu - jamais en éditant du Lua sur un serveur en production.

Caractéristiques

• Natif FiveM Enhanced - tourne sur cfx-server.exe, gamename: gta5enhanced. Pas de sv_enforceGameBuild (ce sont des numéros de build Legacy, qui bloquent les clients Enhanced). NUI compatible CEF 140 (https://cfx-nui-…).
• v-core - joueurs persistés en BDD, système de callbacks serveur/client, paliers de permission, log d'audit structuré, sélection multi-personnages. Tous les modules passent par lui.
• Design system v-ui, entièrement thémable - une feuille de style canonique partagée par toutes les pages NUI, pilotée par v-ui/config.lua : 6 presets de couleurs, un accent d'où toute la famille de surbrillance est dérivée, arrondi des angles, densité, vitesse d'animation (0 = aucune), opacité des panneaux, échelle de police. Changer l'un d'eux dans Admin -> Réglages -> Interface restyle tous les modules d'un coup - aucun module ne code une couleur en dur.
• Écran de chargement animé - v-loadscreen/config.js : un diaporama de fonds (vidéos en boucle et images), un lecteur de musique intégré, des astuces qui défilent, une bande de raccourcis et un compteur de joueurs en direct, le tout dans un fichier. Il se ferme sur le signal player-loaded du framework, avec un filet de sécurité pour ne laisser personne bloqué.
• Éditeur de contenu en jeu - 30 domaines que le menu admin crée, modifie et supprime sans redémarrage : blips, boutiques, métiers & grades, gangs & rangs, items, recettes de craft, boutiques de vêtements & emplacements, garages, points de location, stations-service, ateliers, concessions, catalogue véhicules, types de licence, territoires de gang, code pénal, substances, canaux radio, trésoreries de faction et thèmes par module. Adossé à v-world, appliqué à chaud.
• Conçu pour être étendu - un script écrit par quelqu'un d'autre se branche avec une ligne de manifest. Services (V.Service('banking')) pour demander une capacité plutôt qu'un nom de ressource ; hooks qu'il peut refuser ou réécrire, ce que de simples events ne permettent pas ; et un registre listant chaque module, service, hook, event et commande. Voir DEVELOPERS.md.
• Registre de modules & réglages - chaque module déclare ses réglages à v-core ; l'onglet Réglages du menu admin affiche ce qu'on lui donne, il n'a donc jamais à changer. Un script tiers ajoute v_module 'yes' à son manifest et y apparaît aussi - voir DEVELOPERS.md.
• Aucune commande chat joueur - la surface d'interaction, c'est l'œil de ciblage, les touches et la NUI.
• Bilingue nativement - chaque texte joueur existe en anglais et en français ; le joueur choisit sa langue à la première connexion.
• Autoritaire serveur par défaut - proximité, fonds, propriété et permissions sont revérifiés côté serveur à chaque action. Les contrôles côté client sont de l'UX, pas de la sécurité.
• MariaDB locale à la demande - jamais en service Windows, ne démarre jamais avec Windows.

Modules de gameplay

• v-inventory - inventaire grille (poids, utiliser/jeter/donner), catalogue de 302 items, armes fonctionnelles (munitions, série, durabilité/enrayage, accessoires), sacs & armure, poche cachée, coffres de véhicule & stashes partagés/gang, et fouille/vol de joueur + mains en l'air.
• v-world - la couche de contenu modifiable par les admins (blips, boutiques, métiers, items, recettes).
• v-admin - panneau en jeu (F10) : tableau de bord, joueurs, scripts, monde, logs, Éditeur, et outils (noclip, mode dieu, invisible, blips joueurs, observation, ouvrir l'inventaire d'un joueur).
• v-appearance / v-spawn - moteur d'apparence à identité vêtement stable, sélection multi-personnages, coiffeur / chirurgien / salon de tatouage.
• v-crafting - 105 recettes sur 6 stations (établi, rechargement, cuisine, électronique, recyclage/raffinage, labo de drogue caché), autoritaire serveur, recettes éditables en jeu.
• v-gathering - points de ressources (minage, casse, textile, cultures de cannabis cachées).
• v-shops - boutiques avec achat & vente, distributeurs, revendeur de ferraille, et dealer / blanchisseur illégal (argent sale). Positions modifiables en jeu.
• v-target - œil d'interaction universel (maintiens Alt gauche) : options filtrées par permission & métier.
• v-jobs - métiers, grades, salaires en service ; la référence pour tous les gates métier.
• v-vehicles / v-garages - persistance des véhicules possédés (mods, carburant, dégâts), plaques générées par le serveur, système de clés, et 9 garages dont une fourrière et les garages de métier, et un aperçu 3D showroom - le tout modifiable en jeu.
• v-fuel - quatre carburants (91 / 98 / gazole / électrique), consommation selon la charge moteur, 18 stations dont des bornes de recharge à plusieurs niveaux avec courbe de charge, jerricans ; stations et prix modifiables en jeu.
• v-mechanic - usure sur 20 pièces (12 en électrique) selon la distance, la conduite et les accidents, vrai compteur kilométrique, 27 pièces fabricables, kits de réparation et ateliers verrouillés par métier - le tout modifiable en jeu.
• v-vehicleshop - 6 concessions, catalogue de 56 véhicules avec aperçu 3D showroom, essais routiers, achats conditionnés au permis et revente ; concessions et catalogue modifiables en jeu.
• v-licenses - 12 licences & permis (identité, conduite, poids lourd, bateau, pilote, port d'arme…) avec suspension, retrait, expiration et points ; la référence unique des droits du perso.
• v-cityhall - le guichet emploi de la mairie : postuler à un poste laissé ouvert par un admin, ou démissionner. Les métiers sur whitelist (police, EMS, …) n'y apparaissent jamais.
• v-rentals - location courte durée à quatre comptoirs : caution et frais prélevés d'avance, plaque temporaire RENT### et minuteur. Rendu à temps, la caution revient. Une location ne crée jamais de ligne de propriété : c'est la seule règle qui sépare une location d'une voiture gratuite.
• v-factions - un seul moteur pour les factions légales et illégales : elles diffèrent par la table qui porte leur définition, jobs ou gangs, et par rien d'autre. Adhésion, rangs, et une trésorerie qui est un vrai compte avec sa piste d'audit plutôt qu'un nombre dans un fichier. Les salaires peuvent en sortir.
• v-bossmenu (F6) - le panneau dont un patron a besoin : membres, rangs, recrutement, renvoi, trésorerie et paie. Verrouillé sur le rang, pas sur la permission admin - le staff n'est pas patron.
• v-gangs - territoires avec capture et influence. L'influence appartient à celui qui tient le territoire et un rival l'use au lieu de la prendre : un territoire contesté est un combat, pas une course. L'influence non défendue décroît, un territoire doit être tenu et pas seulement pris.
• v-police - menottes, escorte, fouille, saisie, inculpation, amendes, prison et un MDT (casier, mandats, permis, véhicules). La police est un métier, pas une permission. Le code pénal est une donnée : 21 infractions avec amende, prison et points de permis, modifiables en jeu.
• v-banking (DAB Fleeca) · v-status (faim/soif/stress/saignement) · v-hud (cinq thèmes, dix compteurs, vingt et un témoins de tableau de bord, une boussole, une minimap ronde et un menu de réglages par joueur) · v-sport (salle de sport : force, souffle et endurance, avec un QTE rythmé) · v-notify · v-clothing (16 emplacements portables, 10 boutiques, emplacements & boutiques modifiables en jeu) · v-loadscreen.
• v-music (F4) - enceintes, juke-box et autoradio, positionnels et synchronisés par horodatage pour qu'un arrivant tardif tombe en cours de morceau. Liste blanche d'hôtes, parce que la lecture d'URL arbitraires est un problème de modération, pas technique.
• v-radio (F3) - l'appareil : suivre plusieurs canaux à la fois, émettre sur un seul, présélections sur un pavé. Il ne décide d'aucune permission - il demande à v-voice.
• v-3dsound - un primitif de son positionnel que les autres modules appellent : un nom, un lieu et une portée passent sur le fil, jamais de l'audio, et seuls les auditeurs à portée sont prévenus.
• v-anticheat - contrôles serveur sur les déplacements, la santé, les explosions, la création d'entités par le client, l'argent et les dégâts d'arme. Journalise par défaut au lieu d'expulser, parce qu'un anticheat qui expulse des joueurs légitimes est pire que rien.
• v-voice - voix de proximité en trois paliers, canaux radio verrouillés sur le métier ou le rang de gang, et un canal séparé pour les appels. Un saignement réduit la portée, les menottes coupent la radio, et quitter un métier quitte son canal.
• v-drugs - des plantations que le joueur pose et peut perdre, et un deal de rue qui résiste : la demande décroît par quartier à mesure qu'on y vend, et la chaleur pilote les refus comme le risque d'interpellation. Les ventes paient en argent sale, qui doit passer par le blanchisseur.
• Boucles économiques - légale : récolter → fabriquer → vendre. Illégale : cultiver → traiter → dealer → blanchir.

Installation

1. Artifacts - les binaires serveur vont dans artifacts/ (non suivi par git). Télécharge cfx-server_win_x64.zip (Windows) ou cfx-server_linux_x64.tar.xz (Linux) depuis les artifacts cfx.re et extrais-les dans artifacts/. L'archive doit contenir cfx-server.exe - server.zip / FXServer.exe est la branche Legacy et refusera les clients Enhanced avec bad_request.
2. Clé de licence - récupère une clé gratuite sur keymaster.fivem.net et renseigne sv_licenseKey dans server.cfg.
3. Base de données - fais pointer mysql_connection_string dans server.cfg vers ton MySQL/MariaDB, puis importe database/schema.sql.
4. Lancement - ./start.ps1.
5. Connexion - dans FiveM, appuie sur F8 et tape connect localhost:30120.

Le core : v-core

resources/[local]/v-core est le framework. Les autres ressources l'utilisent via les exports :

local Core = exports['v-core']:GetCore()

Pour ajouter une ressource :

1. Crée resources/[local]/<ta-ressource>/ avec un fxmanifest.lua.
2. Récupère le core avec exports['v-core']:GetCore() et bâtis sur Core.GetPlayer, Core.Notify, etc.
3. Ajoute ensure <ta-ressource> dans server.cfg après v-core.
4. Livre une UI de gestion protégée par permission dans v-admin pour tout ce qu'un opérateur voudra régler - voir le pattern v-world dans ARCHITECTURE.md §7.
5. Dans la console serveur : refresh puis ensure <ta-ressource>.

Base de données (à la demande)

N'importe quelle instance MySQL ou MariaDB convient - le framework ne lui parle qu'à travers oxmysql, donc la façon de la lancer t'appartient (service, Docker, ou installation locale à la demande).

Configure la connexion dans server.cfg :

set mysql_connection_string "mysql://user:password@localhost:3306/ta_base?charset=utf8mb4"

Puis importe database/schema.sql (24 tables). Les migrations s'appliquent automatiquement au démarrage.

Dépendances

• FiveM / cfx.re · Natives FiveM · Manuel serveur · MariaDB · oxmysql · screenshot-basic - miniatures du catalogue de vêtements

Contrôles

Quatre scripts dans tools/ répondent à des questions dont la mauvaise réponse est silencieuse en jeu. Chacun lit le dépôt, ne modifie rien, et sort en code non nul quand il trouve quelque chose, pour qu'un hook ou une étape de CI puisse échouer dessus. À lancer depuis la racine :

python tools/lua-syntax.py        # chaque fichier Lua compile, y compris les fichiers client
python tools/privacy-sweep.py     # tout ce qui ne doit jamais être commité
python tools/locale-check.py      # clés définies une fois, des deux côtés, et toutes celles utilisées existent
python tools/manifest-check.py    # chaque asset chargé par une page NUI est bien servi par la ressource

lua-syntax répond à une question que démarrer le serveur ne peut pas trancher. Un script CLIENT cassé n'est jamais lu par le serveur : la ressource annonce « Started », enregistre ses réglages et ne journalise rien, et le fichier ne tourne simplement pas quand un joueur se connecte. Cela a été mesuré et non supposé : un fichier client volontairement cassé a produit un démarrage totalement propre.

Un cinquième exige une base de données, d'où sa place à part. Les quatre ci-dessus lisent le dépôt et n'ont besoin de rien d'autre. sql-check demande à la base si chaque requête SQL du framework est une requête qu'elle accepterait, ce qu'un démarrage ne peut pas dire : il n'exécute que les requêtes du démarrage, et un SELECT derrière une boutique ou une application du téléphone n'est vu que lorsqu'un joueur s'en approche.

database\start-db.bat
set VCORE_DB=mysql://user:password@host:port/database
python tools/sql-check.py --client "C:/Program Files/MariaDB 12.3/bin/mariadb.exe"

PREPARE fait tourner l'analyseur et le résolveur de noms puis s'arrête : rien n'est lu, rien n'est écrit. Sur 903 requêtes complètes, aucune n'est refusée aujourd'hui. Il dit à voix haute ce qu'il ne juge pas plutôt que de le compter comme réussi : 66 requêtes assemblées à l'exécution, et la poignée écrites dans le schéma de qb-core ou d'ox_core derrière une branche Bridge.framework == 'qb', qui ne tournent jamais ici et sont listées à part pour qu'un échec permanent n'apprenne à personne à ignorer le contrôle.

Un module peut porter la sienne, et le téléphone le fait. v-phone/tools/test-all.py en enchaîne vingt-deux, dans l'ordre où l'échec coûte le moins cher d'abord : compilation Lua, ses propres contrôles statiques, puis une sonde qui pilote une vraie souris à travers le compositeur et vérifie que chaque commande est atteignable sur les 37 applications. À lancer depuis le dossier de la ressource, car ses motifs sont relatifs :

cd "resources/[local]/v-phone" && python tools/test-all.py --fast

--fast saute les 71 captures ; sans lui elles sont reconstruites. L'un de ces contrôles est un autotest qui montre à chacun des autres une faute qu'il doit attraper, la propriété qui empêche un feu vert de vouloir dire que personne n'a regardé.

locale-check lit aussi le JavaScript des pages NUI, et non le seul Lua. Pour un module dont l'interface est une page web, c'est là que vit presque tout le texte : v-phone demande 591 clés à app.js et quatre au Lua. Ne lire que le Lua validait quatre clés sur 852 en annonçant que tout allait bien. Le téléphone résout une clé par S[k] || k, donc une clé absente s'affiche au joueur sous son propre nom. Les interfaces ne s'accordent pas sur le nom de ce résolveur : v-phone l'appelle L, v-appearance et v-inventory t, v-hud y accède par S.t. Les quatre formes sont lues, ce qui a fait entrer sous contrôle les 118 chaînes du menu de v-hud et les 13 de v-inventory.

Chacun a été écrit parce que ce qu'il cherche s'était déjà produit ici au moins une fois : une chaîne de connexion vivante dans un fichier suivi, une clé définie deux fois dont la seconde gagnait en silence, et un script chargé par la page que le manifeste ne listait pas, qui répond 404 et laisse une fonctionnalité inerte.

Deux des trois sont silencieux aujourd'hui. privacy-sweep signale encore une ligne : l'URL de base de données dans server.cfg, identifiants compris, dans un fichier suivi. C'est root:root contre un MariaDB local dans un dépôt privé, donc l'exposition est faible, mais le remède est le motif que ce même fichier applique déjà à sa clé de licence : déplacer la ligne dans un database.cfg gitignoré et l'exec, au prix d'une étape de configuration sur chaque nouvelle machine. Cet arbitrage appartient à l'opérateur : c'est pourquoi le contrôle le signale au lieu que quoi que ce soit l'ait modifié.

Deux modules embarquent leurs propres contrôles plus profonds, qui valident l'équilibrage, les locales, les callbacks NUI et le manifeste selon les règles du module. Ils trouvent leur ressource depuis leur propre emplacement, donc ils se lancent depuis la racine comme les autres :

python "resources/[local]/v-sport/tools/check.py"
python "resources/[local]/v-phone/tools/check.py"

Credits

Author: vyrriox