World Object Documentation

Overview

The World object provides access to all world-specific data, player interactions, tiles, and item effects. Methods are used with the colon operator (world:methodName()).

World Info

world:getOwner(player) -- Checks if a player is the owner of the world.
world:getName() -- Returns the world's name.
world:getID() -- Returns the world's ID.
world:getSizeX() -- Returns the horizontal size of the world.
world:getSizeY() -- Returns the vertical size of the world.
world:getWorldSizeX()
world:getWorldSizeY()
world:getTiles() -- Returns a table of all tiles in the world.
world:getTilesByActionType(actionType) -- Returns tiles with a specific action type.
world:getWorldLock() -- Returns the world lock tile, or nil if world is not locked.

World Access Management

Manage player access to worlds and specific tiles:

world:hasAccess(player) -- Checks if player has build access to the entire world.
world:hasTileAccess(player, tile) -- Checks if player has build access to a specific tile.
 
-- Grant/remove access (only works if world is World Locked)
world:addAccess(player, adminType) -- Give player access (0 = regular, 1 = super-admin).
world:removeAccess(player) -- Remove player's world access.
 
-- Tile-specific access (very powerful - be careful!)
world:addTileAccess(player, tile) -- Give permanent tile access (can break locks!).
world:removeTileAccess(player, tile) -- Remove tile access.
world:removeAllTileAccess() -- Emergency: Remove all tile access grants.

⚠️

Powerful Access Control

addTileAccess is very powerful - if you give players access to lock tiles, they can break them! Use with extreme caution.

World Punishments

Manage world-specific punishments like bans and mutes:

world:addPunishment(player, punishment_type, timestamp_when_expire_in_seconds, reason, by_user_id)
world:removePunishment(player, punishment_type)
world:getPunishment(player, punishment_type)
world:getAllPunishments()

Punishment Types:

WORLD_BAN = 1 - Ban player from the world
WORLD_MUTE = 2 - Mute player in the world

Example Usage:

-- Ban a player from the world for 1 hour
local WORLD_BAN = 1
local expire_time = os.time() + 3600 -- 1 hour from now
world:addPunishment(player, WORLD_BAN, expire_time, "Breaking rules", 0)
 
-- Mute a player for 30 minutes
local WORLD_MUTE = 2
world:addPunishment(player, WORLD_MUTE, os.time() + 1800, "Spam", 0)
 
-- Remove a punishment
world:removePunishment(player, WORLD_BAN)
 
-- Check if player has a punishment
local punishment = world:getPunishment(player, WORLD_MUTE)
if punishment then
    print("Invoker ID: " .. punishment.invokerID)
    print("User ID: " .. punishment.userID)
    print("Type: " .. punishment.type)
    print("Expires: " .. punishment.expires)
    print("Reason: " .. punishment.reason)
    print("IP: " .. punishment.IP)
end
 
-- Get all world punishments
local allPunishments = world:getAllPunishments()
for i, pun in ipairs(allPunishments) do
    print("Punishment " .. i .. ": " .. pun.reason)
end

ℹ️

By User ID Parameter

Keep by_user_id at 0 unless a specific player is issuing the punishment to another player. Use the punisher’s user ID to track who issued the punishment.

World Flags

Check world flags for special properties:

world:hasFlag(id) -- Check if world has a specific flag.

ℹ️

World Flag Constants

See World Flags for a complete list of all 18 available flag IDs and their descriptions.

Example:

-- Check if world is open to public
if world:hasFlag(0) then
    player:onConsoleMessage("This world is public!")
end
 
-- Check if punching is disabled
if world:hasFlag(2) then
    player:onConsoleMessage("Punching is jammed!")
end

Player Interaction

world:hasAccess(player) -- Checks if player has build access to the entire world.
world:hasTileAccess(player, tile) -- Checks if player has build access to a specific tile.
world:setPlayerPosition(player, x, y) -- Teleports a player to a specific tile coordinate.
world:kill(player) -- Kills a player in the world.
world:setClothing(player, itemID) -- Force equips an item on a player.
world:updateClothing(player) -- Updates player's clothing.
world:addXP(player, amount) -- Adds XP to a player.
world:adjustGems(player, tile, gem_count, val) -- Adjusts gem count for a player from a tile action.

Players in World

world:getPlayers() -- Returns a table of all player objects currently in the world.
world:getPlayersCount(includeInvisible) -- Returns the number of players, pass `1` to include invisible players.
world:getVisiblePlayersCount() -- Returns the number of visible players.
world:findNPCByName(name) -- Finds an NPC by name and returns its player object.
world:createNPC(name, x, y) -- Spawns an NPC in the world and returns its player object.
world:removeNPC(npc) -- Removes an NPC from the world.

ℹ️

NPC System

You can create and manage NPCs in worlds to add interactive elements or guide players through custom content!

Messaging & Effects

