Developer reference

Use config/contextMenus.lua to configure weapons, animations, and a registry-based context menu system that lets you add your own actions and providers without editing client code. The menu is powered by a lightweight registry available at runtime via GM.ContextMenu:

Actions: registerAction(id, handler) maps a menu id to a function.
Prefix actions: registerActionPrefix(prefix, handler) handles any id starting with the prefix.
Providers: register(providerFn) returns a list of items for the current click context (ground, ped, vehicle, selection).
Default items: Always-visible items can be added statically with Config.ContextMenuDefaultItems, or dynamically at runtime.

Handlers receive (data, meta). meta.actionId is the clicked id; meta.context mirrors build-time context and can include ground, selectionCount, targetPed, targetVehicle.

Example: register actions and a provider

config/contextMenus.lua

-- Wait until the context menu registry is ready
CreateThread(function()
  while not (GM and GM.ContextMenu and GM.ContextMenu.registerAction) do
    Wait(50)
  end
  local CM = GM.ContextMenu

  -- Stop all selected peds (no extra data required)
  CM.registerAction('example_stop_selected', function(_, _)
    if not (GM and GM.State and GM.State.selection) then return end
    for _, ent in ipairs(GM.State.selection) do
      if DoesEntityExist(ent) and IsEntityAPed(ent) then
        if ClearPedTasks then ClearPedTasks(ent) end
        if TaskStandStill then TaskStandStill(ent, -1) end
      end
    end
  end)

  -- Move selection to your last right-clicked ground position
  CM.registerAction('example_goto_last_click', function(_, meta)
    local ctx = meta and meta.context
    if ctx and ctx.ground and GM and GM.Commands then
      GM.Commands.goToDirect(ctx.ground)
    end
  end)

  -- Provider: show a hello action when hovering a ped
  CM.register(function(ctx)
    local items = {}
    if ctx and ctx.targetPed and IsEntityAPed(ctx.targetPed) then
      items[#items + 1] = { id = 'example_stop_selected', label = 'Stop Selected', data = {} }
    end
    return items
  end)
end)

Hello world: your first custom action and provider

This is the smallest end-to-end example. It registers a new action that prints a message using Bridge.Debug, and a provider that shows the item when you right-click on a ped.

config/contextMenus.lua

-- 1) Register the action (what happens when clicked)
CreateThread(function()
  while not (GM and GM.ContextMenu and GM.ContextMenu.registerAction) do Wait(50) end
  local CM = GM.ContextMenu

  CM.registerAction('example_hello_world', function(data, _)
    local msg = (data and data.message) or 'Hello from Context Menu!'
    if Bridge and Bridge.Debug then
      Bridge.Debug('[GM] ' .. tostring(msg))
    end
  end)

  -- 2) Provide the item (when and where it appears)
  CM.register(function(ctx)
    local items = {}
    if ctx and ctx.targetPed and IsEntityAPed(ctx.targetPed) then
      items[#items + 1] = {
        id = 'example_hello_world',
        label = 'Hello World',
        data = { message = 'Howdy!' }
      }
    end
    return items
  end)
end)

If you want your hello world to always be visible, add it as a default item instead:

config/contextMenus.lua

Config.ContextMenuDefaultItems = {
  { id = 'example_hello_world', label = 'Hello World', data = { message = 'Always visible' } },
}

Providers explained for beginners

Think of a provider as a menu generator. It runs each time you open the menu and returns a list of items that make sense for the current situation.
The ctx (context) tells you what the player pointed at:
- ctx.ground: where the right-click happened (a vector3)
- ctx.selectionCount: how many entities are currently selected
- ctx.targetPed: the ped under the cursor, if any
- ctx.targetVehicle: the vehicle under the cursor, if any
Return an array of items shaped like { id, label, data?, children? }:
- id: must match a registered action or a built-in one
- label: the text players see
- data: optional parameters passed to the handler
- children: optional array for submenus

Start simple. Add one item, confirm it appears in the right place, then enhance the logic or add submenus.

