Player Object Documentation

player:getGems() -- Returns the player's gems count.
player:addGems(amount, sendPacket:optional, isDisplay:optional) -- Adds gems to the player.
player:removeGems(amount, sendPacket:optional, isDisplay:optional) -- Removes gems from the player.
player:setGems(number) -- Sets the player's gems count.
player:getCoins() -- Returns the player's premium currency count.
player:addCoins(amount, sendPacket:optional) -- Adds premium currency to the player.
player:removeCoins(amount, sendPacket:optional) -- Removes premium currency from the player.
player:setCoins(number) -- Sets the player's premium currency count.
player:getBankBalance() -- Returns bank balance.
player:addBankBalance(amount) -- Adds to bank balance.
player:setBankBalance(number) -- Sets bank balance.
player:removeBankBalance(amount) -- Removes from bank balance.

player:getInventorySize() -- Returns the player's inventory size.
player:isMaxInventorySpace() -- Returns true if inventory is full.
player:upgradeInventorySpace(amount) -- Increases inventory slots.
player:getItemAmount(itemID) -- Returns the count of a specific item.
player:changeItem(itemID, amount, sendPacket) -- Adds/removes an item.
player:getInventoryItems() -- Returns table of all inventory items.
player:getBackpackItems() -- Returns the items in the player's backpack.
player:getBackpackUsedSize() -- Returns backpack used slots.

player:getClothingItemID(slot) -- Returns the item ID equipped in the specified clothing slot.

player:getGems()
player:getCoins()
player:getUnlockedAchievementsCount()
player:getAchievementsCount()
player:isFacingLeft()
player:isOnline()
player:getGameVersion() -- Returns the player's game version as a float (e.g., 3.02).

player:onConsoleMessage(message) -- send console message to the player.
player:onTalkBubble(netID, message, isApi) -- Show a talk bubble, netID set to player:getNetID() if you want only you can see isApi = 0 is false and 1 is true.
player:onDialogRequest(dialog) -- Opens a dialog.
player:setNextDialogRGBA(r, g, b, a) -- Change dialog background color.
player:setNextDialogBorderRGBA(r, g, b, a) -- Change dialog border color.
player:resetDialogColor() -- Reset dialog color to default.
player:onTextOverlay(text) -- Displays overlay text.

player:onTradeScanUI()
player:onGrow4GoodUI()
player:onGuildNotebookUI()
player:onGrowmojiUI()
player:onGrowpassUI()
player:onNotebookUI()
player:onBillboardUI()
player:onPersonalizeWrenchUI()
player:onOnlineStatusUI()
player:onFavItemsUI()
player:onCoinsBankUI()
player:onUnlinkDiscordUI()
player:onLinkDiscordUI()
player:onClothesUI(targetPlayer)
player:onAchievementsUI(targetPlayer)
player:onTitlesUI(targetPlayer)
player:onWrenchIconsUI(targetPlayer)
player:onNameIconsUI(targetPlayer)
player:onVouchersUI()
player:onMentorshipUI()
player:onBackpackUI(targetPlayer)
player:onStorePurchaseResult()
player:onRedeemMenu()
player:onGrow4GoodDonate()

player:playAudio("audio.wav") -- Plays an audio file.
player:setNickname(name) -- Sets the player's display name (now supports colors, spaces, '@', saved on relog).
player:resetNickname() -- Resets the player's display name to their original name.
player:doAction(actionString) -- Sends a packet on behalf of the player (server thinks player sent it).

player:hasRole(roleID) -- Checks if player has role.
player:setRole(roleID) -- Sets player's role (replaces existing role).
player:hasTitle(id) -- Check if the player has a title.
player:addTitle(id) -- Adds a title to the player.
player:removeTitle(id) -- Removes title from the player.
player:getActiveTitles() -- Returns the players active titles.
player:sendAction("action|play_sfx\nfile|audio/blabla.mp3\ndelayMS|0")
player:sendVariant({"OnTalkBubble", player:getNetID(), "Hello", 0, 0})
player:sendVariant({"OnConsoleMessage", "Hello"})
player:sendVariant({"OnConsoleMessage", "Hello"}, delay, netID)

player:getRoleQuestLevel(type) -- Returns the role quest level for the given type.
player:setRoleQuestLevel(type, level) -- Sets the role quest level for the given type.

player:doAction(actionString)

-- Make player say something
player:doAction("action|input\n|text|Hello world!")
 
-- Make player use a dialog
player:doAction("action|dialog_return\ndialog_name|custom_dialog\nbuttonClicked|accept_button\n")
 
-- Make player redeem a code via dialog
player:doAction("action|dialog_return\ndialog_name|redeem_code\nbuttonClicked|redeem_code_button\nredeemcode|MYCODE123\n")
 
-- Trigger player actions
player:doAction("action|wrench\ntarget_userID|123\n")

