wolfhacklua API 1.1 Forum

mem

Read the game's memory and, if the user allows it, write it. Opt-in, limited, and undone automatically when the script stops.

since 1.1permission: memory, memory_write, memory_patch

Added in API 1.1. Three permissions, each listed in the manifest and granted by the user on the Scripts page:

PermissionAllows
memoryReads, scans, and the lookups below. Nothing is changed.
memory_writeWrites to data pages. Also needs the master switch Scripts > Let scripts write game memory, which is off at every start unless the user turned it on.
memory_patchWrites to code pages as well. Needs memory_write in the manifest too.

Addresses are plain Lua integers. Reads answer nil when an address cannot be read (the game changes under you; that is normal). Writes answer true, or false, reason when the place cannot be written, and raise an error for what a script must not do at all: no permission, the master switch off, or too many writes in a frame.

Every write is undone when the script stops (disabled, reloaded, removed, stopped by the host, or the permission or the switch taken away). The host remembers the bytes each write replaced and puts them back, unless the game has changed those bytes since (then they are left as the game has them). If the game was restarted in between, old writes are forgotten rather than undone. A script that wants a change to last has to keep running.

Limits: 4096 bytes per read and 8192 reads per frame; 1 to 256 bytes per write, 512 writes per frame, at most 4096 writes (64 KB) in force; user-mode addresses only; one write must stay inside one memory region; 8 scans at a time.

Use mem.can_write() to find out why writes are not working instead of letting a write raise an error every frame.

Reference#

mem.module#permission: memorysince 1.1

mem.module(name: string): integer | nil, integer

Finds a loaded module.

ParameterTypeDescription
namestringA module of the game process, for example "client.dll".
ReturnsDescription
integer | nilThe module's base address.
integerIts size in bytes.
lua
local base, size = mem.module("client.dll")

mem.offset#permission: memorysince 1.1

mem.offset(key: string): integer | nil

Looks up a schema field offset from the overlay's own offset table.

ParameterTypeDescription
keystring"Class->field", a schema offset the overlay knows, for example "C_BaseEntity->m_iHealth".
ReturnsDescription
integer | nilThe offset, or nil when the overlay does not know it.

mem.global#permission: memorysince 1.1

mem.global(name: string): integer | nil

An address the overlay has resolved. The *_slot, entity_list, planted_c4 and global_vars values are slots that hold a pointer: read them with mem.read_ptr. view_matrix is the matrix itself, csgo_input is the object itself, and local_pawn and local_controller are the live entity addresses.

ParameterTypeDescription
namestringentity_list, view_matrix, local_controller_slot, planted_c4, global_vars, csgo_input, network_game_client, entity_system, local_pawn or local_controller.
ReturnsDescription
integer | nilAn address, or nil when it is not resolved yet.
lua
local pawn = mem.global("local_pawn")
local off = mem.offset("C_BaseEntity->m_iHealth")
if pawn and off then log.info(mem.read_i32(pawn + off)) end

mem.region#permission: memorysince 1.1

mem.region(addr: integer): table | nil

Describes the memory region an address is in.

ParameterTypeDescription
addrintegerAn address.
ReturnsDescription
table | nil{base, size, committed, executable, writable, protect}, or nil when it cannot be examined.

mem.read_u8#permission: memorysince 1.1

mem.read_u8(addr: integer): integer | nil

Reads an unsigned 8-bit integer. The also functions read the other integer sizes the same way (read_i32 has its own entry).

Same signature: mem.read_i8, mem.read_u16, mem.read_i16, mem.read_u32, mem.read_i64.

ParameterTypeDescription
addrintegerAn address.
ReturnsDescription
integer | nilThe value, or nil when unreadable.

mem.read_i32#permission: memorysince 1.1

mem.read_i32(addr: integer): integer | nil

Reads a signed 32-bit integer.

ParameterTypeDescription
addrintegerAn address.
ReturnsDescription
integer | nilThe value, or nil.
lua
local hp = mem.read_i32(pawn + off)

mem.read_f32#permission: memorysince 1.1

mem.read_f32(addr: integer): number | nil

Reads a 32-bit float. read_f64 (listed as also) reads a 64-bit one.

Same signature: mem.read_f64.

ParameterTypeDescription
addrintegerAn address.
ReturnsDescription
number | nilThe value, or nil (also for NaN and infinity).

mem.read_ptr#permission: memorysince 1.1

mem.read_ptr(addr: integer): integer | nil

Reads a pointer. Returning nil for a bad pointer means a chain of reads stops at the first broken link.

ParameterTypeDescription
addrintegerAn address holding a pointer.
ReturnsDescription
integer | nilThe pointer, or nil when the read fails or the value is not a user-mode address.
lua
local entities = mem.read_ptr(mem.global("entity_list"))

mem.read_vec3#permission: memorysince 1.1

