F5 StudioF5 Studio
Skip to main content

Installation

F5 Combat HUD is a per-player combat HUD with a server-owned policy layer. Every player opens one menu (/chud) and builds their own crosshair — 11 shapes, 64 ready-made presets, dynamic spread, glow, rainbow, HP-based colour, animations, per-weapon crosshairs, or an uploaded image — then their own hit effects (hitmarker, GTA particle bursts, damage numbers, killmarker, headshot marker, kill flash, hit direction) and their own scoreboard layer (killstreak announcements, streak counter, K/D HUD, kill feed). Everything is saved per player in your database, across up to five named profiles, and shared through share codes or a built-in crosshair marketplace with its own moderation panel.

You decide what any of that is allowed to be. config/features.lua switches whole tabs and individual sections on or off, and the server enforces the ones that matter — a modified NUI gains nothing.

Requirements​

RequirementDetails
FrameworkQBCore, QBox Core, or ESX (auto-detected)
FiveM ServerRecent artifacts recommended
Lua5.4 (enabled automatically via lua54 'yes')
DatabaseMySQL 5.7+ / MariaDB 10.2+ (8.0+ / 10.6+ recommended)
Database Resourceoxmysql (recommended), mysql-async, or ghmattimysql — auto-detected by the built-in SQL bridge
Inventory / TargetNot required. The HUD uses no items and no target system
Steam Web API keyOptional — only for avatars in the kill feed and marketplace
Multi-Framework

F5 Combat HUD detects your framework at startup: it takes the first of qbx_core, qb-core, es_extended that is running, in that order — so a QBox server that still keeps qb-core around for older scripts is read as QBox. Everything framework-specific lives in the open bridge/ folder. See Framework Compatibility.

Database driver auto-detection

The resource ships its own SQL layer (server/db.lua) that looks for oxmysql, mysql-async and ghmattimysql in that priority order, retrying for up to 30 seconds after start. Whichever it finds is announced in the console:

[f5_combathud] MySQL bridge: oxmysql

The manifest declares no hard database dependency, so the resource starts on whichever supported driver is running — just make sure your database resource is listed before f5_combathud in server.cfg.

Step by Step​

1. Download​

Purchase F5 Combat HUD from the F5 Studio store. Claim the asset on Cfx.re Keymaster and download the latest version.

2. Folder Structure​

Place the resource in your server's resources directory. The folder must be named f5_combathud:

Folder structure
resources/
  [f5]/
    f5_combathud/
      bridge/            ← framework layer (editable)
        client/
        server/
        init.lua
      client/
      config/            ← all configuration (editable)
        main.lua
        features.lua
        defaults.lua
        presets.lua
        weapons.lua
        limits.lua
      html/              ← NUI: index.html, script.js, style.css, sounds/
      images/icons/      ← weapon icons for the kill feed
      locales/           ← 12 languages (editable)
      server/
        config_server.lua  ← Discord webhook (server-only)
      shared/
      install.sql
      fxmanifest.lua
Do not rename the folder

The NUI addresses its callbacks to the literal resource name f5_combathud (html/script.js). Rename the folder and the menu still opens, but every save, profile action and marketplace call silently fails. If you must rename it, you have to change that name inside html/script.js as well.

Configuration lives in config/

There is no config.lua in the resource root. Everything is inside the config/ folder, split across six files. Whenever this documentation says "open config/main.lua", it means exactly that path. The manifest loads all six as shared scripts, so they are read by client and server alike.

3. Server Config​

Add the resource to your server.cfg — it must start after your database resource and your framework:

server.cfg
ensure oxmysql
ensure qb-core
ensure f5_combathud
Start order

Framework detection runs once, at startup. If your framework resource is not up yet, the resource refuses to start and prints:

[f5_combathud][bridge] no supported framework detected (qbx_core, qb-core, es_extended) — set F5Cfg.Framework.mode in config/main.lua

The database layer is more forgiving — it keeps looking for a driver for 30 seconds — but the framework is not. Keep the order above.

4. Database​

No manual SQL import is required. With F5Cfg.AutoInstallDatabase = true (the default) the resource reads install.sql at startup, creates any table your database is missing and adds any column a table does not have yet:

