Process

Functions for interacting with process memory, modules, and state.

Process Info & State

proc.is_attached

Signature: proc.is_attached()

Description: Returns true if a process is currently attached.

Parameters: None

Returns:

• boolean: true if a process is attached, false otherwise.

Example:

if proc.is_attached() then
    engine.log("Process attached successfully", 0, 255, 0, 255)
    -- Proceed with process operations
else
    engine.log("No process attached", 255, 0, 0, 255)
end

---

proc.did_exit

Signature: proc.did_exit()

Description: Returns true if the attached process has exited.

Parameters: None

Returns:

• boolean: true if the attached process has exited, false otherwise.

Example:

function check_process_state()
    if proc.is_attached() then
        if proc.did_exit() then
            engine.log("Attached process has exited!", 255, 0, 0, 255)
            -- Handle cleanup
        else
            engine.log("Process is still running", 0, 255, 0, 255)
        end
    end
end

engine.register_on_engine_tick(check_process_state)

---

proc.pid

Signature: proc.pid()

Description: Returns the process ID of the attached process.

Parameters: None

Returns:

• number: The process ID (PID) of the attached process.

Example:

if proc.is_attached() then
    local pid = proc.pid()
    engine.log("Attached to process with PID: " .. pid, 255, 255, 255, 255)
end

---

proc.peb

Signature: proc.peb()

Description: Returns the address of the Process Environment Block (PEB) of the attached process.

Parameters: None

Returns:

• number: The address of the PEB of the attached process.

Example:

if proc.is_attached() then
    local peb_address = proc.peb()
    engine.log("PEB address: 0x" .. string.format("%X", peb_address), 255, 255, 255, 255)
end

---

proc.base_address

Signature: proc.base_address()

Description: Returns the base address of the attached process.

Parameters: None

Returns:

• number: The base address of the attached process.

Example:

if proc.is_attached() then
    local base = proc.base_address()
    engine.log("Process base address: 0x" .. string.format("%X", base), 255, 255, 255, 255)
    
    -- Read a value at an offset from the base address
    local value = proc.read_int32(base + 0x1000)
    engine.log("Value at base+0x1000: " .. value, 255, 255, 255, 255)
end

---

proc.get_base_module

Signature: proc.get_base_module()

Description: Returns the base address and size of the main module of the attached process.

Parameters: None

Returns:

• address (number): The base address of the main module.

• size (number): The size of the main module in bytes.

Example:

if proc.is_attached() then
    local base_address, module_size = proc.get_base_module()
    engine.log("Main module base: 0x" .. string.format("%X", base_address), 255, 255, 255, 255)
    engine.log("Main module size: " .. module_size .. " bytes", 255, 255, 255, 255)
end

---

proc.find_module

Signature: proc.find_module(module_name)

Description: Finds a module by name and returns its base address and size.

Parameters:

• module_name (string): The name of the module to find (e.g., "kernel32.dll").

Returns:

• address (number): The base address of the found module, or nil if not found.

• size (number): The size of the found module in bytes.

Example:

if proc.is_attached() then
    local dll_name = "user32.dll"
    local module_base, module_size = proc.find_module(dll_name)
    
    if module_base then
        engine.log("Found module '" .. dll_name .. "' at 0x" .. 
                  string.format("%X", module_base) .. " with size " .. 
                  module_size .. " bytes", 0, 255, 0, 255)
    else
        engine.log("Module '" .. dll_name .. "' not found", 255, 0, 0, 255)
    end
end

---

proc.find_signature

Signature: proc.find_signature(base_address, size, signature)

Description: Searches for a memory pattern (signature) within a specified memory range.

Parameters:

• base_address (number): The starting address to begin the search.

• size (number): The number of bytes to search.

• signature (string): The pattern to search for (e.g., "48 8B 05 ?? ?? ?? ??").

Returns:

• address (number): The address where the pattern was found, or nil if not found.

Example:

if proc.is_attached() then
    local base_address, module_size = proc.get_base_module()
    
    -- Example signature with wildcards (??)
    local signature = "48 8B 05 ?? ?? ?? ?? 48 85 C0 74 10"
    
    local result = proc.find_signature(base_address, module_size, signature)
    if result then
        engine.log("Signature found at: 0x" .. string.format("%X", result), 0, 255, 0, 255)
    else
        engine.log("Signature not found in memory range", 255, 0, 0, 255)
    end
