> ## Documentation Index
> Fetch the complete documentation index at: https://rsg.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ❗ Commands

> Complete guide to creating and using commands in RSG Framework

## Introduction

RSG Framework provides a robust command system that allows you to create custom commands with permission levels, argument validation, and suggestions. Commands can be restricted to specific permission groups like admin, mod, or user.

**Location**: `resources/[framework]/rsg-core/server/commands.lua`

<Info>
  Commands are automatically registered with FiveM's native suggestion system, showing available commands and their arguments based on player permissions.
</Info>

***

## Core Features

### 🔐 Permission-based Access

* **User**: Available to all players
* **Mod**: Moderator-only commands
* **Admin**: Administrator commands
* **God**: Super admin commands

### 📝 Argument Handling

* **Required/Optional**: Control if arguments are mandatory
* **Help Text**: Descriptions shown in suggestions
* **Type Validation**: Validate argument types in callbacks

### ⚡ Auto-completion

* **Dynamic Suggestions**: Commands show based on permissions
* **Argument Hints**: Display help text for each argument
* **Refresh System**: Update suggestions when permissions change

***

## Creating Commands

### RSGCore.Commands.Add

This function allows you to register a command with a specified user level

```lua theme={null}
RSGCore.Commands.Add(name, help, arguments, argsrequired, callback, permission, ...)
```

* name: `string`

* help: `string`

* arguments: `table`

* argsrequired: `boolean`

* callback: `function`

* permission: `string`

Example:

```lua theme={null}
local arguments = {
    { name = 'arg 1', help = 'This will give helpful hints on what arg is for' },
    { name = 'arg 2', help = 'This will give helpful hints on what arg is for' }
}

local argsRequired = true -- if this is true the command won't work without args entered

RSGCore.Commands.Add('test', 'Trigger a test command', arguments, argsRequired, function(source)
    print('Congrats, you made a test command that anyone can trigger!')
end, 'user')
```

## RSGCore.Commands.Refresh

This function will trigger a refresh of all commands suggestions. This is helpful for when setting permissions to a higher level, it will refresh the suggestions list so the player can now see the new commands they have access to!

```lua theme={null}
RSGCore.Commands.Refresh(source)
```

* source: `number`

Example:

```lua theme={null}
RegisterCommand('refreshCommands', function()
    RSGCore.Commands.Refresh(source)
    print('You have refreshed all command suggestions for yourself')
end, true)
```

***

## Practical Examples

### Example 1: Basic User Command

```lua theme={null}
-- Simple command any player can use
RSGCore.Commands.Add('mycoords', 'Get your current coordinates', {}, false, function(source)
    local src = source
    local ped = GetPlayerPed(src)
    local coords = GetEntityCoords(ped)

    TriggerClientEvent('ox_lib:notify', src, {
        title = 'Coordinates',
        description = string.format('X: %.2f Y: %.2f Z: %.2f', coords.x, coords.y, coords.z),
        type = 'inform'
    })
end, 'user')
```

### Example 2: Admin Command with Arguments

```lua theme={null}
-- Give item to player
local arguments = {
    { name = 'id', help = 'Player ID to give item to' },
    { name = 'item', help = 'Item name from shared/items.lua' },
    { name = 'amount', help = 'Amount to give (default: 1)' }
}

RSGCore.Commands.Add('giveitem', 'Give an item to a player', arguments, true, function(source, args)
    local targetId = tonumber(args[1])
    local itemName = args[2]
    local amount = tonumber(args[3]) or 1

    local Player = RSGCore.Functions.GetPlayer(targetId)
    if not Player then
        TriggerClientEvent('ox_lib:notify', source, {
            description = 'Player not found',
            type = 'error'
        })
        return
    end

    if exports['rsg-inventory']:AddItem(targetId, itemName, amount) then
        TriggerClientEvent('ox_lib:notify', source, {
            description = 'Gave '.. amount ..'x '.. itemName ..' to player '.. targetId,
            type = 'success'
        })
    end
end, 'admin')
```

### Example 3: Command with Optional Arguments

