ShadowBan
Advanced ban system with native AdaptiveCards and an unban request workflow.
- Version
- 1.6.0
- Resource
- SF-Ban
Overview#
SF-Ban replaces the plain kick message with five native AdaptiveCards displayed directly inside the FiveM launcher: the ban notice, the appeal form, the confirmation, and the follow-up screens. Bans are matched on every identifier a player carries, so changing licence alone is not enough to come back. Staff get thirteen commands, players get a self-service appeal flow, and everything lands in Discord as a formatted embed.
Five native AdaptiveCards
The ban notice, appeal form and confirmations are rendered by the FiveM launcher itself, with no external website.
Multi-identifier matching
Every identifier seen for a player is stored, so a ban still applies after a licence change.
Self-service appeals
Banned players submit an appeal from the ban screen; staff approve or deny it with a command.
Flexible durations
Seconds, minutes, hours, days, weeks, months, years or permanent.
Full history
Every ban, unban and appeal is kept, so you can see a player entire record.
Five Discord embed types
Ban, offline ban, unban, appeal submitted and appeal handled each get their own embed.
Search and statistics
Search bans by name or identifier and pull per-player statistics.
Automatic cleanup
Purge expired bans and old appeals with a single command.
Dependencies#
| Resource | Required | Why |
|---|---|---|
oxmysql | Yes | Stores bans, identifiers, appeals and history. |
MySQL / MariaDB | Yes | Needs support for views, stored procedures and triggers. |
Installation#
- Drop the SF-Ban folder into your server resources directory.
- Import the SQL file shipped with the resource: it creates four tables, one view, three stored procedures and their triggers.
- Add the ensure lines below to your server.cfg.
- Set your Discord webhooks and your timezone in config.lua.
- Give the shadowban ACE permissions to your staff groups.
ensure oxmysql ensure SF-Ban add_ace group.admin shadowban.admin allow add_ace group.mod shadowban.moderator allow add_ace group.mod shadowban.tempban allow
Configuration#
| Key | Default | What it does |
|---|---|---|
Config.Timezone | UTC+2 | Timezone used to display ban dates and expiry. |
Config.Webhooks | — | One Discord webhook per embed type. |
Config.Language | — | Language of the AdaptiveCards and messages. |
Config.UnbanRequests | — | Enables the appeal flow and sets its cooldown. |
Commands#
| Command | Permission | What it does |
|---|---|---|
/sban [id] [duration] [reason] | shadowban.tempban | Ban a connected player. |
/sbanoff [identifier] [duration] [reason] | shadowban.admin | Ban a player who is not connected. |
/sunban [banId] | shadowban.admin | Lift a ban. |
/sbaninfo [banId] | shadowban.moderator | Show every detail of a ban. |
/sbanlist | shadowban.moderator | List the currently active bans. |
/ssearchbans [query] | shadowban.moderator | Search bans by name or identifier. |
/sbanhistory [identifier] | shadowban.moderator | Show the complete ban history of a player. |
/splayerstats [identifier] | shadowban.moderator | Show the statistics of a player: bans, warnings, appeals. |
/sunbanrequest [message] | Banned player | Submit an appeal. Used by the banned player. |
/sunbanrequests | shadowban.admin | List the pending appeals. |
/sapproverequest [requestId] | shadowban.admin | Approve an appeal and lift the ban. |
/sdenyrequest [requestId] [reason] | shadowban.admin | Deny an appeal. |
/scleanbans | shadowban.admin | Purge the bans that have expired. |
/scleanrequests | shadowban.admin | Purge the handled appeals. |
/shelp | — | Show the list of available commands in game. /sbhelp is an alias. |
/slogs | shadowban.log | Browse the logs recorded by the resource. |
/sloginfo [logId] | shadowban.log | Show the detail of a log entry. |
/sclearlogs | shadowban.log | Clear the stored logs. |
/smetrics | Admin | Show the performance metrics of the resource. |
Permissions#
| ACE node | Group | Allows |
|---|---|---|
shadowban.admin | — | Full access: ban, unban, handle appeals and run cleanups. |
shadowban.tempban | — | Issue temporary bans only. |
shadowban.moderator | — | Read-only access: list, search, inspect bans and statistics. |
shadowban.log | — | Access to the log commands: browse, inspect and clear the logs. |
Database#
| Table | Contents |
|---|---|
shadowban_bans | The bans themselves: reason, author, start, expiry and status. |
shadowban_identifiers | Every identifier tied to a banned player, used to match on reconnection. |
shadowban_unban_requests | Appeals submitted by banned players and their outcome. |
shadowban_history | Immutable trail of every ban and unban action. |