end

---

Memory Read Operations

proc.read_double

Signature: proc.read_double(address)

Description: Reads a 64-bit floating-point number (double) from the specified memory address.

Parameters:

• address (number): The memory address to read from.

Returns:

• number: The double value read from memory.

Example:

if proc.is_attached() then
    local address = 0x12345678  -- Replace with an actual address
    local value = proc.read_double(address)
    engine.log("Double value: " .. value, 255, 255, 255, 255)
end

---

proc.read_float

Signature: proc.read_float(address)

Description: Reads a 32-bit floating-point number (float) from the specified memory address.

Parameters:

• address (number): The memory address to read from.

Returns:

• number: The float value read from memory.

Example:

if proc.is_attached() then
    local base = proc.base_address()
    local offset = 0x1234  -- Replace with an actual offset
    local value = proc.read_float(base + offset)
    engine.log("Float value: " .. value, 255, 255, 255, 255)
end

---

proc.read_int64

Signature: proc.read_int64(address)

Description: Reads a 64-bit integer from the specified memory address.

Parameters:

• address (number): The memory address to read from.

Returns:

• number: The 64-bit integer value read from memory.

Example:

if proc.is_attached() then
    local address = 0x12345678  -- Replace with an actual address
    local value = proc.read_int64(address)
    engine.log("Int64 value: " .. value, 255, 255, 255, 255)
end

---

proc.read_int32

Signature: proc.read_int32(address)

Description: Reads a 32-bit integer from the specified memory address.

Parameters:

• address (number): The memory address to read from.

Returns:

• number: The 32-bit integer value read from memory.

Example:

if proc.is_attached() then
    local base = proc.base_address()
    local offset = 0x1000  -- Replace with an actual offset
    local value = proc.read_int32(base + offset)
    engine.log("Int32 value: " .. value, 255, 255, 255, 255)
end

---

proc.read_int16

Signature: proc.read_int16(address)

Description: Reads a 16-bit integer from the specified memory address.

Parameters:

• address (number): The memory address to read from.

Returns:

• number: The 16-bit integer value read from memory.

Example:

if proc.is_attached() then
    local address = 0x12345678  -- Replace with an actual address
    local value = proc.read_int16(address)
    engine.log("Int16 value: " .. value, 255, 255, 255, 255)
end

---

proc.read_int8

Signature: proc.read_int8(address)

Description: Reads an 8-bit integer from the specified memory address.

Parameters:

• address (number): The memory address to read from.

Returns:

• number: The 8-bit integer value read from memory.

Example:

if proc.is_attached() then
    local base = proc.base_address()
    local offset = 0x2000  -- Replace with an actual offset
    local value = proc.read_int8(base + offset)
    engine.log("Int8 value: " .. value, 255, 255, 255, 255)
end

---

proc.read_string

Signature: proc.read_string(address, size)

Description: Reads a string from the specified memory address with the given maximum size.

Parameters:

• address (number): The memory address to read from.

• size (number): The maximum number of bytes to read.

Returns:

• string: The string read from memory.

Example:

if proc.is_attached() then
    local string_address = 0x12345678  -- Replace with an actual address
    local max_size = 64
    local text = proc.read_string(string_address, max_size)
    engine.log("String value: " .. text, 255, 255, 255, 255)
end

---

proc.read_wide_string

Signature: proc.read_wide_string(address, size)

Description: Reads a wide (UTF-16) string from the specified memory address with the given maximum size.

Parameters:

• address (number): The memory address to read from.

• size (number): The maximum number of wide characters to read.

Returns:

• string: The wide string read from memory, converted to a Lua UTF-8 string.

Example:

if proc.is_attached() then
    local wide_string_address = 0x12345678  -- Replace with an actual address
    local max_size = 32
    local text = proc.read_wide_string(wide_string_address, max_size)
    engine.log("Wide string value: " .. text, 255, 255, 255, 255)
end

---

proc.read_to_memory_buffer

Signature: proc.read_to_memory_buffer(address, buffer, size)

Description: Reads memory from the attached process into a local memory buffer.

Parameters:

• address (number): The memory address to read from.