```lua theme={null}
-- Heal command - heal yourself or another player
local arguments = {
    { name = 'id', help = 'Player ID (optional, heals yourself if empty)' }
}

RSGCore.Commands.Add('heal', 'Heal yourself or another player', arguments, false, function(source, args)
    local targetId = tonumber(args[1]) or source
    local targetPed = GetPlayerPed(targetId)

    if not targetPed or targetPed == 0 then
        TriggerClientEvent('ox_lib:notify', source, {
            description = 'Invalid player',
            type = 'error'
        })
        return
    end

    -- Heal the player
    local Player = RSGCore.Functions.GetPlayer(targetId)
    if Player then
        Player.Functions.SetMetaData('isdead', false)
        Player.Functions.SetMetaData('hunger', 100)
        Player.Functions.SetMetaData('thirst', 100)

        TriggerClientEvent('rsg-player:client:heal', targetId)

        TriggerClientEvent('ox_lib:notify', source, {
            description = targetId == source and 'You have been healed' or 'Player '.. targetId ..' has been healed',
            type = 'success'
        })
    end
end, 'admin')
```

***

## Built-in Commands

## AdminMenu

<AccordionGroup>
  <Accordion title="/tp [id / x ] [opt: y] [opt: z]- teleport to player or location" defaultOpen={false}>
    Teleports you to either a player with the given `id` or to a given `x, y, z` location

    **Permission level:** admin

    * **id or x** - (required) The player id or x coordinate

    * **y** - (optional) The y coordinate (required if using x for the first argument)

    * **z** - (optional) The z coordinate (required if using x for the first argument)
  </Accordion>

  <Accordion title="/tpm - teleport to a marked location" defaultOpen={false}>
    Teleports you to the marked location on the map.

    **Permission level:** admin
  </Accordion>

  <Accordion title="/noclip - toggle noclip on/off" defaultOpen={false}>
    Allows you to fly around the map.

    **Permission level:** admin
  </Accordion>

  <Accordion title="/togglepvp - toggle PVP on server" defaultOpen={false}>
    Toggles Player vs Player mode on the server

    **Permission level:** admin
  </Accordion>

  <Accordion title="/addpermission [id] [permission] - gives a player permission" defaultOpen={false}>
    Toggles Player vs Player mode on the server

    **Permission level:** admin
  </Accordion>

  <Accordion title="/removepermission [id] [permission] - removes a player permission" defaultOpen={false}>
    Removes the given `permission` from the player with the given `id`. The player must be online.

    **Permission level:** god
  </Accordion>

  <Accordion title="/openserver - open server for everyone" defaultOpen={false}>
    Opens the server allowing everyone to join.

    **Permission level:** admin
  </Accordion>

  <Accordion title="/closeserver - close the server for people without permission" defaultOpen={false}>
    Closes the server for people without the correct permission. Kicks any players currently online without the required permission giving the `reason` in the kick message.

    **Permission level:** admin
  </Accordion>

  <Accordion title="/wagon [mode] - spawns a wagon" defaultOpen={false}>
    Spawns a wagon of the given `model` type.

    **Permission level:** admin
  </Accordion>

  <Accordion title="/horse [model] - spawns a horse" defaultOpen={false}>
    Spawns a wagon of the given `model` type.

    **Permission level:** admin
  </Accordion>

  <Accordion title="/dv - delete vehicle" defaultOpen={false}>
    Deletes the vehicle you are sitting in or deletes all vehicles within 5.0 units of your position.

    **Permission level:** admin
  </Accordion>

  <Accordion title="/givemoney [id] [type] [amount] - give money to the player" defaultOpen={false}>
    Gives money to a player

    **Permission level:** admin

    * **id** - (required) The `id` of the player

    * **type** - (required) The money type \[cash, bank etc...]

    * **amount** - (required) The amount to give
  </Accordion>

  <Accordion title="/setmoney [id] [type] [amount] - set the amount a player has" defaultOpen={false}>
    Sets the amount of money a player has.

    **Permission level:** admin

    * **id** - (required) The `id` of the player

    * **type** - (required) The money type \[cash, bank etc...]

    * **amount** - (required) The amount to set
  </Accordion>

  <Accordion title="/job - display your current job" defaultOpen={false}>
    Displays your current job name and grade

    **Permission level:** user
  </Accordion>

  <Accordion title="/setjob [id] [job] [grade] - sets a players job" defaultOpen={false}>
    Displays your current job name and grade

    **Permission level:** user
  </Accordion>

  <Accordion title="/gang - display your current gang" defaultOpen={false}>
    Displays your current gang name and grade

    **Permission level:** user
  </Accordion>

  <Accordion title="/setgang [id] [gang] [grade] - sets a players gang" defaultOpen={false}>
    Sets a player with the given `id` to be part of the given `gang` with the given `grade`

    **Permission level:** admin

    * **id** - (required) The `id` of the player

    * **gang** - (required) The gang name

    * **grade** (required) The gang grade
  </Accordion>

  <Accordion title="/clearinv [opt: id] - clears a players inventory" defaultOpen={false}>
    Sets a player with the given `id` to be part of the given `gang` with the given `grade`

    **Permission level:** admin

    * **id** - (required) The `id` of the player

    * **gang** - (required) The gang name

    * **grade** (required) The gang grade
  </Accordion>

  <Accordion title="/giveitem [id] [item] [amount] - gives a player items" defaultOpen={false}>
    Give An Item to player

    **Permission level:** admin

    * **id** - The id of a player

    * **item** - The itenm of shared/items.lua

    * **amount** - (optional) The amount item receive of a player
  </Accordion>

  <Accordion title="/randomitems - give random items to players inventory" defaultOpen={false}>
    Give Random Items

    **Permission level:** god
  </Accordion>

  <Accordion title="/resetinv [type] [id] -reset inventory" defaultOpen={false}>
    Reset the inventory of type and id/plate (ID of stash or license plate)

    * **type** - The type of stash / trunk / glovebox

    * **id** - The id of stash or license plate

    **Permission level:** admin
  </Accordion>

  <Accordion title="/id - notify of your server ID" defaultOpen={false}>
    Notify you of your server ID

    **Permission level:** user
  </Accordion>

  <Accordion title="/cid - notify you of your Citizen ID" defaultOpen={false}>
    Notify you of your citizen ID

    **Permission level:** user
  </Accordion>

  <Accordion title="/rob - rob a player" defaultOpen={false}>
    Stealing between players, when the target has his hands raised

    **Permission level:** user
  </Accordion>

  <Accordion title="/loadskin - Refresh Skin" defaultOpen={false}>
    Refresh Skin player

    **Permission level:** user
  </Accordion>

  <Accordion title="/customweapon - custom weapon skin" defaultOpen={false}>
    Access to the menu of components, materials and engravings

    **Permission level:** admin
  </Accordion>

  <Accordion title="/w_inspect - inspect a weapon" defaultOpen={false}>
    Access to the info of weapon

    **Permission level:** admin
  </Accordion>

  <Accordion title="/loadweapon - Refresh skin weapon player" defaultOpen={false}>
    Refresh Skin wepaon player

    **Permission level:** user
  </Accordion>

  <Accordion title="/addressbook - Player addressbook" defaultOpen={false}>
    Opens Address book for player

    **Permission level:** user
  </Accordion>
