Lua:Class:MemScan

From Cheat Engine
Revision as of 19:36, 23 June 2026 by Leunsel (talk | contribs)
Jump to navigation Jump to search

{} Class

class MemScan : Object

The MemScan class represents a memory scan object.

A MemScan inherits from Object. It can perform first scans, next scans, unknown initial value scans, value comparisons, and saved-result comparisons. It can also be used together with a FoundList object to access scan results.

Inheritance

Class Inherits From Description
MemScan Object A memory scan object used to perform and manage memory scans.

Creation

<> Lua API Reference

function getCurrentMemscan() : MemScan

<> Lua API Reference

function createMemScan(progressbar) : MemScan

Returns or creates a MemScan object.

getCurrentMemscan returns the current memory scan object. If tabs are used, it returns the MemScan object of the currently selected tab.

createMemScan creates a new MemScan object. The optional progressbar parameter can be used to attach scan progress to a progress bar.

Function Parameters

Function Parameter Description
getCurrentMemscan() None Returns the current MemScan object.
createMemScan(progressbar) progressbar (optional) Creates a new MemScan object and optionally attaches a progress bar.

Returns

MemScan — A memory scan object.

Scan State Properties

Property Type Description
LastScanWasRegionScan Boolean Returns true if the previous scan was an unknown initial value scan.
LastScanValue String The value used by the previous scan.
LastScanType ScanType or String The type of the previous scan, such as stNewScan or stNextScan.
ScanresultFolder String The path where the scan results are stored.
FoundList FoundList The FoundList currently attached to this MemScan object.
OnlyOneResult Boolean If true, the scan stops after finding the first result and writes the address to Result.
IsUnique Boolean Similar to OnlyOneResult, but uses multiple threads. If the value is not unique, a random matching address may be returned.
Result Integer If OnlyOneResult is used, this contains the found address after the scan has finished.

Event Properties

Property Type Description
OnScanDone Function Function called when the scan has finished. Receives the MemScan object as parameter.
OnGuiUpdate Function Function called during the scan so the interface can be updated.

OnGuiUpdate Parameters

Parameter Type Description
memscan MemScan The MemScan object that is currently scanning.
TotalAddressesToScan Integer The total number of addresses that will be scanned.
CurrentlyScanned Integer The number of addresses already scanned.
ResultsFound Integer The number of results found so far.

Scan Configuration Properties

Property Type Description
CodePage Boolean Controls code page handling for scans that use text input.
ScanOption TScanOption The scan option to use.
VariableType TVariableType The variable type to scan for.
VarType TVariableType Alias for VariableType.
Roundingtype TRoundingType The rounding mode used for floating-point scans.
Scanvalue String The primary value to scan for.
Scanvalue1 String Alias for Scanvalue.
Scanvalue2 String The secondary value to scan for, such as the upper value in a value-between scan.
Startaddress Integer The start address of the scan range.
Stopaddress Integer The stop address of the scan range.
Hexadecimal Boolean If true, the input value is treated as hexadecimal.
BinaryStringAsDecimal Boolean If true and the variable type is vtBinary, the input is treated as decimal instead of a binary string.
UTF16 Boolean If true and the variable type is vtString, a UTF-16 string scan is performed.
Casesensitive Boolean If true and the variable type is vtString, the scan is case-sensitive.
Fastscanmethod TFastScanMethod The fast scan alignment method.
Fastscanparameter String The parameter used by the selected fast scan method.
Customtype TCustomType The custom type to use when scanning with a custom variable type.

Scan Region Properties

Property Type Description
ScanWritable TScanRegionPreference Controls whether writable memory is included, excluded, or ignored.
ScanExecutable TScanRegionPreference Controls whether executable memory is included, excluded, or ignored.
ScanCopyOnWrite TScanRegionPreference Controls whether copy-on-write memory is included, excluded, or ignored.

Saved Scan Properties

