Sharp Aion2 Lua SDK
API reference

gameLua table

Read character and world values, and request game actions.

The game table is available in every script. Values that require a logged-in character or loaded world return nil, error while unavailable. A successful action call reports a local request; read the relevant value again to see its result.

Character

game.local_position()

Parameters: None. Returns: {x, y, z} in game world units, or nil, error.

game.local_health_fraction()

Parameters: None. Returns: Displayed health fraction from 0 to 1, or nil, error.

game.local_level()

Parameters: None. Returns: Displayed integer level, or nil, error.

game.local_name()

Parameters: None. Returns: Character name as UTF-8 text, or nil, error.

game.local_character_class()

Parameters: None. Returns: Character class code, or nil, error. Codes are 1 Novice, 2 Gladiator, 3 Templar, 4 Ranger, 5 Assassin, 6 Elementalist, 7 Sorcerer, 8 Cleric, and 9 Chanter.

game.local_pc_data_id()

Parameters: None. Returns: Character data identifier, or nil, error. It is distinct from the class code.

game.local_resource_text()

Parameters: None. Returns: {health, mana} strings as displayed by the game, or nil, error.

game.local_displayed_resources()

Parameters: None. Returns: {health={current, maximum}, mana={current, maximum}} with integer values when both displays use current / maximum, or nil, error.

local level, err = game.local_level()
if level == nil then
    log.warn(err)
else
    local position = game.local_position()
    if position then
        log.info(string.format("Level %d at %.0f, %.0f", level, position.x, position.y))
    end
end

Current world

game.current_level_name()

Parameters: None. Returns: Loaded level name as UTF-8 text, or nil, error. This is different from the numeric game map ID.

game.current_map_id()

Parameters: None. Returns: Positive numeric map ID, or nil, error.

game.current_area_id()

Parameters: None. Returns: Positive numeric area ID, or nil, error.

game.entities(radius, limit, filter)

Parameters: Optional radius defaults to 3000 world units and must be greater than 0 and at most 100000. Optional limit defaults to 128 and accepts 1–512. Optional filter is character, player, mob, npc, pet, object, loot, gatherable, or actor.

Returns: An array of records with id, name, kind, subkind, x, y, z, distance, and alive, or nil, error. Filtering happens before the result limit.

local mobs, err = game.entities(2500, 50, "mob")
if not mobs then
    log.warn(err)
else
    for _, mob in ipairs(mobs) do
        if mob.alive then log.info(mob.name) end
    end
end

The entities library provides nearest and living-character helpers.

Movement

game.clear_target()

Parameters: None. Returns: true when the clear request is sent, or nil, error. Read your target again after an action that depends on it.

game.request_path(x, y, z)

Parameters: Finite world coordinates. Returns: true when a path request is sent, or nil, error. Check position as movement continues.

game.path_destination()

Parameters: None. Returns: Current path destination as {x, y, z}, or nil, error when unavailable.

game.destination_marker()

Parameters: None. Returns: Tracked destination as {id, x, y, z}, or nil, error. Coordinates use world units.

game.popup_message_text()

Parameters: None. Returns: The text of a visible game message popup, or nil, error when no single message is available. This call only reads the text.

local destination = game.path_destination()
if destination then
    log.info(string.format("Path to %.0f, %.0f", destination.x, destination.y))
end

See configurable travel for a complete module.

Travel

game.is_teleport_unlocked(id)

Parameters: Destination ID from 1 to 2147483647. Returns: true or false, or nil, error for an invalid ID or unavailable destination list.

game.unlocked_dungeon_waypoints()

Parameters: None. Returns: An array of unlocked dungeon waypoint IDs in current list order, an empty array when none are unlocked, or nil, error when unavailable.

local unlocked, err = game.is_teleport_unlocked(12345)
if unlocked == nil then
    log.warn(err)
elseif unlocked then
    log.info("Destination unlocked")
end

Items and shortcuts

game.use_item(uid)

Parameters: A positive integer item UID. Returns: true when the client accepts the item-use request, or nil, error. Check the inventory afterward to see whether the item was consumed.

game.shortcut_press(slot)

Parameters: Integer slot from 0 to 59. Returns: true when the press edge is sent, or nil, error.

game.shortcut_release(slot)

Parameters: Integer slot from 0 to 59. Returns: true when the release edge is sent, or nil, error. A sent edge does not confirm skill activation.

game.place_skill(skill_id, slot, combo_index)

Parameters: Positive skill ID, slot from 0 to 255, and combo index from 0 to 3. Returns: true when the client accepts the request, or nil, error. Read the shortcut again to see whether it changed.

function on_start()
    local ok, err = script.start_worker(function()
        local pressed, pressError = game.shortcut_press(0)
        if not pressed then log.warn(pressError); return end
        script.sleep(50)
        local released, releaseError = game.shortcut_release(0)
        if not released then log.warn(releaseError) end
    end)
    if not ok then log.warn(err) end
end

Quests

game.active_quest_ids()

Parameters: None. Returns: Active quest IDs in current list order, an empty array when none are active, or nil, error.

game.available_quest_ids()

Parameters: None. Returns: Available quest IDs in current list order, an empty array when none are available, or nil, error.

game.completed_quest_ids()

Parameters: None. Returns: Completed quest IDs in current list order, an empty array when none are completed, or nil, error.

game.claim_quest(id)

Parameters: Quest ID from 1 to 4294967295. Returns: true when the client request finishes, or nil, error. Check the quest lists afterward.

game.execute_quest(id, track_id)

Parameters: Quest ID from 1 to 4294967295 and track ID from 0 to 4294967295. Returns: true when the client request finishes, or nil, error. Check quest progress afterward.

game.submit_quest(quest_uid, reward_index)

Parameters: Active quest UID from 1 to 2147483647 and reward index from -1 to 2147483647. Use -1 when no reward choice is needed. The UID differs from the quest ID.

Returns: true when the client accepts the request, or nil, error. Check the quest list afterward to confirm completion.

local available, err = game.available_quest_ids()
if not available then
    log.warn(err)
elseif #available > 0 then
    local requested, requestError = game.claim_quest(available[1])
    if not requested then log.warn(requestError) end
end

See the quest journal guide for a module that handles all three lists.