Admin Menu

Requirements

Required

• Framework: QBox (qbx_core) or QBCore (qb-core). The bridge auto-detects, so qbx_core is deliberately not listed as a hard dependency in the manifest — a QBCore server would otherwise refuse to start it.
• ox_lib
• oxmysql

Optional

• ox_inventory — enables inventory viewing, editing and transfer.
• screenshot-basic or screencapture — enables screenshots and Live Watch.
• Any weathersync resource — makes time and weather changes persist.

Current release is v1.1.0.

Installation

1. Drop the XS-AdminMenu folder into your resources directory.
2. Import sql/admin.sql into your database. It creates the roles, assignments, bans, warnings, audit log and notes tables. Default roles are seeded on first start. The four tables added in 1.2.0 — threat flags, identifiers, ban identifiers and mutes — create themselves on start and need no import.
3. Add ensure XS-AdminMenu to server.cfg.
4. Set your own license identifier in Config.Owners — without this nobody can open the panel.
5. Restart the server, then review the roles in the Permissions panel.

ensure XS-AdminMenu

Finding your license identifier

Run this in the server console while you are connected:

print(GetPlayerIdentifierByType(source, 'license'))

Then paste the result into the config:

Config.Owners = {
    'license:YOURLICENSEHERE',
}

Configuration

All options live in config.lua.

-- License identifiers that are always Owner, regardless of database role
Config.Owners = { 'license:...' }

-- Default keybind to open the panel (players can rebind in Settings)
Config.OpenKey = 'F7'

-- Discord webhook for audit entries (kicks, bans, warns)
Config.AuditWebhook = ''

-- 'ox_inventory' | 'qb-inventory' | 'qs-inventory'
Config.InventoryResource = 'ox_inventory'

-- Drives the Self Actions "Clothing" and "Revert Ped" buttons.
-- 'illenium-appearance' | 'fivem-appearance' | 'qb-clothing'
-- | 'rcore_clothing' | 'qbx_core'
Config.AppearanceResource = 'illenium-appearance'

-- Shown in the Server Stats panel
Config.ServerName = 'My FiveM Server'

-- %s = reason, %s = expiry
Config.BanMessage = 'You have been banned...'

Interface

Applied at runtime — a resource restart, no CSS editing.

Config.Theme = {
    Accent    = '#e5484d',
    Side      = 'right',   -- which edge the drawer opens from
    Width     = '80vw',
    Scanlines = true,
    Dim       = 0.45,      -- backdrop opacity behind the drawer
}

Accent and danger are separated by weight rather than hue, so Ban and Delete stay red whatever you set the accent to. That is deliberate: a filled red button should always mean the same thing.

Config.DefaultPanel sets which panel opens first.

Notifications

Config.Notify.Resource takes 'ox_lib', 'qb', 'chat', or 'custom' with your own event name in CustomEvent. Every in-game message the resource sends goes through it, so it matches the rest of your server.

Self action tuning and pick lists

Config.SelfTuning holds the numbers — health and armour amounts, sprint multiplier, noclip speeds, ammo counts. The pick lists are editable too: Config.Landmarks, Config.SelfWeapons, Config.PedModels, Config.RandomPeds, Config.WalkStyles and Config.VehicleColours. Add your own server's locations to the landmark list and they appear in both the Self Actions teleport and the Send To modal.

Data retention

Threat flags grow fastest — one speed hack writes a row every sweep. Config.Retention prunes flags, audit rows and identifier records on a nightly sweep at RunAtHour. Set any value to 0 to keep that table forever. Bans and warnings are never pruned.

Mute and voice

Muting a player mutes chat. Voice belongs to whichever voice resource you run and there is no common API across them, so it is opt-in — point Config.MuteVoiceExport at your own resource's export to extend it.

Automatic warning actions

Warnings can escalate on their own:

Config.WarningThresholds = {
    { count = 3, action = 'kick',    reason = 'Auto-kick: 3 warnings' },
    { count = 5, action = 'tempban', duration = 86400, reason = 'Auto-ban: 5 warnings' },
}

duration is in seconds, so 86400 is 24 hours.

Roles and permissions

Four roles are seeded on first start: Support, Moderator, Admin and Senior Admin. Anyone in Config.Owners bypasses every role check.

Roles and their individual permissions are edited live from the Permissions panel inside the menu — no restart needed. To assign a role, use that panel or write the row directly into the admin_assignments table.

What is in the panel

Players

Live list with online time and a notes tooltip. Kick, warn, mute, temp or permanent ban, freeze, revive, heal, set exact health and armour, kill, eject from a vehicle, teleport to and bring, send to a landmark or coordinates, spectate, screenshot and Live Watch (auto-refreshing every 2.5s), private DM, slap, reset position, give weapon, delete nearest vehicle, and view identifiers.

Mass actions

