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 item_database global provides access to the Growtopia item database, allowing you to look up item information, properties, and metadata.

​
Database Access

​
Get Item by ID

​
item_database:get_item
function
​
item_id
number
required
The item ID to look up
Returns the item object, or nil if not found.
local item = item_database:get_item(2)  -- Get Dirt
if item then
    logger.info("Item {}: {}", item.item_id, item.item_name)
    logger.info("Type: {}, Rarity: {}", item.item_type, item.rarity)
end

​
Get Database Version

​
item_database:get_version
function
Returns the item database version number.
logger.info("Item database version: {}", item_database:get_version())

​
Get Item Count

​
item_database:get_count
function
Returns the total number of items in the database.
logger.info("Total items: {}", item_database:get_count())

​
Item Properties

​
item_id
number
Unique item identifier
​
item_name
string
Display name of the item
​
item_type
number
Item type enum (see Item Type Enums)
​
material
number
Material type enum
​
rarity
number
Item rarity value
​
collision_type
number
Collision type enum (Solid, NonSolid, Gas, etc.)
​
visual_effect
number
Visual effect enum
​
clothing_type
number
Clothing type enum (Hat, Shirt, Pants, etc.)
​
texture_file_path
string
Path to the item’s texture file
​
max_amount
number
Maximum stackable amount (typically 200)
​
health
number
Item health value (for blocks)
​
flags
table
Table of item flags

​
Item Type Enums

​
Item Types

item.Type.Consumable  -- Consumable items
item.Type.Block       -- Placeable blocks
item.Type.Vehicle     -- Vehicles

​
Collision Types

item.CollisionType.Solid    -- Solid blocks (can't walk through)
item.CollisionType.NonSolid -- Non-solid blocks (can walk through)
item.CollisionType.Gas      -- Gas blocks

​
Visual Effects

item.VisualEffect.None        -- No visual effect
item.VisualEffect.SpawnEffect -- Spawn effect
item.VisualEffect.Fire        -- Fire effect

​
Material Types

item.MaterialType.None  -- No material
item.MaterialType.Front -- Front layer
item.MaterialType.Back  -- Back layer

​
Clothing Types

item.ClothingType.None  -- Not clothing
item.ClothingType.Hat   -- Hat
item.ClothingType.Shirt -- Shirt
item.ClothingType.Pants -- Pants
item.ClothingType.Feet  -- Shoes
item.ClothingType.Face  -- Face item
item.ClothingType.Hand  -- Hand item
item.ClothingType.Mask  -- Mask

​
Examples

​
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 not item then
        ctx:reply("`4Error: ``Item not found")
        return false
    end
    
    ctx:reply("`2Item {}: ``{}", item.item_id, item.item_name)
    ctx:reply("`2Type: ``{}, `2Rarity: ``{}", item.item_type, item.rarity)
    ctx:reply("`2Max Amount: ``{}", item.max_amount)
    
    return true
end)

​
Database Info Command

command.register("dbinfo", "Show database info", function(ctx)
    local version = item_database:get_version()
    local count = item_database:get_count()
    
    ctx:reply("`2Item Database Info:")
    ctx:reply("`2Version: ``{}", version)
    ctx:reply("`2Total Items: ``{}", count)
    
    return true
end)

​
Search by Rarity

