Local Player

The Player object represents the local player character. Provides access to stats, buffs, position, and other player data.

Always Validate

Call player:is_valid() before using any other methods. Player objects can become invalid at any time.

Functions

Validation

player:is_valid() -> boolean

Validates the object exists in the game world. Always call this first.

local player = core.object_manager.get_local_player()
if not player or not player:is_valid() then
    return  -- Exit early
end

---

Basic Information

player:get_id() -> number

Returns the character ID.

player:get_name() -> string

Returns the character name.

player:get_level() -> number

Returns the character level.

player:get_exp() -> number

Returns current experience points.

player:get_job() -> number

Returns the job ID.

Common Job IDs

Job ID	Class
0	Beginner
100	Warrior
200	Magician
300	Bowman
400	Thief
500	Pirate

---

Health & Mana

player:get_health() -> number

Returns current HP.

player:get_max_health() -> number

Returns maximum HP.

player:get_mana() -> number

Returns current MP.

player:get_max_mana() -> number

Returns maximum MP.

HP/MP Percentage

local hp_percent = (player:get_health() / player:get_max_health()) * 100
if hp_percent < 50 then
    core.input.use_item(2000001)  -- Use HP potion
end

---

Currency & Position

player:get_meso() -> number

Returns the amount of meso (currency).

player:get_position() -> table

Returns position as a table with x and y fields.

local pos = player:get_position()
-- pos.x, pos.y

---

Buff Management

Buff Object Structure

Property	Type	Description
id	number	Unique buff identifier
type	number	Buff type identifier
name	string	Readable buff name
time_remaining	number	Milliseconds remaining

player:has_buff(buff_id: number) -> boolean

Returns true if the buff is currently active. More efficient than iterating get_buffs().

player:get_buff(buff_id: number) -> buff | nil

Returns a specific buff object if active, or nil if not found.

player:get_buffs() -> table<buff>

Returns all active buffs as an array.

Example

-- Maintain buff and monitor HP
local MAGIC_GUARD = 2001002

function on_tick()
    local player = core.object_manager.get_local_player()
    if not player or not player:is_valid() then return end

    -- HP monitoring
    local hp_percent = (player:get_health() / player:get_max_health()) * 100
    if hp_percent < 30 then
        core.input.use_item(2000001)  -- Red Potion
    end

    -- Buff maintenance
    if not player:has_buff(MAGIC_GUARD) then
        if not core.skill_book.is_skill_on_cooldown(MAGIC_GUARD) then
            core.input.use_skill(MAGIC_GUARD)
        end
    end
end