[Memhack] Pilot - Redacted-Rice/ITB-RedactedRiceExts GitHub Wiki

Memhack Pilot

The Memhack Pilot struct represents a pilot in game memory and provides access to pilot data.

It has the standard memhack base struct functions/fields

Note: Pointers to pilots in the game seem to use smart pointers which are "double" pointers in memory. To properly set a pilot pointer, you would need to changed both. This is possible but not implemented yet so you should see no setters for pointers to pilot in any of the structs. I have not had a reason to need to set pilots yet

Table of Contents

Data

Field Type Offset Description
name ItBString | [memhack] ItBString 0x14 The displayed name of the Pilot in game. E.g. "Pilot_Original_Name" or "John Doe"
xp int 0x30 The current xp of the pilot
levelUpXp int 0x34 The amount of xp needed to level up
level int 0x5C The current level of the pilot
skill ItBString | [memhack] ItBString 0x60 The skill Id of the pilots unique skill. E.g. "Extra_XP"
id ItBString | [memhack] ItBString 0x78 The ID of the pilot. E.g. "Pilot_Original"
personality ItBString | [memhack] ItBString 0x94 Personality string of the pilot that determines what dialog is used E.g. "Original"
sex int (enum) 0xC8 Sex enum value of pilot. SEX_MALE (0), SEX_FEMALE(1), SEX_AI(2), SEX_VEK (3)
lvlUpSkills PilotLvlUpSkillsArray | [memhack] PilotLvlUpSkillsArray 0xCC Selected level up skills of the pilot
power Vector | [Memhack] Vector 0x24C Innate skill power-core vector (noSetter on the field - use getPowerList / setPowerList / setPowerListSlot). Elements are memhack.CORE_TYPE_*.
prevTimelines int 0x27C How many timelines they have been in

Data Functions

These are functions that draw from the data in the struct or set the data in the struct

Game Functions

These are functions that are implemented for this struct but are not primarily about retrieving/setting information in this struct

Other Functions

There are a number of private and internal functions. These should generally be avoided outside of memhack

getName

  • ItBString Pilot:getName()

Returns the pilot's name as an ItBString struct. Use :get() to extract the string, or use the convenience wrapper getNameStr().

Example:

local pilot = pawn:GetPilot()
local nameStruct = pilot:getName()
local nameStr = nameStruct:get()
-- Or use in string concatenation (uses __tostring):
LOG("Pilot name: " .. pilot:getName())

getNameStr

  • string Pilot:getNameStr()

Convenience wrapper that returns the pilot's name as a string directly.

Example:

local pilot = pawn:GetPilot()
LOG("Pilot name: " .. pilot:getNameStr())

setName

  • void Pilot:setName(name)
Argument name Type Description
name string or ItBString The new name

Sets the pilot's display name.

Example:

pilot:setName("New Name")

getXp

  • number Pilot:getXp()

Returns the pilot's current experience points within their current level.

Example:

local xp = pilot:getXp()
LOG("Current XP: " .. xp .. "/" .. pilot:getLevelUpXp())

setXp

  • void Pilot:setXp(xp)
Argument name Type Description
xp int The new XP value

Sets the pilot's current XP. Automatically handles level-ups when XP reaches the required amount, and level-downs when XP becomes negative.

Example:

pilot:setXp(75)  -- Set to 75 XP, will level up if >= levelUpXp

addXp

  • void Pilot:addXp(amount)
Argument name Type Description
amount int The amount of XP to add

Adds the specified amount of XP to the pilot. Automatically handles level-ups.

Example:

pilot:addXp(25)  -- Add 25 XP

getLevelUpXp

  • number Pilot:getLevelUpXp()

Returns the amount of XP required to level up from the current level.

Example:

local needed = pilot:getLevelUpXp()
LOG("XP needed to level up: " .. needed)

getLevel

  • number Pilot:getLevel()

Returns the pilot's current level (0-2).

Example:

local level = pilot:getLevel()
LOG("Pilot level: " .. level)

setLevel

  • void Pilot:setLevel(level)
Argument name Type Description
level int The target level (0-2)

Sets the pilot's level. Automatically adjusts XP and fires appropriate hooks. Calls levelUp or levelDown as needed to reach the target level.

Example:

pilot:setLevel(2)  -- Set to max level

levelUp

  • void Pilot:levelUp()

Increases the pilot's level by 1 if not already at max level (2). Resets XP to 0 and recalculates bonuses.

