Skip to content
Retro Docs

Retro Radial

Modes

Section titled “Modes”

rs_radial operates in a few practical workflow modes. These are usage modes, not separate resources.

Static-Config Mode

Section titled “Static-Config Mode”

This is the default mode for servers that define everything in config.lua.

Typical behavior:

  • All items live in Config.Pages.
  • Job / gang / cuffed / dead gating is declared per-item.
  • No third-party resource needs to call rs_radial’s API.
  • Items are stable across the server lifetime.

Use this mode when you control all the radial content yourself.

Runtime-API Mode

Section titled “Runtime-API Mode”

In this mode, other resources add their own items to rs_radial at runtime.

Typical behavior:

  • Server-owned items are added via exports['rs_radial']:AddMenuItem(pageId, item).
  • New pages are registered via exports['rs_radial']:AddSubMenu(pageId, def).
  • Per-player items are added via the server-side AddMenuItemForPlayer(src, ...) export.
  • rs_radial sweeps items belonging to a resource when that resource stops, so reloads stay clean.

Use this mode when you want job/feature scripts (e.g. qbx_garages, custom job resources) to contribute their own radial entries without editing config.lua.

ox_lib Bridge Mode

Section titled “ox_lib Bridge Mode”

In this mode, rs_radial impersonates ox_lib’s radial API so third-party scripts that target lib.addRadialItem work without changes.

Typical behavior:

  • Config.OxLibBridge.enabled = true.
  • bridge/ox_lib.lua patches the global lib table.
  • Third-party calls to lib.addRadialItem, lib.removeRadialItem, lib.registerRadial, lib.hideRadial, lib.getCurrentRadialId are forwarded into rs_radial.
  • If real ox_lib is installed, only the radial functions are patched notifications and other ox_lib features still work normally.

Use this mode when migrating from ox_lib’s radial or running scripts written for it.

Server-Authoritative Mode

Section titled “Server-Authoritative Mode”

This is the mode for servers that care about anti-cheat / event protection.

Typical behavior:

  • Config.Security.serverSideValidation = true.
  • Every type='server' item is routed through rs_radial:server:dispatch.
  • The server re-runs all visibility checks (job, gang, cuffed, dead, cooldown, predicates, reqItems) before firing the configured event.
  • Server starts the cooldown clock after successful dispatch clients can’t tamper with it.
  • RegisterServerItem(pageId, itemId, validator/handler) lets you bind extra server-side rules per item.

Use this mode for any server with cheaters or where item misuse has real consequences.

Per-Player Customization Mode

Section titled “Per-Player Customization Mode”

This is the per-player experience that ships on by default.

Typical behavior:

  • Player opens Settings (gear icon).
  • Live preview as they pick theme colors, scale, position, sounds, vehicle bar colors.
  • Save persists to KVP per-player; Discard reverts to the previous saved state.
  • Reset Defaults clears everything back to Config.Theme.default etc.
  • Server admins can lock any toggle from Config.Settings.

Use this mode out of the box it’s enabled by default and requires no server-side wiring.

Vehicle Control Mode

Section titled “Vehicle Control Mode”

This is the in-vehicle interaction surface.

Typical behavior:

  • Driver presses the configured key while in a vehicle.
  • The Vehicle Control bar appears at the configured position.
  • Buttons control doors, windows, engine, neon, seat swap, etc.
  • Driver-only by default passengers see a read-only preview of the bar in driver-lock state.
  • State changes (door open, neon color) are synced to all vehicle occupants via state bags.

Use this mode when you want vehicle controls outside the radial flow.

Async Action Mode

Section titled “Async Action Mode”

This is for items that take time to resolve server-side.

Typical behavior:

  • Item is declared with async = true.
  • Click shows a spinner on the item.
  • Server-side handler does the work and calls exports['rs_radial']:CompleteAsyncAction(itemId, ok, errorMessage) when done.
  • On ok=false, the error message is shown briefly in the radial center label.
  • On ok=true, the spinner clears and the cooldown (if any) starts.

Use this mode for actions that hit a database, external API, or have a long-running side effect.