Command System

Reference for registering server commands using cv.command.add().

---

Overview

The command system provides structured command registration with parameter validation, type checking, and optional ACE permission restrictions.

Key Features: - Named parameter definitions with type validation - Support for string, number, playerId, longString, args, src, cvPlayer, and charId types - Optional parameters - ACE permission restrictions (boolean, string, or array) - Help text display - Auto-injection of special parameter types (no user input required)

---

Basic Usage

Register a command with the cv.command.add function:

cv.command.add("giveitem", {
    help = "Gives an item to a player",
    params = {
        {
            name = "targetPlayer",
            type = "charId",
            help = "Target character ID",
        },
        {
            name = "item",
            type = "string",
            help = "Name of the item to give",
        },
        {
            name = "count",
            type = "number",
            help = "Amount of the item",
            optional = true,
        },
    },
    restricted = "group.admin"
}, function(adminPlayer, source, args, raw)
    local targetPlayer = args.targetPlayer  -- Already resolved cvPlayer object
    if not targetPlayer then
        cv.notify(source, 'Error', 'Target character not found', 'error')
        return
    end

    -- Add item logic here
end)

Callback Signature:

function(cvPlayer, source, args, raw)
    -- cvPlayer: CVPlayer object of the command executor (auto-injected)
    -- source: Server ID of the command executor
    -- args: Table of parsed arguments as defined in params
    -- raw: Raw command string
end

---

Parameter Types

Standard Types (parsed from command arguments): - string → Standard text input - number → Numeric value (validated as number) - playerId → Player server ID (validated as number) - longString → Captures all remaining text (includes spaces)

Special Types (auto-injected, no user input required): - src → Current player's source ID (server ID) - cvPlayer → CVPlayer object of command executor (resolved via charId) - args → All remaining raw input as single string - charId → Accepts character ID as argument, returns resolved CVPlayer object

Examples

Using charId parameter type:

cv.command.add("giveitem", {
    help = "Give item to a character",
    params = {
        {
            name = "targetChar",
            type = "charId",
            help = "Character ID of target",
        },
        {
            name = "itemName",
            type = "string",
            help = "Item to give",
        }
    }
}, function(adminPlayer, source, args, raw)
    -- args.targetChar is already a CVPlayer object
    local target = args.targetChar
    if target then
        -- Give item to target
    end
end)

Command usage: /giveitem 5 apple (where 5 is the character ID)

Using src parameter type:

cv.command.add("myinfo", {
    help = "Get your info",
    params = {
        {
            name = "playerId",
            type = "src",  -- Auto-injected
            help = "Your server ID",
        }
    }
}, function(player, source, args, raw)
    -- args.playerId already contains source
    cv.notify(source, 'Info', 'Your ID: ' .. args.playerId, 'info')
end)

Using args parameter type:

cv.command.add("announce", {
    help = "Announce a message to the server",
    params = {
        {
            name = "message",
            type = "args",  -- Captures all remaining input
            help = "Message to announce",
        }
    }
}, function(player, source, args, raw)
    TriggerClientEvent('chat:addMessage', -1, {
        args = { 'Announcement', args.message }
    })
end)

Command usage: /announce Hello everyone this is a test message

---

Permission Restrictions

The restricted option supports three formats:

Boolean → Requires command.<name> ACE permission:

cv.addCommand("ban", {
    help = "Ban a player",
    restricted = true,
    -- ...
})
-- Requires: add_ace group.admin command.ban allow

String → Requires specific permission or group:

restricted = "group.admin"
restricted = "command.custom_permission"

Array → Multiple groups/permissions:

restricted = { "group.admin", "group.moderator" }

---

Character Context Validation

The cvPlayer parameter is auto-injected and always returns the command executor's CVPlayer object:

cv.command.add("job", {
    help = "Check your current job",
    params = {
        {
            name = "action",
            type = "string",
            help = "Action to perform (info|leave)",
            optional = true,
        }
    }
}, function(player, source, args, raw)
    -- player is already the CVPlayer object (auto-injected)
    if not player or not player.charId then
        cv.notify(source, 'Error', 'No character selected', 'error')
        return
    end

    local action = args.action or 'info'
    if action == 'info' then
        cv.notify(source, 'Job', player.job.name, 'info')
    end
end)

---

Help Display

Users can view command help by typing the command with no arguments or with help/hilfe:

/giveitem
/giveitem help
/giveitem hilfe

This will display: /giveitem <target> <item> [count] : Gives an item to a player

---

Configuration

Commands with restrictions require proper ACE setup in permission.cfg:

add_ace group.admin command.giveitem allow
add_ace group.admin command.announce allow
add_ace group.moderator command.announce allow

---

Admin Command Reference

Available commands registered in cv_framework:

Command	Beschreibung	Parameter	Berechtigung
givemoney	Geld an einen Spieler geben	target (number), type (string, optional), amount (number)	group.administrator
removemoney	Geld von einem Spieler entfernen	target (playerId), amount (number), type (string, optional)	- (auskommentiert)
test:notify	Test command	arg1 (string), arg2 (number, optional), msg (longString, optional)	-
heal	Heilt / belebt einen Spieler wieder	target (playerId, optional)	group.supporter
giveitem	Gives an item to a player	target (playerId), item (string), count (number, optional)	group.administrator
noclip	Noclip aktivieren/deaktivieren	-	group.supporter
relog	Bringt einen Spieler zurück zur Charakterauswahl	target (playerId, optional)	group.administrator
tp	Teleportiert dich zu den angegebenen Koordinaten	x, y, z (string), heading (string, optional)	-
tpm	Teleportiert dich zum Wegpunkt auf der Karte	-	-
tempveh	Spawnt ein temporäres Fahrzeug (löscht sich beim Neustart)	model (string)	group.supporter
giveveh	Spawnt ein dauerhaftes System-Fahrzeug (DB-gespeichert)	model (string)	group.administrator
dv	Fahrzeug despawnen	radius (number, optional)	group.administrator