Example:

pilot:levelUp()

levelDown

  • void Pilot:levelDown()

Decreases the pilot's level by 1 if not already at level 0. Resets XP to 0 and recalculates bonuses.

Example:

pilot:levelDown()

getSkill

  • ItBString Pilot:getSkill()

Returns the pilot's starting skill as an ItBString struct.

Example:

local skill = pilot:getSkill()
LOG("Pilot's starting skill: " .. skill)  -- Uses __tostring

getSkillStr

  • string Pilot:getSkillStr()

Convenience wrapper that returns the pilot's starting skill as a string directly.

Example:

local skillStr = pilot:getSkillStr()
LOG("Pilot's starting skill: " .. skillStr)

setSkill

  • void Pilot:setSkill(skillId)
Argument name Type Description
skillId string or ItBString The skill ID

Sets the pilot's starting skill.

Example:

pilot:setSkill("Extra_XP")

getId

  • ItBString Pilot:getId()

Returns the pilot's ID as an ItBString struct.

Example:

local id = pilot:getId()
LOG("Pilot ID: " .. id)  -- Uses __tostring

getIdStr

  • string Pilot:getIdStr()

Convenience wrapper that returns the pilot's ID as a string directly.

Example:

local idStr = pilot:getIdStr()
LOG("Pilot ID: " .. idStr)

setId

  • void Pilot:setId(id)
Argument name Type Description
id string or ItBString The pilot ID

Sets the pilot's unique ID.

Example:

pilot:setId("Pilot_Custom")

getPersonality

  • ItBString Pilot:getPersonality()

Returns the pilot's Personality as an ItBString struct.

Example:

local personality = pilot:getPersonality()
LOG("Pilot Personality: " .. personality)  -- Uses __tostring

getPersonalityStr

  • string Pilot:getPersonalityStr()

Convenience wrapper that returns the pilot's personality as a string directly.

Example:

local personalityStr = pilot:getPersonalityStr()
LOG("Pilot Personality: " .. personalityStr)

getSex

  • int (enum) Pilot:getSex()

Returns the pilot's sex enum value. Valid values: SEX_MALE (0), SEX_FEMALE(1), SEX_AI(2), SEX_VEK (3)

This seems to only be used on start up for assigning names for "generic" pilots. Maybe is used in some dialogs as well?

Note: This is not saved and is re-generated on load. A generic pilot may change sexes if you relaunch the game.

Example:

local level = pilot:getLevel()
LOG("Pilot level: " .. level)

getLvlUpSkill

  • PilotLvlUpSkill Pilot:getLvlUpSkill(index)
Argument name Type Description
index int The skill index (1 or 2)

Returns the pilot's level-up skill at the specified index. Index must be 1 or 2.

Example:

local skill1 = pilot:getLvlUpSkill(1)
local skill2 = pilot:getLvlUpSkill(2)

LOG("Skill 1: " .. skill1:getId())
LOG("Skill 2: " .. skill2:getId())

getLvlUpSkills

  • PilotLvlUpSkillsArray Pilot:getLvlUpSkills()

Returns the array containing the pilot's level-up skills as a wrapped struct.

Example:

local skillsArray = pilot:getLvlUpSkills()
local skill1 = skillsArray:getSkill1()

getLvlUpSkillsPtr

  • number Pilot:getLvlUpSkillsPtr()

Returns the raw pointer value to the skills array. Use getLvlUpSkills() instead unless you specifically need the raw pointer.

Example:

local ptr = pilot:getLvlUpSkillsPtr()
LOG(string.format("Skills array pointer: 0x%X", ptr))

setLvlUpSkill

  • void Pilot:setLvlUpSkill(index, skill)
Argument name Type Description
index int The skill index (1 or 2)
skill PilotLvlUpSkill or table The skill struct or a table of field values

Sets the pilot's level-up skill at the specified index.

Example:

-- Set using a table of values
pilot:setLvlUpSkill(1, {
    id = "Move",
    shortName = "Pilot_MoveShort",
    fullName = "Pilot_MoveName",
    description = "Pilot_MoveDesc",
    moveBonus = 1,
    saveVal = 1
})

setLvlUpSkillsPtr

  • void Pilot:setLvlUpSkillsPtr(ptr)
Argument name Type Description
ptr int Pointer to skills array

Sets the raw pointer to the skills array. For internal use only - modifying this incorrectly can corrupt memory.

