Lua:Class:MemoryRecord

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

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

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

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

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

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

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

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

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

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

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

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

Basic Usage

-- 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

-- 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

-- 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

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

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

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

-- 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

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

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

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

• Lua
• Script engine

Related Functions

• getMainForm - Get the main Cheat Engine form
• getAddressList - Get the address list containing memory records
• readInteger - Read integer values from memory
• readFloat - Read float values from memory
• readString - Read string values from memory
• writeInteger - Write integer values to memory
• writeFloat - Write float values to memory
• writeString - Write string values to memory
• AOBScan - Scan for array of bytes patterns
• autoAssemble - Execute auto assembler scripts

Related Classes

• Addresslist - The address list that contains memory records
• MemoryRecordHotkey - Hotkey objects attached to memory records
• CustomType - Custom variable type definitions
• Stringlist - String list used for dropdown values
• Object - Base class for all Lua-exposed objects