onPlayerCommandCallback(function(world, player, fullCommand)
    local command, code = fullCommand:match("^(%S+)%s*(.*)")
    if command == "/autoredeem" then
        if code == "" then
            player:onConsoleMessage("`4Please provide a code!")
            return true
        end
        
        -- Make the player redeem the code automatically
        player:doAction(
            "action|dialog_return\n" ..
            "dialog_name|redeem_code\n" ..
            "buttonClicked|redeem_code_button\n" ..
            "redeemcode|" .. code .. "\n"
        )
        
        return true
    end
    return false
end)

player:getWorld() -- Returns the current World object or nil.
player:getWorldName() -- Returns the current worldName as a string.
player:enterWorld(worldName, doorID) -- Enters specified world, optional doorID for spawn location.
player:disconnect() -- Disconnects the player from server.
player:setBroadcastWorld(worldName) -- Sets broadcast world for this player (/go will work).

player:getNetID() -- Returns the player's net ID.
player:getUserID() -- Returns the player's user ID.
player:getName() -- Returns the player's display name.
player:getCleanName() -- Returns the player's clean name.
player:getRealName() -- Returns the real name of a player even if they are using a nickname.
player:getRealCleanName() -- Returns the real name without colors, even if using nickname.
player:getEmail() -- Returns the player's email address.
player:getGender() -- Returns the player's gender (0 = Male, 1 = Female).
player:getCountry() -- Returns player's country (string, online only).
player:setCountry(country) -- Sets the player's country code (e.g., "US", "GB").
player:getCountryFlagBackground() -- Returns the country flag background item ID.
player:getCountryFlagForeground() -- Returns the country flag foreground item ID.
player:setCountryFlagBackground(item_id) -- Sets the country flag background item (0 = none).
player:setCountryFlagForeground(item_id) -- Sets the country flag foreground item (0 = none).
player:getPlatform() -- Returns player's platform ID (0=Windows, 1=iOS, 2=MacOS, 4=Android).
player:getPlaytime() -- Returns the player's total playtime in seconds.
player:getDiscordID() -- Returns the player's Discord ID.
player:getDiscordInvites() -- Returns the player's Discord invite count/data.
player:getAccountCreationDateStr() -- Returns account creation date.
player:getType() -- Returns the player's type. Non-zero means it is an NPC.
player:hasGrowID() -- Returns true if player has a GrowID.

player:getOwnedWorlds() -- Returns table of world IDs that player owns (with world locks).
player:getRecentWorlds() -- Returns table of world IDs that player recently entered.
player:getAccessWorlds() -- Returns table of world IDs that player has access to.
player:getSmallLockedWorlds() -- Returns table of world IDs locked by player with small locks (SL, BL, HL, etc).

player:getIPHistory() -- Returns table of strings (IP addresses recently used to login).
player:getRIDHistory() -- Returns table of strings (RID addresses recently used to login).
player:getAltAccounts() -- Returns an array of the player's known alternate accounts.

player:setAAPEnabled(1) -- Enable AAP (1 = enable, 0 = disable).

-- Enable AAP for a player
if player:getDiscordID() then
    player:setAAPEnabled(1)
    player:onConsoleMessage("`2AAP has been enabled for your account!")
else
    player:onConsoleMessage("`4You must link Discord before enabling AAP!")
end

player:getFriends() -- Returns table of friend user IDs (numbers).
player:addFriend(targetPlayer) -- Adds a friend (bidirectional, updates both players).
player:removeFriend(targetPlayer) -- Removes a friend (bidirectional, updates both players).

player:getLifeGoals() -- Returns table of life goal task objects.
player:getBiweeklyQuests() -- Returns table of biweekly quest task objects.
getJimDailyQuest() -- (Global function) Returns Jim's daily quest object (same for everyone).

lifeGoal.taskID
lifeGoal.taskTargetValue
lifeGoal.taskCompletedValue
lifeGoal.taskReward
lifeGoal.deliverItem
lifeGoal.rewardAmount
lifeGoal.claimed
lifeGoal.givenup
lifeGoal.completed
lifeGoal.lastAnnouncePercentage

jimDaily.firstItemID
jimDaily.firstItemCount
jimDaily.secondItemID
jimDaily.secondItemCount
jimDaily.completedPlayers -- Table of user IDs who completed it

player:getPing() -- Returns player's ping in milliseconds.

player:getMod(modID) -- Returns player's mod status.
player:addMod(modID, durationSeconds) -- Adds a mod/buff to the player.
player:removeMod(modID) -- Removes a mod/buff from the player.
player:getHomeWorldID() -- Returns player's home world ID.
player:getOnlineStatus() -- Returns online status.
player:getGuildID() -- Returns guild ID.
player:getTransformProfileButtons() -- Returns transform profile buttons.

player:getLevel() -- Returns the player's current level.
player:setLevel(level) -- Sets the player's level directly.
player:addLevel(amount) -- Adds a specified number of levels to the player.
player:removeLevel(amount) -- Removes a specified number of levels from the player.
player:setXP(amount) -- Sets the player's XP directly.
player:removeXP(amount) -- Removes XP from the player. To add XP, use world:addXP(player, amount).