Summon All, Freeze All, Unfreeze All and Revive Nearby. Freeze All skips other staff on purpose — an admin who freezes the server and forgets has otherwise locked out everyone who could undo it.

Character lookup

Search by name or CitizenID, online or offline. View and set job and grade, cash and bank balance, add notes, or delete the character from the database.

Item spawner

Browses your server's real item list rather than a list baked into the resource, so it shows whatever you actually installed. Search by item name or label, pick a quantity, and give to yourself or to any online player.

Settings

Per-admin interface preferences: accent colour from eight presets or a custom hex, which side the drawer opens from, its width, the backdrop dim, the scanline texture, and which panel opens first.

These are stored in that admin's own browser profile, not on the server, and layer over Config.Theme — so the owner's default remains the default for everyone who has not changed anything. Ban and Delete stay red whatever accent is chosen.

Inventory

View any player's inventory including offline by CitizenID. Compare Mode puts your inventory beside theirs with one-click transfer in either direction. Give, remove, clear and filter items.

Self Actions

66 actions across eight sections, with a live filter and a favourites bar — right-click any action to pin it. The Weapons section is hidden unless you hold the giveweapon permission.

Threats

Live detection feed with a 24-hour summary, severity filter and one-click spectate, screenshot or ban. A second tab lists ban evasion matches and linked accounts.

• Personal: God Mode, Heal, Revive, Food & Water, Armour Only, Infinite Stamina, Fireproof, No Ragdoll, Clear Wanted, Set Wanted
• Appearance: Invisible, Ped Model, Random Ped, Revert Ped, Clothing, Walk Style
• Movement: Noclip, Super Jump, Super Sprint, To Waypoint, To Coords, Save Position, Load Position, Undo Teleport
• Vehicle: Spawn, Repair, Max Mods, Take Keys, Flip Upright, Refuel, Clean, Vehicle God, Set Plate, Delete
• World: Weather, Time, Freeze Time, Blackout, Announce, Traffic density, Pedestrian density
• Area: Clear Area, Clear Vehicles, Clear Peds, Clear Objects, Delete Ped
• Utility: Copy Vector4, Copy Vector3, Entity Info, Spawn Prop

Entity inspector

Scan nearby vehicles and NPCs within 50, 100, 150 or 250 metres. Shows model, plate, health and distance, and can delete any entity by network ID.

Bans, reports, admin chat and audit

Searchable ban list with unban and preset durations. Player reports with claim, respond and close plus an unread badge. Staff-only in-game chat. Every admin action written to the database and optionally to Discord.

Server and resources

Live player count, uptime, resource counts, OneSync mode and game mode. Any resource can be restarted from the panel.

Threat detection

Ten detections, all configured under Config.AntiCheat. Eight read state on the server, where the client has no say. Two come from a client heartbeat and are labelled advisory in the panel, because a client can lie about what it reports.

What it checks

• Server-side: health overflow, impossible movement, impossible speed, explosion abuse, weapon damage anomalies, entity spawn abuse, client weapon gives, remote task clears.
• Advisory: armour overflow, and the client agent going silent. The silence is the reliable half — a client that stops answering has had the resource stopped or blocked.

Actions

Every detection has its own action and threshold:

health = {
    enabled = true, action = 'flag', threshold = 2,
    maxHealth = 200,
},

action is flag, kick or ban. threshold is how many hits from one player before it fires. Everything ships as flag — watch your own server for a week before turning anything up, because the shipped numbers are a starting point and not tuned to your traffic.

Who is exempt

Staff are exempt by default (ExemptAdmins), and the target of any admin action is exempt for ActionExemptSeconds afterwards. This is not optional in practice: noclip is a teleport, god mode is a health anomaly, and a bring is a 900 metre position jump on the person being brought.

OneSync

Health, position and speed are read from the server's own copy of the ped, which needs OneSync. With it off, those checks do not run and the panel says so rather than looking quiet. The event-based detections run either way.

Blacklists

BlacklistedModels, BlacklistedExplosions and BlacklistedWeapons are cancelled outright rather than logged after the fact. Empty them on a military roleplay server — tank shells are legitimate there.

Ban evasion

Configured under Config.BanEvasion. Every identifier a player presents is recorded on connect and anchored to their licence, and a ban attaches all of them — so a ban placed on a Discord account still catches that person on a new licence, and an offline ban still gets the full set from the last time they connected.

What is matched

MatchOn decides which identifier types can deny a connection. Recording is deliberately broader than matching: an identifier you never recorded cannot be switched on later, but one you recorded and ignored can.

Hardware tokens

FiveM derives opaque tokens from the client machine. They survive an account change, which makes them the strongest signal available here. Set StoreTokens = false if you would rather not hold them.

Why IP does not block