world:sendPlayerMessage(player, message) -- Sends a message to a player.
world:onCreateChatBubble(x, y, text, netID) -- Creates a chat bubble in the world.
world:onCreateExplosion(x, y, radius, power) -- Creates an explosion at coordinates.
world:useItemEffect(playerNetID, itemID, targetNetID, effectDelay) -- Triggers a visual item effect in the world.
spawnGems(x, y, amount, player) -- Spawns gems in the world.

Ghost Spawning

Spawn ghosts in your world with various types and behaviors:

world:spawnGhost(tile, type, spawned_by_user_id, remove_in, m_speed)

Parameters:

tile - The tile object where the ghost will spawn
type - Ghost type (see table below)
spawned_by_user_id - User ID who spawned the ghost (use 0 if not applicable)
remove_in - Time in seconds until ghost disappears (0 for permanent)
m_speed - Movement speed (recommended: 33 for normal ghosts, 132 for mind ghost)

Ghost Types:

Type	Constant	Speed
1	GHOST_NORMAL	33
4	GHOST_ANCESTOR	33
6	GHOST_SHARK	33
7	GHOST_WINTERFEST	33
11	GHOST_BOSS	33
12	GHOST_MIND	132

Example:

local GHOST_NORMAL = 1
local GHOST_MIND = 12
 
-- Spawn a normal ghost at tile (10, 10) that disappears in 60 seconds
local tile = world:getTile(10, 10)
world:spawnGhost(tile, GHOST_NORMAL, 0, 60, 33)
 
-- Spawn a permanent mind ghost with faster speed
local mindTile = world:getTile(15, 15)
world:spawnGhost(mindTile, GHOST_MIND, 0, 0, 132)
 
-- Spawn a boss ghost owned by a specific player
local bossTile = world:getTile(20, 20)
world:spawnGhost(bossTile, 11, player:getUserID(), 0, 33)

Path-Finding

Find paths between tiles in the world:

world:findPathByTile(start_tile, end_tile, x, y)

Parameters:

start_tile - Starting tile object
end_tile - Destination tile object
x - Maximum horizontal search distance (255 = entire world, but slower)
y - Maximum vertical search distance (255 = entire world, but slower)

Returns: Table of path steps with x and y coordinates, or nil if no path found

Example:

local start_tile = world:getTile(0, 0)
local end_tile = world:getTile(10, 10)
 
-- Search within a 20x20 area
local path = world:findPathByTile(start_tile, end_tile, 20, 20)
 
if path == nil then
    print("No available path found")
else
    print("Found available path:")
    for i, step in ipairs(path) do
        print("Step " .. i .. ": (" .. step.x .. ", " .. step.y .. ")")
    end
end
 
-- Search entire world (slower)
local fullPath = world:findPathByTile(start_tile, end_tile, 255, 255)

ℹ️

Performance Tip

Use smaller search distances (e.g., 6-20) for better performance. Only use 255 when you need to search the entire world.

Tile Manipulation

world:setTileForeground(tile, itemID, isVisual:optional, player:optional) -- Sets the foreground of a tile.
world:setTileBackground(tile, itemID, isVisual:optional, player:optional) -- Sets the background of a tile.
world:updateTile(tile) -- Forces a visual update for a tile.
world:punchTile(tile) -- Simulates a punch on a tile (break logic).
world:getTileDroppedItems(tile) -- Returns a table of all dropped items on the tile.

Items & Dropped Objects

world:getDroppedItems() -- Returns a table of all dropped items in the world.
world:removeDroppedItem(DropUID) -- Removes a dropped item by its UID.
world:spawnItem(x, y, itemID, count, center) -- Spawns an item, returns dropped item object.
-- center: 1 (default) = centered, 0 = not centered
 
world:getMagplantRemoteTile(player) -- Returns tile being used with magplant remote.
world:useConsumable(player, tile, id, should_NOT_trigger_callback) -- Use a consumable item.
-- should_NOT_trigger_callback: 1 = suppress callback, 0 = trigger (default)

ℹ️

Spawn Item Returns Object

The spawnItem() function now returns the dropped item object, allowing you to get its UID and manipulate it directly!

Example:

local droppedItem = world:spawnItem(5, 5, 2, 1, 0) -- Spawn 1 dirt at (5,5), not centered
if droppedItem then
    local uid = droppedItem:getUID()
    print("Spawned item UID: " .. uid)
end
 
-- Magplant remote example
local magplantTile = world:getMagplantRemoteTile(player)
if magplantTile then
    local itemID = magplantTile:getForegroundItemID()
    print("Player's magplant remote is linked to tile with item: " .. itemID)
end
 
-- Using consumable without triggering callback (prevents infinite recursion)
world:useConsumable(player, tile, itemID, 1)

✅

Callback Control

You can now suppress the onPlayerUsedConsumableCallback when calling useConsumable() to prevent infinite recursion in your scripts!

Game Status

world:isGameActive() -- Returns true if the game is active.
world:onGameWinHighestScore() -- Returns the game's highest win score.

Discord Slash Command Tutorial Player