Mr millchick: fixed formatting, added related links

2025-10-21T04:24:43Z

fixed formatting, added related links

Mr millchick: Created page with "Category:Lua '''function''' AOBScanModuleUnique(''ModuleName'', ''AOBString'', ''ProtectionFlags'' OPTIONAL, ''AlignmentType'' OPTIONAL, ''AlignmentParam'' HALFOPTIONAL)..."

2025-10-20T22:46:32Z

Created page with "Category:Lua '''function''' AOBScanModuleUnique(''ModuleName'', ''AOBString'', ''ProtectionFlags'' OPTIONAL, ''AlignmentType'' OPTIONAL, ''AlignmentParam'' HALFOPTIONAL)..."

New page

[[Category:Lua]]
'''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 [[Lua:AOBScan|AOBScan]], this function returns a single integer address (or nil) instead of a StringList, so there's no need to call destroy().

=== Function Parameters ===

{|width="85%" cellpadding="10%" cellpadding="5%" cellspacing="0" border="0"
!align="left"|Parameter
!align="left"|Type
!style="width: 80%;" align="left"|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 ===

{|width="85%" cellpadding="10%" cellpadding="5%" cellspacing="0" border="1"
!Function
!Return Type
!Scope
!Uniqueness
|-
|AOBScanModuleUnique
|Integer or nil
|Single module
|Yes (returns nil if multiple matches)
|-
|[[Lua:AOBScanUnique|AOBScanUnique]]
|Integer or nil
|All memory
|Yes (returns nil if multiple matches)
|-
|[[Lua:AOBScan|AOBScan]]
|StringList or nil
|All memory
|No (returns all matches)
|-
|[[Lua:AOBScanModule|AOBScanModule]]
|StringList or nil
|Single module
|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:AOBScanUnique|AOBScanUnique]] - Scan all memory for a unique pattern
* [[Lua:AOBScan|AOBScan]] - Scan all memory and return all matches
* [[Lua:AOBScanModule|AOBScanModule]] - Scan a module and return all matches
* [[Lua:getAddress|getAddress]] - Convert symbol names to addresses

@@ Line 4: / Line 4: @@
 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.
+* '''Returns:''' The address as an integer if a unique match is found, or '''nil''' if no match or multiple matches are found.
+* '''Note:''' Unlike [[Lua:AOBScan|AOBScan]], this function returns a single integer address (or nil) instead of a StringList, so there's no need to call destroy().
 === Function Parameters ===
@@ Line 152: / Line 151: @@
 |StringList or nil
 |All memory
 |No (returns all matches)
 |}
@@ Line 174: / Line 168: @@
-=== See Also ===
+{{LuaSeeAlso}}
 * [[Lua:AOBScanUnique|AOBScanUnique]] - Scan all memory for a unique pattern
-* [[Lua:AOBScan|AOBScan]] - Scan all memory and return all matches
 * [[Lua:getAddress|getAddress]] - Convert symbol names to addresses

Lua:AOBScanModuleUnique - Revision history

Mr millchick: fixed formatting, added related links

Mr millchick: Created page with "Category:Lua '''function''' AOBScanModuleUnique(''ModuleName'', ''AOBString'', ''ProtectionFlags'' OPTIONAL, ''AlignmentType'' OPTIONAL, ''AlignmentParam'' HALFOPTIONAL)..."