Property Type Description
Percentage Boolean If true, the scan uses percentage-based comparison where supported.
CompareToSavedScan Boolean If true, the scan compares against a saved scan result.
SavedScanName String The name of the saved scan result to compare against.

Methods

Method Return Type Description
scan() void Performs either a first scan or next scan based on the current property values.
firstScan() void Performs a first scan based on the current property values.
nextScan() void Performs a next scan based on the current property values.
newScan() void Clears the current scan results.
firstScan(scanoption, vartype, roundingtype, input1, input2, startAddress, stopAddress, protectionflags, alignmenttype, alignmentparam, isHexadecimalInput, isNotABinaryString, isunicodescan, iscasesensitive) void Performs an initial scan using the specified parameters.
nextScan(scanoption, roundingtype, input1, input2, isHexadecimalInput, isNotABinaryString, isunicodescan, iscasesensitive, ispercentagescan, savedresultname) void Performs a next scan based on the previous scan or a saved result list.
waitTillDone() void Waits for the MemScan thread or threads to finish scanning. This should be used after starting a scan.
saveCurrentResults(name) void Saves the current scan results to a unique name for this MemScan object.
getSavedResultList() Table Returns an indexed table containing the names of all saved results.
getSavedResultHandler(name) SavedResultHandler Returns the SavedResultHandler object with the given name, or nil on failure.
getAttachedFoundlist() FoundList Returns the attached FoundList object, or nil if no FoundList is attached.
setOnlyOneResult(state) void If true before a scan starts, the scanner only returns one result. This does not work with a FoundList.
getOnlyResult() Integer or nil Only works if OnlyOneResult is true. Returns the found address or nil if no result was found.
getProgress() Table Returns a table containing progress information.

Progress Table Fields

Field Type Description
TotalAddressesToScan Integer The total number of addresses that will be scanned.
CurrentlyScanned Integer The number of addresses already scanned.
ResultsFound Integer The number of results found so far.

First Scan Parameters

Parameter Type Description
scanoption TScanOption Defines what type of first scan is performed.
vartype TVariableType Defines the variable type to scan for.
roundingtype TRoundingType Defines how exact-value floating-point scans are handled.
input1 String The primary input value, if required by the scan option.
input2 String The secondary input value, if required by the scan option.
startAddress Integer or CEAddressString The start address to scan from. Commonly 0.
stopAddress Integer or CEAddressString The address where the scan should stop. Commonly 0xffffffffffffffff.
protectionflags String Protection flags that control which memory regions are scanned.
alignmenttype TFastScanMethod The scan alignment type.
alignmentparam String The alignment parameter used by the selected alignment type.
isHexadecimalInput Boolean If true, the input value is treated as hexadecimal. If false, it is treated as decimal.
isNotABinaryString Boolean If true and vartype is vtBinary, the input is treated as decimal instead of a binary string.
isunicodescan Boolean If true and vartype is vtString, a UTF-16 string scan is performed.
iscasesensitive Boolean If true and vartype is vtString, the scan checks for matching case.

Next Scan Parameters

Parameter Type Description
scanoption TScanOption Defines what type of next scan is performed.
roundingtype TRoundingType Defines how exact-value floating-point scans are handled.
input1 String The primary input value, if required by the scan option.
input2 String The secondary input value, if required by the scan option.
isHexadecimalInput Boolean If true, the input value is treated as hexadecimal. If false, it is treated as decimal.
isNotABinaryString Boolean If true and the previous variable type is vtBinary, the input is treated as decimal instead of a binary string.
isunicodescan Boolean If true and the previous variable type is vtString, a UTF-16 string scan is performed.
iscasesensitive Boolean If true and the previous variable type is vtString, the scan checks for matching case.
ispercentagescan Boolean If true and supported by the scan option, Cheat Engine performs a percentage scan instead of a normal value scan.
savedresultname String (optional) The name of a saved result list that should be compared against. The first scan is named FIRST.

First Scan Options