mem.read_vec3(addr: integer): number | nil, number, number

Reads three 32-bit floats.

ParameterTypeDescription
addrintegerAn address.
ReturnsDescription
number | nilx
numbery
numberz

mem.read_bytes#permission: memorysince 1.1

mem.read_bytes(addr: integer, n: integer): string | nil

Reads a block. Cheaper than many small reads.

ParameterTypeDescription
addrintegerAn address.
nintegerHow many bytes, 1 to 4096.
ReturnsDescription
string | nilThe bytes as a Lua string.
lua
local b = mem.read_bytes(addr, 4)
local a, c = b:byte(1, 2)

mem.read_cstring#permission: memorysince 1.1

mem.read_cstring(addr: integer, max?: integer): string | nil

Reads a zero-terminated string.

ParameterTypeDescription
addrintegerAn address.
max optionalintegerLongest string to read, up to 1024. default 256
ReturnsDescription
string | nilThe text up to the first zero byte.

mem.scan#permission: memorysince 1.1

mem.scan(module: string, pattern: string, on_done: function | table): ScanHandle

Searches a module for a byte pattern. It reads the module a few milliseconds per frame, so a big module such as client.dll takes a second or two but never stalls the overlay. The callback gets the first match, or nil when there is none.

ParameterTypeDescription
modulestringA module name.
patternstringHex bytes with ? or ?? wildcards, for example "48 8B 0D ?? ?? ?? ??". At most 256 bytes and at least one fixed byte.
on_donefunction | tableA function fn(address), or {on_done = fn, rip_offset = n, rip_length = n} to resolve a relative operand: the result is the address that the 32-bit relative value at match + rip_offset points to, for an instruction rip_length bytes long (default 7).
ReturnsDescription
ScanHandleA handle for task.await, :cancel() and :is_done().
lua
mem.scan("client.dll", "48 8B 0D ?? ?? ?? ?? 48 89 7C 24 ?? 8B FA C1 EB", {
  rip_offset = 3, rip_length = 7,
  on_done = function(addr) log.info(addr and string.format("0x%X", addr) or "not found") end,
})

mem.write_u8#permission: memory_writesince 1.1

mem.write_u8(addr: integer, value: integer): boolean, string?

Writes an 8-bit integer. The also functions write the other integer sizes the same way. Needs memory_write and the master switch.

Same signature: mem.write_i8, mem.write_u16, mem.write_i16, mem.write_u32, mem.write_i32, mem.write_i64.

ParameterTypeDescription
addrintegerAn address in a data page.
valueintegerThe value.
ReturnsDescription
booleantrue when it was written.
string?The reason when it was not.

mem.write_f32#permission: memory_writesince 1.1

mem.write_f32(addr: integer, value: number): boolean, string?

Writes a 32-bit float. write_f64 (listed as also) writes a 64-bit one.

Same signature: mem.write_f64.

ParameterTypeDescription
addrintegerAn address in a data page.
valuenumberThe value.
ReturnsDescription
booleantrue when it was written.
string?The reason when it was not.
lua
-- manifest: "permissions": ["memory", "memory_write"]
if mem.can_write() then mem.write_f32(pawn + off, 0.0) end

mem.write_bytes#permission: memory_writesince 1.1

mem.write_bytes(addr: integer, bytes: string): boolean, string?

Writes raw bytes. In a code page this needs memory_patch as well; without it the answer is false and the reason says so.

ParameterTypeDescription
addrintegerAn address.
bytesstring1 to 256 bytes.
ReturnsDescription
booleantrue when it was written.
string?The reason when it was not.

mem.undo#permission: memory_writesince 1.1

mem.undo(addr: integer): boolean

Puts one write back now. A place the game changed since is left as it is.

ParameterTypeDescription
addrintegerThe address a write started at.
ReturnsDescription
booleantrue when a write was put back.

mem.undo_all#permission: memory_writesince 1.1

mem.undo_all(): integer

Puts every write of this script back.

ReturnsDescription
integerHow many writes were put back.

mem.writes#since 1.1

mem.writes(): integer

Counts this script's writes that have not been undone.

ReturnsDescription
integerHow many writes are in force.

mem.can_write#since 1.1

mem.can_write(): boolean, boolean

Asks whether writes would work right now.

ReturnsDescription
booleanWhether memory_write is granted and the master switch is on.
booleanWhether memory_patch is granted.

ScanHandle#

Returned by mem.scan. Pass it to task.await to wait for the result inside a task.

scan:cancel#since 1.1

scan:cancel(): boolean

Stops the scan.

ReturnsDescription
booleantrue when a scan was cancelled.

scan:is_done#since 1.1

scan:is_done(): boolean

Asks whether the scan has finished.

ReturnsDescription
booleanWhether the scan has finished.
API 1.1 · source docs-src/api/mem.json