command.register("rare", "List rare items", function(ctx)
    if #ctx.args < 1 then
        ctx:reply("`4Usage: ``/rare <min_rarity>")
        return false
    end
    
    local min_rarity = tonumber(ctx.args[1])
    if not min_rarity then
        ctx:reply("`4Error: ``Invalid rarity")
        return false
    end
    
    local found = {}
    local total = item_database:get_count()
    
    for i = 0, total - 1 do
        local item = item_database:get_item(i)
        if item and item.rarity >= min_rarity then
            table.insert(found, item)
        end
    end
    
    ctx:reply("`2Found {} items with rarity >= {}", #found, min_rarity)
    
    for i, item in ipairs(found) do
        if i <= 10 then  -- Limit to 10 items
            ctx:reply("  [{}] {} (Rarity: {})", item.item_id, item.item_name, item.rarity)
        end
    end
    
    if #found > 10 then
        ctx:reply("`2... and {} more", #found - 10)
    end
    
    return true
end)

​
Clothing Filter

command.register("hats", "List all hats", function(ctx)
    local found = {}
    local total = item_database:get_count()
    
    for i = 0, total - 1 do
        local item = item_database:get_item(i)
        if item and item.clothing_type == item.ClothingType.Hat then
            table.insert(found, item)
        end
    end
    
    ctx:reply("`2Found {} hats", #found)
    
    for i, item in ipairs(found) do
        if i <= 20 then
            ctx:reply("  [{}] {}", item.item_id, item.item_name)
        end
    end
    
    return true
end)

​
Block Health Check

command.register("blockhealth", "Check block health", function(ctx)
    if #ctx.args < 1 then
        ctx:reply("`4Usage: ``/blockhealth <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 not item then
        ctx:reply("`4Error: ``Item not found")
        return false
    end
    
    ctx:reply("`2{} ``health: `2{}", item.item_name, item.health)
    
    return true
end)

​
Collision Type Filter

command.register("solid", "List solid blocks", function(ctx)
    local found = 0
    local total = item_database:get_count()
    
    ctx:reply("`2Scanning {} items...", total)
    
    for i = 0, total - 1 do
        local item = item_database:get_item(i)
        if item and item.collision_type == item.CollisionType.Solid then
            found = found + 1
        end
    end
    
    ctx:reply("`2Found {} solid blocks", found)
    return true
end)

​
Item Type Statistics

command.register("itemstats", "Show item type statistics", function(ctx)
    local stats = {
        consumable = 0,
        block = 0,
        vehicle = 0,
        other = 0
    }
    
    local total = item_database:get_count()
    
    for i = 0, total - 1 do
        local item = item_database:get_item(i)
        if item then
            if item.item_type == item.Type.Consumable then
                stats.consumable = stats.consumable + 1
            elseif item.item_type == item.Type.Block then
                stats.block = stats.block + 1
            elseif item.item_type == item.Type.Vehicle then
                stats.vehicle = stats.vehicle + 1
            else
                stats.other = stats.other + 1
            end
        end
    end
    
    ctx:reply("`2Item Statistics:")
    ctx:reply("`2Consumables: ``{}", stats.consumable)
    ctx:reply("`2Blocks: ``{}", stats.block)
    ctx:reply("`2Vehicles: ``{}", stats.vehicle)
    ctx:reply("`2Other: ``{}", stats.other)
    ctx:reply("`2Total: ``{}", total)
    
    return true
end)

​
Random Item Generator

command.register("random", "Get a random item", function(ctx)
    local total = item_database:get_count()
    local random_id = math.random(0, total - 1)
    
    local item = item_database:get_item(random_id)
    if item then
        ctx:reply("`2Random Item: ``{}" .. item.item_name)
        ctx:reply("`2ID: ``{}, `2Rarity: ``{}", item.item_id, item.rarity)
    else
        ctx:reply("`4Error: ``Failed to get random item")
    end
    
    return true
end)

​
Validate Object IDs

event.on("server:SendMapData", function(ctx)
    if ctx:has_packet() then
        local object_map = world:get_object_map()
        local objects = object_map:get_objects()
        
        logger.info("Validating {} objects...", #objects)
        
        for i, obj in ipairs(objects) do
            local item = item_database:get_item(obj.item_id)
            if item then
                logger.info("Object {}: {} x{}", i, item.item_name, obj.amount)
            else
                logger.warn("Unknown item ID: {}", obj.item_id)
            end
        end
    end
end)

​
Best Practices

Always check if item exists
local item = item_database:get_item(item_id)
if not item then
    -- Item not found
    return
end

-- Safe to use item
Be careful with large scansScanning the entire database can be slow:
-- This can be slow
for i = 0, item_database:get_count() - 1 do
    local item = item_database:get_item(i)
    -- Process item
end
Consider limiting results or caching data when possible.
Cache frequently accessed items
local common_items = {
    dirt = item_database:get_item(2),
    bedrock = item_database:get_item(8),
    -- etc.
}

-- Later:
logger.info("Dirt: {}", common_items.dirt.item_name)

​
See Also

World API

Use item data with world objects

Examples

More item database examples

Build docs developers (and LLMs) love

Get started for freeTalk to us