Default items: static and dynamic

Static via config: set once, shown at the bottom of every context menu.

config/contextMenus.lua

Config.ContextMenuDefaultItems = {
  { id = 'example_goto_last_click', label = 'Go To Last Click', data = {} },
}

Dynamic via API or events: add or replace at runtime from any client script.

-- Using the registry directly (once CM is ready)
GM.ContextMenu.addDefaultItems({
  { id = 'example_stop_selected', label = 'Stop Selected', data = {} },
})

-- Or with events (does not require direct access to the registry)
TriggerEvent('gm:context_menu:add_default_items', {
  { id = 'example_goto_last_click', label = 'Go To Last Click', data = {} }
})
TriggerEvent('gm:context_menu:set_default_items', {
  { id = 'example_stop_selected', label = 'Stop Selected', data = {} }
})

Default items must reference action IDs that are either built-in or registered by you. Avoid actions that require a specific data.target (for example ped_kill) because defaults do not automatically provide one. Prefer actions that operate on your selection or use meta.context.ground.

Example: add quick orders to known locations

You can also mix built-in action IDs for convenience shortcuts. This example adds two global entries that use only a fixed coordinate and your current selection:

config/contextMenus.lua

Config.ContextMenuDefaultItems = {
  { id = 'goto_direct', label = 'Go to Town Square', data = { coord = vector3(-180.12, 627.84, 114.09) } },
  { id = 'attack_area', label = 'Attack in Arena', data = { coord = vector3(-279.55, 699.10, 113.50) } },
}

When you right-click anywhere, these entries appear. If you have peds selected, they will either walk directly to the first coordinate or engage enemies within an area around the second.

Use game/admin tools to capture coordinates and paste them into vector3(x, y, z).

Built-in action IDs you can reuse

Movement: goto_direct, goto_path, goto_stand (require data.coord)
Combat: attack_area (requires data.coord)

Other IDs like attack, ped_remove_weapon, ped_revive, ped_toggle_god, ped_toggle_freeze, vehicle_unmount_all, vehicle_destroy, ped_enter_vehicle, ped_play_anim_*, and ped_give_weapon_named_* require a specific data.target (and sometimes more), which defaults cannot supply. Keep those for contextual menus provided by the script.

Weapons submenu

Add or remove weapons available under “Give Weapon…”. Each entry looks like:

config/contextMenus.lua

{ id = 'pistol_m1899', label = 'Pistol M1899', weapon = 'WEAPON_PISTOL_M1899' }

Use canonical RedM weapon names for the weapon field so the game can grant them properly.

Animations submenu

Control which animations appear under “Animations…”. Each entry looks like:

config/contextMenus.lua

{ id = 'gentletip', label = 'Gentle Tip', dict = 'mech_loco_m@character@dutch@fancy@unarmed@idle@_variations', name = 'idle_b',
  blendInSpeed = 1.0, blendOutSpeed = -1.0, duration = 2500, flag = 31, playbackRate = 0.0 }

Flags correspond to eScriptedAnimFlags (for example: 1 = loop, 2 = hold last frame, 16 = upper body). Duration -1 means use the animation’s natural length.

Gamemaster

Stockmarket

Horse manager

Ambient ped manager

Weapon controller

Background select

MapMarker

Prop placer

Registry-based menu system

Example: register actions and a provider

Hello world: your first custom action and provider

Providers explained for beginners

Default items: static and dynamic

Example: add quick orders to known locations

Built-in action IDs you can reuse

Weapons submenu

Animations submenu

​Registry-based menu system

​Example: register actions and a provider

​Hello world: your first custom action and provider

​Providers explained for beginners

​Default items: static and dynamic

​Example: add quick orders to known locations

​Built-in action IDs you can reuse

​Weapons submenu

​Animations submenu

Registry-based menu system

Example: register actions and a provider

Hello world: your first custom action and provider

Providers explained for beginners

Default items: static and dynamic

Example: add quick orders to known locations

Built-in action IDs you can reuse

Weapons submenu

Animations submenu