Hexa Matrix

On this page

Return conventions
Data structures
Hexa cost
Hexa core
Hexa Stat line
Hexa Stat core
Reading Hexa Matrix state
Hexa Matrix actions
Complete example

The core.hexa module lets scripts inspect Hexa Matrix resources and cores, activate and upgrade cores, and inspect or activate Hexa Stat cores.

Return conventions

Read functions return their value directly. When the Hexa Matrix is unavailable or an argument is invalid, they return nil, error_message.

lua

local resources, err = core.hexa.get_resources()
if not resources then
    core.log("Unable to read the Hexa Matrix: " .. err)
    return
end

get_core() and get_stat_core() return nil without an error message when the requested ID is not available to the current character.

Actions return true when submitted successfully, or false, error_message when they cannot be submitted.

lua

local ok, err = core.hexa.upgrade_core(core_id)
if not ok then
    core.log("Unable to upgrade the Hexa core: " .. err)
end

Actions change live character data

Activating and upgrading cores are real actions. A true result means the action was submitted successfully, not that the character state has already changed. Submit one action at a time and confirm the result by reading the core again on a later on_tick.

IDs and target levels must be positive whole numbers.

Data structures

Hexa cost

Resource balances and action costs use the same structure.

Property	Type	Description
`sol_erda`	`number`	Amount of Sol Erda
`fragments`	`number`	Amount of Sol Erda Fragments

Hexa core

Returned by get_cores() and get_core().

Property	Type	Description
`id`	`number`	Core ID used by the other Hexa Matrix functions
`level`	`number`	Current level; `0` when the core is inactive
`max_level`	`number`	Maximum level
`type`	`string`	`"skill"`, `"mastery"`, `"enhancement"`, `"common"`, or `"unknown"`
`position`	`number`	Display position in the current job's Hexa Matrix
`active`	`boolean`	Whether the core is active
`skills`	`table<number>`	Skill IDs associated with the core; may be empty
`activation_cost`	`hexa_cost?`	Activation cost when available; omitted for active cores
`upgrade_cost`	`hexa_cost?`	Next-level cost when available; omitted for inactive or maxed cores

Hexa Stat line

Active Hexa Stat cores expose one main line and two additional lines.

Property	Type	Description
`type`	`string`	Stat name
`level`	`number`	Current level of the stat line

The supported stat names are:

Name	Stat
`critical_damage`	Critical Damage
`boss_damage`	Boss Damage
`ignore_defense`	Ignore Enemy Defense
`damage`	Damage
`attack_power`	Attack Power
`magic_attack`	Magic Attack
`main_stat`	Main Stat

Hexa Stat core

Returned by get_stat_cores() and get_stat_core().

Property	Type	Description
`id`	`number`	Core ID used by the Hexa Stat functions
`position`	`number`	Display position in the Hexa Matrix
`level`	`number`	Combined level of all three stat lines; `0` when inactive
`max_level`	`number`	Maximum combined level
`active`	`boolean`	Whether the core is active
`activation_cost`	`hexa_cost?`	Activation cost; present for an inactive core when available
`selected_slot`	`number?`	Selected zero-based configuration index; present when active
`main`	`hexa_stat_line?`	Main stat line; present when active
`additional`	`table<hexa_stat_line>?`	Two additional stat lines; present when active

Hexa Stat support currently covers inspection and activation. Upgrading, resetting, changing stat lines, and switching configurations are not exposed by core.hexa.

Reading Hexa Matrix state

`core.hexa.get_resources() -> hexa_cost | nil, string?`

Returns the character's current Sol Erda and Sol Erda Fragment balances.

lua

local resources, err = core.hexa.get_resources()
if resources then
    core.log(string.format(
        "Hexa resources: %d Sol Erda, %d Fragments",
        resources.sol_erda,
        resources.fragments
    ))
else
    core.log(err)
end

`core.hexa.get_cores() -> table<hexa_core> | nil, string?`

Returns every Hexa core available to the current job, including inactive cores.

lua

local cores, err = core.hexa.get_cores()
if not cores then
    core.log(err)
    return
end

for _, hexa_core in ipairs(cores) do
    core.log(string.format(
        "%d: %s level %d/%d%s",
        hexa_core.id,
        hexa_core.type,
        hexa_core.level,
        hexa_core.max_level,
        hexa_core.active and "" or " (inactive)"
    ))
end

`core.hexa.get_core(core_id: number) -> hexa_core | nil, string?`

Returns one Hexa core by ID.

lua

-- Use an ID returned by get_cores().
local hexa_core, err = core.hexa.get_core(core_id)
if hexa_core then
    core.log("Core level: " .. hexa_core.level)
elseif err then
    core.log(err)
end

`core.hexa.get_upgrade_cost(core_id: number, target_level?: number) -> hexa_cost | nil, string?`

Returns the total cost to upgrade an active core from its current level to the absolute target_level. Omit target_level to get the next-level cost. The target must be above the current level and no higher than max_level.

lua

-- Use an active core ID returned by get_cores().
local cost, err = core.hexa.get_upgrade_cost(core_id)
if cost then
    core.log(string.format(
        "Next level costs %d Sol Erda and %d Fragments",
        cost.sol_erda,
        cost.fragments
    ))
