Developer Events

A comprehensive guide to the Lua events exposed by monoAdmin for external script integration.

monoAdmin exposes a wide variety of server and client-side events that allow external scripts to react to admin actions, player lifecycles, and session state changes.

Quick Start

You can listen for these events using the standard FiveM AddEventHandler.

-- Server-side listener example
AddEventHandler('monoadmin:action:kick_player', function(data)
    print(('Player %d was kicked. Reason: %s'):format(data.target_server_id, data.reason))
end)

-- Client-side listener example (client scripts only)
AddEventHandler('monoadmin:action:mode_changed', function(data)
    print(('Mode changed to: %s'):format(data.mode))
end)

Server-Side Admin Action Events

These events fire on the server after admin commands are executed via the Web Panel.

`monoadmin:action:kick_player`

Fires when a player is kicked by an admin.

Field	Type	Description
`target_server_id`	number	Server ID of the kicked player
`reason`	string	Kick reason message
`command_id`	string	Unique command identifier

AddEventHandler('monoadmin:action:kick_player', function(data)
    -- Log to Discord, database, etc.
    print(('[MonoAdmin] Kicked player %d: %s'):format(data.target_server_id, data.reason))
end)

`monoadmin:action:ban_player`

Fires when a player is banned by an admin.

Field	Type	Description
`target_server_id`	number	Server ID of the banned player
`reason`	string	Ban reason message
`duration`	number	Ban duration in seconds (0 = permanent)
`command_id`	string	Unique command identifier

AddEventHandler('monoadmin:action:ban_player', function(data)
    local durationText = data.duration > 0 and ('%d seconds'):format(data.duration) or 'permanent'
    print(('[MonoAdmin] Banned player %d for %s: %s'):format(data.target_server_id, durationText, data.reason))
end)

`monoadmin:action:set_job`

Fires when an admin sets a player’s job.

Field	Type	Description
`target_server_id`	number	Server ID of the target player
`job`	string	Job name
`grade`	number	Job grade/rank
`command_id`	string	Unique command identifier

AddEventHandler('monoadmin:action:set_job', function(data)
    print(('[MonoAdmin] Set player %d job to %s (grade %d)'):format(data.target_server_id, data.job, data.grade))
end)

`monoadmin:action:give_item`

Fires when an admin gives an item to a player.

Field	Type	Description
`target_server_id`	number	Server ID of the target player
`item`	string	Item name/identifier
`amount`	number	Quantity given
`command_id`	string	Unique command identifier

AddEventHandler('monoadmin:action:give_item', function(data)
    print(('[MonoAdmin] Gave %dx %s to player %d'):format(data.amount, data.item, data.target_server_id))
end)

`monoadmin:action:spawn_vehicle`

Fires when an admin spawns a vehicle for a player.

Field	Type	Description
`target_server_id`	number	Server ID of the target player
`model`	string	Vehicle model name
`network_id`	number	Network ID of spawned vehicle
`command_id`	string	Unique command identifier

AddEventHandler('monoadmin:action:spawn_vehicle', function(data)
    print(('[MonoAdmin] Spawned %s for player %d (netId: %d)'):format(data.model, data.target_server_id, data.network_id))
end)

`monoadmin:action:delete_vehicle`

Fires when an admin deletes a player’s vehicle.

Field	Type	Description
`target_server_id`	number	Server ID of the target player
`command_id`	string	Unique command identifier

AddEventHandler('monoadmin:action:delete_vehicle', function(data)
    print(('[MonoAdmin] Deleted vehicle for player %d'):format(data.target_server_id))
end)

Server-Side NUI Action Events

These events fire on the server when admins use the In-Game Control Panel.

`monoadmin:action:player_mode`

Fires when an admin changes their player mode.

Field	Type	Description
`source`	number	Server ID of the admin
`user_id`	number	MonoAdmin user ID
`mode`	string	Mode name (NoClip, Freecam, GodMode, SuperJump, Normal)

AddEventHandler('monoadmin:action:player_mode', function(data)
    print(('[MonoAdmin] Admin %d enabled %s mode'):format(data.source, data.mode))
end)

`monoadmin:action:teleport_waypoint`

Fires when an admin teleports to waypoint.

Field	Type	Description
`source`	number	Server ID of the admin
`user_id`	number	MonoAdmin user ID
`destination`	table	`{ x, y, z }` coordinates

AddEventHandler('monoadmin:action:teleport_waypoint', function(data)
    print(('[MonoAdmin] Admin %d teleported to %.1f, %.1f, %.1f'):format(
        data.source, data.destination.x, data.destination.y, data.destination.z
    ))
end)

`monoadmin:action:fix_vehicle`

Fires when an admin repairs their vehicle.

Field	Type	Description
`source`	number	Server ID of the admin
`user_id`	number	MonoAdmin user ID

AddEventHandler('monoadmin:action:fix_vehicle', function(data)
    print(('[MonoAdmin] Admin %d repaired their vehicle'):format(data.source))
end)

`monoadmin:action:heal_self`

Fires when an admin heals themselves.

Field	Type	Description
`source`	number	Server ID of the admin
`user_id`	number	MonoAdmin user ID

