Lua:Class:MemoryRecord

From Cheat Engine
Jump to navigation Jump to search

MemoryRecord class: (Inheritance: Object)

The MemoryRecord class represents an entry in the Cheat Engine address list. Each memory record can represent an address, pointer, script, or group header, and provides access to its properties, children, hotkeys, and events.

Properties[edit]

Property Type Description
ID Integer Unique ID of the memory record.
Index Integer The index of this record in the address list (0 is top, ReadOnly).
Description String The description of the memory record.
Address String Get/set the interpretable address string. Supports symbols, module+offset notation, and Lua expressions. See getAddress and getNameFromAddress.
AddressString String The address string shown in CE (ReadOnly).
OffsetCount Integer The number of offsets. Set to 0 for a normal address.
Offset[index] Integer Array to access each offset by index (0-based).
OffsetText[index] String Array to access each offset using interpretable text style (0-based).
CurrentAddress Integer The address the memory record points to (ReadOnly). Alias: CachedAddress. See getAddress and memory reading functions.
CachedAddress Integer The cached/real address value (ReadOnly). Same as CurrentAddress.
VarType String The variable type of this record as a string name (e.g., "vtByte", "vtDword"). See Variable Types and VariableType.
Type Integer The variable type of this record as an integer constant (0-16). See Variable Types.
CustomTypeName String If the type is vtCustom, this contains the name of the CustomType.
CustomType CustomType If the type is vtCustom, this contains the actual CustomType object (ReadOnly).
Script String If the type is vtAutoAssembler, this contains the auto assembler script. See Auto Assembler and autoAssemble.
Value String The value in string form. For direct memory access, see readInteger, readFloat, readString, writeInteger, etc.
DisplayValue String The value as displayed in the address list, formatted according to display settings (ReadOnly).
NumericalValue Number The value in numerical form, or nil if it cannot be parsed.
Selected Boolean True if selected (ReadOnly).
Active Boolean Set to true to activate/freeze, false to deactivate/unfreeze.
Color Integer The color of the memory record.
ShowAsHex Boolean Show value as hexadecimal.
ShowAsSigned Boolean Show value as signed.
AllowIncrease Boolean Allow value increasing; unfreeze resets to false.
AllowDecrease Boolean Allow value decreasing; unfreeze resets to false.
Collapsed Boolean Set to true to collapse this record, false to expand.
IsGroupHeader Boolean True if the record is a group header with no address or value info.
IsAddressGroupHeader Boolean True if the record is a group header with address.
IsReadableAddress Boolean False if record contains an unreadable address (ReadOnly, set after value is accessed).
IsReadable Boolean Alias for IsReadableAddress. False if record contains an unreadable address (ReadOnly).
Options String set A string enclosed by square brackets with options separated by commas (e.g., [moHideChildren,moActivateChildrenAsWell]). See MemoryRecord Options.
DropDownLinked Boolean True if dropdown list refers to another memory record's list.
DropDownLinkedMemrec String Description of linked memory record or empty string if not linked.
DropDownList Stringlist List of "value:description" lines. Use DropDownList.Text to set (the stringList field cannot be overwritten directly). See Stringlist.
DropDownReadOnly Boolean True if 'Disallow manual user input' is set.
DropDownDescriptionOnly Boolean If true, only the description is shown (not the value).
DisplayAsDropDownListItem Boolean If true, the value is displayed as a dropdown list item.
DropDownCount Integer Equivalent to DropDownList.Count (ReadOnly).
DropDownValue[index] String Array to access values in DropDownList by index (0-based, ReadOnly).
DropDownDescription[index] String Array to access descriptions in DropDownList by index (0-based, ReadOnly).
Count Integer Number of child records (ReadOnly).
Child[index] MemoryRecord Array to access child records by index (0-based).
Parent MemoryRecord The parent of the memory record.
HotkeyCount Integer Number of hotkeys attached to this memory record (ReadOnly).
Hotkey[index] MemoryRecordHotkey Array to index the hotkeys by index (0-based). See MemoryRecordHotkey.
Async Boolean Set to true if activating this entry will be asynchronous (only for AA/Lua scripts).
AsyncProcessing Boolean True when async is true and it's being processed (ReadOnly).
AsyncProcessingTime Qword The time that it has been processing in milliseconds (ReadOnly).
HasMouseOver Boolean True if the mouse is currently over it (ReadOnly). Alias: HasMouseFocus.
HasMouseFocus Boolean Alias for HasMouseOver. True if the mouse is currently over it (ReadOnly).
LastAAExecutionFailed Boolean True if the last auto assembler script execution failed (ReadOnly).
LastAAExecutionFailedReason String Contains the error message if LastAAExecutionFailed is true (ReadOnly).
ScriptHotKey MemoryRecordHotkey The hotkey that was used to toggle this script (ReadOnly). Only set when a hotkey activates an auto-assembler script.
DontSave Boolean Don't save this memoryrecord and its children.
OnActivate function Event callback: function(memoryrecord, before):boolean. See Events / Callbacks.
OnDeactivate function Event callback: function(memoryrecord, before):boolean. See Events / Callbacks.
OnDestroy function Event callback: function(). See Events / Callbacks.
OnGetDisplayValue function Event callback: function(memoryrecord, valuestring):boolean,string. See Events / Callbacks.
OnValueChanged function Event callback: function(memoryrecord, oldvalue, newvalue). See Events / Callbacks.
OnValueChangedByUser function Event callback: function(memoryrecord, oldvalue, newvalue). See Events / Callbacks.