TablePurpose
f5_combathud_player_crosshairsOne row per player: settings, uploaded image, kills, deaths, active profile
f5_combathud_player_crosshair_profilesNamed profiles (up to F5Cfg.Profiles.maxProfiles each)
f5_combathud_marketplacePublished crosshair listings
f5_combathud_marketplace_likesOne row per player per liked listing
f5_combathud_marketplace_appliesOne row per player per applied listing
f5_combathud_marketplace_bansMarketplace bans, permanent or expiring
f5_combathud_admin_auditModeration audit trail
f5_combathud_schema_versionSchema version marker (currently 5)

Auto-repair only ever adds — it never drops, renames or retypes a column, so it is safe to leave on. Indexes are created together with a new table.

An incomplete schema stops the resource

If tables or columns are still missing after startup, the resource does not run on with nothing being saved — it stops itself and names what is missing:

[f5_combathud] DATABASE SCHEMA INCOMPLETE — the resource will not run.
[f5_combathud] Missing tables: f5_combathud_marketplace
[f5_combathud] Stopping the resource so this is not mistaken for a working install.

The usual cause is a database user without CREATE / ALTER rights. Either grant them, or set F5Cfg.AutoInstallDatabase = false and import install.sql by hand. See Database.

5. Framework​

Left at 'auto', nothing needs configuring:

config/main.lua
F5Cfg.Framework = {
    mode = 'auto',  -- 'auto' | 'qb' | 'qbx' | 'esx' | 'custom'
}

Name one yourself when the guess is wrong, or use 'custom' for a fork of QBCore / QBox / ESX and describe only what your fork renamed. See Framework Compatibility.

6. Language​

config/main.lua
F5Cfg.Locale = 'en'   -- en, pl, de, es, fr, pt, nl, cs, tr, ar, zh, th

Twelve languages ship complete (897 keys each). Anything missing falls back to English. See Localization.

7. Moderator Access​

The marketplace Moderation tab — hiding and deleting listings, and marketplace bans — is unlocked by the list in config/features.lua:

config/features.lua
F5Cfg.ModeratorAces = {
    'command.combathud_admin',
    'god',
    'admin',
    'mod',
}

Your existing staff usually qualify already, because god / admin / mod are QBCore's own admin groups and admin is also the ESX group and the QBox group.admin ACE. For someone who moderates without being a server admin, grant this resource's own permission:

server.cfg
add_ace group.moderator command.combathud_admin allow

Every moderation call is re-checked server-side, so a visible tab never grants the power. See Permissions.

8. Steam Avatars (optional)​

Avatars in the kill feed and on marketplace listings come from Steam. Without a Web API key they stay blank and the resource says so once at startup:

[f5_combathud] steam_webApiKey convar is not set — Steam avatars in the kill feed and marketplace will stay blank.
server.cfg
set steam_webApiKey "YOUR_KEY"

Get a key at steamcommunity.com/dev/apikey. Everything else works without it.

9. Discord Webhook (optional)​

Marketplace publishing and moderation can be mirrored to Discord. The URL lives in a server-only file that is never sent to a client:

server/config_server.lua
F5Cfg.MarketplaceWebhook = {
    enabled = true,
    url = 'CHANGE_ME',
}

Leaving enabled = true with the placeholder URL is harmless but pointless — the resource warns once and sends nothing. See Discord Webhooks.

10. Verify​

Restart the server. A healthy boot is quiet — with F5Cfg.Debug = false (the default) you should see exactly two lines:

[f5_combathud] Config validated.
[f5_combathud] MySQL bridge: oxmysql

Config loaded with N warnings. in place of the first line means the resource is running but something in config/ deserves a look — every warning names its own key. CONFIG INVALID — N errors. Resource will not start. means it is not running at all. See Troubleshooting.

A start that had to create or repair the database prints more — the tables and columns it added, then Database schema ready (N tables). That is expected on a first run and on the run after an update.

In game:

CheckExpected
/chudThe menu opens
F9Toggles the crosshair on and off
Change a setting, relogThe setting is still there
Kill someoneKill feed entry, K/D counts up

What You Can Edit​

Four folders ship as open, editable source:

FolderWhat lives there
config/Every option in this documentation — six files
bridge/The framework layer: detection, player lookup, groups, weapon names
locales/Twelve translation files, plus any language you add
html/The NUI: fonts, sounds, styling

client/, server/ and shared/ are protected and cannot be edited — but everything they do is driven by the four folders above, and this documentation describes that behaviour rather than the code.

Server-only file

server/config_server.lua is loaded by server_scripts only. Your webhook URL never reaches a client. Never move it into config/.

Next Steps​