Player structure

Here you will learn how to work with the player structure.

---

Basic Player Info

player:getName() -- Player's display name
player:getCleanName() -- Lowercase, no formatting
player:getNetID() -- Unique player network ID
player:getUserID() -- Unique account ID
player:getWorldName() -- Name of the world the player is in
player:getCountry() -- Player's country (online only)
player:getPlatform() -- Platform (0=Windows, 1=iOS, 4=Android, etc.)
player:getOnlineStatus() -- Online/offline status
player:getDiscordID() -- Returns Discord ID as a STRING
player:getDiscordInvites() -- List/info about created invites
player:getType() -- Non-zero = NPC
player:getAccountCreationDateStr() -- Date string
player:isOnline() -- True/false

---

Levels & Experience

getMaxLevel() -- Maximum possible level on the server

player:getLevel()
player:setLevel(number)
player:addLevel(number)
player:removeLevel(number)

player:setXP(number)
player:removeXP(number)

-- To ADD XP:
world:addXP(player, amount)

---

Currency & Items

player:getGems()
player:addGems(amount)
player:setGems(number)
player:removeGems(amount)

player:getCoins()
player:setCoins(number)
player:removeCoins(amount)

player:getItemAmount(itemID)
player:changeItem(itemID, amount)

player:getBankBalance()
player:addBankBalance(amount)
player:setBankBalance(number)
player:removeBankBalance(amount)

---

Titles

player:hasTitle(id)
player:addTitle(id)
player:removeTitle(id)

---

Inventory

player:getInventorySize()
player:isMaxInventorySpace()
player:upgradeInventorySpace(amount)
player:getInventoryItems() -- Returns all items

Example:

for _, item in ipairs(player:getInventoryItems()) do
    print(item:getItemID(), item:getItemCount())
end

---

UI & Messages

player:onConsoleMessage("Hello!")
player:onTalkBubble(player:getNetID(), "Hi!", 0)
player:onTextOverlay("Overlay text")
player:playAudio("audio.wav")

Dialog Requests with Callbacks

-- Old style (global callback):
player:onDialogRequest(dialog)

-- New style (direct callback):
function handleMyDialogResponse(world, player, data)
    if data["buttonClicked"] == "test" then
        player:onConsoleMessage("Button clicked!")
    end
end

player:onDialogRequest(
    "set_default_color|`o\n" ..
    "add_button|test|Test Button|left|\n" ..
    "end_dialog|my_gazette|||",
    0, -- delay (optional)
    handleMyDialogResponse -- callback (optional)
)

---

Game Features & UIs

player:onStorePurchaseResult()
player:onGrow4GoodDonate()
player:onRedeemMenu()

player:enterWorld("WORLDNAME", "Welcome!")

player:onGrowmojiUI()
player:onNotebookUI()
player:onCoinsBankUI()
player:onOnlineStatusUI()
player:onClothesUI(player)
player:onAchievementsUI(player)
player:onBackpackUI(player)

---

Roles, Mods & Stats

player:hasRole(roleID)
player:setRole(roleID)

local all_roles = getRoles() -- every role on server
local highest = getHighestPriorityRole() -- best role on server

local role = player:getRole() -- full role object

player:getMod(modID)
player:addMod(modID, value)

player:getSubscription("subscriptionName")

player:updateStats(world, PlayerStats.ConsumablesUsed, 1)

---

Dialog Styling

player:setNextDialogRGBA(r, g, b, a)
player:setNextDialogBorderRGBA(r, g, b, a)
player:resetDialogColor()

---

Nicknames

-- Nicknames are now UNLOCKED! Can contain colors, '@', spaces, and more.
-- Nicknames are saved and persist after re-login.

player:setNickname("Nickname")
player:resetNickname()

---

Friends Management

player:getFriends() -- Returns table with friend user IDs (numbers)