Value Description
soUnknownValue Unknown initial value scan.
soExactValue Exact value scan.
soValueBetween Value between scan.
soBiggerThan Bigger than scan.
soSmallerThan Smaller than scan.

Next Scan Options

Value Description
soExactValue Exact value scan.
soValueBetween Value between scan.
soBiggerThan Bigger than scan.
soSmallerThan Smaller than scan.
soIncreasedValue Increased value scan.
soIncreasedValueBy Increased value by scan.
soDecreasedValue Decreased value scan.
soDecreasedValueBy Decreased value by scan.
soChanged Changed value scan.
soUnchanged Unchanged value scan.

Variable Types

Value Description
vtByte 1-byte integer.
vtWord 2-byte integer.
vtDword 4-byte integer.
vtQword 8-byte integer.
vtSingle Single-precision floating-point value.
vtDouble Double-precision floating-point value.
vtString String value.
vtByteArray Byte array.
vtGrouped Grouped scan value.
vtBinary Binary value.
vtAll All supported variable types.

Rounding Types

Value Description
rtRounded Normal rounded scan. For example, an exact value of 3 includes values from 3.0 to 3.49999999.
rtTruncated Truncated scan. For example, an exact value of 3 includes values from 3.0 to 3.99999999.
rtExtremerounded Extreme rounded scan. For example, an exact value of 3 includes values from 2.0000001 to 3.99999999.

Alignment Types

Value Description
fsmNotAligned No alignment check.
fsmAligned The address must be divisible by the value in alignmentparam.
fsmLastDigits The last digits of the address must end with the digits provided by alignmentparam.

Scan Region Preference Values

Value Description
scanDontCare Do not care whether this memory region attribute is present.
scanExclude Exclude memory regions with this attribute.
scanInclude Only include memory regions with this attribute.

Examples

local memscan = createMemScan()

memscan.firstScan(
  soExactValue,
  vtDword,
  rtRounded,
  "100",
  "",
  0,
  0xffffffffffffffff,
  "",
  fsmAligned,
  "4",
  false,
  true,
  false,
  false
)

memscan.waitTillDone()

print("First scan done")

local memscan = createMemScan()

memscan.firstScan(
  soExactValue,
  vtDword,
  rtRounded,
  "100",
  "",
  0,
  0xffffffffffffffff,
  "",
  fsmAligned,
  "4",
  false,
  true,
  false,
  false
)

memscan.waitTillDone()

memscan.nextScan(
  soIncreasedValue,
  rtRounded,
  "",
  "",
  false,
  true,
  false,
  false,
  false
)

memscan.waitTillDone()

print("Next scan done")

local memscan = createMemScan()

memscan.setOnlyOneResult(true)

memscan.firstScan(
  soExactValue,
  vtDword,
  rtRounded,
  "100",
  "",
  0,
  0xffffffffffffffff,
  "",
  fsmAligned,
  "4",
  false,
  true,
  false,
  false
)

memscan.waitTillDone()

local result = memscan.getOnlyResult()

if result ~= nil then
  print("Found address: " .. string.format("%X", result))
else
  print("No result found")
end

local memscan = createMemScan()

memscan.OnGuiUpdate = function(memscan, total, scanned, found)
  print("Scanned: " .. tostring(scanned) .. " / " .. tostring(total))
  print("Found: " .. tostring(found))
end

memscan.OnScanDone = function(memscan)
  print("Scan finished")
end

local memscan = getCurrentMemscan()

if memscan ~= nil then
  local progress = memscan.getProgress()

  print("Total: " .. tostring(progress.TotalAddressesToScan))
  print("Scanned: " .. tostring(progress.CurrentlyScanned))
  print("Found: " .. tostring(progress.ResultsFound))
end

Main Pages

Core Lua documentation entry points

◆ Lua
◆ Script Engine



Retrieved from "https://wiki.cheatengine.org/index.php?title=Lua:Class:MemScan&oldid=8053"