Skip to content

[Memhack] State Tracker

Jump to bottom
DasKeifer edited this page Sep 30, 2026 · 2 revisions

Memhack State Tracker

memhack.stateTracker supports change detection for pilots and level-up skills, and separates set values from memory values for skill bonuses so combining can work correctly.

Exposed as memhack.stateTracker.

For day to day modding you usually use PilotLvlUpSkill getters/setters (getHealthBonus / setHealthBonus, cores/grid/move, etc.). Those already call the set value APIs below and trigger Pilot:_combineBonuses() when a parent pilot exists. Call the state tracker directly only when you need the tracked set values themselves (for example debugging or custom combining).

Set vs Memory Values

When a pilot reaches level 2, cores/grid (and related) bonuses from both skills can be combined into skill 1 in memory for the actual game effect, while each skill still needs to remember what was set on it.

  • Set values - what external code should see for healthBonus, coresBonus, gridBonus, moveBonus (tracked in stateTracker._skillSetValues by skill address)
  • Memory values - what is actually written in the skill struct (may be the combined total on skill 1)

Public skill getters use getSkillSetValue so callers see the set value. Public setters call setSkillSetValue then pilot:_combineBonuses(), which writes the appropriate memory values. Raw memory access uses the hidden _get* / _set* getters/setters on PilotLvlUpSkill.

Table of Contents

Skill Set Value APIs

Change Tracking (internal)

State Tracker also captures/compares pilot and skill state, fires Events and Hooks, wraps hook firing for reentrancy, and cleans stale trackers. Those paths are used by memhack itself (for example on save / console toggle / game enter-leave). Most mods should subscribe to hooks rather than calling the tracker's change-check entry points.

getSkillSetValue

  • number memhack.stateTracker:getSkillSetValue(skill, field)
Argument name Type Description
skill PilotLvlUpSkill Skill struct
field string One of "healthBonus", "coresBonus", "gridBonus", "moveBonus"

Returns the tracked set value for that field if present. If not tracked yet, reads the raw memory value via "_" .. stdGetterName (for example _getCoresBonus), initializes the set-value tracker with it, and returns that memory value.

Example:

local skill = pilot:getLvlUpSkill(1)
local cores = memhack.stateTracker:getSkillSetValue(skill, "coresBonus")
-- Same result as skill:getCoresBonus() for normal use

setSkillSetValue

  • void memhack.stateTracker:setSkillSetValue(skill, field, value)
Argument name Type Description
skill PilotLvlUpSkill Skill struct
field string One of "healthBonus", "coresBonus", "gridBonus", "moveBonus"
value number Value external code should see for this field

Records the set value for the skill address. Does not write memory by itself - PilotLvlUpSkill setters call this, then _combineBonuses() (or the raw _set* path if there is no parent pilot) to update memory.

Example:

-- Prefer the skill setter so combining and hooks run:
skill:setCoresBonus(2)

-- Direct tracker write only updates the set-value map:
memhack.stateTracker:setSkillSetValue(skill, "coresBonus", 2)

getSkillSetValues

  • table memhack.stateTracker:getSkillSetValues(skill)
Argument name Type Description
skill PilotLvlUpSkill Skill struct

Returns a table of all tracked bonus set values (initializing from memory when a field was not yet tracked):

{
    healthBonus = ...,
    coresBonus = ...,
    gridBonus = ...,
    moveBonus = ...,
}

Example:

local skill = pilot:getLvlUpSkill(1)
local bonuses = memhack.stateTracker:getSkillSetValues(skill)
LOG("cores=" .. bonuses.coresBonus .. " grid=" .. bonuses.gridBonus)

Clone this wiki locally