ShadowAdmin — Documentation

Overview#

SF-Admin gives your staff a single in-game interface to moderate the server. It covers player moderation, vehicle tools, a custom role system with granular permissions, a player report queue and detailed Discord logging. Every action is written to the database and can be sent to a dedicated Discord channel, so nothing a staff member does is invisible.

Player management

Kick, ban, warn, jail, heal, revive, teleport, spectate and inspect the inventory of any connected player.

Vehicle tools

Repair, clean, recolour, change the plate, refuel, flip and delete the vehicle you are looking at.

Granular role system

Create your own staff roles and tick exactly which of the 28 permissions each one gets.

Report queue

Players open reports, staff claim them, teleport to the reporter and close them once handled.

Per-category Discord logs

Seven separate webhooks: sanctions, connections, players, vehicles, roles, reports and admin actions.

Staff toolkit

Noclip, godmode, invisibility, staff outfits and player blips, all behind their own permission.

Five languages

Ships with English, French, Spanish, German and Italian translation files.

Framework detection

Detects ESX or QBCore automatically, and runs standalone when neither is present.

Dependencies#

Resource	Required	Why
`oxmysql`	Yes	Stores roles, sanctions, reports and the action history.
`MySQL / MariaDB`	Yes	Database backing oxmysql.
`SF-UID`	Optional	When present, permanent player IDs are shown next to each player.
`SF-Ban`	Optional	When present, bans issued from the menu are handled by SF-Ban.

Installation#

Drop the SF-Admin folder into your server resources directory.
Add the ensure lines below to your server.cfg, keeping oxmysql before SF-Admin.
Open config.lua and set your Discord webhooks, jail position and default language.
Grant the superadmin ACE group to yourself so you can create the first roles in game.
Restart the server. The tables are created automatically on first start.

server.cfg

ensure oxmysql
ensure SF-Admin

# Give yourself full access (replace with your own identifier)
add_principal identifier.license:YOUR_LICENSE group.superadmin

Configuration#

Key	Default	What it does
`Config.OpenKey`	`'F10'`	Key that opens the admin menu.
`Config.Framework`	`'auto'`	Force esx or qbcore, or leave on auto-detection.
`Config.DefaultLanguage`	`'en'`	Language used when a player has no preference.
`Config.SuperAdmin`	—	Identifiers that always get every permission, regardless of roles.
`Config.Permissions`	—	The list of the 28 permission nodes assignable to a role.
`Config.Logs`	—	One Discord webhook URL per log category.
`Config.Jail`	—	Coordinates of the jail and default sentence length.
`Config.Vehicle`	—	Vehicle tool options: fuel resource, available colours, plate format.
`Config.Reports`	—	Report queue behaviour: cooldown, maximum open reports, notifications.
`Config.StaffOutfits`	—	Outfits staff can switch to while on duty.
`Config.TrollCommands`	—	Enables or disables the fun/troll actions on players.
`Config.Integrations`	—	Toggles the SF-UID and SF-Ban bridges.
`Config.AutoRefresh`	—	How often the connected player list refreshes while the menu is open.

Permissions#

ACE node	Group	Allows
`open_menu`	Admin	Open the admin menu.
`admin_full`	Admin	Full admin access: cleanup, time, weather and announcements.
`staff_tools`	Admin	Noclip, godmode, invisibility, staff outfit and blips.
`player_kick`	Players	Kick a player.
`player_ban`	Players	Ban a player.
`player_warn`	Players	Warn a player.
`player_heal`	Players	Heal a player.
`player_revive`	Players	Revive a player.
`player_teleport`	Players	Teleport yourself or another player.
`player_spectate`	Players	Spectate a player.
`player_inventory`	Players	Inspect and edit a player inventory.
`player_troll`	Players	Use the fun and troll actions on a player.
`player_jail`	Players	Send a player to jail.
`vehicle_repair`	Vehicles	Repair a vehicle.
`vehicle_clean`	Vehicles	Clean a vehicle.
`vehicle_color`	Vehicles	Change the colour of a vehicle.
`vehicle_plate`	Vehicles	Change the plate of a vehicle.
`vehicle_refuel`	Vehicles	Refuel a vehicle.
`vehicle_flip`	Vehicles	Flip a vehicle back on its wheels.
`vehicle_delete`	Vehicles	Delete a vehicle.
`reports_view`	Reports	View the report queue.
`reports_take`	Reports	Claim a report.
`reports_close`	Reports	Close a report.
`reports_teleport`	Reports	Teleport to the player who opened the report.
`give_roles`	Roles	Assign a role to a player.
`create_roles`	Roles	Create a new role.
`edit_roles`	Roles	Edit an existing role.
`delete_roles`	Roles	Delete a role.

Exports#

Signature	Side	Returns
`exports['SF-Admin']:GetPerformanceMetrics()`	server	Returns the resource performance counters.
`ShadowLogs.AdminAction(source, action, details)`	server	Writes an admin action to the log and the matching Discord webhook.
`ShadowLogs.PlayerConnect(source)`	server	Logs a player connection.
`ShadowLogs.PlayerDisconnect(source, reason)`	server	Logs a player disconnection with its reason.
`ShadowLogs.Report(source, target, message)`	server	Logs a report to the reports webhook.
`ShadowLogs.RoleAction(source, role, action)`	server	Logs a role creation, edit, deletion or assignment.
`ShadowLogs.VehicleAction(source, plate, action)`	server	Logs a vehicle tool action.
`ShadowLogs.TrollAction(source, target, action)`	server	Logs a fun or troll action used on a player.
`ShadowIntegrations.IsIdUniqueAvailable()`	server	Returns true when SF-UID is running and the bridge is enabled.
`ShadowIntegrations.GetPermanentId(source)`	server	Reads the permanent ID of a player through SF-UID.
`ShadowIntegrations.GetPermanentIdAsync(source)`	server	Asynchronous version of GetPermanentId.
`ShadowIntegrations.GetPlayerInfo(source)`	server	Returns the aggregated information about a player.
`ShadowIntegrations.IsShadowBanAvailable()`	server	Returns true when SF-Ban is running and the bridge is enabled.
`ShadowIntegrations.BanPlayer(source, target, reason, duration)`	server	Issues a ban through SF-Ban instead of the built-in system.

Good to know#

Permissions are checked on the server for every action, so a player cannot trigger a staff action by calling the event from the client.

Each log category has its own webhook: you can send sanctions to a private staff channel and connections to a public one.