Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ZTzTopia/GTProxy/llms.txt

Use this file to discover all available pages before exploring further.

​
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 statusReturn 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 worldMany 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

Build docs developers (and LLMs) love

Get started for freeTalk to us