Hooks and server actions

Goal: plug your own code where no preset fits, and create server-checked actions. Files: config_client.lua (Config.ClientHooks) and config_server.lua (Config.ServerHooks, Config.ServerActions).

How hooks work

A defined hook replaces the matching preset: the bridge calls your function and no longer runs the preset code. Leave a hook nil (undefined) to keep the preset chosen in config.lua. Server hooks are called after the engine checks: no need to re-check the permission of the action that triggers them.

Some hooks also change an option’s availability: defining SendBill, GiveVehicleKeys or RestoreAppearance makes the matching option available even with the selector set to 'custom'.

Notable exception: with Config.Medical.nativeHealFallback = true, the extra native heal applies after your HealSelf or HealPlayer hook.

Client hooks

Server hooks

Example: custom notifications

my_notify is an example resource name.

Config.ClientHooks.Notify = function(message, ntype, duration)
    exports['my_notify']:Show(message, ntype, duration)
end

Config.ServerHooks.Notify = function(source, message, ntype, duration)
    TriggerClientEvent('my_notify:show', source, message, ntype, duration)
end

Client routines

The server can run a whitelisted client routine: TriggerClientEvent('ox_target:core:run', id, '<Routine>', ...). Routines documented by the archive: PlayEmote(emote), Me(text), ReviveSelf(), HealSelf(), NativeRevive(), NativeHeal(). They go through the bridge, hence through your client hooks. PlayEmote re-validates the name with Config.Emotes; Me truncates to 120 characters.

Config.ServerHooks.RevivePlayer = function(source, targetId)
    TriggerClientEvent('ox_target:core:run', targetId, 'NativeRevive')
end

Custom server actions

An action declared in Config.ServerActions is called by a type = 'server_action' option. The engine runs its checks, then your handler(ctx).

Built-in action names (admin_revive, weather_set…) cannot be reused.

Argument rules

Every rule accepts optional = true. A missing non-optional or invalid argument makes the request refused (invalid_input) and reports it as suspicious.

ctx object

Full example

Server side (config_server.lua); my_script:showLicense is an example name:

Config.ServerActions = {
    check_license = {
        permission  = 'everyone',
        jobs        = { 'police' },
        target      = 'player',
        maxDistance = 3.0,
        cooldown    = 2000,
        args        = { { type = 'string', oneOf = { quick = true, full = true } } },
        handler     = function(ctx)
            TriggerClientEvent('my_script:showLicense', ctx.target, ctx.source, ctx.args[1])
            ctx.notify('Request sent.', 'success')
        end,
    },
}

Client side (config_interactions.lua):

{ name = 'check_license', label = 'Check papers', icon = 'fa-solid fa-id-card', jobs = { 'police' }, type = 'server_action', action = 'check_license', args = { 'quick' } },

The client sends the target’s server ID for the Players and Self lists, and the entity network ID for the other lists. Choose target accordingly.

Logging

Config.ServerHooks.OnActionExecuted = function(source, actionName, ctx)
    print(('[ox_target] %s used %s'):format(GetPlayerName(source), actionName))
end

Other resources can register actions with exports.ox_target:registerAction.

Common mistakes

• Action without permission: allowed to everyone, rarely what you want for a sensitive action.
• target = 'player' on a vehicle option: the request sends a network ID, refused as a nonexistent player target.
• Empty hook function() end: the preset is replaced by a function that does nothing.
• Handler that changes money or inventory without re-checking amounts: the engine validates the declared types and bounds, not the business logic.