Custom Functionality API

This document describes the supported custom-function APIs used to extend user-facing behavior in Luxu Admin.

Scope

These APIs are loaded from:

• config/custom_functions/client.lua
• config/custom_functions/server.lua

API Overview

1) RegisterAddons (Client)

Registers custom addons in bulk.

RegisterAddons(data)

data is an array of addon objects.

Addon object shape:

{
  type = "button" | "quick_action" | "quick_toggle",
  name = "unique_name",
  label = "Display Label",
  icon = "mdi:icon-name" | "material-icon-theme:icon-name",
  color = "#RRGGBB",
  options = { "option_1", "option_2" }, -- optional (quick_action / quick_toggle)
  permission = "permission.name", -- optional
  handler = function(...) end
}

Handler signatures:

• button: handler(target, callServer)
• quick_action: handler(target, option)
• quick_toggle: handler(option) and must return a boolean state

2) RegisterAddonCallback (Server)

Registers server callback logic for addon buttons.

RegisterAddonCallback(name, callback, permission)

• name: must match button name
• callback: server function called by callServer(...)
• permission (optional): server-side permission gate

Callback signature:

function(source, target, ...)
  -- source: admin/staff source id
  -- target: selected player source id
  -- ...: extra args passed from callServer(...)
  return true or false
end

3) RegisterAddonStatisticBlocks (Client)

Registers custom statistics block keys shown in the stats page.

RegisterAddonStatisticBlocks({ "block_1", "block_2" })

4) RegisterAddonStatisticBlocksCallback (Server)

Provides server-side values for each registered stats block.

RegisterAddonStatisticBlocksCallback(name, callback)

Callback signature:

function(source)
  return {
    title = "Title",
    description = "Description",
    value = 123, -- string or number
    formatToCash = false -- optional, boolean
  }
end

5) RegisterZoneHandler (Client)

Registers client-side handlers for custom admin map zones.

RegisterZoneHandler(name, handler)

Handler returns:

function()
  return {
    onEnter = function(zone) end,
    onExit = function(zone) end,
    inside = function(zone) end
  }
end

Minimal End-to-End Example

Client (custom_functions/client.lua)

RegisterAddons({
  {
    type = "button",
    name = "warn_selected_player",
    label = "Warn",
    icon = "mdi:alert",
    color = "#f59e0b",
    permission = "player.warn",
    handler = function(target, callServer)
      local reason = "Custom warning"
      local ok = callServer(reason)
      print("Warn result:", ok)
    end,
  },
})

RegisterAddonStatisticBlocks({ "online_staff_count" })

Server (custom_functions/server.lua)

RegisterAddonCallback("warn_selected_player", function(source, target, reason)
  if not source or not target or type(reason) ~= "string" or reason == "" then
    return false
  end

  -- Your secure server-side logic
  return true
end, "player.warn")

RegisterAddonStatisticBlocksCallback("online_staff_count", function(source)
  return {
    title = "Staff Online",
    description = "Current on-duty staff",
    value = 5,
    formatToCash = false,
  }
end)

Security Requirements

• Never trust client input.
• Validate source, target, and all arguments on the server.
• Use permission checks (permission parameter) for privileged actions.
• Keep critical logic server-side.
• Log sensitive operations.

Notes

• Addon/statistic names are case-sensitive and must match exactly between client and server registration.
• Keep heavy logic out of zone inside handlers to avoid client performance issues.