Developer Exports

Programmatically interact with MonoAdmin from your own FiveM resources for anti-cheat, custom scripts, and automated moderation.

MonoAdmin provides exports that allow you to programmatically interact with the admin system from your own FiveM resources. This enables integration with anti-cheat systems, custom scripts, and automated moderation tools.

Prerequisites

MonoAdmin resource must be running and connected to the cloud
Players must be online and tracked by MonoAdmin before punishments can be issued

CreatePunishment

Create a punishment for a player programmatically. Punishments created via this export are logged with fivem_server as the actor type in audit logs.

Signature

exports['monoadmin']:CreatePunishment(data, callback)

Parameters

Parameter	Type	Required	Description
`data`	table	✅	Punishment configuration (see below)
`callback`	function	❌	Called when punishment is created or fails

Data Table Fields

Field	Type	Required	Description
`source`	number	✅	Server ID of the player to punish
`punishment_type`	string	✅	Type of punishment (see valid values below)
`reason`	string	✅	Reason for the punishment
`duration_minutes`	number	❌	Duration in minutes. `nil` = permanent
`enforcement_mode`	string	❌	`'sticky'` (default) or `'non_sticky'`
`targeted_identifiers`	table	❌	Required for `non_sticky` mode
`kick_if_online`	boolean	❌	Kick player immediately if issuing a ban
`community_service_total`	number	❌	Total hours for `community_service` type

Valid Punishment Types

Type	Description
`ban`	Ban the player from the server
`warn`	Issue a warning to the player
`kick`	Kick the player from the server
`community_service`	Assign community service hours

Enforcement Modes

Mode	Description
`sticky`	Punishment applies to all player identifiers (default)
`non_sticky`	Punishment only applies to specified identifiers

Callback Response

The callback function receives three parameters:

function(success, punishmentId, error)

Parameter	Type	Description
`success`	boolean	`true` if punishment was created successfully
`punishmentId`	number	The ID of the created punishment (only if successful)
`error`	string	Error message (only if failed)

Success Response Example

-- success = true, punishmentId = 12345, error = nil

Error Response Example

-- success = false, punishmentId = nil, error = "Player not found in active players"

Usage Examples

Basic Permanent Ban

exports['monoadmin']:CreatePunishment({
    source = playerSource,
    punishment_type = 'ban',
    reason = 'Cheating detected by anti-cheat',
    kick_if_online = true
}, function(success, punishmentId, error)
    if success then
        print('Player banned with ID: ' .. punishmentId)
    else
        print('Failed to ban player: ' .. error)
    end
end)

Temporary Ban (24 Hours)

exports['monoadmin']:CreatePunishment({
    source = playerSource,
    punishment_type = 'ban',
    reason = 'Toxic behavior - 24 hour ban',
    duration_minutes = 1440, -- 24 hours
    kick_if_online = true
})

Issue a Warning

exports['monoadmin']:CreatePunishment({
    source = playerSource,
    punishment_type = 'warn',
    reason = 'First offense - breaking server rules'
})

Kick Player

exports['monoadmin']:CreatePunishment({
    source = playerSource,
    punishment_type = 'kick',
    reason = 'AFK for too long'
})

Assign Community Service

exports['monoadmin']:CreatePunishment({
    source = playerSource,
    punishment_type = 'community_service',
    reason = 'Minor rule violation - 10 hours community service',
    community_service_total = 10
})

Complete Example with Error Handling

local function punishPlayer(source, punishmentType, reason, durationMinutes)
    -- Validate inputs
    if not source or source <= 0 then
        print('[MyResource] Invalid player source')
        return false
    end

    -- Check if MonoAdmin is available
    if not exports['monoadmin']:IsConnected() then
        print('[MyResource] MonoAdmin is not connected to cloud')
        return false
    end

    -- Create punishment
    local success = exports['monoadmin']:CreatePunishment({
        source = source,
        punishment_type = punishmentType,
        reason = reason,
        duration_minutes = durationMinutes,
        kick_if_online = punishmentType == 'ban'
    }, function(success, punishmentId, error)
        if success then
            print(('[MyResource] Punishment created: %s (ID: %d)'):format(punishmentType, punishmentId))
            -- Optionally log to Discord, database, etc.
        else
            print(('[MyResource] Failed to create punishment: %s'):format(error))
            -- Handle error (retry, notify admin, etc.)
        end
    end)

    return success
end

-- Usage
punishPlayer(source, 'ban', 'Cheating detected', nil) -- Permanent ban
punishPlayer(source, 'warn', 'Breaking rules', nil) -- Issue warning

Error Handling

Common Errors

Error	Cause	Solution
`Missing required field: source`	`source` not provided	Ensure player source is passed
`Missing required field: punishment_type`	`punishment_type` not provided	Specify a valid punishment type
`Missing required field: reason`	`reason` not provided or empty	Provide a reason string
`Invalid punishment_type`	Unknown punishment type	Use one of the valid types listed above
`Not connected to MonoAdmin cloud`	MonoAdmin not connected	Wait for connection or check config
`Player not found in active players`	Player not tracked	Player must be online and tracked by MonoAdmin
`Player does not have a player_id`	Player ID not assigned	Player needs to be fully registered
`community_service_total is required`	Missing hours for CS	Provide `community_service_total` for community_service type

Best Practices

Always provide a callback to handle success/failure scenarios
Check connection status with exports['monoadmin']:IsConnected() before calling
Validate player source before attempting to create a punishment
Log failures for debugging and audit purposes
Handle async nature — the export returns immediately, callback fires later

Notes & Limitations

Player Must Be Online: The target player must be currently online and tracked by MonoAdmin. You cannot punish offline players via this export.
Async Operation: CreatePunishment returns true immediately if the request was sent successfully. The actual result comes through the callback.
Audit Logging: All punishments created via this export are logged with:
- actor_type = 'fivem_server'
- issued_by = NULL (system-issued)
- created_via = 'developer_export'
Dashboard Visibility: Punishments appear in the MonoAdmin dashboard immediately after creation, showing “System” as the issuer.

Other Exports

MonoAdmin provides additional exports for various purposes:

Export	Description
`IsConnected()`	Check if connected to MonoAdmin cloud
`GetProjectInfo()`	Get current project information
`HasPermission(roleId, slug)`	Check if a role has a permission
`IsPlayerBanned(identifiers)`	Check if identifiers match a ban
`GetPunishmentStatus(identifiers)`	Get full punishment status for identifiers
`UpdateCommunityService(serverId, amount)`	Update community service progress