Command Registration API

Register and manage custom proxy commands

Overview

The command global allows you to register custom commands that can be executed from the game client. Commands are executed with a configurable prefix (default: /).

Registering Commands

With Description

command.register · function

name · string · required

The command name (without prefix)

description · string

Optional description of what the command does

callback · function · required

Function to execute when command is called. Must return true on success, false on failure.

command.register("say", "Echo a message", function(ctx)
    if #ctx.args < 1 then
        ctx:reply("Usage: /say <message>")
        return false
    end
    
    local message = table.concat(ctx.args, " ")
    logger.info(message)
    return true
end)

Without Description

You can omit the description parameter:

command.register("echo", function(ctx)
    if #ctx.args < 1 then
        ctx:reply("Usage: /echo <message>")
        return false
    end
    
    local message = table.concat(ctx.args, " ")
    local log = LogPacket.new()
    log.msg = message
    send.to_client(log)
    
    return true
end)

Command Context

Every command callback receives a context object:

ctx.args · table

Array of command arguments

-- For command: /test arg1 arg2 arg3
ctx.args[1] -- "arg1"
ctx.args[2] -- "arg2"
ctx.args[3] -- "arg3"
#ctx.args   -- 3

ctx.raw · string

The raw command string (including command name)

-- For command: /test arg1 arg2
ctx.raw -- "/test arg1 arg2"

ctx:reply · function

Send a message to the player

message · string · required

The message to send (supports Growtopia color codes)

Returns true on success, false on failure.

ctx:reply("`2Success!")
ctx:reply("`4Error: ``Invalid input")

Command Management

List All Commands

command.list · function

Returns a table mapping command names to descriptions

local commands = command.list()
for name, description in pairs(commands) do
    logger.info("Command: {} - {}", name, description or "No description")
end

Execute Commands Programmatically

command.execute · function

command_string · string · required

The full command string (including prefix)

Returns true if the command executed successfully.

local success = command.execute("/say Hello World")
if success then
    logger.info("Command executed successfully")
end

Get Command Prefix

command.get_prefix · function

Returns the current command prefix

local prefix = command.get_prefix()
logger.info("Current prefix: {}", prefix)

Set Command Prefix

command.set_prefix · function

prefix · string · required

The new command prefix

command.set_prefix("!")
logger.info("Prefix changed to !")

Examples

Basic Echo Command

command.register("say", "Echo a message to the client", function(ctx)
    if #ctx.args < 1 then
        ctx:reply("Usage: /say <message>")
        return false
    end
    
    local message = table.concat(ctx.args, " ")
    
    local log = LogPacket.new()
    log.msg = message
    send.to_client(log)
    
    return true
end)

Position Command

command.register("pos", "Show your current position", function(ctx)
    local player = world:get_local_player()
    
    if not player then
        ctx:reply("`4Error: ``Not in a world")
        return false
    end
    
    ctx:reply("`2Position: ``({}, {})", player.position.x, player.position.y)
    return true
end)

Item Info Command

command.register("item", "Get item information", function(ctx)
    if #ctx.args < 1 then
        ctx:reply("`4Usage: ``/item <item_id>")
        return false
    end
    
    local item_id = tonumber(ctx.args[1])
    if not item_id then
        ctx:reply("`4Error: ``Invalid item ID")
        return false
    end
    
    local item = item_database:get_item(item_id)
    if item then
        ctx:reply("`2Item {}: ``{}", item.item_id, item.item_name)
        ctx:reply("`2Type: ``{}, `2Rarity: ``{}", item.item_type, item.rarity)
    else
        ctx:reply("`4Error: ``Item not found")
    end
    
    return true
end)

Help Command

command.register("help", "List all commands", function(ctx)
    local commands = command.list()
    local prefix = command.get_prefix()
    
    ctx:reply("`2Available Commands:")
    
    for name, description in pairs(commands) do
        ctx:reply("`2{}{} ``- {}", prefix, name, description or "No description")
    end
    
    return true
end)

Teleport Command

command.register("tp", "Teleport to coordinates", function(ctx)
    if #ctx.args < 2 then
        ctx:reply("`4Usage: ``/tp <x> <y>")
        return false
    end
    
    local x = tonumber(ctx.args[1])
    local y = tonumber(ctx.args[2])
    
    if not x or not y then
        ctx:reply("`4Error: ``Invalid coordinates")
        return false
    end
    
    local player = world:get_local_player()
    if not player then
        ctx:reply("`4Error: ``Not in a world")
        return false
    end
    
    -- Send teleport packet
    local pkt = GamePacket.new()
    pkt.type = packet.PacketType.PACKET_STATE
    pkt.net_id = player.net_id
    pkt.pos_x = x
    pkt.pos_y = y
    send.to_server(pkt)
    
    ctx:reply("`2Teleporting to ``({}, {})", x, y)
    return true
end)

World Info Command

command.register("worldinfo", "Display world information", function(ctx)
    local local_player = world:get_local_player()
    if not local_player then
        ctx:reply("`4Error: ``Not in a world")
        return false
    end
    
    local players = world:get_players()
    local player_count = 0
    for _ in pairs(players) do
        player_count = player_count + 1
    end
    
    ctx:reply("`2World Information:")
    ctx:reply("`2Players: ``{}", player_count)
    ctx:reply("`2Version: ``{}", world:get_version())
    
    return true
end)

Greet Command

command.register("greet", "Greet the player", function(ctx)
    local player = world:get_local_player()
    if player then
        ctx:reply("`2Hello, ``{}!`2 Welcome to GTProxy!", player.name)
    else
        ctx:reply("`2Hello! ``Welcome to GTProxy!")
    end
    return true
end)

Best Practices

Always validate arguments

command.register("example", function(ctx)
    if #ctx.args < 1 then
        ctx:reply("Usage: /example <arg>")
        return false
    end
    
    -- Safe to use ctx.args[1]
    return true
end)

Use Growtopia color codes

• `2 - Green (success messages)
• `4 - Red (error messages)
• “ - White (reset to default)

ctx:reply("`2Success: ``Operation completed")
ctx:reply("`4Error: ``Invalid input")

Return appropriate status

Return true when the command succeeds, false when it fails:

if not valid_input then
    ctx:reply("`4Error: ``Invalid input")
    return false  -- Command failed
end

-- Do work
return true  -- Command succeeded

Check if player is in a world

Many commands require the player to be in a world:

local player = world:get_local_player()
if not player then
    ctx:reply("`4Error: ``You must be in a world")
    return false
end

See Also

World API

Access player and world data

Logger API

Log command execution

Examples

More command examples