GrowtopiaBot

The GrowtopiaBot class allows you to create and manage bot connections to real Growtopia servers from within your GTPS Cloud private server. This enables integration between real Growtopia and your private server.

Creating a Bot Instance

local bot = GrowtopiaBot.new(token)

Parameters:

• token (string): Your authentication token from the purchased addon

Returns: A new GrowtopiaBot instance

Example:

local bot = GrowtopiaBot.new("LEPr2BRNoZGD")

Methods

start()

Starts the bot connection to Growtopia servers.

bot:start()

Note: The bot automatically handles subserver connections and anti-cheat responses. No additional configuration is needed.

sendStr()

Sends a string packet to the Growtopia server.

bot:sendStr(type, content)

Parameters:

• type (number): Packet type (typically 3 for text packets)
• content (string): The packet content

Example:

bot:sendStr(3, "action|join_request\nname|WORLDNAME\ninvitedWorld|0\n")

sendRaw()

Sends a raw binary packet to the Growtopia server.

bot:sendRaw(data)

Parameters:

• data (binary): Raw packet data

reconnect()

Reconnects the bot to the Growtopia server.

bot:reconnect()

Callbacks

onReceiveTextCallback()

Registers a callback function that triggers when the bot receives a text packet.

bot:onReceiveTextCallback(function(str, data)
    -- Handle text packet
end)

Parameters:

• str (string): The received text content
• data (table): Additional packet data

onReceiveVariantCallback()

Registers a callback function that triggers when the bot receives a variant packet. This is the most commonly used callback for handling game events.

bot:onReceiveVariantCallback(function(data)
    -- Handle variant packet
end)

Parameters:

• data (table): Variant list data where data[1] is the variant type

Common Variant Types:

• "OnConsoleMessage" - Console messages (data[2] contains the message)
• "OnFailedToEnterWorld" - Failed world entry
• "OnSpawn" - Player spawn events
• "OnTalkBubble" - Chat messages

Example:

bot:onReceiveVariantCallback(function(data)
    if data[1] == "OnConsoleMessage" then
        local message = data[2]
        print("Console: " .. message)
    elseif data[1] == "OnFailedToEnterWorld" then
        bot:reconnect()
    end
end)

onReceiveTrackCallback()

Registers a callback function that triggers when the bot receives a track packet.

bot:onReceiveTrackCallback(function(str, data)
    -- Handle track packet
end)

Parameters:

• str (string): The track data
• data (table): Additional packet data

onReceiveRawCallback()

Registers a callback function that triggers when the bot receives any raw packet. Useful for parsing low-level game packets.

bot:onReceiveRawCallback(function(data)
    -- Handle raw packet
end)

Parameters:

• data (binary): Raw packet data

Warning: This callback has a CPU impact, especially in worlds with many players. Only use it when necessary and remove it if not needed.

BinaryReader

The BinaryReader utility helps parse raw binary packet data.

local rd = BinaryReader(data)

Methods

• rd:Skip(bytes) - Skip a number of bytes
• rd:ReadUInt8() - Read an unsigned 8-bit integer
• rd:ReadInt32() - Read a signed 32-bit integer
• rd:ReadUInt16() - Read an unsigned 16-bit integer
• rd:ReadUInt32() - Read an unsigned 32-bit integer
• rd:ReadFloat() - Read a float value
• rd:ReadString(length) - Read a string of specified length

Common Packet Types

When using onReceiveRawCallback, the packet type can be read after skipping the first 4 bytes:

Example Use Cases

World Entry and Verification

function enterWorld()
    bot:sendStr(3, "action|join_request\nname|WORLDNAME\ninvitedWorld|0\n")
end
 
bot:onReceiveVariantCallback(function(data)
    if data[1] == "OnConsoleMessage" then
        if string.find(data[2], "Where would you like to go?") then
            enterWorld()
        end
    end
end)

Parsing Console Messages

bot:onReceiveVariantCallback(function(data)
    if data[1] == "OnConsoleMessage" then
        local message = data[2]
        
        -- Extract player name
        local player = message:match("w(%w+) places")
        
        -- Extract quantity
        local quantity = tonumber(message:match("`5(%d+)``"))
        
        -- Extract item name
        local item = message:match("`2([^`]+)``")
    end
end)

Reading World Name from Raw Packet

bot:onReceiveRawCallback(function(data)
    local rd = BinaryReader(data)
    rd:Skip(4)
    
    local game_packet_type = rd:ReadUInt8()
    
    if game_packet_type == 4 then
        rd:Skip(55) -- Skip game update packet structure
        rd:Skip(6)  -- Skip world data info
        
        local world_name_length = rd:ReadUInt16()
        local world_name = rd:ReadString(world_name_length)
        
        print("Current world: " .. world_name)
    end
end)

Notes

• The bot automatically handles ENet connections and anti-cheat systems
• No need to manually change subservers or send anti-cheat responses
• All backend communication is handled automatically
• The bot requires a valid token from the purchased addon

See Also

• GrowtopiaBot Tutorial - Complete example with deposit system