local sub = player:getSubscription(1) -- Returns subscription object or nil
 
if sub ~= nil then
    -- Player has this subscription type
end

sub:getType() -- Returns the subscription type ID.
sub:getExpireTime() -- Returns expiration timestamp (seconds).
sub:getActivationTime() -- Returns activation timestamp (seconds).
sub:isPermanent() -- Returns true if subscription is permanent.
sub:getNextRewardTime() -- Returns next reward timestamp (seconds).
 
-- Modification methods
sub:setExpireTime(timestamp) -- Set new expiration time (seconds).
sub:setNextRewardTime(timestamp) -- Set next reward time (seconds).

local sub = player:addSubscription(type, expire_timestamp_seconds)
-- If expire_timestamp_seconds is 0, the subscription is permanent

-- Check if player is a supporter
if player:getSubscription(0) ~= nil then
    player:onConsoleMessage("You are a supporter!")
end
 
-- Add a 30-day subscription
local currentTime = os.time()
local expireTime = currentTime + (30 * 24 * 60 * 60) -- 30 days
local sub = player:addSubscription(3, expireTime) -- TYPE_MONTH_SUBSCRIPTION
 
-- Modify existing subscription
local sub = player:getSubscription(4) -- Get GrowPass
if sub ~= nil then
    sub:setExpireTime(os.time() + (365 * 24 * 60 * 60)) -- Extend by 1 year
    
    -- If player is offline, manually save them
    if not player:isOnline() then
        savePlayer(player)
    end
end

player:getItemEffects() -- Returns table with combined buffs from all equipped clothes.

local effects = player:getItemEffects()
 
player:onConsoleMessage("Your total bonuses:")
player:onConsoleMessage("Extra gems: " .. effects.extra_gems .. "%")
player:onConsoleMessage("Extra XP: " .. effects.extra_xp .. "%")
player:onConsoleMessage("Break range: +" .. effects.break_range)
player:onConsoleMessage("Build range: +" .. effects.build_range)
 
if effects.one_hit then
    player:onConsoleMessage("One-hit break: ACTIVE")
end

player:getTitles() -- Returns array of titles the player owns.

local titles = player:getTitles()
 
player:onConsoleMessage("You have " .. #titles .. " titles:")
 
for i, title in ipairs(titles) do
    if title.isActive then
        player:onConsoleMessage("→ " .. title.titleName .. " (ACTIVE)")
    else
        player:onConsoleMessage("  " .. title.titleName)
    end
end

player:getClassicProfileContent(category, flags)

player:getDungeonScrolls() -- Returns how many dungeon scrolls the player has.
player:setDungeonScrolls(number) -- Sets dungeon scrolls (max 255).

player:addBlessing(blessing_id) -- Adds a blessing to the player.
player:removeBlessing(blessing_id) -- Removes a blessing from the player.
player:hasBlessing(blessing_id) -- Returns true if the player has the blessing (regardless of power orb state).
player:hasActiveBlessing(blessing_id) -- Returns true if the player has the blessing and it is currently active (power orb state matters).

player:addMail(mailDataTable) -- Adds a new mail to the player's mailbox.
player:clearMailbox() -- Clears all mail from the player's mailbox.

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

player:adjustBlockHitCount(amount) -- Adjust block break difficulty (-10 to +10).
player:getAdjustedBlockHitCount() -- Get current adjustment value.

player:setStats(type, amount) -- Sets player statistics.
player:setStats(jsonString) -- Sets player statistics from JSON string.

-- Set specific stat
player:setStats(0, 100) -- Set stat type 0 to 100
 
-- Set multiple stats using JSON
local statsJSON = json.encode({
    gems = 5000,
    coins = 10000,
    level = 50
})
player:setStats(statsJSON)

player:setPassword(newPassword) -- Changes the player's password.
player:checkPassword(passwordString) -- Returns true if the string matches the player's current password.

-- Change player password
player:setPassword("NewSecurePassword123")
player:onConsoleMessage("`2Your password has been changed!")

player:addNote("Some note text") -- Adds an account note (visible in punishment UI).
player:addMod(GAME_BAN, 60) -- Bans player for 60 seconds (0 = permanent).
player:ban(length_seconds, reason, banned_by_player, ban_device, ban_ip) -- Bans the player. If length_seconds is 0 the ban is permanent. ban_device and ban_ip are 0 or 1 flags.

function handleMyGazetteDialogResponse(world, player, data)
    if data["buttonClicked"] == "test" then
        player:onConsoleMessage("tada!")
    end
end
 
player:onDialogRequest(
    "set_default_color|`o\n" ..
    "add_button|test|Test Button|left|\n" ..
    "end_dialog|my_gazette|||",
    0, -- delay (optional)
    handleMyGazetteDialogResponse -- callback (optional)
)