A household shares one. A phone hotspot shares one. A university campus shares one. IP is recorded and shown as a link because it is useful context, but MatchOn.ip is false out of the box. Turning it on means eventually banning somebody's brother.

Linked accounts

Accounts that have ever shared an identifier are treated as linked. A clean account linked to a banned one raises a flag rather than a denial by default — shared hardware is a real thing. Change LinkedAccountAction to 'deny' if you would rather refuse the connection.

Existing bans

Bans issued before 1.2.0 are backfilled into the new matcher on first start, so upgrading does not quietly stop enforcing anything.

Commands

Every name below is set in Config.Commands. Rename any of them around a clash, or set one to '' to skip registering it — /r in particular collides with a lot of radio and reply resources.

/admin opens the panel as an alternative to the keybind. The keybind itself is Config.OpenKey, and players can rebind it in the FiveM settings.

/report <message>   Submit a support report
/reply  <message>   Reply to your most recent open report

Live map, offline bans and the ladder

Live map is a new tab showing every player on a map of San Andreas. Blue dots are on foot, amber in a vehicle, grey are down. Click a dot to spectate, go to or bring them — same permissions as the player list. Positions come from the server, not from clients, so nothing a cheater sends can move their dot. It only updates while the tab is open.

If dots sit slightly off from where players stand, adjust the world bounds at the top of html/js/panels/livemap.js — stand somewhere recognisable and nudge until the dot lands on you.

Offline actions: the character lookup now has Warn and Ban buttons that work whether the player is online or not.

The ban ladder: the ban menu checks how many times they've been banned before and preselects the next step — 1 day, then a week, then a month, then permanent. It's a suggestion; pick whatever you want.

No config or database changes for 2.0 — drop in and restart.

Integrations

Time and weather

Whatever runs your clock reasserts it every tick, so setting the time means telling that resource rather than setting the clock and hoping. Config.TimeResource defaults to auto, which tries qbx_weathersync, qb-weathersync, renewed-weathersync, rcore_weathersync, cd_easytime, vSync and av_weather.

The server console says which one it used. If it reports that none were detected and the time snaps back, yours is not on that list — put its resource name in Config.TimeResource.

Revive

Reviving has to go through whatever owns the death state, or the ped stands up while the ambulance script still has the player marked dead — which is exactly what a revive that appears to do nothing looks like. Set Config.AmbulanceResource to qbx_medical, qb-ambulancejob, wasabi_ambulance, or custom with your own event.

Vehicle keys

Spawning a car does not hand over keys unless something is told to. Set Config.VehicleKeysResource to qbx_vehiclekeys, qb-vehiclekeys, qs-vehiclekeys, wasabi_carlock or mk_vehiclekeys. Config.GiveKeysOnSpawn controls whether that happens automatically.

The engine ownership flags are set either way, so a spawned vehicle is drivable even with no keys resource installed — you just will not hold a key item for it.

Appearance

Config.AppearanceResource has to match the clothing script you actually run, or the Clothing and Revert Ped buttons silently do nothing.

Screenshots

Screenshot and Live Watch need screenshot-basic or screencapture started. Without one, those buttons fail quietly.

Before going live

Troubleshooting

The panel will not open

Your identifier is not in Config.Owners and you have no role assigned in admin_assignments. Check the license value matches exactly, including the license: prefix.

Clothing and Revert Ped do nothing

Config.AppearanceResource does not match your actual appearance script.

Screenshots fail silently

Neither screenshot-basic nor screencapture is started.

Inventory panel is empty

Config.InventoryResource does not match the inventory you run, or the target has no character loaded.

Time and weather revert after a restart

No weathersync resource was detected, so the change was only broadcast to connected clients.

Every player is flagged as Client agent silent

client/detection.lua did not upload. That detection fires when a client stops answering, and a client that never received the file never answers — so a partial upload flags your whole playerbase at once. Re-upload the entire folder.

The Threats panel says events only

OneSync is off. Health, position and speed are read from the server's copy of the ped and need it. The event-based detections still run.

Staff keep appearing in the threat feed

Config.AntiCheat.ExemptAdmins is off, or that person has no role assigned so the resource does not recognise them as staff. Owners listed in Config.Owners are always exempt.

A legitimate script keeps tripping a detection

Turn off that one detection rather than the engine — every entry in Config.AntiCheat.Detections has its own enabled flag. Military roleplay servers will also want to empty BlacklistedModels and BlacklistedExplosions.

Updating

1. Back up the database — this resource owns real data (bans, warnings, audit history, notes).
2. Keep a copy of your edited config.lua.
3. Check recent commits for SQL changes and apply any new migrations.
4. Replace the resource folder, merge your config back, restart.
5. Replace the whole folder rather than picking out changed files. 1.2.0 adds five new ones, and a partial upload is the single most common cause of a broken update.

Support

Include your framework (QBox or QBCore), inventory resource, the full console error and the steps that caused it.