red-valley/resources/luxu_admin/config/custom_functions/AGENTS.md

AGENTS.md - Custom Functions

Practical guidance for contributors and AI agents working in config/custom_functions/.

This folder is the supported extension point for Luxu Admin. Use it to add custom addon buttons, quick actions, quick toggles, statistic blocks, and map zone handlers without editing core modules.

Folder Purpose

Files in this directory:

• client.lua: client-side registrations and handlers (addons, statistics declaration, zone handlers)
• server.lua: server-side callbacks (addon buttons + statistic block providers)
• types.lua: type definitions and signatures (Addon, Zone, ZoneHandlerReturn, registration APIs)

Runtime loading:

• client.lua is loaded from client/cl_main.lua
• server.lua is loaded from server/sv_main.lua
• types.lua is for editor type hints and as reference for expected shapes

Event Flow

Base flow:

UI -> NUI callback -> client handler -> server callback (optional)

Common routes:

• Addon button:
  • custom_functions:button:{name} on client
  • optional callServer(...) to custom_functions:callback:{name} on server
• Quick action:
  • custom_functions:quick_action:{name} on client (client-only by built-in API)
• Quick toggle:
  • custom_functions:quick_toggle:{name} on client (client-only by built-in API)
• Statistic blocks:
  • custom_functions:statistic_blocks:get fetches all registered server block callbacks

Registration API

Function	File	Use
RegisterAddons()	client.lua	Register buttons, quick actions, quick toggles
RegisterAddonStatisticBlocks()	client.lua	Declare statistic block keys
RegisterAddonCallback()	server.lua	Handle server logic for addon buttons
RegisterAddonStatisticBlocksCallback()	server.lua	Return data for statistic blocks
RegisterZoneHandler()	client.lua	Register map zone behavior

Addon Types

Definitions come from types.lua.

1) Button (Player Management)

Use when action targets a selected player and may require server authority.

• set type = "button" in RegisterAddons(...)
• handler signature: function(target, callServer)
• target is selected player server ID
• if using callServer(...), register RegisterAddonCallback(name, callback, permission?) on server

2) Quick Action (Quick Menu Main tab)

Use for fast client-side actions with optional option selection.

• built-in path is client-only
• handler signature: function(target, option)
• option is selected option key or nil

3) Quick Toggle (Quick Menu Toggles tab)

Use for toggled states (god mode, speed mode, noclip state, etc).

• built-in path is client-only
• handler signature: function(option)
• must return a boolean representing new state

4) Statistic Blocks (Statistics page)

Use for custom server-backed metrics.

• client declaration:
  • RegisterAddonStatisticBlocks({ "block_a", "block_b" })
• server provider:
  • RegisterAddonStatisticBlocksCallback("block_a", function(source) ... end)
• expected return:
  • { title, description, value, formatToCash? }
  • value can be string or number

5) Zone Handler (Admin map zones)

Use for custom behavior when entering/exiting/remaining inside a configured zone.

• register in client:
  • RegisterZoneHandler("handler_name", function() return { onEnter, onExit, inside } end)
• zones reference the handler via customHandler value
• zone shape reference: see Zone in types.lua

Security Requirements (Critical)

Treat every client-triggered path as untrusted.

1. Validate everything server-side:
   • source, target, option values, ranges, and expected types
2. Use permissions:
   • set addon permission and enforce matching permission in RegisterAddonCallback(...)
3. Enforce duty/admin state:
   • check IsOnDuty(source) (or your project equivalent) before privileged actions
4. Deny by default:
   • reject unknown options and invalid targets early
5. Audit sensitive actions:
   • log who executed what and on whom

Performance Requirements

FiveM servers are sensitive under player load. Keep custom code lightweight.

• do not run heavy work in per-frame inside handlers
• cache expensive statistic computations when possible
• avoid large synchronous loops over all players each click/tick
• for large payloads between client/server, prefer latent events
• fail fast on invalid input to avoid unnecessary work

Naming and Style Conventions

• use snake_case for addon/block/handler names
• names are case-sensitive and must match between client/server registration
• use hex colors like "#22c55e"
• icon examples:
  • MDI: "mdi:heart-pulse"
  • Material icon theme: "material-icon-theme:icon-name"

Reference: https://pictogrammers.com/library/mdi/

Quick Implementation Recipes

Add button with server authority

1. In client.lua, add addon with type = "button" and call callServer(...) in handler.
2. In server.lua, register RegisterAddonCallback("same_name", function(source, target, ...) ... end, "optional.permission").
3. Validate inputs and enforce permission/duty before executing action.

Add quick action

1. In client.lua, add addon with type = "quick_action".
2. Add optional options and implement handler(target, option).
3. Keep behavior client-safe; do not trust this path for privileged logic.

Add quick toggle

1. In client.lua, add addon with type = "quick_toggle".
2. Implement handler(option) and return new boolean toggle state.
3. Keep state transitions explicit and deterministic.

Add statistic block

1. In client.lua, include block key in RegisterAddonStatisticBlocks({ ... }).
2. In server.lua, implement RegisterAddonStatisticBlocksCallback("same_key", function(source) return {...} end).
3. Keep callback fast; cache where possible.

Add zone behavior

1. In client.lua, register RegisterZoneHandler("handler_name", function() return { onEnter, onExit, inside } end).
2. In admin map zone config, set customHandler to "handler_name".
3. Keep inside callback minimal to prevent frame drops.

Pre-merge Checklist

• Names match exactly between UI/client/server registrations
• Required server callbacks exist for every callServer(...) path
• Permission and duty checks are in place for privileged actions
• Invalid input paths are handled safely
• High-frequency handlers (inside) are lightweight