Special Properties by Type[edit]

When a MemoryRecord is set to specific variable types, additional properties become available through nested property accessors. These properties configure type-specific behavior.

String Type Properties[edit]

When VarType = vtString, the following properties are available:

Property Type Description
String.Size Integer The length of the string in characters (or bytes for non-Unicode). If Unicode is enabled, each character is 2 bytes.
String.Unicode Boolean If true, the string is treated as a Unicode (UTF-16) string. If false, it's an ANSI or codepage string. Setting this to true automatically sets Codepage to false.
String.Codepage Boolean If true, the string uses the system codepage encoding (Windows codepage). If false, it's treated as standard ANSI. Setting this to true automatically sets Unicode to false.

Example: 

local mr = AddressList.createMemoryRecord()
mr.Type = vtString
mr.Address = "player_name"
mr.String.Size = 32           -- 32 characters max
mr.String.Unicode = true      -- Use Unicode encoding
-- mr.String.Codepage is now false (mutually exclusive with Unicode)

Binary Type Properties[edit]

When VarType = vtBinary, the following properties are available for bitfield manipulation:

Property Type Description
Binary.Startbit Integer The bit position (0-based) within the byte(s) where the bitfield starts. For example, Startbit=2 means the bitfield begins at bit 2.
Binary.Size Integer The number of bits in the bitfield (also called bitlength). For example, Size=4 means a 4-bit field.

Note: The Binary type allows you to read/write specific bits within a memory address. The value is extracted by shifting and masking the underlying bytes.

Example: 

local flags = AddressList.createMemoryRecord()
flags.Type = vtBinary
flags.Address = "0x00400000"
flags.Binary.Startbit = 3     -- Start at bit 3
flags.Binary.Size = 2         -- Read 2 bits (bits 3-4)
-- This will read bits 3 and 4 from the byte at 0x00400000
-- If the byte is 0b00011000 (0x18), the value will be 0b11 (3)

ByteArray Type Properties[edit]

When VarType = vtByteArray, the following property is available:

Property Type Description
Aob.Size Integer The number of bytes in the array. This determines how many bytes are read/written from memory.

Example: 

local signature = AddressList.createMemoryRecord()
signature.Type = vtByteArray
signature.Address = "module+1000"
signature.Aob.Size = 16       -- Read 16 bytes
signature.ShowAsHex = true    -- Display as hex bytes
-- Value might display as: 48 8B 05 12 34 56 78 90 AB CD EF 01 23 45 67 89

Variable Types[edit]

Constant Value Description
vtByte 0 1 byte (unsigned)
vtWord 1 2 bytes (unsigned)
vtDword 2 4 bytes (unsigned)
vtQword 3 8 bytes (unsigned)
vtSingle 4 4 bytes (float)
vtDouble 5 8 bytes (double/float)
vtString 6 String (ASCII)
vtUnicodeString
vtWideString 		7 Unicode string (Only used by autoguess)
vtByteArray 8 Array of bytes
vtBinary 9 Binary (bitfield)
vtAll 10 All types (used for scans)
vtAutoAssembler 11 Auto Assembler script
vtPointer 12 Pointer (Only used by autoguess and structures)
vtCustom 13 Custom type
vtGrouped 14 Grouped type
vtByteArrays 15 Multiple byte arrays
vtCodePageString 16 Code page string

