Lua:AOBScanModuleUnique

function AOBScanModuleUnique(ModuleName, AOBString, ProtectionFlags OPTIONAL, AlignmentType OPTIONAL, AlignmentParam HALFOPTIONAL)

Scans for a byte pattern within a specific module and returns the address if exactly one unique match is found.

• Returns: The address as an integer if a unique match is found, or nil if no match or multiple matches are found.
• Note: Unlike AOBScan, this function returns a single integer address (or nil) instead of a StringList, so there's no need to call destroy().

Function Parameters

Parameter	Type	Description
ModuleName	string	The name of the module to scan within (e.g., "game.exe", "kernel32.dll"). Use "" (empty string) to scan all memory
AOBString	string	A hex byte pattern with space/comma/dash separators. Use ?? or * for full-byte wildcards. Supports nibble wildcards like 7? or ?A
ProtectionFlags	string	Optional. Memory protection filter. Default: "*X*W*C" (don't care about all flags, scan all memory regions)
AlignmentType	integer	Optional. Alignment mode: 0=None, 1=Divisible, 2=Last digits. Default: 0
AlignmentParam	string	Optional. Hex value for alignment checking. Default: "1"

Protection Flags

The ProtectionFlags parameter filters memory regions based on protection attributes:

Syntax: Prefix each flag with:

• + = Region MUST have this flag set
• - = Region MUST NOT have this flag set
• * = Don't care (default)

Flags:

• X = Executable
• W = Writable
• C = Copy On Write
• D = Dirty (macOS only)

Examples:

 "+X"       All executable memory (typical for code scanning in modules)
 "+X-W"     Readonly executable memory (code sections)
 ""         Uses default "*X*W*C" (scan all regions in the module)

Alignment Parameters

AlignmentType values:

• 0 = fsmNotAligned - No alignment check (default)
• 1 = fsmAligned - Address must be divisible by AlignmentParam
• 2 = fsmLastDigits - Address must end with specific hex digits

AlignmentParam:

• Interpreted as a hexadecimal value
• For AlignmentType=1: Alignment boundary (e.g., "10" = 16-byte aligned)
• For AlignmentType=2: Required ending hex digits (e.g., "00" = addresses ending in ...00)

Usage Examples

Basic unique scan in a module:

local address = AOBScanModuleUnique("game.exe", "48 8B 05 ?? ?? ?? 89")
if address then
  print(string.format("Found at: %X", address))
else
  print("Pattern not found or not unique")
end

Scan executable memory in module:

local address = AOBScanModuleUnique("kernel32.dll", "55 8B EC", "+X")
if address then
  -- Use the address directly, no cleanup needed
  print("Address: " .. address)
end

Scan all memory (empty module name):

local address = AOBScanModuleUnique("", "DE AD BE EF")
if address then
  print("Found in any module at: " .. address)
end

With alignment (16-byte aligned):

local address = AOBScanModuleUnique("game.exe", "FF 15 ?? ?? ?? ??", "+X", 1, "10")

Helper function to get module base + offset:

function findPattern(module, pattern)
  local addr = AOBScanModuleUnique(module, pattern, "+X")
  if addr then
    local base = getAddress(module)
    return addr, addr - base  -- returns address and offset
  end
  return nil
end

local addr, offset = findPattern("game.exe", "48 89 5C 24")
if addr then
  print(string.format("Found at offset: +%X", offset))
end

Return Value

• Success (unique match): Returns the address as an integer
• Failure: Returns nil in these cases:
  • Pattern not found in the module
  • Multiple matches found (not unique)
  • Invalid module name
  • Empty AOBString parameter

Performance Tips

• Scanning within a specific module is much faster than scanning all memory
• Use +X protection flag for code patterns to speed up scanning
• The scan stops after finding more than one match (ensuring uniqueness)
• Module name is case-insensitive

Comparison with Related Functions

Function	Return Type	Scope	Uniqueness
AOBScanModuleUnique	Integer or nil	Single module	Yes (returns nil if multiple matches)
AOBScanUnique	Integer or nil	All memory	Yes (returns nil if multiple matches)
AOBScan	StringList or nil	All memory	No (returns all matches)

Error Handling

Not enough parameters:

-- Returns nil and pushes error message
local result = AOBScanModuleUnique("game.exe")  -- Missing AOBString
-- result will be nil

Empty AOBString:

-- Returns nil and pushes error message
local result = AOBScanModuleUnique("game.exe", "")
-- result will be nil

See also

• Lua
• Script engine

Related Functions

• AOBScan - Scan all memory and return all matches
• AOBScanUnique - Scan all memory for a unique pattern

• getAddress - Convert symbol names to addresses

• autoAssemble
• disassemble
• getInstructionSize
• getPreviousOpcode
• allocateSharedMemory
• mapMemory
• unmapMemory
• readBytes
• readPointer
• writeBytes
• readBytesLocal
• readPointerLocal
• writeBytesLocal
• wordToByteTable
• dwordToByteTable
• qwordToByteTable
• floatToByteTable
• doubleToByteTable
• stringToByteTable
• wideStringToByteTable
• byteTableToWord
• byteTableToDword
• byteTableToQword
• byteTableToFloat
• byteTableToDouble
• byteTableToString
• byteTableToWideString