• buffer (handle): A memory buffer handle obtained from m.alloc().

• size (number): The number of bytes to read.

Returns:

• boolean: true if the read operation was successful, false otherwise.

Example:

if proc.is_attached() then
    -- Allocate a buffer to hold the memory data
    local buffer_size = 1024
    local buffer = m.alloc(buffer_size)
    
    if buffer then
        local address = proc.base_address() + 0x1000  -- Replace with an actual address
        
        -- Read memory into the buffer
        local success = proc.read_to_memory_buffer(address, buffer, buffer_size)
        
        if success then
            engine.log("Successfully read " .. buffer_size .. " bytes to buffer", 0, 255, 0, 255)
            
            -- Process the buffer data (for example, read the first int32)
            local value = m.read_int32(buffer, 0)
            engine.log("First int32 in buffer: " .. value, 255, 255, 255, 255)
        else
            engine.log("Failed to read memory to buffer", 255, 0, 0, 255)
        end
        
        -- Free the buffer when done
        m.free(buffer)
    end
end

---

Memory Write Operations

proc.write_double

Signature: proc.write_double(address, value)

Description: Writes a 64-bit floating-point number (double) to the specified memory address.

Parameters:

• address (number): The memory address to write to.

• value (number): The double value to write.

Returns:

• boolean: true if the write operation was successful, false otherwise.

Example:

if proc.is_attached() then
    local address = 0x12345678  -- Replace with an actual address
    local value = 3.14159265359
    
    local success = proc.write_double(address, value)
    if success then
        engine.log("Successfully wrote double value " .. value, 0, 255, 0, 255)
    else
        engine.log("Failed to write double value", 255, 0, 0, 255)
    end
end

---

proc.write_float

Signature: proc.write_float(address, value)

Description: Writes a 32-bit floating-point number (float) to the specified memory address.

Parameters:

• address (number): The memory address to write to.

• value (number): The float value to write.

Returns:

• boolean: true if the write operation was successful, false otherwise.

Example:

if proc.is_attached() then
    local base = proc.base_address()
    local offset = 0x1234  -- Replace with an actual offset
    local value = 2.71828
    
    local success = proc.write_float(base + offset, value)
    if success then
        engine.log("Successfully wrote float value " .. value, 0, 255, 0, 255)
    else
        engine.log("Failed to write float value", 255, 0, 0, 255)
    end
end

---

proc.write_int64

Signature: proc.write_int64(address, value)

Description: Writes a 64-bit integer to the specified memory address.

Parameters:

• address (number): The memory address to write to.

• value (number): The 64-bit integer value to write.

Returns:

• boolean: true if the write operation was successful, false otherwise.

Example:

if proc.is_attached() then
    local address = 0x12345678  -- Replace with an actual address
    local value = 1234567890123456
    
    local success = proc.write_int64(address, value)
    if success then
        engine.log("Successfully wrote int64 value " .. value, 0, 255, 0, 255)
    else
        engine.log("Failed to write int64 value", 255, 0, 0, 255)
    end
end

---

proc.write_int32

Signature: proc.write_int32(address, value)

Description: Writes a 32-bit integer to the specified memory address.

Parameters:

• address (number): The memory address to write to.

• value (number): The 32-bit integer value to write.

Returns:

• boolean: true if the write operation was successful, false otherwise.

Example:

if proc.is_attached() then
    local base = proc.base_address()
    local offset = 0x1000  -- Replace with an actual offset
    local value = 42
    
    -- Read the original value first
    local original = proc.read_int32(base + offset)
    engine.log("Original value: " .. original, 255, 255, 255, 255)
    
    -- Write the new value
    local success = proc.write_int32(base + offset, value)
    if success then
        -- Verify the write by reading back
        local new_value = proc.read_int32(base + offset)
        engine.log("New value: " .. new_value, 0, 255, 0, 255)
    else
        engine.log("Failed to write int32 value", 255, 0, 0, 255)
    end
end

---

proc.write_int16

Signature: proc.write_int16(address, value)

Description: Writes a 16-bit integer to the specified memory address.

Parameters:

• address (number): The memory address to write to.

• value (number): The 16-bit integer value to write.

Returns:

• boolean: true if the write operation was successful, false otherwise.

Example:

