Local Player

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

#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 the experience points earned within the current level.

#player:get_exp_percent() -> number

Returns progress through the current level as a percentage (0–100), derived from get_exp() and the current level. Returns 0 at max level.

#player:get_job() -> number

Returns the job ID.

#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.

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_sol_erda() -> number

Returns the amount of Sol Erda (the HEXA Matrix currency). Returns 0 if unavailable.

#player:get_position() -> table

Returns position as a table with x and y fields.

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

#player:get_server_position() -> table

Returns the position the server believes the character is at, as a table with x and y. Useful when client-side movement and the server's view can drift apart (e.g. during teleport/rush automation) — checks against this position survive a desync where get_position() would lie.

local sp = player:get_server_position()
-- sp.x, sp.y

#player:get_move_action() -> number

Returns the raw move action value for the character.

#player:is_left() -> boolean

Returns true when the character is currently facing left.

if player:is_left() then
    core.log("Facing left")
else
    core.log("Facing right")
end

#Hyperstats

#player:get_hyperstat_sp() -> number | nil

Returns the hyperstat skill points available on the currently active preset. Returns nil if no character data is available.

local sp = player:get_hyperstat_sp()

#Skill Points

#player:get_skill_sp(tier: number) -> number

Returns the skill points available to spend on the given job-advancement tier (the skill window's tab). Most modern jobs use per-tier Extended SP — each job advancement has its own pool — so a single SP value isn't enough; pass the tier you want.

• tier 0 = beginner skills (separate novice-SP pool)
• tier 1+ = 1st / 2nd / 3rd / 4th / 5th job advancements

local sp = player:get_skill_sp(4)  -- 4th job SP available

#player:level_up_skill(skill_id: number, count: number)

Sends a skill-up request, spending SP to raise skill_id by count levels. Server-validated (same path as the in-game + button), so invalid requests are simply rejected.

-- Auto-distribute a tier's available SP into one skill
local sp = player:get_skill_sp(4)
if sp > 0 then
    player:level_up_skill(target_skill_id, sp)
end

#Symbols

Arcane and Sacred symbols are individual equipped items, each with its own level and growth EXP. These return one entry per equipped symbol — unequipped region slots are skipped.

#Symbol Object Structure

#player:get_arcane_symbols() -> table<symbol>

Returns an array of the player's equipped Arcane symbols, in Arcane River region order.

#player:get_sacred_symbols() -> table<symbol>

Returns an array of the player's equipped Sacred (Authentic) symbols, in Grandis region order.

for _, sym in ipairs(player:get_arcane_symbols()) do
    if sym.can_level_up then
        core.log(("arcane #%d ready: lvl %d (%d/%d)"):format(
            sym.index, sym.level, sym.exp, sym.exp_to_next))
    end
end

#Buff Management

#Buff Object Structure

#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