AddEventHandler('monoadmin:action:heal_self', function(data)
    print(('[MonoAdmin] Admin %d healed themselves'):format(data.source))
end)

Client-Side Action Events

These events fire on the client (local to the admin using the panel).

`monoadmin:action:spectate_start`

Fires when spectating begins.

Field	Type	Description
`target_server_id`	number	Server ID of player being spectated
`target_name`	string	Name of player being spectated

AddEventHandler('monoadmin:action:spectate_start', function(data)
    print(('Now spectating %s (%d)'):format(data.target_name, data.target_server_id))
end)

`monoadmin:action:spectate_stop`

Fires when spectating ends. Payload is empty.

AddEventHandler('monoadmin:action:spectate_stop', function(data)
    print('Stopped spectating')
end)

`monoadmin:action:mode_changed`

Fires when player modes are toggled.

Field	Type	Description
`mode`	string	Mode that was just toggled
`active_modes`	table	Array of currently active mode names

AddEventHandler('monoadmin:action:mode_changed', function(data)
    print(('Toggled mode: %s'):format(data.mode))
    print(('Active modes: %s'):format(table.concat(data.active_modes, ', ')))
end)

Player Lifecycle Events

These events fire on the server during player session lifecycle.

`monoadmin:session:start`

Fires when a player session begins (after spawn delay).

Field	Type	Description
`session_id`	string	Unique session identifier
`server_id`	number	Player’s server ID
`name`	string	Player name
`identifiers`	table	Player identifiers (license, discord, etc.)
`ip_address`	string	Player IP address

AddEventHandler('monoadmin:session:start', function(data)
    print(('[Session] Started for %s (ID: %d)'):format(data.name, data.server_id))
end)

`monoadmin:player:joined`

Fires when a player fully loads with framework data.

Field	Type	Description
`server_id`	number	Player’s server ID
`name`	string	Player name
`identifiers`	table	Player identifiers
`ip_address`	string	Player IP address
`job`	string\|nil	Player’s job (if framework present)
`position`	table\|nil	`{ x, y, z }` spawn position
`group`	string	Permission group (e.g., ‘user’, ‘admin’)

AddEventHandler('monoadmin:player:joined', function(data)
    -- Custom welcome message
    TriggerClientEvent('chat:addMessage', data.server_id, {
        args = { 'Server', 'Welcome to the server, ' .. data.name .. '!' }
    })
end)

`monoadmin:session:end`

Fires when a player session ends.

Field	Type	Description
`session_id`	string	Session identifier
`server_id`	number	Player’s server ID
`quit_reason`	string	Reason for disconnect
`last_position`	table\|nil	`{ x, y, z }` last known position

AddEventHandler('monoadmin:session:end', function(data)
    print(('[Session] Ended for server ID %d: %s'):format(data.server_id, data.quit_reason))
end)

`monoadmin:player:left`

Fires when a player disconnects.

Field	Type	Description
`server_id`	number	Player’s server ID
`identifier`	string	Primary identifier
`session_id`	string\|nil	Session ID if available
`quit_reason`	string	Reason for disconnect

AddEventHandler('monoadmin:player:left', function(data)
    print(('[%d] Player left: %s'):format(data.server_id, data.quit_reason))
end)

Integration Examples

Discord Logging

local WEBHOOK_URL = 'https://discord.com/api/webhooks/...'

AddEventHandler('monoadmin:action:ban_player', function(data)
    local playerName = GetPlayerName(data.target_server_id) or 'Unknown'
    local duration = data.duration > 0 and ('%d hours'):format(data.duration / 3600) or 'Permanent'

    PerformHttpRequest(WEBHOOK_URL, function() end, 'POST', json.encode({
        embeds = {{
            title = '🔨 Player Banned',
            color = 16711680,
            fields = {
                { name = 'Player', value = playerName, inline = true },
                { name = 'Duration', value = duration, inline = true },
                { name = 'Reason', value = data.reason, inline = false }
            }
        }}
    }), { ['Content-Type'] = 'application/json' })
end)

Anti-Abuse Detection

local modeUsage = {}

AddEventHandler('monoadmin:action:player_mode', function(data)
    modeUsage[data.source] = modeUsage[data.source] or { count = 0, lastUsed = 0 }

    local now = os.time()
    local record = modeUsage[data.source]

    -- Reset counter if more than 60 seconds since last use
    if now - record.lastUsed > 60 then
        record.count = 0
    end

    record.count = record.count + 1
    record.lastUsed = now

    -- Alert if suspiciously high usage
    if record.count > 20 then
        print(('[ALERT] Admin %d is toggling modes excessively (%d times)'):format(data.source, record.count))
    end
end)

Session Statistics

local sessions = {}

AddEventHandler('monoadmin:session:start', function(data)
    sessions[data.server_id] = {
        startTime = os.time(),
        name = data.name
    }
end)

AddEventHandler('monoadmin:session:end', function(data)
    local session = sessions[data.server_id]
    if session then
        local duration = os.time() - session.startTime
        print(('[Stats] %s played for %d minutes'):format(session.name, duration / 60))
        sessions[data.server_id] = nil
    end
end)