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() -- To check if world is owned or not 'nil' means not owned.
world:setOwner(userID) -- Sets a player as the owner by user ID.
world:removeOwner() -- Removes owner of the world.
world:getName() -- Returns the world's name.
world:getID() -- Returns the world's ID.
world:getWorldSizeX() -- Returns the horizontal size of the world.
world:getWorldSizeY() -- Returns the vertical size of the world.
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:getWorldType() -- Returns the world's type.
world:redeemCode(player, code) -- Makes a player redeem a code in this world.

Code Redemption

You can programmatically redeem codes for players:


world:redeemCode(player, code)

Parameters:

player - The player object who will redeem the code
code - The code string to redeem

Example:


-- Redeem a code for a player
world:redeemCode(player, "WELCOME2024")
 
-- Auto-redeem code on first login
onPlayerFirstTimeLoginCallback(function(player)
    local world = getWorld(player:getWorldID())
    if world then
        world:redeemCode(player, "NEWPLAYER")
        player:onConsoleMessage("`2Welcome! Redeemed starter pack!")
    end
end)
 
-- Command to redeem codes
onPlayerCommandCallback(function(world, player, fullCommand)
    local command, code = fullCommand:match("^(%S+)%s*(.*)")
    if command == "/redeem" then
        if code == "" then
            player:onConsoleMessage("`4Usage: /redeem <code>")
            return true
        end
        
        world:redeemCode(player, code)
        return true
    end
    return false
end)

ℹ️

Note

The world: prefix is required for this method, even though it operates on the player. This is because code redemption is contextual to the world state.

Example:


-- Set a player as owner
local userID = player:getUserID()
world:setOwner(userID)
player:onConsoleMessage("`2You are now the owner of this world!")
 
-- Remove ownership
world:removeOwner(userID)

World Lifecycle

Create, persist, and destroy worlds at runtime:


world:new(name, sizeX, sizeY, worldType) -- Static. Creates a new world object in memory.
world:newFromTemplate(name, templateFile) -- Static. Creates a new world from a .dat template file.
world:save() -- Saves a world created with world:new() or world:newFromTemplate() to the server.
world:delete() -- Deletes a world object from memory.

ℹ️

Template Names

You can find template names in the World Manager dashboard. Pass the template name as the second argument to newFromTemplate.

Example:


-- Create a fresh world and save it
local w = world:new("MYWORLD", 100, 60, 0)
w:save()
 
-- Create from a template
local w2 = world:newFromTemplate("EVENTARENA", "arena_template")
w2:save()

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 Weather


world:setWeather(weather_id) -- Sets the weather in the world.

Minigame State


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

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!

NPC Visual Effects

NPCs can now perform visual actions like breaking and building:


npc:visualPunch(tile) -- Makes the NPC show a breaking/punching effect and automatically rotates.
npc:visualBuild(tile) -- Makes the NPC show a building/placing effect and automatically rotates.

Example:


local npc = world:createNPC("Builder Bot", 50, 25)
local tile = world:getTile(51, 25)
 
-- Make NPC visually punch/break
npc:visualPunch(tile)
 
-- Wait a moment, then make NPC visually build
-- (In actual code, you'd use a timer or callback)
npc:visualBuild(tile)

✅

Automatic Rotation

The visualPunch() and visualBuild() methods automatically handle NPC rotation towards the target tile, making your NPCs look more realistic and alive!

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.
world:spawnGems(x, y, amount, player) -- Spawns gems in the world.
world:onLoot(player, tile, gem_count) -- Triggers gem loot from a tile with particle effects (use instead of adjustGems when you want visual effects).

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)

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:punchTile(tile) -- Punches a tile — can break blocks, harvest trees, and trigger any punchable action.
world:spawnItem(x, y, itemID, count, center) -- Spawns item drops at coordinates. center=1 (default) centers the item, center=0 does not.
world:removeDroppedItem(dropUID) -- Removes a specific dropped item by its UID.
world:useConsumable(player, tile, id, should_NOT_trigger_callback) -- Uses a consumable item at a tile for a player.
world:updateTile(tile) -- Sends a visual update for a tile, necessary after using tile:setTileData.

Dropped Items


world:getDroppedItems() -- Returns a table of all currently dropped items in the world.
world:getTileDroppedItems(tile) -- Returns a table of dropped items at a specific tile.

Magplant Remote


world:getMagplantRemoteTile(player) -- Returns the tile that the player's Magpull/Magplant remote is currently pointed at.