player:addFriend(target_player) -- Adds to both players' friend lists (not one-way)
player:removeFriend(target_player) -- Removes from both players' friend lists

---

Quests & Life Goals

player:getLifeGoals() -- Returns table of life goal task objects
-- Properties: taskID, taskTargetValue, taskCompletedValue, taskReward,
--             deliverItem, rewardAmount, claimed, givenup, completed, lastAnnouncePercentage

player:getBiweeklyQuests() -- Returns table of biweekly quest task objects
-- Same properties as getLifeGoals

getJimDailyQuest() -- Global function, returns Jim's daily quest
-- Properties: firstItemID, firstItemCount, secondItemID, secondItemCount, completedPlayers (table of user IDs)

---

Growpass Management

player:addGrowpassPoints(points) -- Add growpass points that can be spent on rewards

---

Block Hit Adjustment

player:adjustBlockHitCount(amount)
-- Adjust difficulty of breaking blocks.
-- 1 = harder to break (varies by block type)
-- -1 = easier to break
-- Range: -10 to +10
-- Note: -10 makes most blocks 1-hit breakable, +10 makes them much harder
-- Example: Digger's Spade increases by 1 for non-dirt blocks
-- (You must add your own saving if you want this to persist)

player:getAdjustedBlockHitCount() -- Get current adjusted hit count

---

Other Utilities

player:sendVariant({"OnTalkBubble", player:getNetID(), "Hi!", 0, 0})
player:sendVariant({"OnConsoleMessage", "Welcome!"})

player:sendAction("action|play_sfx\nfile|audio/sound.mp3\ndelayMS|0")

player:getWorld() -- Returns world or nil
player:disconnect() -- Kick player

getPlayerByName("Name")

local bytes = string.char(1,2,3,4)
player:sendRawPacket(bytes)

---

Country & Flags

player:setCountry("us") -- Sets player's country

player:setCountryFlagForeground(item_id)
player:getCountryFlagForeground()

player:setCountryFlagBackground(item_id)
player:getCountryFlagBackground()

---

Blessings

player:hasActiveBlessing(id)
player:hasBlessing(id)
player:addBlessing(id)
player:removeBlessing(id)

getBlessingName(id)
getBlessingInfo(id)
getBlessingRarity(id)

---

Moderation & Account Management

player:ban(length_seconds, reason, banned_by, shouldBanDevice, shouldBanIP)
-- length_seconds = 0 -> permanent
-- banned_by = player or nil

player:getIP()
player:getRID()
player:setPassword("new password")

player:getEmail()
player:getBackpackItems()
player:getGender()
player:getAltAccounts()

---

World & Access Tracking

player:getOwnedWorlds()
-- Returns list of world IDs that the player owns (using world locks and other locks that lock the entire world)

player:getRecentWorlds()
-- Returns list of world IDs that the player recently entered

player:getAccessWorlds()
-- Returns list of world IDs that the player has access to

player:getSmallLockedWorlds()
-- Returns list of world IDs that the player locked with small locks (SL, BL, HL, etc)

Example:

local owned = player:getOwnedWorlds()
for _, worldID in ipairs(owned) do
    print("Player owns world ID:", worldID)
end

---

Security & Login History

player:getIPHistory()
-- Returns list of IP addresses that recently were used to login into the account

player:getRIDHistory()
-- Returns list of RID addresses that recently were used to login into the account

---

Broadcast World

player:setBroadcastWorld(world_name)
-- Sets the broadcast world for this player (useful for custom broadcasts, /go command will work)

---

Extras

player:isFacingLeft()
player:getGuildID()
player:getHomeWorldID()
player:getTransformProfileButtons()
player:getClassicProfileContent(category, flags)
player:getClothingItemID()
player:getClothingItemID(PlayerClothes.CHANGETHIS)

player:getUnlockedAchievementsCount()
player:getAchievementsCount()
player:getBackpackUsedSize()

getAutofarm() -- Player autofarm status
setSlots(amount)