MemoryRecord Options[edit]

The following options can be set in the Options property of a MemoryRecord. The value is a string enclosed in square brackets, with options separated by commas (e.g., [moHideChildren,moActivateChildrenAsWell]).

Option Description
moHideChildren Hides the child records of this memory record.
moActivateChildrenAsWell Activating this record also activates its children.
moDeactivateChildrenAsWell Deactivating this record also deactivates its children.
moRecursiveSetValue Setting the value will also set the value of all children recursively.
moAllowManualCollapseAndExpand Allows the user to manually collapse or expand this record in the address list.
moManualExpandCollapse Enables manual expand/collapse behavior for this record.
moAlwaysHideChildren Always hides the children, regardless of other settings.

Methods[edit]

Method Parameters Returns Description
getDescription None String Gets the description.
setDescription String None Sets the description.
getAddress None String [, Table] Returns the interpretable address string. For pointer records, returns two values: the base address string and a table of offsets (1-indexed).
setAddress String [, Table] None Sets the interpretable address string. Optional second parameter: offset table (1-indexed) for pointer records.
getOffsetCount None Integer Returns the number of offsets.
setOffsetCount Integer None Sets the number of offsets.
getOffset Integer (index) Integer Gets the offset at the given index (0-based).
setOffset Integer (index), Integer (value) None Sets the offset at the given index (0-based).
getCurrentAddress None Integer Returns the current address as an integer.
appendToEntry MemoryRecord None Appends the current memory record to the given memory record as a child.
getHotkey Integer (index) MemoryRecordHotkey Returns the hotkey from the hotkey array at the given index (0-based).
getHotkeyByID Integer (id) MemoryRecordHotkey Returns the hotkey with the given id.
reinterpret None None Reinterprets the memory record's address.
createHotkey Table (keys), Integer (action), String (value, OPTIONAL), String (description, OPTIONAL) MemoryRecordHotkey Creates a hotkey object and registers it. The keys table is 1-indexed and contains up to 5 virtual key codes (e.g., {0x70} for F1, {0x11, 0x70} for Ctrl+F1). See Virtual Key Codes. The action is one of the hotkey action constants (0-7). Returns the created and registered hotkey object.
disableWithoutExecute None None Sets the entry to disabled without executing the disable section (for AA scripts).
beginEdit None None Call when you wish to take a long time to edit a record. Prevents automatic updates.
endEdit None None Marks the end of your long edit sequence. Re-enables automatic updates.
delete None None Deletes this memory record (frees the object).

Hotkey Actions[edit]

The following constants define the actions a hotkey can perform:

Constant Value Description
mrhToggleActivation 0 Toggle the active state of the memory record.
mrhToggleActivationAllowIncrease 1 Toggle activation and allow the value to increase while frozen.
mrhToggleActivationAllowDecrease 2 Toggle activation and allow the value to decrease while frozen.
mrhActivate 3 Activate (freeze) the memory record.
mrhDeactivate 4 Deactivate (unfreeze) the memory record.
mrhSetValue 5 Set the memory record to the specified value.
mrhIncreaseValue 6 Increase the current value by the specified amount.
mrhDecreaseValue 7 Decrease the current value by the specified amount.

Events / Callbacks[edit]

Event Parameters Description
OnActivate function(memoryrecord, before):boolean Called when the memoryrecord will change (or changed) Active to true. If before is true, not returning true will cause the activation to stop. The before parameter indicates if this is called before (true) or after (false) activation.
OnDeactivate function(memoryrecord, before):boolean Called when the memoryrecord will change (or changed) Active to false. If before is true, not returning true will cause the deactivation to stop. The before parameter indicates if this is called before (true) or after (false) deactivation.
OnDestroy function() Called when the memoryrecord is destroyed.
~~OnActivationFailure~~ ~~function(memoryrecord, reason, reasonText)~~ Deprecated/Not Implemented: This callback was mentioned in older documentation but is not exposed in the Lua API. To detect activation failures, check the LastAAExecutionFailed property after attempting to activate an auto-assembler script.
OnGetDisplayValue function(memoryrecord, valuestring):boolean,string Called when rendering the value of a memory record. The function receives the memoryrecord and current value string. Return true and a modified string to override the displayed value, or false to use the default.
OnValueChanged function(memoryrecord, oldvalue, newvalue) Called whenever the value of a memory record has changed. Parameters are the memoryrecord object, old value string, and new value string.
OnValueChangedByUser function(memoryrecord, oldvalue, newvalue) Called whenever the value of a memory record has changed by the user (not by the freezer). Parameters are the memoryrecord object, old value string, and new value string.

