Mr millchick: fixed formatting, added related links

2025-10-21T04:21:15Z

fixed formatting, added related links

Mr millchick: Created page with "Category:Lua '''function''' AOBScanUnique(''AOBString'', ''ProtectionFlags'' OPTIONAL, ''AlignmentType'' OPTIONAL, ''AlignmentParam'' HALFOPTIONAL) Scans the entire proce..."

2025-10-20T22:47:09Z

Created page with "Category:Lua '''function''' AOBScanUnique(''AOBString'', ''ProtectionFlags'' OPTIONAL, ''AlignmentType'' OPTIONAL, ''AlignmentParam'' HALFOPTIONAL) Scans the entire proce..."

New page

[[Category:Lua]]
'''function''' AOBScanUnique(''AOBString'', ''ProtectionFlags'' OPTIONAL, ''AlignmentType'' OPTIONAL, ''AlignmentParam'' HALFOPTIONAL)

Scans the entire process memory for a byte pattern 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().

'''Implementation:''' This function is equivalent to calling AOBScanModuleUnique("", AOBString, ...) with an empty module name.

=== Function Parameters ===

{|width="85%" cellpadding="10%" cellpadding="5%" cellspacing="0" border="0"
!align="left"|Parameter
!align="left"|Type
!style="width: 80%;" align="left"|Description
|-
|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" (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 (recommended for code patterns)
"+W-C" Writable memory excluding copy-on-write
"+X-W-C" Readonly executable memory (code sections)
"" Uses default "*X*W*C" (scan all memory)

=== 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, "4" = 4-byte aligned)
* For '''AlignmentType=2''': Required ending hex digits (e.g., "00" = addresses ending in ...00)

=== Usage Examples ===

'''Basic unique scan:'''
local address = AOBScanUnique("48 8B 05 ?? ?? ?? 89")
if address then
print(string.format("Found at: %X", address))
-- Use address directly for reading/writing
writeBytes(address, 0x90, 0x90, 0x90)
else
print("Pattern not found or not unique")
end

'''Scan executable memory only (faster):'''
local address = AOBScanUnique("55 8B EC 83 EC", "+X")
if address then
print("Function found at: " .. address)
end

'''With alignment checking:'''
local address = AOBScanUnique("FF 15 ?? ?? ?? ??", "+X", 1, "10")
-- Only matches on 16-byte aligned addresses

'''Register the result as a symbol:'''
local addr = AOBScanUnique("48 89 5C 24 ?? 57", "+X")
if addr then
registerSymbol("MyFunction", addr)
print("Registered MyFunction at " .. addr)
end

'''Conditional execution based on pattern:'''
local patchAddr = AOBScanUnique("74 ?? 8B 45", "+X")
if patchAddr then
-- Apply patch only if pattern is unique
writeBytes(patchAddr, 0xEB) -- Change JE to JMP
print("Patched at: " .. patchAddr)
else
print("ERROR: Pattern not unique or not found!")
return false
end

'''Find and calculate relative offset:'''
local callAddr = AOBScanUnique("E8 ?? ?? ?? ??", "+X")
if callAddr then
local offset = readInteger(callAddr + 1)
local target = callAddr + 5 + offset
print(string.format("Call target: %X", target))
end

=== Return Value ===

* '''Success (unique match):''' Returns the address as an integer
* '''Failure:''' Returns '''nil''' in these cases:
** Pattern not found anywhere in memory
** Multiple matches found (not unique)
** Empty AOBString parameter

=== Performance Tips ===

* Use '''+X''' protection flag when scanning for code to dramatically reduce scan time
* For module-specific scans, use [[Lua:AOBScanModuleUnique|AOBScanModuleUnique]] instead (much faster)
* The scan stops after finding more than one match to ensure uniqueness
* More specific patterns (fewer wildcards) are faster and more likely to be unique

=== When to Use AOBScanUnique ===

'''Use AOBScanUnique when:'''
* You expect exactly one match in the entire process
* You want automatic validation that the pattern is unique
* You need a simple integer address for immediate use
* You're looking for a specific global function or unique code sequence

'''Use [[Lua:AOBScan|AOBScan]] when:'''
* You expect or want multiple matches
* You need to analyze all occurrences of a pattern
* The pattern might appear in multiple locations

=== Comparison with Related Functions ===

{|width="85%" cellpadding="10%" cellpadding="5%" cellspacing="0" border="1"
!Function
!Return Type
!Scope
!Uniqueness
|-
|AOBScanUnique
|Integer or nil
|All memory
|Yes (returns nil if multiple matches)
|-
|[[Lua:AOBScanModuleUnique|AOBScanModuleUnique]]
|Integer or nil
|Single module
|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)
|}

=== Common Pitfalls ===

'''Pattern too generic:'''
-- This will likely fail because "90 90" appears many times
local addr = AOBScanUnique("90 90") -- Returns nil (multiple matches)

'''Solution - Make pattern more specific:'''
local addr = AOBScanUnique("90 90 90 C3 48 89 5C") -- More unique context

'''Not checking for nil:'''
-- WRONG - will crash if pattern not found
local addr = AOBScanUnique("48 8B")
writeBytes(addr, 0x90) -- ERROR if addr is nil!

'''Solution - Always check return value:'''
local addr = AOBScanUnique("48 8B")
if addr then
writeBytes(addr, 0x90)
else
print("Pattern not found or not unique")
end

=== See Also ===

* [[Lua:AOBScanModuleUnique|AOBScanModuleUnique]] - Scan within a specific module (faster)
* [[Lua:AOBScan|AOBScan]] - Scan all memory and return all matches
* [[Lua:registerSymbol|registerSymbol]] - Register found addresses as symbols
* [[Lua:writeBytes|writeBytes]] - Write bytes to found addresses

@@ Line 4: / Line 4: @@
 Scans the entire process memory for a byte pattern 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().
-'''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().
+* '''Implementation:''' This function is equivalent to calling AOBScanModuleUnique("", AOBString, ...) with an empty module name.
 === Function Parameters ===
@@ Line 171: / Line 169: @@
 |StringList or nil
 |All memory
 |No (returns all matches)
 |}
@@ Line 203: / Line 196: @@
-=== See Also ===
+{{LuaSeeAlso}}
 * [[Lua:AOBScanModuleUnique|AOBScanModuleUnique]] - Scan within a specific module (faster)
-* [[Lua:AOBScan|AOBScan]] - Scan all memory and return all matches
 * [[Lua:registerSymbol|registerSymbol]] - Register found addresses as symbols
 * [[Lua:writeBytes|writeBytes]] - Write bytes to found addresses

Lua:AOBScanUnique - Revision history

Mr millchick: fixed formatting, added related links

Mr millchick: Created page with "Category:Lua '''function''' AOBScanUnique(''AOBString'', ''ProtectionFlags'' OPTIONAL, ''AlignmentType'' OPTIONAL, ''AlignmentParam'' HALFOPTIONAL) Scans the entire proce..."