158 online 3 members  + Join RP Base  +
FreeScript

bansystem

by iamilia  ·  version 1.0.0  ·  updated 3 days ago

No reviews yet

Downloads
0
Reviews
0
Size
129 KB
Code check
Clean
Licence
LGPL-3.0
Released
Nov 2026

Multi-signal ban system for FiveM. Full bans and function bans — shoot, drive, voice, chat — keyed on a primary identifier plus hardware tokens, so alt accounts

bansystem
bansystem
Multi-signal ban system for FiveM. Two kinds of ban:

  • Full ban — the player cannot connect.
  • Function ban — the player keeps playing, but specific capabilities are locked (shooting, driving, voice, chat, jumping, sprinting, and more).

Matching is done on a primary identifier + hardware tokens, so a fresh account on the same machine still gets caught and logged as evasion.
Requirements
  • ox_lib
  • oxmysql
  • OneSync
Install
  1. Drop the folder in your resources and ensure bansystem.
  2. The schema is created automatically on first start. DataBase.sql is there if you prefer to import it manually.
  3. Grant permissions in server.cfg:

add_ace group.admin bansystem.ban       allow
add_ace group.admin bansystem.unban     allow
add_ace group.admin bansystem.permanent allow
add_ace group.admin bansystem.immune    allow
add_ace group.mod   bansystem.fban      allow
add_ace group.mod   bansystem.view      allow
add_ace group.mod   bansystem.unban     allow

Every permission lives under the bansystem object, so a group can be granted the whole set at once and denied individual leaves. The most specific rule always wins, which is the short way to say "everything except immunity":

add_ace group.admin bansystem        allow
add_ace group.admin bansystem.immune deny

Everything else is tuned in shared/config.lua.
Primary identifier
A ban is keyed on one identifier. Which one is your choice:

Config.Identity = {
    primary  = 'license',            -- license, license2, steam, discord, fivem, xbl, live, ip
    fallback = 'license',            -- used when the primary is missing; false rejects the connection
    label    = 'Rockstar license',   -- shown to players in error messages
    bare     = { pattern = '^%x+$', length = 40 },
}

bare is what lets an admin type /ban 4f2a9c... 7d instead of the full license:4f2a9c.... Change it to match whatever primary is:

primary, bare

license, license2, { pattern = '^%x+$', length = 40 }
discord, steam, fivem, xbl, live, { pattern = '^%d+$', length = false }
anything, false to require the prefixed form

Only license is guaranteed to exist for every player — Steam is missing for non-Steam launches, Discord is missing when Discord isn't running. That is what fallback is for: set it and those players stay bannable, or set it to false to refuse the connection outright. Everything listed in storeExtra is recorded alongside for reference, so you can still see a player's Steam and Discord ids regardless of which one is primary.

ip is accepted but a bad idea — addresses are shared and reassigned, so you get false positives and trivial evasion. The resource prints a warning at boot if you pick it.

Switching primary on a live server does not rewrite existing rows: old bans stay keyed on the old identifier and keep working via token matching, but their primary-identifier match no longer applies. Change it before you go live, or clear bansystem_bans afterwards.
Commands
Command, Example

/ban [reason], /ban 12 7d cheating
/fban [reason], /fban 12 shoot,drive 3d rdm
/unban [reason], /unban BAN-7KQ2XF appeal accepted
/unfban [functions] [reason], /unfban 12 voice
/checkban , /checkban 12
/baninfo , /baninfo BAN-7KQ2XF
/bans [page] [search], /bans 2 rdm
/banpanel, opens the admin panel
/banfunctions, lists every function and group
/banreasons, lists every reason preset
/banimport [apply], /banimport import/playersDB.json apply

`` accepts a server id, the primary identifier (prefixed or bare), or a stored player name.

Durations: 30m, 6h, 3d, 2w, 1mo, 1d12h, or perm. A bare number means minutes.

Functions: any key from Config.Functions, any group from Config.FunctionGroups (combat, vehicle, communication, movement, misc), or all. Comma separated.
Importing from another ban system
Drop a backup in the resource's import/ folder and run the import from the server console. The format is worked out from the file, so the command is the same either way.

banimport import/playersDB.json          # dry run - reads the file, writes nothing
banimport import/playersDB.json apply    # writes
banimport import/dump.sql apply hrban    # third argument forces a format

Two sources are understood today:

Format, File, Where it comes from

txadmin, playersDB_.json, txAdmin → Settings → Backup
hrban, a .sql dump, phpMyAdmin / mysqldump of an hr_bansystem table

The dry run is the whole point: it prints exactly what would happen, so you can check the numbers before anything touches the database. Run it first, every time.

[DRY RUN - nothing written] import/playersDB.json
source  : txAdmin playersDB
players : 39 read | 39 new | 0 updated | 0 without a license | 280 tokens
bans    : 1 read | 1 imported (1 active) | 0 already imported | 0 skipped | 0 failed | 12 tokens

What maps to what

txAdmin, here

players[], bansystem_players — name, hardware tokens, every identifier, original join and last-seen dates
actions[] with type: "ban", bansystem_bans as a full ban
hwids on an action, bansystem_ban_tokens — this is what catches the alt account
expiration: false, permanent
expiration: , imported as inactive history, revoke_reason = 'expired before import'
revocation.timestamp, imported as inactive, revoker and date preserved
actions[] with type: "warn", counted in the report, not imported — there is no warning concept here

hr_bansystem, here

Steam License IP Discord Xbox Live, identifiers, keyed on whichever one Config.Identity.primary names — accepted bare or already prefixed
Tokens, tokens on both the identity row and the ban — a JSON array, or a comma separated list
isBanned = 1, a full ban
isBanned = 0, identity row only, no ban — those rows still carry tokens worth keeping
Expire = 0, permanen

…