Global Events[edit]

Note: These global event functions can be defined in your Lua scripts to monitor all memory record activation/deactivation events globally. 

function onMemRecPreExecute(memoryrecord, newstate BOOLEAN)
  -- Called before action is performed. Active property is about to change to newState.
  -- Return false to cancel the operation.
end

function onMemRecPostExecute(memoryrecord, newState BOOLEAN, succeeded BOOLEAN)
  -- Called after action is performed. Active property was supposed to change to newState.
  -- If 'succeeded' is true, Active state has changed and is newState.
end

Examples[edit]

Basic Usage[edit]

-- Get the first memory record in the address list
local mr = AddressList[0]

-- Print some basic properties
print("ID:", mr.ID)
print("Description:", mr.Description)
print("Address:", mr.Address)
print("Current Value:", mr.Value)
print("Active:", mr.Active)

-- Change the value and activate the record
mr.Value = "999"
mr.Active = true

Working with Pointers[edit]

-- Create a pointer-based memory record
local mr = AddressList.createMemoryRecord()
mr.Description = "Player Health"

-- Set as a 4-byte pointer with offsets
mr.Type = vtDword
mr.setAddress("player_base", {0x10, 0x8, 0x120})  -- Base + offsets (1-indexed table)

-- Alternative: Set offsets individually
mr.Address = "player_base"
mr.OffsetCount = 3
mr.Offset[0] = 0x10
mr.Offset[1] = 0x8
mr.Offset[2] = 0x120

-- Or use interpretable offset text
mr.OffsetText[0] = "10"
mr.OffsetText[1] = "8"
mr.OffsetText[2] = "120"

print("Resolved Address:", string.format("%X", mr.CurrentAddress))

Using Special Type Properties[edit]

-- String type
local strRecord = AddressList.createMemoryRecord()
strRecord.Description = "Player Name"
strRecord.Type = vtString
strRecord.Address = "0x00400000"
strRecord.String.Size = 20
strRecord.String.Unicode = false

-- Binary type (bitfield)
local bitRecord = AddressList.createMemoryRecord()
bitRecord.Description = "Flags"
bitRecord.Type = vtBinary
bitRecord.Address = "0x00500000"
bitRecord.Binary.Startbit = 2
bitRecord.Binary.Size = 4

-- Array of Bytes
local aobRecord = AddressList.createMemoryRecord()
aobRecord.Description = "Byte Array"
aobRecord.Type = vtByteArray
aobRecord.Address = "0x00600000"
aobRecord.Aob.Size = 16

Using Dropdown Lists[edit]

local mr = AddressList.createMemoryRecord()
mr.Description = "Game State"
mr.Type = vtByte
mr.Address = "game_state"

-- Add dropdown values
mr.DropDownList.Text = [[0:Menu
1:Playing
2:Paused
3:GameOver]]

mr.DropDownReadOnly = true
mr.DropDownDescriptionOnly = true
mr.DisplayAsDropDownListItem = true

-- Access dropdown items
for i = 0, mr.DropDownCount - 1 do
  print(mr.DropDownValue[i], ":", mr.DropDownDescription[i])
end

Event Callbacks[edit]

local mr = AddressList.getMemoryRecordByDescription("Player Health")

-- OnActivate callback (called before/after activation)
mr.OnActivate = function(memrec, before)
  if before then
    print("About to activate:", memrec.Description)
    -- Return false to prevent activation
    return true
  else
    print("Activated:", memrec.Description)
    return true
  end
end

-- OnValueChanged callback
mr.OnValueChanged = function(memrec, oldvalue, newvalue)
  print(string.format("%s changed from %s to %s", 
    memrec.Description, oldvalue, newvalue))