Example:

-- Don't use this unless you know what you're doing
pilot:setLvlUpSkillsPtr(0x12345678)

getPower

  • Vector Pilot:getPower()

Returns the innate skill power-core Vector at offset 0x24C (noSetter on the field - modify via the list helpers below). Elements are Core Types defined in Constants .

Prefer getPowerList / setPowerList / setPowerListSlot for normal use.

getPowerList

  • table or nil Pilot:getPowerList()

Returns a 1-indexed Lua list of memhack.CORE_TYPE_* ints from the power vector, or nil if the vector is unavailable. Does not grow the vector. memhack.CORE_TYPE_* are defined in Constants

Example:

local power = pilot:getPowerList()
if power then
    for i, coreType in ipairs(power) do
        LOG(string.format("Power slot %d = %d", i, coreType))
    end
end

setPowerList

  • boolean Pilot:setPowerList(values)
Argument name Type Description
values table List of memhack.CORE_TYPE_* ints. #values must match the live vector size

Writes the full power list. Returns false if the vector is missing, values is not a table, or the size does not match. Does not grow or shrink the vector. memhack.CORE_TYPE_* are defined in Constants

Example:

local power = pilot:getPowerList()
if power and #power >= 1 then
    power[1] = memhack.CORE_TYPE_SKILL_BONUS
    pilot:setPowerList(power)
end

setPowerListSlot

  • boolean Pilot:setPowerListSlot(slotIndex, value)
Argument name Type Description
slotIndex int 1-based index into the power vector
value int memhack.CORE_TYPE_*

Sets a single slot. Returns false if the vector is missing or the index is out of range. Does not grow the vector. memhack.CORE_TYPE_* are defined in Constants

Example:

pilot:setPowerListSlot(1, memhack.CORE_TYPE_SKILL_BONUS)

getPrevTimelines

  • number Pilot:getPrevTimelines()

Returns the number of previous timelines the pilot has been in.

Example:

local timelines = pilot:getPrevTimelines()
LOG("Previous timelines: " .. timelines)

setPrevTimelines

  • void Pilot:setPrevTimelines(timelines)
Argument name Type Description
timelines int The number of previous timelines

Sets the number of previous timelines for the pilot.

Example:

pilot:setPrevTimelines(5)

getPawnId

  • number Pilot:getPawnId()

Returns the pawn ID (0-2) for the mech this pilot is currently piloting. Returns nil if the pilot is not currently piloting a mech.

Example:

local pawnId = pilot:getPawnId()
if pawnId then
    LOG("Pilot is in mech " .. pawnId)
else
    LOG("Pilot is in storage")
end

isPiloting

  • boolean Pilot:isPiloting()

Returns true if the pilot is currently piloting a mech, false otherwise.

Example:

if pilot:isPiloting() then
    LOG("Pilot is active in combat")
end

Private and Internal Functions

These functions are for internal use or advanced manipulation. Most users should use the public functions above instead. These are expected to primarily be used when making changes in memhack itself

_setXp

  • void Pilot:_setXp(xp)

Raw XP setter that does not handle auto-leveling or fire hooks. Use setXp() instead unless you need direct memory access.

_setLevel

  • void Pilot:_setLevel(level)

Raw level setter that does not fire hooks or recalculate bonuses. Use setLevel() or levelUp()/levelDown() instead.

_setLevelUpXp

  • void Pilot:_setLevelUpXp(xp)

Raw levelUpXp setter. This is typically managed automatically by level changes.

_calculateLevelUpXp

  • number Pilot._calculateLevelUpXp(level)
Argument name Type Description
level int The current level

Static function that calculates the XP required to level up from a given level. Formula: (level + 1) * 25

For internal use only.

Example:

local xpNeeded = memhack.structs.Pilot._calculateLevelUpXp(1)  -- Returns 50

_combineBonuses

  • void Pilot:_combineBonuses()

Combines health, grid, core, and move bonuses from both skills when the pilot is level 2 or higher. This is called automatically when the pilot's level changes or skills are modified.

When a pilot reaches level 2, if both skills have non-zero values for cores or grid bonuses, they are combined into skill 1 for the actual game effect, while the individual skill values are preserved for tracking purposes.

Health and Move have similar functionality but this is only needed for virtual skill support

For internal use only.

Example:

-- Usually called automatically, but can be called manually if needed
pilot:_combineBonuses()