if proc.is_attached() then
    local address = 0x12345678  -- Replace with an actual address
    local value = 12345  -- 16-bit value (max 65535)
    
    local success = proc.write_int16(address, value)
    if success then
        engine.log("Successfully wrote int16 value " .. value, 0, 255, 0, 255)
    else
        engine.log("Failed to write int16 value", 255, 0, 0, 255)
    end
end

---

proc.write_int8

Signature: proc.write_int8(address, value)

Description: Writes an 8-bit integer to the specified memory address.

Parameters:

• address (number): The memory address to write to.

• value (number): The 8-bit integer value to write.

Returns:

• boolean: true if the write operation was successful, false otherwise.

Example:

if proc.is_attached() then
    local base = proc.base_address()
    local offset = 0x2000  -- Replace with an actual offset
    local value = 127  -- 8-bit value (max 255)
    
    local success = proc.write_int8(base + offset, value)
    if success then
        engine.log("Successfully wrote int8 value " .. value, 0, 255, 0, 255)
    else
        engine.log("Failed to write int8 value", 255, 0, 0, 255)
    end
end

---

proc.write_string

Signature: proc.write_string(address, text)

Description: Writes a string to the specified memory address.

Parameters:

• address (number): The memory address to write to.

• text (string): The string to write (null terminated).

Returns:

• boolean: true if the write operation was successful, false otherwise.

Example:

if proc.is_attached() then
    local string_address = 0x12345678  -- Replace with an actual address
    local text = "Hello, Process Memory!"
    
    local success = proc.write_string(string_address, text)
    if success then
        engine.log("Successfully wrote string to memory", 0, 255, 0, 255)
        
        -- Verify by reading back
        local read_text = proc.read_string(string_address, #text + 1)
        engine.log("Read back: " .. read_text, 255, 255, 255, 255)
    else
        engine.log("Failed to write string to memory", 255, 0, 0, 255)
    end
end

---

proc.write_wide_string

Signature: proc.write_wide_string(address, text)

Description: Writes a wide (UTF-16) string to the specified memory address.

Parameters:

• address (number): The memory address to write to.

• text (string): The string to write as a wide string (will be converted to UTF-16).

Returns:

• boolean: true if the write operation was successful, false otherwise.

Example:

if proc.is_attached() then
    local wide_string_address = 0x12345678  -- Replace with an actual address
    local text = "Unicode Text: 你好, こんにちは, Привет"
    
    local success = proc.write_wide_string(wide_string_address, text)
    if success then
        engine.log("Successfully wrote wide string to memory", 0, 255, 0, 255)
        
        -- Verify by reading back (chars * 2 for UTF-16)
        local read_text = proc.read_wide_string(wide_string_address, #text)
        engine.log("Read back: " .. read_text, 255, 255, 255, 255)
    else
        engine.log("Failed to write wide string to memory", 255, 0, 0, 255)
    end
end

---

proc.write_from_memory_buffer

Signature: proc.write_from_memory_buffer(address, buffer, size)

Description: Writes memory from a local buffer to the attached process's memory.

Parameters:

• address (number): The memory address to write to.

• buffer (handle): A memory buffer handle obtained from m.alloc().

• size (number): The number of bytes to write.

Returns:

• boolean: true if the write operation was successful, false otherwise.

Example:

if proc.is_attached() then
    -- Allocate and prepare a buffer
    local buffer_size = 16
    local buffer = m.alloc(buffer_size)
    
    if buffer then
        -- Fill the buffer with some values
        m.write_int32(buffer, 0, 0x12345678)
        m.write_int32(buffer, 4, 0x9ABCDEF0)
        m.write_int32(buffer, 8, 0x11223344)
        m.write_int32(buffer, 12, 0x55667788)
        
        -- Write the buffer to process memory
        local target_address = proc.base_address() + 0x3000  -- Replace with an actual address
        local success = proc.write_from_memory_buffer(target_address, buffer, buffer_size)
        
        if success then
            engine.log("Successfully wrote " .. buffer_size .. " bytes from buffer to memory", 0, 255, 0, 255)
        else
            engine.log("Failed to write from buffer to memory", 255, 0, 0, 255)
        end
        
        -- Free the buffer when done
        m.free(buffer)
    end
end