end

-- OnGetDisplayValue callback (customize display)
mr.OnGetDisplayValue = function(memrec, value)
  local numValue = tonumber(value)
  if numValue then
    return true, string.format("%d HP", numValue)
  end
  return false  -- Use default display
end

Creating Hotkeys[edit]

local mr = AddressList.getMemoryRecordByDescription("God Mode")

-- Create a hotkey: F1 to toggle
local keys = {0x70}  -- VK_F1 (1-indexed table)
local action = 0     -- mrhToggleActivation
local hotkey = mr.createHotkey(keys, action, "", "Toggle God Mode")

print("Hotkey ID:", hotkey.ID)
print("Hotkey String:", hotkey.HotkeyString)  -- e.g., "F1"
print("Owner Description:", hotkey.Owner.Description)

-- Create a hotkey: Ctrl+F2 to set value
local keys2 = {0x11, 0x71}  -- VK_CONTROL + VK_F2
local action2 = 5           -- mrhSetValue
local hotkey2 = mr.createHotkey(keys2, action2, "100", "Set to 100")

-- Access hotkeys by index or ID
print("Hotkey count:", mr.HotkeyCount)
for i = 0, mr.HotkeyCount - 1 do
  local hk = mr.Hotkey[i]
  print(string.format("Hotkey %d: %s - %s", hk.ID, hk.HotkeyString, hk.Description))
end

-- Get specific hotkey by ID
local specificHotkey = mr.getHotkeyByID(hotkey.ID)

-- Manually trigger a hotkey
hotkey.doHotkey()

Working with Children[edit]

-- Create a parent group
local parent = AddressList.createMemoryRecord()
parent.Description = "Player Stats"
parent.IsGroupHeader = true

-- Create children
local health = AddressList.createMemoryRecord()
health.Description = "Health"
health.Type = vtDword
health.Address = "player_base+10"
health.appendToEntry(parent)

local mana = AddressList.createMemoryRecord()
mana.Description = "Mana"
mana.Type = vtDword
mana.Address = "player_base+14"
mana.appendToEntry(parent)

-- Iterate through children
print("Child count:", parent.Count)
for i = 0, parent.Count - 1 do
  local child = parent.Child[i]
  print("Child:", child.Description, "Value:", child.Value)
end

-- Set options
parent.Options = "[moActivateChildrenAsWell,moDeactivateChildrenAsWell]"

Auto Assembler Scripts[edit]

local script = AddressList.createMemoryRecord()
script.Description = "Infinite Ammo"
script.Type = vtAutoAssembler
script.Script = [[
[ENABLE]
aobscan(ammo_code,FF 0D * * * * 83 C4 08)
alloc(newmem,32)

label(code)
label(return)

newmem:
code:
  // Don't decrease ammo
  nop
  nop
  nop
  nop
  nop
  nop
  jmp return

ammo_code:
  jmp newmem
return:
registersymbol(ammo_code)

[DISABLE]
ammo_code:
  db FF 0D * * * * 83 C4 08
unregistersymbol(ammo_code)
dealloc(newmem)
]]

-- Activate the script
script.Active = true

-- Check if execution failed
if script.LastAAExecutionFailed then
  print("Script failed:", script.LastAAExecutionFailedReason)
end

Async Script Execution[edit]

local asyncScript = AddressList.createMemoryRecord()
asyncScript.Description = "Slow Script"
asyncScript.Type = vtAutoAssembler
asyncScript.Async = true  -- Enable async processing
asyncScript.Script = [[
[ENABLE]
// ... complex AA script ...

[DISABLE]
// ... disable code ...
]]

asyncScript.Active = true

-- Check processing status
if asyncScript.AsyncProcessing then
  print("Processing... Time:", asyncScript.AsyncProcessingTime, "ms")
end

Editing Records Efficiently[edit]

local mr = AddressList[0]

-- Begin edit to prevent updates during batch changes
mr.beginEdit()

mr.Description = "Modified Entry"
mr.Address = "new_address"
mr.Type = vtQword
mr.ShowAsHex = true

-- End edit to re-enable updates
mr.endEdit()

See also[edit]

Related Functions[edit]

Related Classes[edit]



Retrieved from "https://wiki.cheatengine.org/index.php?title=Lua:Class:MemoryRecord&oldid=7761"