else
    core.log(err)
end

`core.hexa.get_stat_cores() -> table<hexa_stat_core> | nil, string?`

Returns every Hexa Stat core available to the character, including inactive cores.

lua

local stat_cores, err = core.hexa.get_stat_cores()
if not stat_cores then
    core.log(err)
    return
end

for _, stat_core in ipairs(stat_cores) do
    core.log(string.format(
        "%d: level %d/%d%s",
        stat_core.id,
        stat_core.level,
        stat_core.max_level,
        stat_core.active and "" or " (inactive)"
    ))
end

`core.hexa.get_stat_core(core_id: number) -> hexa_stat_core | nil, string?`

Returns one Hexa Stat core by ID.

lua

-- Use an ID returned by get_stat_cores().
local stat_core, err = core.hexa.get_stat_core(core_id)
if stat_core and stat_core.active then
    core.log("Main Hexa Stat: " .. stat_core.main.type)
elseif err then
    core.log(err)
end

Hexa Matrix actions

Actions validate the core's current state, prerequisites, and required resources before submission.

`core.hexa.activate_core(core_id: number) -> boolean, string?`

Activates an eligible, inactive Hexa core.

lua

-- Set this from a core selected through get_cores().
local selected_core_id = nil

if selected_core_id then
    local ok, err = core.hexa.activate_core(selected_core_id)
    if not ok then core.log(err) end
end

`core.hexa.upgrade_core(core_id: number, target_level?: number) -> boolean, string?`

Upgrades an active Hexa core to the absolute target_level. Omit target_level to upgrade by one level. A target may span multiple levels.

lua

-- Set this from a core selected through get_cores().
local selected_core_id = nil

if selected_core_id then
    local ok, err = core.hexa.upgrade_core(selected_core_id)
    if not ok then core.log(err) end
end

`core.hexa.activate_stat_core(core_id: number, main_type: string, additional_type_1: string, additional_type_2: string) -> boolean, string?`

Activates an eligible, inactive Hexa Stat core with the selected main and additional stat types. Each stat type must use one of the names listed under Hexa Stat line.

lua

-- Set this from a core selected through get_stat_cores().
local selected_stat_core_id = nil

if selected_stat_core_id then
    local ok, err = core.hexa.activate_stat_core(
        selected_stat_core_id,
        "main_stat",
        "critical_damage",
        "boss_damage"
    )
    if not ok then core.log(err) end
end

Complete example

This read-only example prints Hexa resources, cores, next-level costs, and Hexa Stat cores without changing anything.

lua

local resources, resources_err = core.hexa.get_resources()
if not resources then
    core.log(resources_err)
    return
end

core.log(string.format(
    "Hexa resources: %d Sol Erda, %d Fragments",
    resources.sol_erda,
    resources.fragments
))

local cores, cores_err = core.hexa.get_cores()
if not cores then
    core.log(cores_err)
    return
end

for _, hexa_core in ipairs(cores) do
    core.log(string.format(
        "[%d] %s %d/%d%s",
        hexa_core.id,
        hexa_core.type,
        hexa_core.level,
        hexa_core.max_level,
        hexa_core.active and "" or " (inactive)"
    ))

    if hexa_core.upgrade_cost then
        core.log(string.format(
            "  Next level: %d Sol Erda, %d Fragments",
            hexa_core.upgrade_cost.sol_erda,
            hexa_core.upgrade_cost.fragments
        ))
    end
end

local stat_cores, stat_err = core.hexa.get_stat_cores()
if not stat_cores then
    core.log(stat_err)
    return
end

for _, stat_core in ipairs(stat_cores) do
    core.log(string.format(
        "[Stat %d] %d/%d%s",
        stat_core.id,
        stat_core.level,
        stat_core.max_level,
        stat_core.active and "" or " (inactive)"
    ))

    if stat_core.active then
        core.log(string.format(
            "  Main: %s level %d",
            stat_core.main.type,
            stat_core.main.level
        ))

        for _, stat_line in ipairs(stat_core.additional) do
            core.log(string.format(
                "  Additional: %s level %d",
                stat_line.type,
                stat_line.level
            ))
        end
    end
end

#Return conventions

#Data structures

#Hexa cost

#Hexa core

#Hexa Stat line

#Hexa Stat core

#Reading Hexa Matrix state

#core.hexa.get_resources() -> hexa_cost | nil, string?

#core.hexa.get_cores() -> table<hexa_core> | nil, string?

#core.hexa.get_core(core_id: number) -> hexa_core | nil, string?

#core.hexa.get_upgrade_cost(core_id: number, target_level?: number) -> hexa_cost | nil, string?

#core.hexa.get_stat_cores() -> table<hexa_stat_core> | nil, string?

#core.hexa.get_stat_core(core_id: number) -> hexa_stat_core | nil, string?

#Hexa Matrix actions

#core.hexa.activate_core(core_id: number) -> boolean, string?

#core.hexa.upgrade_core(core_id: number, target_level?: number) -> boolean, string?

#core.hexa.activate_stat_core(core_id: number, main_type: string, additional_type_1: string, additional_type_2: string) -> boolean, string?

#Complete example