</AccordionGroup>

***

## Best Practices

<Tip>
  **Use Clear Names**: Command names should be short but descriptive

  * Good: `giveitem`, `setjob`, `tpm`
  * Bad: `gi`, `sj`, `thing`
</Tip>

<Warning>
  **Always Validate Input**: Never trust user input - always validate arguments

  ```lua theme={null}
  RSGCore.Commands.Add('setcash', 'Set player cash', arguments, true, function(source, args)
      local amount = tonumber(args[1])
      if not amount or amount < 0 or amount > 1000000 then
          TriggerClientEvent('ox_lib:notify', source, {
              description = 'Invalid amount',
              type = 'error'
          })
          return
      end
      -- Process valid amount
  end, 'admin')
  ```
</Warning>

<Check>
  **Provide Helpful Arguments**: Good help text makes commands easier to use

  ```lua theme={null}
  local arguments = {
      { name = 'id', help = 'Target player server ID (1-255)' },
      { name = 'amount', help = 'Dollar amount (max: 100000)' }
  }
  ```
</Check>

### Permission Levels

When choosing permission levels, follow these guidelines:

| Level   | Use For                                                        |
| ------- | -------------------------------------------------------------- |
| `user`  | Safe commands any player can use (view own data, cosmetic)     |
| `mod`   | Commands that affect other players but not severely            |
| `admin` | Commands that modify game state, spawn items, teleport         |
| `god`   | Dangerous commands that can break things or affect all players |

***

## Next Steps

* [Server Functions Reference](/api-reference/endpoint/serverfunctionreference) - Complete function reference
* [Player Data](/essentials/playerdata) - Access player data in commands
* [Callbacks](/essentials/callbacks) - Client-server communication
* [Configuration](/essentials/configuration) - Configure permission levels

***

Need help? Join the [RSG Framework Discord](https://discord.gg/rsg-redm-framework-914413479157448744)!