Complete function reference for every module in
Manifold-Modules/Manifold.Modules/.
Concepts, bootstrapping and flows are covered in Manifold-Framework.md.
Conventions used here:
- Functions with a leading
_are internal helpers. They are documented because they are exposed throughregisterLuaFunctionHighlightand are needed when extending the modules, but they are not part of the stable API. - Almost every module has
New(...),GetModuleInfo()andPrintModuleInfo(). Those three are described in detail only for the first module that has them.Manifold.Trampolineshas noPrintModuleInfo, andManifold.Bootstrapis a namespace with nothing to instantiate, so it has none of the three. - Every production module declares itself to
Manifold.Bootstrapwhen its file executes. Where a module still has aCheckDependencies()method, that method is now a single call intoBootstrap.Resolve. It returnsboolean, table, meaning resolved plus the list of missing dependency names, and it loads nothing by itself whileBootstrap.Settings.AutoLoadisfalse, which is the default. - A declared dependency comes in three kinds. One marked
requiredmakesNew()refuse rather than come up half built. One markedruntimeis documentation only, so it is never looked up during construction and never counts as missing. One with neither marker, written as{ "name" }, is called an optional dependency throughout this reference. It is looked up at construction, and a missing one leaves the module degraded but running.
Contents#
- Manifold.Bootstrap
- Manifold.Json
- Manifold.Logger
- Manifold.CustomIO
- Manifold.Helper
- Manifold.Utils
- Manifold.ProcessHandler
- Manifold.Memory
- Manifold.State
- Manifold.AutoAssembler
- Manifold.Callbacks
- Manifold.AssemblerCommands
- Manifold.Trampolines
- Manifold.Forms
- Manifold.UI
- Manifold.Teleporter
- Manifold.TeleporterMap
- Manifold.Testing
Manifold.Bootstrap#
Bootstrap, version 1.0.3. It requires nothing and declares nothing, because it is the framework
root and sits below Manifold.Json. It is a namespace rather than a class, so its functions are
dot-called and there is no instance to create. The published table lives in the global
ManifoldBootstrap.
The registry survives a reload. CETrequire re-executes a file on every call, so this module
keeps all of its state in one _G slot and mutates the published API table in place instead of
replacing it. A module that captured local BOOTSTRAP = ... stays valid after the core is
re-executed.
Module registry#
| Function | Returns | Description |
|---|---|---|
Bootstrap.Declare(spec) |
table |
Called once at chunk scope by every module. spec is {class, global, name, version, author, description, prefix, deps}. Returns the descriptor that Resolve and Ready are given later. This is also the collision detector, since it runs on every execution of the module file. |
Bootstrap.Resolve(mod) |
boolean, table |
The single dependency lookup for the whole framework. required = true raises out of New() with one legible message. runtime = true is documentation only and never gates or orders anything. |
Bootstrap.Ready(mod, instance) |
table |
Closes New(). Emits exactly one line per module per generation, carrying the name and version. Info when every declared dependency was satisfied, Warning when the module came up degraded. |
Bootstrap.Register(key, spec) |
table|nil, string? |
Teaches the core about a module that is not in KNOWN, for example a Manifold.Dev tool or a fork. It never overwrites an existing entry and gets no position in the order of execution. |
Bootstrap.Configure(key, config) |
table |
Stores the constructor config for a module so a lazy bring-up gets the configuration the cheat table intended. Call it before Bootstrap.Boot(). Returns Bootstrap for chaining. |
Lookup and construction#
| Function | Returns | Description |
|---|---|---|
Bootstrap.Require(path, class, force) |
table|nil, string? |
The sanctioned replacement for a bare pcall(CETrequire, path). Skips the call entirely when the module table is already present, and turns a path typo into a real error. |
Bootstrap.Acquire(key, config) |
table|nil, string? |
Guarantees that key names a live, usable instance in _G, loading and constructing it only when it genuinely is not there. Lazy runtime call sites must use this instead of Class:New(). |
Bootstrap.Get(key) |
table|nil, string? |
The same read-first lookup as Acquire, named for the place it is used. |
Bootstrap.Contract(key, value, extra) |
boolean, string? |
The usability half of validation. Does this value answer the calls its consumers make? |
Bootstrap.Validate(key, value, extra) |
boolean, string? |
Contract plus identity. Is this global still a pristine instance of the module table loaded right now? The metatable test detects an instance orphaned by a re-executed chunk. |
Bootstrap.Verify(raise) |
boolean, table |
Proves the order of execution. Every ORDER key exists in KNOWN, every KNOWN key appears in ORDER exactly once, and every non-runtime dependency sits earlier in ORDER. An order that passes cannot contain a load-time cycle. |
Bootstrap.Boot(options) |
boolean, table |
Walks Bootstrap.ORDER and acquires every module. Entirely optional. options accepts config, skip, only, after, stopOnError and verify (default true). A module whose needs were skipped, failed or not booted is skipped with one Info line, and so is an optional module whose file is not shipped; neither counts as a failure. |
Bootstrap.Reload(key) |
table|nil, string? |
Forces one module through a full reload: drop the globals, re-require, reconstruct. The one supported way to reload during development. |
Diagnostics#
| Function | Returns | Description |
|---|---|---|
Bootstrap.Once(key, fn) |
boolean |
Runs fn at most once per session, latched in the registry so a re-executed module file cannot reset it. For load-time side effects that must not stack. |
Bootstrap.Flush() |
integer |
Replays every line queued before a logger existed, oldest first. Safe to call at any time. |
Bootstrap.WriteManifest() |
integer |
Re-writes the manifest of every module that has announced so far into the log file. Call it once, immediately after logger:ClearLogFile(), and never at any other point. |
Bootstrap.Report() |
table |
Everything the registry knows. Two rows with the same name and different sources is a collision you can act on. |
Bootstrap.PrintReport() |
Logs the report, one entry per module, through Logger:BuildBlock. An on-demand diagnostic, deliberately outside the one-line-per-module rule. Falls back to its own renderer when no logger exists yet. |
|
Bootstrap.GetModuleInfo() / PrintModuleInfo() |
table / |
The usual metadata pair, dot-called. |
Fields#
| Field | Description |
|---|---|
Bootstrap.KNOWN |
The single source of truth for how a module is found and built: path, class, construct, an optional contract predicate and rebuild. An entry may add needs (keys it cannot be built without) and optional (its file may be left out of a table); teleporterMap declares both. |
Bootstrap.ORDER |
The order of execution as a linear array. Every load-time edge points strictly backwards in it. |
Bootstrap.Settings |
ReadyLevel (default "Info"), DegradedLevel ("Warning"), ReloadLevel ("Warning"), ConflictLevel ("Error") and AutoLoad (false). |
Bootstrap.Registry |
The reload-surviving registry table itself. |
Bootstrap.SOURCE |
Short source name of the chunk that loaded the core. |
Bootstrap.ORDER = {
"json", "logger", "customIO", "helper", "memory", "forms",
"processHandler", "ui", "utils", "state", "trampolines",
"assemblerCommands", "autoAssembler", "teleporter", "teleporterMap", "callbacks",
}
Two constraints in that order are hand-injected rather than produced by the topological pass.
logger comes before customIO because CustomIO's json-miss path indexes the logger unguarded,
and callbacks is last because its chunk binds Cheat Engine handlers at load time.
AutoLoad is false by default, which means Bootstrap.Resolve never loads anything. A missing
dependency is reported, and when it is required the constructor refuses. The cheat table's Lua
script therefore stays the single source of truth for what is loaded and in what order. Setting
AutoLoad to true restores the older behaviour where a module silently pulled in whatever it
was missing. The flag gates the implicit path only. Bootstrap.Acquire and Bootstrap.Get are
explicit lookups and always load.
Manifold.Json#
Json, version 1.0.2. Self-contained encoder and decoder written for the framework. It replaced
the vendored Jeffrey Friedl implementation in 1.0.0. The logger is declared as a runtime
dependency, not a load-time one, because this module is position 1 in Bootstrap.ORDER and is
built before any logger can exist. Every log site in the file is guarded and resolves the global
at call time.
The global is Json, the instance global is json, and JSON is kept as an alias of Json so
call sites written against the previous module keep working.
Construction and metadata#
| Function | Returns | Description |
|---|---|---|
Json:New() |
Json |
Tolerates Json.New() as well as Json:New(). A missing self falls back to the module table instead of producing an orphan without a metatable. |
Json:CheckDependencies() |
boolean, table |
The same single call into Bootstrap.Resolve that its siblings make. Records whether diagnostics are live. It can never refuse, because its one declared dependency is the runtime logger and a runtime dependency is never looked up here. |
Json:GetModuleInfo() |
table |
{ name, version, author, description } |
Json:PrintModuleInfo() |
Prints through logger:Info when a logger exists, and through print when one does not. |
Public API#
Every entry point is call-style agnostic. Json.Encode(v), Json:Encode(v), instance:Encode(v)
and a detached local f = json.Encode all behave identically. There is no "must be called in
method format" guard anywhere in the module. An options table is accepted in either the second or
the third argument slot, so the legacy (value, etc, options) shape still works.
| Function | Returns | Description |
|---|---|---|
Json.Encode(value [, options]) |
string|nil, string|nil |
Compact JSON, or nil plus the error message. |
Json.EncodePretty(value [, options]) |
string|nil, string|nil |
Indented, human readable JSON. Used by CustomIO:WriteToFileAsJson. |
Json.Decode(text [, options]) |
any|nil, string|nil |
JSON null becomes Json.Null so it survives inside tables. Pass { Null = false } to drop null members instead. |
Json.Validate(text [, options]) |
boolean, string|nil |
Decodes quietly. A rejection is the normal outcome here, so it does not fire the usual failure report. Set Json.Debug to see rejections. |
Json.Minify(text [, options]) |
string|nil, string|nil |
Re-encodes JSON text without whitespace. |
Json.Prettify(text [, options]) |
string|nil, string|nil |
Re-encodes with indentation. Turns RecordKeyOrder on for the decode half unless the caller set it. |
Json.NewArray(t) |
table |
Tags a table so it always encodes as a JSON array, even when empty. |
Json.NewObject(t) |
table |
Tags a table so it always encodes as a JSON object, even when empty. |
Json.IsNull(v) |
boolean |
Is this value the JSON null sentinel? |
Json.IsArray(v) |
boolean |
Does this table carry the explicit array marker? |
Json.IsObject(v) |
boolean |
Does this table carry the explicit object marker? |
Json.SetDebug(enabled) |
boolean |
Enables or disables per-call diagnostics and returns the resulting state. |
Fields#
| Field | Default | Description |
|---|---|---|
Json.Debug |
false |
Opt-in per-call summaries. Off costs one field read per public call. |
Json.ExcerptBytes |
96 |
Bytes of the offending input quoted next to a decode failure. 0 quotes nothing. |
Json.Null |
The immutable sentinel used for JSON null. tostring gives "null". |
|
Json.Defaults |
Mutable module-wide defaults, listed below. Per-call options always win. | |
Json.VERSION |
"1.0.1" |
Option keys are matched case-insensitively and ignore underscores, so SortKeys, sortkeys and
sort_keys all address the same setting.
Json.Defaults = {
-- Encoding ------------------------------------------------------------
Indent = " ", -- string, or a number of spaces
SortKeys = nil, -- nil = sort in pretty mode only
PreserveOrder = true, -- honour a decoded key order when present
EmptyTable = "object", -- "object" | "array"
SparseArray = "null", -- "null" | "object" | "error"
MaxSparseRatio = 8, -- fall back to "object" beyond this density
EscapeUnicode = false, -- emit non-ASCII as \uXXXX
EscapeSlash = false, -- emit "/" as "\/"
InvalidNumber = "error", -- NaN/Infinity: "error" | "null" | "string"
InvalidValue = "error", -- functions/userdata: "error" | "null" | "skip"
InvalidKey = "error", -- unusable table keys: "error" | "skip"
MaxDepth = 200,
NullValue = nil, -- extra value to treat as null on encode
-- Decoding ------------------------------------------------------------
Null = Null, -- value produced for JSON null
MarkTables = true, -- tag decoded tables as array/object
RecordKeyOrder = false, -- remember object key order for round-trips
AllowComments = false, -- // line and /* block */ comments
AllowTrailingComma = false,
AllowSingleQuotes = false,
AllowUnquotedKeys = false,
AllowTrailingData = false,
AllowDuplicateKeys = true,
BigIntAsString = false, -- integers beyond int64 stay exact as strings
UnpairedSurrogate = "replace",-- "replace" | "error" | "raw"
Lenient = false, -- enables the whole Allow* group at once
}
Compatibility layer#
| Alias | Target |
|---|---|
Json.new |
Json.New |
Json.encode |
Json.Encode |
Json.encode_pretty |
Json.EncodePretty |
Json.decode |
Json.Decode |
Json.newArray |
Json.NewArray |
Json.newObject |
Json.NewObject |
Json.null |
the null sentinel |
JSON |
Json |
Handle decode failures without raising:
local value, err = json:decode(text)
if not value then logger:Error(err) end
Encoding and decoding no longer verify self.__index == JSON, so an instance created before a
module reload keeps working
(TODO T7, resolved).
Manifold.Logger#
Logger, version 1.2.0. A framework leaf with no declared dependencies, and since 1.2.0 that is
true of the file half as well: it reaches lfs and io directly rather than borrowing customIO.
That is what removed the mutual recursion
(TODO T23, resolved). Without lfs
the module degrades to console output only.
Construction and metadata#
| Function | Returns | Description |
|---|---|---|
Logger:New() |
Logger |
Sets Level = Levels.ERROR, Output = print, DataDir = %USERPROFILE%\AppData\Local\Manifold, LogFileName = "Manifold.Runtime.Unknown.log" and FileLogging = true. |
logger:GetModuleInfo() |
table |
{ name, version, author, description } |
logger:PrintModuleInfo() |
One InfoBlock. Every module in the framework uses this same shape. |
Fields#
| Field | Default | Description |
|---|---|---|
Level |
Levels.ERROR (4) |
Minimum level for console output |
Levels |
{DEBUG=1, INFO=2, WARNING=3, ERROR=4, CRITICAL=5} |
|
LevelNames |
Reverse map of Levels |
|
Output |
print |
Target function for console output |
DataDir |
%USERPROFILE%\AppData\Local\Manifold |
Its own copy, independent of customIO.DataDir |
LogFileName |
Manifold.Runtime.Unknown.log |
Relative to DataDir\Logs |
FileLogging |
true |
While false nothing touches the disk. A failed write sets it. |
FileLogError |
nil |
Why disk logging was switched off, when it was. |
Configuration#
| Function | Description |
|---|---|
logger:SetLevel(level) |
Accepts a number or a name such as "INFO". An unknown name gives Levels.INFO. A real change is reported through ForceInfo, a no-op change through Info. |
logger:SetLogFileName(name) |
Produces Manifold.Runtime.<name>.log. An empty or nil name gives Manifold.Runtime.Unknown.log. |
logger:SetOutput(fn) |
Passing nil restores print. |
logger:ClearLogFile() |
Truncates the file by opening it with "w" and closing it immediately. |
Disk failures#
The file half switches itself off rather than retrying. The first failed write, whether the data
directory cannot be created or the file cannot be opened, sets FileLogging = false, records the
reason in FileLogError and reports it once through ForceWarning. Nothing after that touches the
disk. The console and Output keep working.
That matters because the failure case is an end-user machine where
%USERPROFILE%\AppData\Local\Manifold\Logs cannot be written. Without the switch every log line
paid for a directory check and an open attempt, and customIO reported each failure through this
same logger, which tried to write it to the file that could not be written
(TODO T23).
| Function | Returns | Description |
|---|---|---|
logger:DisableFileLogging(reason) |
Switches the disk off for the session and reports it once. | |
logger:EnableFileLogging() |
Switches it back on and forgets the cached directory state. | |
logger:GetFileLoggingState() |
boolean, string|nil |
Whether the disk is live, and why it is not. |
One retry sits inside the write itself: an open that fails re-checks the directories once and tries again, which covers the log folder being deleted while Cheat Engine is running. The second failure is the one that switches the disk off.
Output#
For each level Debug, Info, Warning, Error and Critical, four functions are generated at
load time:
| Pattern | Example |
|---|---|
logger:<Level>(msg) |
logger:Info("ready") |
logger:<Level>F(fmt, ...) |
logger:InfoF("%d/%d", a, b) |
logger:Force<Level>(msg) |
logger:ForceError("critical") |
logger:Force<Level>F(fmt, ...) |
logger:ForceWarningF("%s", x) |
logger:<Level>Block(title, rows [, options]) |
logger:InfoBlock(MODULE_PREFIX .. " Scan Result", { { "Status", "OK" } }) |
logger:Force<Level>Block(title, rows [, options]) |
logger:ForceWarningBlock(title, rows) |
The Force variants bypass the level filter and tag the line with [FORCED].
| Function | Description |
|---|---|
logger:Log(level, message) |
Direct variant, honours Level. |
logger:ForceLog(level, message) |
Direct variant without filtering. |
logger:BuildBlock(title, rows [, options]) |
Renders a block without logging it. Pure, so it can be tested and reused. |
logger:Stringify(value [, processed]) |
Recursive text representation. A cycle becomes {...} and a null byte becomes \0. |
Blocks#
A multi-row report written as N separate calls repeats the timestamp and the module prefix on every
row, which is most of the line width. BuildBlock renders the whole report as one string, so it
becomes a single log entry with one prefix and labels that align themselves.
logger:InfoBlock(MODULE_PREFIX .. " InstallDetour OK", {
{ "Name", entry.Name },
{ "Relay Offset", string.format("%s+%X", moduleName, offset) },
condition and { "Dest Address", address } or false,
})
[19:48:29] [INFO] [Trampolines] InstallDetour OK
Name : Player
Relay Offset : gamedll_x64_rwdi.dll+500
- Rows are
{ label, value }pairs, or a plain string for a line without a label. - Use
falseto skip a row. A barenilcuts the block short, because the walk is anipairsand stops at the first hole. - Values run through
Stringify, and a value containing newlines hangs under its own label. options:indent(default" "),separator(default" : "),align(defaulttrue).
Format: [HH:MM:SS] [LEVEL] [FORCED] <message>
Internal helpers#
| Function | Description |
|---|---|
logger:_GetLogsDirectory() |
DataDir\Logs |
logger:_GetLogFilePath() |
DataDir\Logs\<LogFileName> |
logger:_EnsureLogDirectories() |
Creates DataDir and Logs through lfs, once. The answer is cached in _DirReady, which SetLogFileName, EnableFileLogging and a failed write clear. |
logger:_AppendToLogFile(text) |
The append itself. Raises on failure. |
logger:_WriteToLogFile(text) |
Appends one line, guarded by FileLogging, the _InFileWrite reentrancy latch and a pcall. A raise here switches the disk off rather than escaping to the caller. |
logger:_ResolveLevel(level) |
Turns a level into name, id. |
logger:_FormatLogMessage(name, msg, forced) |
Builds the output line. |
logger:_DispatchLog(level, msg, forced) |
Central output. It writes to the file first and filters afterwards, so every emitted line costs file access whatever level it carries. That is deliberate (TODO T10), and it is the reason a module reports once with a block rather than several times with lines. |
Manifold.CustomIO#
CustomIO, version 1.0.5. Dependencies: logger and json, both required.
| Function | Returns | Description |
|---|---|---|
CustomIO:New() |
CustomIO |
Calls CheckDependencies() and sets DataDir. |
customIO:CheckDependencies() |
boolean, table |
Reports missing dependencies. It loads nothing. |
Directories#
| Function | Returns | Description |
|---|---|---|
customIO:DirectoryExists(dir) |
boolean |
via lfs.attributes |
customIO:CreateDirectory(dir) |
boolean, string? |
lfs.mkdir. An already present directory gives true. |
customIO:EnsureDirectoryExists(path) |
boolean |
Check and create, not recursive |
customIO:EnsureDataDirectory() |
boolean |
Ensures DataDir |
customIO:OpenDirectory(dir) |
boolean |
start /b "" "<dir>" |
customIO:BuildPath(dir, fileName) |
string|nil |
Appends \ if needed |
Files#
| Function | Returns | Description |
|---|---|---|
customIO:FileExists(path) |
boolean |
|
customIO:DeleteFile(path) |
boolean, string? |
|
customIO:StripExt(fileName) |
string|nil |
Removes the last extension |
customIO:ReadFromFile(path) |
string|nil, string? |
Text mode ("r") |
customIO:WriteToFile(path, data) |
boolean, string? |
Overwrites |
customIO:AppendToFile(path, data) |
boolean, string? |
Appends and adds \n |
JSON#
| Function | Returns | Description |
|---|---|---|
customIO:ReadFromFileAsJson(path) |
table|nil, string? |
|
customIO:WriteToFileAsJson(path, data) |
boolean, string? |
Uses json:encode_pretty |
CSV#
| Function | Returns | Description |
|---|---|---|
customIO:ReadCSV(path) |
table|nil, string? |
Turns lines into arrays. There is no quoting support, and empty fields are lost. |
customIO:WriteCSV(path, data) |
boolean, string? |
table.concat(row, ",") per line, no escaping. |
Cheat Engine table files#
| Function | Returns | Description |
|---|---|---|
customIO:ReadFromTableFile(name) |
string|nil, string? |
Reads an embedded file. |
customIO:WriteToTableFile(name, text) |
boolean |
Creates it on demand and overwrites completely. |
customIO:ReadFromTableFileAsJson(name) |
table|nil, string? |
|
customIO:WriteToTableFileAsJson(name, data) |
boolean |
Uses json:encode, so the output is compact. |
ReadFromTableFile internally uses string.char(table.unpack(bytes)). Very large table files can
exceed Lua's stack limits (TODO T12).
Manifold.Helper#
Helper, version 1.1.1. It declares logger as an optional dependency. Since 1.1.0 the module is
narrowed to one goal, read-only facts about the target process's main loaded module, and
everything it says is derived from enumModules()[1].
| Function | Returns | Description |
|---|---|---|
helper:GetGameModule() |
table|nil |
enumModules()[1], guarded, so the module stays loadable outside Cheat Engine |
helper:GetGameModuleIs64Bit() |
boolean|nil |
nil only when there is no module. A 32-bit target gives false. |
helper:GetGameModuleName() |
string|nil |
|
helper:GetGameModulePathToFile() |
string|nil |
Full path to the executable |
helper:GetGameModuleAddress() |
integer|nil |
Module base |
helper:GetRegistrySizeStr() |
string |
"(x64)" or "(x32)" |
helper:GetFileVersionStr([path]) |
string|nil |
"major.minor.release.build" read through getFileVersion. Defaults to the module's own PathToFile. |
Deprecated#
These three describe the Cheat Engine process global, which belongs to
Manifold.ProcessHandler. All three still answer. IsProcessAvailable and GetProcessTrimmed
delegate to the process handler when it is loaded and run their original bodies when it is not.
GetProcess never delegates, because its whole body is a return of the process global. They
will be removed in Helper 2.0.0.
| Function | Returns | Description |
|---|---|---|
helper:GetProcess() |
string |
The CE global process. Use processHandler:GetAttachedProcessName(). |
helper:IsProcessAvailable() |
boolean |
Use processHandler:IsProcessAttached(). |
helper:GetProcessTrimmed() |
string|nil |
Without .exe. Use processHandler:GetAttachedNameNoExt(). |
Manifold.Utils#
Utils, version 1.1.1. logger is required. customIO, helper, memory and ui are runtime
dependencies, so a table is entitled not to load them.
Configuration fields#
utils = Utils:New({
Author = "", -- free-form
Target = "", -- process file name, e.g. "Game.exe"
TargetStr = "", -- display name in the window title
AppID = "", -- free-form (e.g. Steam AppID)
AppVersion = "", -- game version for the title
Version = "", -- table version for the title
VerifyMD5 = true,
MD5Hash = "",
AutoDisableTimerInterval = 100,
AutoDisableWaitTimeout = 5000,
IsRelease = false,
})
Target and title#
| Function | Returns | Description |
|---|---|---|
utils:GetTarget() |
string|nil |
nil when Target is empty, not merely when it is unset |
utils:GetTargetNoExt() |
string|nil |
via customIO:StripExt, with a plain pattern fallback when CustomIO is absent |
utils:GetTitleComponents() |
table |
{tableTitle, tableVersion, gameVersion, registrySizeStr, ceRegistrySizeStr, ceVersion}. gameVersion falls back from AppVersion to helper:GetFileVersionStr(). |
utils:FormatTitle(components) |
string |
"%s %s V:%s — CET V:%s — CE %s V:%s" |
utils:SetTitle() |
Sets getMainForm().Caption. |
|
utils:InitializeTable() |
ui:InitializeForm() followed by SetTitle(). Called by the process handler. |
Dialogs#
| Function | Returns |
|---|---|
utils:ShowInfo(msg) |
|
utils:ShowWarning(msg) |
|
utils:ShowError(msg) |
|
utils:ShowConfirmation(msg) |
boolean |
All of them synchronize into the main thread on their own.
Checks#
| Function | Returns | Description |
|---|---|---|
utils:VerifyFileHash() |
boolean |
Compares md5file(helper:GetGameModulePathToFile()) against MD5Hash and warns on a mismatch. It does not block. |
utils:EnsureCompatibleCEVersion(required, closeOnFail) |
required must be a number and the comparison against getCEVersion() is exact. With closeOnFail = true a mismatch calls closeCE(). |
Records and scripts#
| Function | Description |
|---|---|
utils:AutoDisable(id [, interval]) |
Deactivates the record with id after interval ms, defaulting to AutoDisableTimerInterval. Both waits for AsyncProcessing are bounded by AutoDisableWaitTimeout, and a timeout logs a warning and deactivates anyway. |
utils:SetAllScriptsToAsync() |
Sets Async = true on every vtAutoAssembler record. |
utils:SetAllScriptsToNotAsync() |
The inverse. |
utils:RemoveTableFilesByExtension(ext) |
Opens miTable and deletes every table file whose caption contains ext, defaulting to ".lua". For release builds. |
utils:ExecuteTableLuaScript() |
Finds the form "Lua script: Cheat Table" and clicks btnExecute. |
Memory#
| Function | Returns | Description |
|---|---|---|
utils:ResolvePointerPath(base, offsets [, isLocal]) |
integer|nil |
Deprecated in Utils 1.1.0 and moved to Manifold.Memory. It forwards to memory:ResolvePointerPath and logs an error when that module is not loaded. It will be removed in 2.0.0. |
Custom value types#
| Function | Type | Bytes |
|---|---|---|
utils:RegisterTimeTypes() |
Military Hours |
4 |
utils:RegisterDecryptionType() |
Decrypted |
16 |
utils:RegisterPlaytimeMilitaryType() |
Playtime Float |
8 |
Each of the three returns early when the type is already registered.
Miscellaneous#
| Function | Description |
|---|---|
utils:OpenLuaEngineWindow() |
getLuaEngine() or createLuaEngine() followed by Show() |
Manifold.ProcessHandler#
ProcessHandler, version 2.0.0. logger is required and utils is a runtime dependency.
New(config) copies every key of config onto the instance.
The module does four things and nothing else: wait for the process, attach to it, watch it, and start over when it dies.
The one true signal#
Cheat Engine offers three ways to answer "is the process there", and two of them lie:
| Call | Behaviour |
|---|---|
getOpenedProcessID() |
Keeps reporting the PID of a process that has exited |
getProcessIDFromProcessName(name) |
Keeps serving that PID from a cached list, so an exited game is still "found" and openProcess still succeeds on it |
readInteger(process) |
Tracks reality |
So the first two are used only to find a candidate; a read is what confirms one. An attach is never reported until the read succeeds, which is what stops the handler from talking to a corpse.
Fields#
| Field | Default | Description |
|---|---|---|
ProcessName |
nil |
Target process |
AutoAttachTimerInterval |
1000 |
ms between attach attempts |
ProcessWatchTimerInterval |
1000 |
ms between liveness reads |
LivenessFailureThreshold |
2 |
Consecutive failed reads before the process counts as gone |
SamePidLossLimit |
3 |
Quick losses of the same PID in a row before auto-restart gives up |
QuickLossSeconds |
10 |
A session shorter than this counts as a quick loss |
AttachedProcessName / AttachedProcessID |
nil |
Set once an attach is confirmed |
IsAutoAttaching / IsWatchingProcess |
false |
Which timer is live |
Disarmed |
false |
Set when auto-restart has stopped itself |
AutoAttachOptions |
nil |
The options last passed in |
Attaching#
| Function | Returns | Description |
|---|---|---|
processHandler:AutoAttach(name [, options, internalRestart]) |
boolean |
Starts the waiting timer. options may be a number, meaning a timeout in seconds, or a table of { maxSecs, runPostAttachTasks, onAttached }; maxSeconds and timeoutSeconds are aliases of maxSecs. internalRestart is used by the loss handler and is refused while disarmed, so only an explicit call re-arms recovery. |
processHandler:AttachToProcessByName(name) |
boolean |
Attaches right now, without waiting. Refuses a PID that does not answer a read. |
processHandler:AttachToProcess(name [, pid, options]) |
boolean |
The same for a known PID; falls back to the name when pid is nil. |
processHandler:ResolveProcessName([name]) |
string|nil |
Falls back to ProcessName, then AttachedProcessName, and stores the result. |
processHandler:Stop() |
Stops both timers and retires the watch epoch. |
processHandler:AutoAttach("Game.exe", {
maxSecs = 60, -- 0/nil = unlimited
runPostAttachTasks = true, -- false = leave UI/title alone
onAttached = function(handler, name, pid)
logger:InfoF("Attached to %s (%d)", name, pid)
end,
})
Status#
| Function | Returns | Description |
|---|---|---|
processHandler:IsProcessAttached() |
boolean |
Did readInteger(process) succeed? |
processHandler:IsAttachedProcessAvailable() |
integer|nil |
The raw probe value |
processHandler:GetAttachedProcessName() |
string|nil |
|
processHandler:GetAttachedNameNoExt() |
string|nil |
The attached name without its .exe extension |
Cleanup#
| Function | Description |
|---|---|
processHandler:DisableAllWithoutExecute() |
AddressList.disableAllWithoutExecute() plus deleteAllRegisteredSymbols(). The disable scripts cannot run: their process is gone. |
processHandler:ResetProcessBoundState(reason) |
autoAssembler:Reset(), assemblerCommands.ActivePatches = {} and trampolines:Reset(), each only when that module is loaded. |
processHandler:PerformPostAttachTasks() |
utils:InitializeTable() and, when utils.VerifyMD5 is set, utils:VerifyFileHash(). Both guarded, since utils is a runtime dependency. |
Watch epochs#
Watch state is keyed by an epoch counter in _G.__ManifoldProcessHandlerEpoch, not on the instance.
Reloading a cheat table re-runs the module and builds a new handler, but the timers and threads of
the previous one keep running; a counter on the instance could never retire those, and every
surviving watcher then ran its own cleanup when the game exited. Every timer and thread carries the
epoch it was born under and exits as soon as that epoch is gone. Loading the file opens a new epoch,
and so does Stop().
A background thread backs the watch timer up, for hosts where Cheat Engine stops dispatching TTimer events. It stays quiet while the timer is demonstrably still ticking, so the two never race, and it runs the same check.
Giving up#
Losing the same PID SamePidLossLimit times in a row, each within QuickLossSeconds of attaching,
means the reattach is not recovering anything. The handler stops restarting itself and reports once
rather than tearing the table down every few seconds. A session that lasted longer than
QuickLossSeconds was a normal one and resets the count. processHandler:AutoAttach(name) re-arms.
Miscellaneous#
| Function | Description |
|---|---|
processHandler:CloseProcess() |
Asks for confirmation and terminates the process via taskkill /PID <pid> /F. |
processHandler:OpenLink(url) |
Asks for confirmation and opens the URL via ShellExecute. Used by cheat tables for steam://run/<appid>. |
Manifold.Memory#
Memory, version 1.1.1. logger is required.
Memory.LogSuccessfulOperations defaults to false. Every read, write and add used to emit an
Info line, and because the logger writes the file before it applies the level filter, a script
polling a value each frame produced file access every frame. Turn the flag on only while
diagnosing a specific access.
Generated type functions#
For Byte, Word, Integer, QWord, Float and Double:
| Function | Returns |
|---|---|
memory:SafeRead<Type>(address [, signed]) |
number|nil |
memory:SafeWrite<Type>(address, value) |
boolean |
memory:SafeAdd<Type>(address, value [, signed]) |
boolean |
signed only applies to Word and Integer, which are the two types flagged supportsSigned.
Underlying CE functions:
| Type | Read | Write |
|---|---|---|
Byte |
readByte |
writeByte |
Word |
readSmallInteger |
writeSmallInteger |
Integer |
readInteger |
writeInteger |
QWord |
readQword |
writeQword |
Float |
readFloat |
writeFloat |
Double |
readDouble |
writeDouble |
Address resolution#
| Function | Returns | Description |
|---|---|---|
memory:SafeGetAddress(addressOrSymbol [, isLocal]) |
integer|nil |
A number is returned unchanged, and a negative one gives nil. A string goes through getAddressSafe(s, isLocal). An empty string is rejected. |
memory:ResolvePointerPath(base, offsets [, isLocal]) |
number|nil |
Follows the chain, reading a pointer and adding one offset per step. base may be a symbol or a number. Moved here from Manifold.Utils in Memory 1.1.0. |
ResolvePointerPath treats a null pointer mid-chain as a failure rather than an address, so an
object the game has not allocated yet no longer produces a plausible-looking low address. On
failure it logs the chain it walked, so the broken hop is answerable from one log line. On success
it logs nothing. It returns one value deliberately, because a second return would leak into every
multi-value context.
Internal helpers#
| Function | Description |
|---|---|
memory:_IsNumber(v) / _IsOptionalBoolean(v) |
Type checks, where NaN counts as a non-number |
memory:_FormatAddress(addr) |
"0x%08X" |
memory:_RequireAddress(addr, fnName) |
Resolve and validate |
memory:_RequireNumber(v, fnName, param) |
|
memory:_RequireSignedFlag(v, fnName) |
|
memory:_ReadResolvedValue(addr, typeInfo, signed) |
|
memory:_WriteResolvedValue(addr, value, typeInfo) |
|
memory:_SafeReadValue / _SafeWriteValue / _SafeAddValue |
Shared implementation |
memory:_LogReadFailure / _LogWriteFailure |
Error messages |
Manifold.State#
State, version 1.1.1. logger and customIO are required, and processHandler is a runtime
dependency. Since 1.0.5 every Cheat Engine access is main-thread synchronized.
| Function | Returns | Description |
|---|---|---|
State:New() |
State |
Creates TableStateDir. |
state:EnsureStateDirectory() |
string|nil |
DataDir\State |
state:GetStateFilePath(name) |
string|nil |
…\Manifold.<name>.<Process>.State |
state:GetIndexedAddressList() |
table, table |
An indexed list and an id-keyed list of all records |
state:SaveTableState(name) |
boolean |
Saves active records and records with hotkeys. With neither present it returns false plus a warning. |
state:LoadTableState(name) |
boolean |
Reads the file and calls RestoreState. |
state:RestoreState(stateData) |
table |
{activatedCount, deactivatedCount, unchangedCount, failedCount}. Exclusive, so records not listed get deactivated. Reports the whole run as one log entry. |
state:RestoreOriginalState() |
table |
Deactivates everything that is active, iterating backwards. Returns {deactivatedCount, unchangedCount, failedCount} and reports as one entry too. |
state:FormatRestoreReport(stateOutcomes, hotkeyOutcomes, stats [, title]) |
table |
{ Lines, Summary }. Pure, so the layout can be tested without the logger. The summary names only the counters present in stats, so an operation that cannot activate anything does not report 0 activated. |
state:SetMemoryRecordState(mr, state [, timeoutMs]) |
boolean |
The default timeout for async records is 10,000 ms. |
state:WriteStateFile(path, data) |
boolean |
|
state:ReadStateFile(path) |
table|nil |
|
state:CheckDependencies() |
boolean, table |
A restore touching forty records used to produce forty log entries, each with its own timestamp and module prefix, all inside the same second. It is now one entry, grouped by outcome, with the record ids and the async durations in columns:
[13:14:22] [INFO] [State] Restore complete — 36 activated, 0 deactivated, 386 unchanged, 0 failed
Activated
47 [— State : Save —]
106 Manifold.Activation 2360 ms
475 [— CET : Scripts —]
751 Manifold.Teleporter 1375 ms
1503 [— Player : Weapon —]
1523 Disable : Recoil 391 ms
Hotkeys
2118 Manifold.Debug 1 restored
Group headers stay flush left and everything else indents under them, so the block mirrors the
address list. Records that did not change are counted in the summary rather than listed; there are
usually hundreds of them. Sections appear only when they have rows, so a clean restore shows
Activated and nothing else.
Internal helpers#
| Function | Description |
|---|---|
state:_BuildStateRecord(rec) |
Condenses a list entry, returning nil when the record is inactive and has no hotkeys. |
state:_SetMemoryRecordStateOnMainThread(mr, state, timeoutMs) |
Sets Active, waits for AsyncProcessing and returns an outcome object. |
state:_LogMemoryRecordStateOutcome(outcome) |
Evaluates the outcome object. |
state:_RestoreHotkeysOnMainThread(mr, hotkeys) |
Destroys all hotkeys and recreates them. |
Outcome object from _SetMemoryRecordStateOnMainThread:
{ success, changed, state, record, active, async, asyncProcessing,
asyncWasProcessing, didTimeout, waitedMs }
Manifold.AutoAssembler#
AutoAssembler, version 2.0.8. logger is required, customIO is an optional dependency, and
processHandler and trampolines are runtime dependencies.
| Function | Returns | Description |
|---|---|---|
AutoAssembler:GetInstance() |
AutoAssembler |
The preferred entry point. The singleton lives in _instance. |
AutoAssembler:New() |
AutoAssembler |
A fresh instance. |
autoAssembler:SetProcessName(name) |
Sets RequiredProcess, so scripts only run against a matching process. |
|
autoAssembler:AutoAssemble(fileOrText [, memrecOrTargetSelf, targetSelf]) |
boolean |
Toggles a script. See below. |
autoAssembler:Disable([fileOrKey, memrec]) |
boolean |
Without arguments it disables every active state. |
autoAssembler:Reset([reason]) |
Clears States and the transaction depth. |
|
autoAssembler:DisableAllWithoutExecute() |
boolean |
Delegates to the process handler. |
autoAssembler:EnsureDirectoriesExist() |
boolean |
Creates DataDir/CEA/<Process>. |
autoAssembler:GetFilePath(fileName) |
string|nil |
Full path inside the CEA directory. |
autoAssembler:FormatFileName(name) |
string |
Appends .CEA when it is missing. |
autoAssembler:CheckDependencies() |
boolean, table |
Fields#
| Field | Default | Description |
|---|---|---|
RequiredProcess |
"" |
Empty means no check |
LocalFilesFolder |
"CEA" |
Subfolder inside DataDir |
FileExtension |
".CEA" |
|
BreakOnError |
true |
With false it returns false instead of raising |
States |
{} |
Maps a state key to a state table |
Call variants#
autoAssembler:AutoAssemble("InfiniteHealth") -- file CEA/<Process>/InfiniteHealth.CEA
autoAssembler:AutoAssemble("InfiniteHealth", memrec) -- with a stable state key
autoAssembler:AutoAssemble(scriptTextWithNewlines) -- raw text
autoAssembler:AutoAssemble(scriptText, true) -- targetSelf: assemble into CE itself
autoAssembler:AutoAssemble("Script", memrec, true) -- memrec + targetSelf
Whether the argument is raw text or a file name is decided solely by the presence of a newline. A file name is looked up on disk first and then, when that fails, among the Cheat Table's own table files.
State keys#
_stateKey(name, memrec) produces, in order:
"<name>#MRID:<memrec.ID>", preferred, stable across runs"<name>#MRDESC:<memrec.Description>""<name>#MR:<tostring(memrec)>""<name>"when there is no memory record
Internal helpers#
| Function | Description |
|---|---|
autoAssembler:_currentPid() |
getOpenedProcessID() wrapped in pcall |
autoAssembler:_validateProcessOrThrow() |
Is a process attached, and does the name match? |
autoAssembler:_checkProcessChangedOrThrow() |
PID comparison against _lastKnownPid |
autoAssembler:_markProcessChangedAndThrow(old, new) |
Disables everything and resets. It does not raise despite the name, because the error() call is commented out. |
autoAssembler:_loadScriptText(nameOrText) |
Raw text, or a file, or a table file |
autoAssembler:_getOrCreateState(key) |
|
autoAssembler:_txBegin() / _txCommit() / _txRollback() |
Transaction bracket |
autoAssembler:_txRememberEnable(key, text, targetSelf, disableInfo, name) |
Rollback entry |
autoAssembler:_scriptUsesTrampolines(text) |
Searches for ManifoldInstallDetour, ManifoldDestroyDetour, ManifoldEmitOriginal, ManifoldEmitOriginalNoReturn and ManifoldEmitReturn |
autoAssembler:_getTrampolineApi() |
Loads Manifold.Trampolines on demand |
autoAssembler:_beginTrampolineTransaction(text) |
Starts the detour transaction only when it is needed |
Manifold.Callbacks#
Callbacks, version 1.0.7. It is a singleton, so Callbacks:New() always returns the same
instance. logger is required and ui is a runtime dependency.
Options#
| Option | Default | Effect when true |
|---|---|---|
DisableAutoAssemblerEdits |
false |
The AA editor is blocked for records |
DisableDescriptionChange |
false |
Description is read-only |
DisableAddressChange |
false |
Address is read-only |
DisableTypeChange |
false |
Type is read-only |
DisableValueChange |
false |
Value is read-only |
Generated accessors#
Per option: callbacks:Get<Option>(), callbacks:Set<Option>(bool) and
callbacks:Toggle<Option>().
General API#
| Function | Returns | Description |
|---|---|---|
callbacks:GetConfigValue(name) |
boolean|nil |
|
callbacks:SetConfigValue(name, value) |
boolean |
Requires a boolean |
callbacks:ToggleConfigValue(name) |
boolean|nil |
|
callbacks:ResetConfig() |
table |
Puts all options back to false |
Hooks installed at module load#
| Hook | Behaviour |
|---|---|
onMemRecPreExecute(memrec, newstate) |
Debug log |
onMemRecPostExecute(memrec, newstate, succeeded) |
Warning only on failure |
AddressList.OnDescriptionChange |
true blocks the change |
AddressList.OnAddressChange |
The same |
AddressList.OnTypeChange |
The same |
AddressList.OnValueChange |
The same |
AddressList.OnAutoAssemblerEdit |
Chains the previous handler |
getLuaEngine().OnShow |
Runs the original handler, then applies the theme twice |
Manifold.AssemblerCommands#
AssemblerCommands, version 1.2.9. logger and trampolines are both required.
Every command runs on the main thread. A script marked Execute Asynchronous assembles on its own worker thread, so its commands are handed to the main thread with synchronize and finish one after another. Two async scripts can therefore no longer pick the same relay slot or hook the same instruction at once. A failing command still reports its reason.
| Function | Returns | Description |
|---|---|---|
AssemblerCommands:New() |
AssemblerCommands |
|
assemblerCommands:RegisterCoreCommands() |
boolean |
Registers every command in COMMAND_SPECS. Returns false when registerAutoAssemblerCommand is unavailable. |
assemblerCommands:CheckDependencies() |
boolean, table |
Registered commands#
| Command | Arguments | Replaced by |
|---|---|---|
ManifoldScanModule |
symbol, module, signature [, protection, alignType, alignParam] |
define(symbol, module+OFFSET) |
ManifoldAssert |
address, bytePattern |
(empty) |
ManifoldPatch |
address [, bytePattern] |
(empty) |
ManifoldNop |
address [, count] |
(empty) |
ManifoldInstallDetour |
name, injectExpr [, destExpr, minSize] |
Generated detour script |
ManifoldEmitOriginal |
name |
Relocated original code plus jmp <name>_Return |
ManifoldEmitOriginalNoReturn |
name |
Relocated original code without a return |
ManifoldEmitReturn |
name |
jmp <name>_Return |
ManifoldDestroyDetour |
name |
db restore plus unregistersymbol(...) |
ManifoldResolveStatic |
symbol, addrExpr [, dispOffset, instrLen, mode, outputMode] |
define(symbol, TARGET) |
Byte patterns#
_parseBytesPattern splits the argument on whitespace. Each token is either two hexadecimal
digits or one of the wildcard spellings ?, ??, **, ?* and *?. A single * is not
accepted, and neither are prefixed forms such as 0x7B.
ManifoldAssert(HealthHook, 89 41 ?? 8B 45 08)
ManifoldPatch(HealthHook, 90 90 ?? ?? 90 90)
Wildcards are broken, and neither of those two lines does what it looks like it does. The intended
behaviour was positional. A wildcard would be skipped by the comparison in ManifoldAssert and
left untouched by the write in ManifoldPatch, which is what the consumers were written for.
_findPatternMismatch skips a nil entry and _buildPatchedBytes fills one in from the bytes
already at the address. No nil entry ever reaches them. _parseBytesPattern records a wildcard
with bytes[#bytes + 1] = nil, and assigning nil to the slot one past the end of a Lua table
does nothing at all, so a wildcard leaves no hole and does not advance the position. Every byte
written after it moves one position earlier.
89 41 ?? 8B 45 08 therefore parses to the five bytes 89 41 8B 45 08. ManifoldAssert reads
five bytes from the address and lines 8B up against the third byte of the instruction, so a
pattern that describes the target correctly still reports a mismatch at index 3, unless the
wildcarded byte happens to be 8B by chance. ManifoldPatch(HealthHook, 90 90 ?? ?? 90 90)
writes four contiguous 90 bytes over the first four bytes at the address, stores those four as
the original for the later restore, and never touches the fifth and sixth. A pattern made of
nothing but wildcards parses to an empty table and is rejected as an empty bytes pattern.
Until _parseBytesPattern is fixed, write patterns without wildcards and let the byte count match
what you mean.
ManifoldResolveStatic in detail#
| Parameter | Default | Description |
|---|---|---|
symbol |
Output symbol | |
addrExpr |
Address of the instruction | |
dispOffset |
3 (rip) or 1 (absolute) |
Byte offset of the operand within the instruction |
instrLen |
7 (rip) or 5 (absolute) |
Total instruction length |
mode |
"auto" |
"rip", "absolute" or "auto", detected by _detectResolveStaticMode |
outputMode |
"address" |
"address" gives the resolved operand address, "pointer" gives the pointer stored there |
The trailing options are order-independent. Mode names and output mode names are recognised by
value, and the first two unrecognised numbers become dispOffset and instrLen in that order.
_detectResolveStaticMode reads the opcode byte and picks "absolute" for A0 through A3, and
"rip" otherwise.
Computation:
rip: target = baseAddr + instrLen + disp32
absolute: target = abs32
Patch management#
Applied patches live in assemblerCommands.ActivePatches, keyed by address. A second call without
a byte pattern restores the stored original. processHandler:ResetProcessBoundState() clears the
table on a process change.
Internal helpers (selection)#
| Function | Description |
|---|---|
_beginCommand(name, parameters, syntaxcheck) |
Builds the context {Name, Args, Syntaxcheck} |
_splitArgs(parameters) |
Comma-separated and bracket-aware |
_requireArg / _requireSymbolArg / _requireResolvedAddressArg / _requireBytesPatternArg |
Validation with an error message |
_parseNumber(v) |
Decimal, hex, and the $, 0x and # prefixes |
_aobScanModuleUnique(module, sig, prot, alignType, alignParam) |
Scan with a uniqueness check |
_readBytes / _writeBytes / _applyBytesAndVerify |
Memory access with read-back |
_buildPatchedBytes(actual, patch) |
The effective bytes a patch will leave behind, for the log. It fills a nil entry from actual, and no nil entry ever reaches it |
_buildNopBytes(count) |
An array of 0x90 |
_findPatternMismatch(expected, actual) |
Index of the first difference. It ignores a nil entry in expected, and no nil entry ever reaches it |
_buildMismatchMarker(index) |
Text marker for the log |
_storePatch / _restoreStoredPatch / _applyStoredPatch / _executeStoredPatch |
Patch store |
_isModuleSuitableForAttachContext(module) |
Verifies via getAddressSafe and falls back to enumModules |
_getTrampolines() |
Returns the live trampolines instance, constructing one from the class global when needed |
_syntaxDefine(symbol) |
Placeholder define during the syntax check |
Manifold.Trampolines#
Trampolines, version 1.2.0. It declares logger as an optional dependency. Normally it is not
called directly, because Manifold.AssemblerCommands is the interface. It is also the one module
without a PrintModuleInfo.
Constants#
| Constant | Value | Description |
|---|---|---|
HEADER_RELAY_MIN_OFFSET |
0x500 |
Earliest relay offset from the module base |
HEADER_RELAY_MAX_OFFSET |
0x1000 |
Lower bound for the end of the search, taken together with SizeOfHeaders |
HEADER_RELAY_ALIGNMENT |
0x10 |
Slot alignment |
The search window starts at the later of HEADER_RELAY_MIN_OFFSET and the end of the section
headers, and it ends at max(SizeOfHeaders, HEADER_RELAY_MAX_OFFSET) clamped down to the lowest
section virtual address. The clamp matters because _isHeaderCaveFree accepts 0xCC, which is
exactly MSVC's inter-function padding, so without it a relay could land in .text.
Public API#
| Function | Returns | Description |
|---|---|---|
trampolines:InstallDetour(name, injectExpr [, destExpr, minSize]) |
entry, script, err |
Finds a relay slot, collects instructions and builds the AA script. It refuses an inject range that overlaps a live detour, and refuses bytes that visibly belong to somebody else's patch, meaning a leading E9, EB or FF 25. |
trampolines:EmitOriginal(name) |
entry, script, err |
Relocated original code with a return jump. |
trampolines:EmitOriginalNoReturn(name) |
entry, script, err |
Without the return jump. |
trampolines:EmitReturn(name) |
entry, script, err |
Only jmp <name>_Return. |
trampolines:DestroyDetour(name) |
entry, script, err |
Restore script. |
trampolines:Reset() |
Clears all detour tables. | |
trampolines:BeginTransaction() |
Nestable. | |
trampolines:CommitTransaction() |
Commits PendingDetours and PendingDestroys. |
|
trampolines:RollbackTransaction([reason]) |
Writes original and relay bytes back. | |
trampolines:BuildSyntaxScript(name) |
string |
Label scaffolding for syntaxcheck. |
trampolines:BuildOriginalSyntaxScript(name) |
string |
|
trampolines:BuildReturnSyntaxScript(name) |
string |
Detour entry#
{
Name, Key,
InjectExpression, InjectAddress,
DestinationExpression, DestinationAddress,
OverwriteSize, ReturnAddress,
InstructionCount, InstructionOffsets, InstructionSizes,
OriginalBytes,
RelayAddress, RelaySize, RelayModuleName, RelayModuleBase,
RelayOffset, RelayOriginalBytes,
InstallMode = "header-relay",
InstallScript,
Active, Pending, PendingDestroy, OriginalEmitted
}
Key is the detour name lowercased, and it is what the active and pending stores are keyed by.
Generated symbols#
| Symbol | Meaning |
|---|---|
<name>_Block |
Start of the relay block |
<name>_Relay |
jmp qword ptr [<name>_Destination] |
<name>_Destination |
8-byte pointer to the target code, or 4-byte on a 32-bit target |
<name>_Return |
First address after the overwritten range |
<name>_Original |
Relocated original code, only after EmitOriginal |
Internal helpers (selection)#
| Function | Description |
|---|---|
_enumModules() / _moduleSize(module) |
The loaded module list, and a module's span from Size or getModuleSize |
_findModuleContaining(addr) |
The module whose mapped span contains the address. The highest base at or below it wins, so a nested image is the owner |
_resolveModuleForAddress(addr) |
The owning module, from the module list. Parsing getNameFromAddress is only a fallback, and the parsed name must resolve to a real module base |
_formatCodeAddress(addr) |
module+offset for generated Auto Assembler, bare hex outside any module. Never a symbol name |
_collectInstructionRange(addr, minSize) |
Collects whole instructions until the total reaches minSize |
_buildRel32Jump(source, target) |
5-byte E9 jump, with a rel32 range check |
_getPeHeaderInfo(addr) |
MZ and PE signatures, SizeOfHeaders, the end of the section headers and the lowest section RVA. An unreadable header and a wrong signature report separately |
_findHeaderRelaySlot(injectAddr, size) |
Searches for a free, aligned slot |
_isHeaderCaveFree(addr, size) |
Only 0x00 and 0xCC count as free |
_isHeaderRelaySlotReserved(addr, size) |
Collision with existing detours |
_checkInjectRangeFree(addr, size, originalBytes) |
Refuses an overlapping or already patched inject range |
_analyzeRelativeControlFlow(addr, bytes, size) |
Detects relative jumps and calls |
_rewriteAbsoluteMemoryInstruction(instr) |
Turns RIP-relative access into absolute access. Control transfers and stack instructions are position independent already and are copied verbatim instead. |
_emitAbsoluteJump(lines, target) / _emitAbsoluteCall(lines, target) |
Bitness-correct raw bytes whose length this module knows |
_buildRelocatedInstruction(entry, index, lines) |
Builds one relocated line |
_selectTempRegister(instr) |
A free register for the relocation. It rejects a candidate if any spelling of it appears, and returns nil rather than guessing when nothing is free. |
_restoreBytes(addr, bytes, label) |
Rollback write |
_cleanupDetourSymbols(entry) |
unregistersymbol for every detour symbol |
Manifold.Forms#
Forms, version 1.4.0. It declares logger as an optional dependency. New(config) copies
recognised keys from config onto the instance and warns about the rest.
Control factory#
| Function | Returns | Description |
|---|---|---|
forms:CreateForm(opts) |
form |
BorderStyle = "bsSizeable", registered as a root. |
forms:CreatePanel(parent, opts) |
panel |
|
forms:CreateLabel(parent, opts) |
label |
|
forms:CreateTextBox(parent, opts) |
edit |
|
forms:CreateMemo(parent, opts) |
memo |
|
forms:CreateTreeView(parent, opts) |
tree |
|
forms:CreateComboBox(parent, opts) |
combo |
Read-only dropdown. items fills it, itemIndex selects, onChange is attached last so filling does not fire it, dropdownStyle picks the kind (csDropDownList by default; it is not called style, which the theming reads as the font style). Role combo: input colours on the closed box, the list is system drawn. |
forms:CreateListView(parent, opts) |
list |
BorderStyle = "bsNone" |
forms:CreateButton(parent, opts) |
button, label |
Panel plus centred label plus hover |
forms:CreateMemoFrame(parent, opts) |
memo, outer, inner |
Memo wrapped in framing panels |
forms:CreateCard(parent, opts) |
outer, inner, header, content, headerLabel |
Titled card |
forms:CreateFieldRow(parent, opts) |
edit, row, label, border, fill, inner, gap |
Labelled input row |
Common options#
_ApplyCommonOptions transfers these, in PascalCase or in camelCase:
Name, Align, Alignment, Layout, BorderStyle, Width, Height, Left, Top,
Caption, Text, TextHint, AutoSize, Visible, Transparent, ParentColor, ScrollBars,
WordWrap, ReadOnly, ViewStyle, AutoWidthLastColumn, RowSelect, FullRowSelect,
HideSelection, AutoExpand, Cursor, Position, Scaled, Hint, ShowHint
Plus: borderSpacing ({Left, Top, Right, Bottom, Around}), constraints, role, color,
bevelOuter, bevelWidth, bevelColor, fontSize, style, lockColor, onClick
(CreateButton only), root and isRoot.
Theming#
| Function | Returns | Description |
|---|---|---|
forms:ApplyTheme(theme [, includeHidden]) |
table |
Colours every registered control and returns the normalized palette. |
forms:ApplyThemeToControl(entry, designTheme [, includeHidden]) |
A single registry entry. | |
forms:ResolveTheme(theme) |
table |
Turns a token theme into the 17-colour palette. If theme.COLOR_BG is present, the table is copied as it is. |
forms:SetButtonState(button, isHover) |
Hover or normal state. | |
forms:RegisterControl(control, role, opts) |
control |
|
forms:RegisterForm(form, opts) |
form |
isRoot = true |
forms:UnregisterControl(control) |
boolean |
Forgets one control. |
forms:ThemeMenuBar(form) |
boolean |
Gives the form's menu bar and every submenu that exists the dark background Cheat Engine gives its own menus, through SetMenuInfo with MIM_BACKGROUND and MIM_APPLYTOSUBMENUS. A menu made with createMainMenu never gets that step and draws a light frame and light separators around dark entries. Call it once the menu is complete, and again after filling a new submenu. Does nothing outside dark mode or outside Cheat Engine, and reports a failure once. |
forms:UnregisterRoot(form) |
number |
Forgets a form and every control registered under it. Call it from OnClose before returning caFree; the controls are freed with the form and the next ApplyTheme would walk freed memory. Returns how many entries were dropped. |
forms:SetButtonOnClick(button, handler) |
button |
Sets the handler on the panel and on the label. |
forms:ApplyFont(control, color, size, style) |
Forces Consolas. |
|
forms:SetBorderSpacing(control, spacing) |
||
forms:Repaint(control) |
Palette#
| Key | Default | Token source in ResolveTheme |
|---|---|---|
COLOR_BG |
0x202020 |
MainForm.Color |
COLOR_PANEL |
0x2A2A2A |
MainForm.Foundlist3.Color |
COLOR_ACCENT |
0x4A4A4A |
AddressList.CheckboxActiveColor |
COLOR_TEXT |
0xEAEAEA |
Memrec.DefaultForeground.Color, then AddressList.Header.Font.Color |
COLOR_LABEL |
0xC8C8C8 |
Memrec.DefaultForeground.Color, then AddressList.Header.Font.Color |
COLOR_BTN |
0x2A2A2A |
AddressList.Header.Canvas.Brush.Color |
COLOR_BTN_HOVER |
0x4A4A4A |
AddressList.CheckboxActiveColor, then AddressList.Header.Canvas.Pen.Color |
COLOR_BTN_TEXT |
0xEAEAEA |
= COLOR_LABEL |
COLOR_TAB_ACTIVE / COLOR_TAB_INACTIVE |
0x4A4A4A / 0x2A2A2A |
(not mapped) |
COLOR_INPUT |
0x1B1B1B |
AddressList.List.BackgroundColor |
COLOR_INPUT_TEXT |
0xEAEAEA |
TreeView.Font.Color, then AddressList.Header.Font.Color |
COLOR_BORDER |
0x454545 |
AddressList.Header.Canvas.Pen.Color, then MainForm.Panel4.BevelColor |
COLOR_MUTED |
0x8A8A8A |
Memrec.GroupHeader.Color |
COLOR_SURFACE |
0x2F2F2F |
MainForm.Foundlist3.Color |
COLOR_SURFACE_ALT |
0x242424 |
MainForm.Color |
COLOR_SUCCESS |
0x6FD96F |
(not mapped) |
Manifold.UI#
UI, version 1.2.2. logger, customIO and forms are required, json is an optional
dependency, and teleporter is a runtime dependency.
Configuration#
ui = UI:New({
Theme = "Manifold.Dark-Aqua.Min", -- applied during InitializeForm
SloganStr = "MANIFOLD",
SignatureStr = "by Leunsel",
})
Further fields: ThemeList, ActiveTheme, CompactMode, IsApplyingTheme and
ThemeApplyLockTimeoutMs, which defaults to 8000. The apply lock itself lives in the global
__ManifoldThemeApplyLock so it survives a module reload.
Theme tokens#
| Token | Description |
|---|---|
TreeView.Color |
Not used. Use AddressList instead. |
TreeView.Font.Color |
Not used. Use AddressList instead. |
AddressList.CheckboxColor |
Outline of unchecked boxes |
AddressList.CheckboxActiveColor |
Fill of checked boxes |
AddressList.CheckboxSelectedColor |
Outline of selected boxes |
AddressList.CheckboxActiveSelectedColor |
Fill of checked and selected |
AddressList.List.BackgroundColor |
Address list background |
AddressList.Header.Font.Color |
List header font |
AddressList.Header.Canvas.Brush.Color |
List header background |
AddressList.Header.Canvas.Pen.Color |
List header border |
MainForm.Color |
Main window background |
MainForm.Foundlist3.Color |
Scan result list background |
MainForm.Panel4.BevelColor |
Bevel of the bottom panel |
MainForm.lblSigned.Font.Color |
Font colour of the signed label |
MainForm.Splitter1.Color |
Splitter line colour |
MainForm.SLOGAN_STR.Font.Color |
Font colour of the slogan label |
Memrec.AutoAssembler.Color |
AA script entries |
Memrec.AddressGroupHeader.Color |
Address group header (legacy) |
Memrec.GroupHeader.Color |
Group header |
Memrec.UserDefined.Color |
User-defined values |
Memrec.HexValues.Color |
Hex entries |
Memrec.StringType.Color |
String entries |
Memrec.IntegerType.Color |
Integer entries |
Memrec.FloatType.Color |
Float entries |
Memrec.DefaultForeground.Color |
Fallback colour |
UI.ThemeTokens holds the list and UI.TokenDescriptions holds the text shown in the theme
creator.
Theme management#
| Function | Returns | Description |
|---|---|---|
ui:LoadThemes() |
Loads from the data directory and from table files. | |
ui:LoadTheme(themeFile, isExternal) |
boolean |
A single theme. External ones get " (External)". Debug on success, an ErrorBlock naming the file and the reason on failure. |
ui:LoadJsonThemesFromDataDir(list) |
number |
Scans DataDir\Themes and returns how many usable files it found. Unreadable files are one WarningBlock, not one warning each. |
ui:GetJsonThemesFromTableMenu() |
table|nil |
Reads .json entries from miTable. |
ui:FinalizeThemes(list) |
number, number |
Loads all collected files. Returns loaded and failed. |
ui:GetTheme(name) |
table|nil |
Reloads once on a miss. |
ui:ProcessThemeData(raw, name) |
table |
Converts tokens to BGR and collects the missing and invalid ones. |
ui:GetThemeTokens() |
table |
UI.ThemeTokens |
ui:TokenColor(raw, token) |
number|nil |
Looks the token up in tokenColors. |
ui:TokenSearch(scope, token) |
boolean |
|
ui:GetActiveThemeData() |
table|nil |
Token table of the active theme. |
ui:UpdateThemeSelector() |
Rebuilds the theme selector records. | |
ui:EnsureThemeDirectory() |
string|nil |
Theme application#
| Function | Returns | Description |
|---|---|---|
ui:ApplyTheme(name [, allowReapply]) |
boolean |
Full application under a global lock. |
ui:ApplyThemeObject(themeObj) |
boolean |
For {Name, Author, Description, Tokens}, used by the theme creator. |
ui:ApplyThemeToTreeView(theme) |
||
ui:ApplyThemeToAddressList(theme) |
Including Header.Canvas.OnChange. |
|
ui:ApplyThemeToMainForm(theme) |
boolean |
Whether the slogan label was there to colour. |
ui:ApplyThemeToAddressRecords(theme) |
number, number |
One colour per record. Returns recoloured and unchanged. |
ui:ApplyThemeToLuaEngine(theme) |
boolean |
Whether the window was open. Calls the control function twice. |
ui:ApplyThemeToLuaEngineControls(le, theme) |
Sets the caption to "[Manifold] Logger". |
|
ui:CreateOrUpdateLuaEngineExecutePanel(...) |
Replaces btnExecute with a colourable panel. |
|
ui:ApplyThemeToForms(theme, includeHidden) |
table|nil |
Delegates to Manifold.Forms. |
ui:ApplyThemeToTeleporter(teleporter, theme) |
boolean |
Whether the Teleporter window was open. |
ui:SetTeleporterControlColors(uiState, theme) |
The central place for every teleporter colour. | |
ui:GetRecordColor(record, theme, str, int, flt) |
number |
Decision order below. |
ui:AcquireThemeApplyLock(name) |
string|nil, table |
|
ui:ReleaseThemeApplyLock(token) |
||
ui:RGB2BGR(rgb) / ui:BGR2RGB(bgr) |
number |
Decision order in GetRecordColor:
vtAutoAssembler -> Memrec.AutoAssembler.Color
IsAddressGroupHeader -> Memrec.AddressGroupHeader.Color
IsGroupHeader -> Memrec.GroupHeader.Color
OffsetCount == 0 and AddressString is not hex -> Memrec.UserDefined.Color
ShowAsHex -> Memrec.HexValues.Color
string type -> Memrec.StringType.Color
integer type -> Memrec.IntegerType.Color
float type -> Memrec.FloatType.Color
otherwise -> Memrec.DefaultForeground.Color
The user-defined and hex branches fall back to Memrec.DefaultForeground.Color when their own
token is missing, and any branch that produces no colour at all leaves record.Color alone.
CE window tweaks#
| Function | Description |
|---|---|
ui:InitializeForm() |
Compact mode, bevel off, sorting off, signature controls off, slogan and signature, theme. |
ui:EnableCompactMode() / DisableCompactMode() / ToggleCompactMode() |
Panel5 and Splitter1 |
ui:SetControlVisibility(name, visible) / ToggleControlVisibility(name) |
|
ui:HideSignatureControls() / ToggleSignatureControls() |
CommentButton and advancedbutton |
ui:DisableDragDrop() |
Removes the tree view's drag handlers. |
ui:DisableHeaderSorting() |
Removes OnSectionClick. |
ui:HideAddresslistBevel() |
BevelOuter = "bvNone" |
ui:RunInMainThread(fn) |
Wrapper with pcall and logging. |
ui:DeleteSubrecords(record) |
Deletes all child records. |
ui:InitializeTableMenu() |
Clicks miTable so its entries get populated. |
Labels and text animations#
| Function | Description |
|---|---|
ui:CreateSloganStr(text) |
Label SLOGAN_STR, Consolas 20 bold, centred. |
ui:DestroySloganStr() |
|
ui:CreateSignatureStr(str) |
Reuses the existing lblSigned. |
ui:HideSignatureStr() |
|
ui:UpdateTextLabel(name, text, props) |
Creates or updates a label on the main form. |
ui:DestroyTextLabel(name) |
|
ui:CreateOrUpdateLabel(parent, label, props) |
|
ui:CreateTimer(interval, callback) |
|
ui:StartTextAnimation(text [, config]) |
Cycles through several effects. |
ui:ScrollText(text, interval, maxTicks) |
Marquee |
ui:TypingEffect(text, interval) |
Character by character |
ui:RevealEffect(text, interval) |
Placeholders turning into characters |
ui:GlitchText(text, interval) |
Random character swaps |
ui:MatrixReveal(text, interval) |
# turning into characters in random order |
StartTextAnimation configuration:
ui:StartTextAnimation("MANIFOLD", {
animations = { "Typing", "Reveal", "Scrolling", "Matrix" }, -- "Glitch" also available
interval = 100,
minDuration = 5000,
pauseBetweenAnimations = 1000,
})
Theme creator#
| Function | Description |
|---|---|
ui:InitializeThemeCreator() |
Opens the [Manifold] Theme Creator window, 980 by 620 px. |
ui:CreateThemeCreatorForm() |
|
ui:CreateThemeInfoPanel(form, opts) |
Name, author and description |
ui:CreateListViewControl(form, opts) |
Token list with colour swatches |
ui:CreateTokenPreviewPanel(form, opts) |
Preview and copy buttons |
ui:CreateButtonPanel(form, opts) |
Apply, Export and Load |
ui:CreateThemeCreatorStatusBar(parent) / ui:SetThemeCreatorStatus(text) |
|
ui:PopulateListView(listView, tokenInputs) |
|
ui:RebuildImageList(listView [, colorsAndTokens]) |
Redraws the colour swatches |
ui:GetColorsAndTokensFromListView(listView) |
|
ui:OnListViewDblClick(...) / ui:OnListViewSelectItem(...) |
|
ui:HandleColorSelection(item, token) |
Colour dialog |
ui:UpdateColorLabels(colorNum) / ui:UpdateSelectedToken(name) |
|
ui:CreateCopyButton(parent, targetLabel, topOffset) |
|
ui:SetupApplyButton(...) / SetupExportButton(...) / SetupLoadButton(...) |
|
ui:PromptThemeFile() |
createOpenDialog with the filter *.json |
ui:LoadThemeData(path) |
Turns a file into a table |
ui:NormalizeTheme(data) |
{Name, Author, Description, Tokens} with defaults |
ui:PopulateThemeUI(themeData, tokenInputs, name, author, desc) |
|
ui:CreateStyledLabel/Edit/Button(...) |
Thin wrappers around Manifold.Forms |
ui:SetFormsButtonHandler(button, handler) |
Manifold.Teleporter#
Teleporter, version 1.6.2. logger and forms are required, and memory and customIO are
optional dependencies. ui is a runtime dependency. The module also calls utils at runtime, for
GetTargetNoExt and AutoDisable, without declaring it.
Configuration#
| Section | Fields |
|---|---|
Transform |
Symbol = "TransformPtr", Offsets = {0x30, 0x34, 0x38}, ValueType = vtSingle |
Waypoint |
Symbol = "WaypointPtr", Offsets = {0x00, 0x04, 0x08}, ValueType = vtSingle |
Additional |
Symbol = nil, Offsets = {0x00, 0x04, 0x08}, ValueType = vtSingle |
Symbols |
Saved = "SavedPositionFlt", Backup = "BackupPositionFlt" |
Settings |
ValueType, PauseWhileTeleporting, AdjustYCoordinate, YCoordinateIndex, AdjustmentAmount, LogVerbose |
Axes |
{ "X", "Y", "Z" }. Names only. The count comes from Transform.Offsets. |
Areas |
Names = {}, DeriveFromCategory = true. The game's separate maps, for the Teleporter Map. See the guide's 8.4 and 8.6. |
| other | Saves = {}, SaveFileName = "Teleporter.%s.Saves.txt", SaveMemoryRecordName = "[— Teleporter : Saves —] ()->" |
A Transform, Waypoint or Additional block given without a ValueType takes Settings.ValueType
once, in New, so { Symbol = "PlayerPtr", Offsets = { 0x30, 0x34, 0x38 } } reads and writes as
singles on every path.
Dimensions#
A position is as long as Transform.Offsets, so a 2D game configures two offsets and nothing else.
See the framework guide.
| Function | Returns | Description |
|---|---|---|
teleporter:AxisCount() |
number |
How many components a position has. Falls back to #Axes before a Transform exists. |
teleporter:GetAxes() |
table |
The axis names, in memory order. Cached against the offsets and Axes. Missing names fall back to X, Y, Z, W; blank or duplicate names are replaced. |
teleporter:RefreshAxes() |
Drops the cache. Only needed when Axes is edited in place rather than replaced. |
|
teleporter:SaveToPosition(save) |
table|nil |
Reads one key per axis out of a save. nil when any is missing. |
teleporter:PositionToSave(save, pos) |
table |
Writes one key per axis, and removes default axis names this table no longer uses. |
teleporter:ValidateConfiguration([quiet]) |
boolean, table |
Reports every configured symbol whose offset count disagrees with the axis count. A symbol with no name is skipped. |
Memory access#
| Function | Returns | Description |
|---|---|---|
teleporter:ResolveAddress(str, isPointer) |
integer|nil |
With isPointer set it resolves [str]+0 |
teleporter:ReadPositionFromMemory(symbol, offsets, isPointer, valueType) |
table|nil |
One value per offset. |
teleporter:WritePositionToMemory(symbol, offsets, pos, isPointer, valueType) |
boolean |
|
teleporter:CalculateSymbolOffsets() |
table |
One offset per axis, sized from Settings.ValueType. vtSingle in two dimensions gives {0, 4}. |
teleporter:SetValueType(vt) |
Validated against the read and write tables | |
teleporter:GetCurrentPosition() |
table|nil |
Reports an unresolvable pointer as a warning. |
teleporter:PeekCurrentPosition() |
table|nil |
The same read without logging, for a caller that polls. nil while no process is open, the pointer does not resolve, or a component cannot be read. |
teleporter:GetSavedPosition() |
table|nil |
|
teleporter:GetBackupPosition() |
table|nil |
Movement#
| Function | Returns | Description |
|---|---|---|
teleporter:SaveCurrentPosition() |
boolean |
|
teleporter:LoadSavedPosition() |
boolean |
|
teleporter:LoadBackupPosition() |
boolean |
|
teleporter:TeleportToCoordinates(position) |
boolean |
The position must have AxisCount() values. |
teleporter:TeleportToWaypoint() |
boolean |
|
teleporter:TeleportToSave(keyOrName) |
boolean |
Full key, or a display name while unambiguous |
teleporter:GetAdjustedTargetPosition(pos) |
table|nil |
Rejects a position that is not AxisCount() long, naming both counts. |
teleporter:FormatPosition(position) |
string |
Three decimals per component, however many there are. "unknown" for nil or empty. |
teleporter:GetDistance(old, new) |
number|nil |
Straight line, summed over as many components as the shorter of the two has. |
teleporter:_ReportJump(what, from, to, backupStored) |
One InfoBlock for a completed jump. |
|
teleporter:LogDistanceTraveled(old, new) |
Kept for outside callers. _ReportJump puts the distance in the same entry as the destination. |
|
teleporter:PauseGame() / ResumeGame() |
Categories#
| Function | Returns | Description |
|---|---|---|
teleporter:NormalizeCategoryPath(input) |
table |
Accepts a table or a string. The separators are /, \, > and | |
teleporter:CategoryPathToText(path, includeDefault) |
string |
Joins with " / ". An empty path gives "Default" |
teleporter:GetSaveCategoryPath(save, includeDefault) |
table |
Prefers Categories and falls back to Category |
teleporter:SetSaveCategoryPath(save, input) |
Writes both fields | |
teleporter:AddSaveToCategoryTree(root, path, key) |
||
teleporter:BuildSaveHierarchy([filterFn]) |
table |
Author, then category path, then save keys |
Save identity#
Saves are keyed by their full category path plus their name, so the same name may exist in several categories.
| Function | Returns | Description |
|---|---|---|
teleporter:MakeSaveKey(categoryInput, name) |
string|nil |
Joins path and name with " / ". An empty path becomes "Default" |
teleporter:GetSaveKey(save) |
string|nil |
The key a save's own fields imply |
teleporter:GetSaveDisplayName(save, fallbackKey) |
string |
save.Name, falling back to the key |
teleporter:ResolveSaveKey(input) |
string|nil, string|nil |
Exact key, else a unique display name; otherwise nil plus the reason |
Areas#
Area is an optional attribute of a save, never part of its key.
| Function | Returns | Description |
|---|---|---|
teleporter:KnownAreas() |
table, table |
Sorted names and a { [lower] = name } lookup: Areas.Names plus every explicit Area a save carries, learned in key order so the spelling it settles on is the same on every call |
teleporter:CanonicalArea(area [, known]) |
string|nil |
The name in the spelling this table already uses, nil for an empty one. Every path that stores an Area goes through it, and GetSaveArea folds what it reads the same way. |
teleporter:GetSaveArea(save [, known]) |
string|nil, boolean |
The explicit Area; else, while Areas.DeriveFromCategory is on, the top category when it names a known area, spelled the known way. The boolean says it was derived. known is the lookup from KnownAreas, for a caller in a loop. |
teleporter:GetAreas() |
table, number |
Sorted { Name, Count } per known area, declared ones included while empty, and how many saves have none |
teleporter:SetSaveArea(keyOrName, area) |
boolean |
Sets or clears (""/nil) the field and commits. A name already known is taken in its known spelling. |
teleporter:PromptSaveArea([keyOrName]) |
boolean |
Asks for the area with inputQuery, then SetSaveArea |
teleporter:AssignDerivedAreas() |
number |
Writes the derived area into every save without one. One write, one listener call. |
teleporter:RenameArea([old, new]) |
number |
Moves every save in the area, whether it carried the name or derived it from its category: a derived member has the new name written into it, because the old name derives nothing afterwards. A name that is already another area's merges into it and the old declaration goes. Asks when not given; one write. Areas.Names is table-script configuration, so a renamed declaration lasts the session and the log line says so. |
Persistence#
| Function | Returns | Description |
|---|---|---|
teleporter:EnsureTeleporterDir() |
string|nil |
|
teleporter:GetSaveFilePath() |
string, string |
Full path and file name |
teleporter:SaveLookup() |
table|nil |
The data directory first, then the table file |
teleporter:WriteSavesToDataDir() |
boolean |
|
teleporter:WriteSavesToTableFile() |
boolean |
|
teleporter:PersistSaves(preferDataDir) |
||
teleporter:EnsureAuthorsAndCategories() |
number |
Fills in missing fields, normalizes categories, rekeys legacy entries and returns how many were migrated |
teleporter:GetAuthors() |
table |
Maps a name to an author |
teleporter:CountSaves() |
number |
|
teleporter:GetCurrentAuthor() |
string |
USERNAME, then USER, then "Unknown" |
teleporter:FormatSaveTree([options]) |
table |
{ Lines, Summary, Totals }. Options: coordinates, descriptions, width (default 92) |
teleporter:PrintSaves([options]) |
boolean |
Logs the tree as one forced entry. Options are passed to FormatSaveTree |
Management#
| Function | Returns |
|---|---|
teleporter:CreateSaveFromCurrentPosition([name, category, description, area]) |
boolean |
teleporter:CreateSaveAtPosition(position, name [, category, description, area]) |
boolean. One value per axis, taken as it is. CreateSaveFromCurrentPosition delegates to it. area sets the explicit field. |
teleporter:AddSave() |
boolean |
teleporter:DeleteSave([name]) |
boolean |
teleporter:RenameSave(oldName, newName) |
boolean |
teleporter:DuplicateSelectedSave() |
boolean. Delegates to DuplicateSave with the selection. |
teleporter:DuplicateSave(keyOrName) |
boolean. A unique copy name in the same category, with the area. |
teleporter:SetSavePosition(keyOrName, position) |
boolean. One value per axis; commits. What the map's Set To Player Position calls. |
teleporter:UpdateSelectedSaveFromEditor() |
boolean |
teleporter:GenerateUniqueCopyName(base, categoryInput) |
string |
teleporter:CreateTeleporterSaves() |
|
teleporter:ClearSubrecords(record) |
Save listeners#
| Function | Returns | Description |
|---|---|---|
teleporter:AddSaveListener(fn) |
function|nil |
Registers fn(teleporter, key) to be told after every add, update, rename, duplicate and delete (key is the save) and after a load (key is nil). The same function registers once. |
teleporter:RemoveSaveListener(fn) |
boolean |
|
teleporter:_NotifySavesChanged(key) |
Called by _CommitSaveChange and SaveLookup. A listener that raises is reported and skipped. |
User interface#
| Function | Description |
|---|---|
teleporter:InitTeleporterUI() |
Opens or focuses the window |
teleporter:EnsureUiState() |
Creates the UI state table, which Manifold.UI uses for theming |
teleporter:RefreshUi([preserveSelection]) |
Rebuilds the tree view |
teleporter:SetStatus(text) |
Status bar |
teleporter:ClearEditor() |
|
teleporter:LoadSaveIntoEditor(keyOrName) |
|
teleporter:GetSelectedSaveName() / SetSelectedSaveName(key) |
Holds the save key, not the display name |
teleporter:GetAxisEdits() |
The editor's coordinate boxes, in axis order. Skips any that were not built. |
teleporter:_CommitSaveChange(key, status) |
Persists, reselects, refreshes and reloads the editor. The shared tail of add, update, rename, duplicate and delete. key = nil clears the editor, which is the delete case. |
teleporter:TryGetEditorPosition() |
Reads X, Y and Z from the editor fields |
teleporter:GetSaveKeyFromTreeNode(node) |
Walks back up to the author node to rebuild the key |
teleporter:GetSaveNameFromTreeNode(node) |
Deprecated alias for GetSaveKeyFromTreeNode |
teleporter:OnThemeApplied(themeData) |
Reaction to a theme change |
teleporter:GetMap() |
The teleporterMap instance when the table loaded one, looked up on every call, else nil |
teleporter:OpenMap() |
Opens the map with the selected save focused. false with a warning when there is no map. |
teleporter:CreateMenuStrip/Header/StatusBar/TreePanel/EditorPanel/TreeContextMenu(...) |
UI construction. The Map button and the Tools → Open Map entry are built only when GetMap() finds one. |
Manifold.TeleporterMap#
TeleporterMap, version 1.3.4. logger, forms and teleporter are required, customIO is
optional, and json, utils and ui are runtime dependencies. See
the framework guide for what the window does.
Configuration#
Every section is copied per instance, and a config table merges into the copy key by key, so
TeleporterMap:New({ View = { ShowGrid = false } }) changes one option and keeps the rest.
| Section | Fields |
|---|---|
Plane |
Horizontal = nil, Vertical = nil (position indexes; nil derives them from the up axis), FlipHorizontal = false, FlipVertical = false |
Area |
Selected = nil: every area; false: the saves without one; a string: that area. Which area a save is in is teleporter:GetSaveArea's answer. |
View |
Zoom = nil (pixels per unit; nil fits on first open), MinZoom = 0.0005, MaxZoom = 400, ZoomStep = 1.25, ZoomAnimationMs = 120 (0 applies a notch at once), ZoomFrameMs = 15, FrameMs = 15 (how often mouse moves, the player poll, a resize and Invalidate may repaint; Windows rounds a timer up to its 15.6 ms tick, so 16 fires about every 30 ms), GridTargetPixels = 72, FollowPlayer = false, ShowGrid, ShowRulers, ShowLabels, ShowTrail, ShowDetails (all true), OneClickTeleport = true, ConfirmTeleport = true, ScaleByHeight = true (size, shade and the legend together), HeightScaleMax = 1.5, HeightSnapRadius = 25 (world units; 0 off), HeightBand = 0 (world units; 0 off), MarkerRadius = 3, HitRadius = 13, FontSize = 9, LabelLimit = 150 |
Player |
RefreshInterval = 100 ms, TrailLength = 400, TrailMinDistance = 0.25, TrailBreakDistance = 25, FailureBackoff = 5 |
Settings |
PersistView = true, ViewFileName = "Teleporter.%s.Map.txt" |
Plane#
| Function | Returns | Description |
|---|---|---|
teleporterMap:GetUpAxis() |
number|nil |
Settings.YCoordinateIndex when the Teleporter's lift is on, else 2; nil for a 2D table |
teleporterMap:GetPlane() |
h, v, hName, vName |
The two position indexes drawn and their axis names. An invalid override falls back to the derived pair. |
teleporterMap:HeightAxis() |
number|nil |
The component marker size and shade stand for: the up axis while the plane leaves it out, else the one remaining component; nil for a 2D table |
teleporterMap:SetPlane(h, v) |
Rebuilds the markers, clears the trail and fits | |
teleporterMap:PlaneChoices() |
table |
Every pair { H, V, Caption = "X / Z" }, for the View menu |
teleporterMap:FlipHorizontal() / FlipVertical() |
Areas#
| Function | Returns | Description |
|---|---|---|
teleporterMap:AreaEntries() |
table |
What the selector offers: { Selected, Caption } for All Areas, each area with its count, the area being shown even when nothing knows it any more, and (No Area) while any save has none or while it is the view being shown |
teleporterMap:SetArea(selected) |
boolean |
Shows one area (string), every area (nil) or the saves without one (false). Remembers the camera being left, restores the other's or fits, drops the trail. |
teleporterMap:CycleArea(step) |
boolean |
Previous or next entry, wrapping. PageUp and PageDown. |
teleporterMap:AreaCaption() |
string |
"14 saves in Slums" and the like |
teleporterMap:AreaKey([selected]) |
string |
"all", "none" or "area:<name>", each suffixed with the plane, because a camera framed on one pair of axes means nothing on another |
Markers#
| Function | Returns | Description |
|---|---|---|
teleporterMap:RebuildMarkers() |
table |
One marker per save with a usable position, sorted by name: { Key, Name, Category, Author, Description, Area, AreaDerived, Position, X, Y, Height, HeightT, Scale, Radius, HitExtra, Search }. HeightT is the mirrored height as a fraction, 0 highest and 1 lowest, which drives both the size and the shade. The selection survives when its save still exists. |
teleporterMap:_ScaleMarkers([markers]) |
Sets Scale, Radius, HitExtra and HeightT from each marker's Height against the range over every marker, and records the range in HeightRange. Called by RebuildMarkers, LoadView, the toggle, and by every frame through _EnsureScaled when MarkerRadius, HeightScaleMax or ScaleByHeight was edited in place. |
|
teleporterMap:FindMarker(key) |
table|nil |
|
teleporterMap:MarkerAt(sx, sy) |
table|nil |
The closest marker within View.HitRadius plus its HitExtra pixels that is not dimmed. A marker whose disc is off the map has no screen position and cannot be hit. |
teleporterMap:SetFilter(text) |
Dims every marker whose search text does not contain it. The height band dims the same way. | |
teleporterMap:SetHeightBand(units) |
boolean |
Dims every save further than this from the player's height; 0 is off. Refuses a band on a table with no height axis. |
teleporterMap:CycleHeightBand(step) |
boolean |
Steps through Off, 2, 5, 10, 25, 50. Comma and period. |
teleporterMap:SelectMarker(marker|nil) |
Updates the details card and the status bar | |
teleporterMap:FocusSave(key) |
boolean |
Selects and centres, first switching to the save's area (or (No Area)) when it is not the one being shown. A save without a usable position changes nothing. |
Camera#
| Function | Returns | Description |
|---|---|---|
teleporterMap:ToWorld(sx, sy) |
wx, wy |
|
teleporterMap:ZoomBy(factor [, sx, sy]) |
Around a screen point, or the middle, at once. What a script and the tests use. | |
teleporterMap:ZoomSmooth(factor [, sx, sy]) |
The same, arriving over View.ZoomAnimationMs on a timer of its own, in geometric steps that hold the anchor. Steps are paced by the clock, so the option stays milliseconds whatever a frame costs. A second call moves the target rather than restarting. Anything that scales the camera cancels it, and so do PanBy, CenterOn and a drag, but following the player does not. Falls back to ZoomBy with no window or with the option at 0. |
|
teleporterMap:SettleZoom() |
boolean |
Puts a zoom in flight at its destination at once. The view file and the closing window use it. |
teleporterMap:ZoomIn() / ZoomOut() |
One View.ZoomStep, smoothed |
|
teleporterMap:SetZoom(scale) |
Pixels per unit, clamped | |
teleporterMap:CenterOn(wx, wy) |
||
teleporterMap:PanBy(dx, dy) |
Screen pixels | |
teleporterMap:FitAll([includeOutliers]) |
boolean |
Fits the saves that sit together, and says in the status bar how many far ones it left out. true fits every save; Shift+Home and View → Fit Every Save pass it. |
teleporterMap:FitNote() |
string |
What the last fit left out, as a phrase for a status line, or empty. SetArea and Show append it to their own line so a fit's warning is not overwritten. |
teleporterMap:ZoomToPile() |
boolean |
Zooms into the pile under the pointer. Z. |
teleporterMap:CenterOnPlayer() |
boolean |
|
teleporterMap:SetFollow(enabled) |
||
teleporterMap:Toggle(option) |
Flips a boolean View option by name |
Player#
| Function | Returns | Description |
|---|---|---|
teleporterMap:PeekPlayerPosition() |
table|nil |
teleporter:PeekCurrentPosition(), or the same quiet read done locally on a Teleporter older than 1.5.0 |
teleporterMap:Tick() |
One poll: read, trail, follow, repaint when something moved, and the deferred view write. Runs on the window's timer. | |
teleporterMap:ClearTrail() |
Teleport#
| Function | Returns | Description |
|---|---|---|
teleporterMap:TeleportToMarker(marker) |
boolean |
Asks first, then teleporter:TeleportToSave(marker.Key) with the trail broken |
teleporterMap:TeleportToSelected() |
boolean |
|
teleporterMap:PositionForPoint(wx, wy [, keepPlayerHeight, source]) |
table|nil, table|nil |
The plane components from the point, the height from the nearest shown save within View.HeightSnapRadius (returned as the second value), every other component from the player. keepPlayerHeight skips the snap; source is a marker the caller already resolved, so the height a question named is the height that is written. |
teleporterMap:TeleportToPoint(wx, wy [, keepPlayerHeight]) |
boolean |
Names the height source in the question, asks, then reads the player's other components |
teleporterMap:AddSaveAtPoint(wx, wy) |
boolean |
Asks for a name, then teleporter:CreateSaveAtPosition with the snapped height and the shown area |
teleporterMap:OpenInEditor() |
boolean |
Opens the Teleporter window with the selection loaded |
teleporterMap:DuplicateMarker(marker) |
boolean |
teleporter:DuplicateSave |
teleporterMap:MoveSaveToPlayer(marker, heightOnly) |
boolean |
Asks every time, then teleporter:SetSavePosition |
teleporterMap:CopyCoordinates(marker) |
boolean |
Comma separated, in axis order, to the clipboard |
teleporterMap:DeleteSelectedSave() / RenameSelectedSave() |
boolean |
Through the Teleporter's own question and prompt. Delete and F2. |
Persistence#
| Function | Returns | Description |
|---|---|---|
teleporterMap:GetViewFilePath() |
string|nil |
<Teleporter dir>\Teleporter.<Target>.Map.txt; nil when persistence is off or customIO, utils or the directory are unavailable |
teleporterMap:SaveView() |
boolean |
Zoom, centre, plane, flips, the boolean toggles, HeightBand, the shown area as { Kind, Name } and AreaViews, one camera per area and plane |
teleporterMap:LoadView() |
boolean |
Reads it back. A camera key written before cameras were kept per plane is carried over under the plane the file was framed on; one that already names a plane wins. |
Window#
| Function | Returns | Description |
|---|---|---|
teleporterMap:Show() |
form |
Opens or focuses the window. InitMapUI() is an alias. |
teleporterMap:Close() |
||
teleporterMap:Redraw() |
boolean |
Paints one frame into the off-screen buffer and presents it. One pcall per frame; five consecutive failures stop the map. |
teleporterMap:Invalidate() |
Repaint with the next frame, within View.FrameMs while the window is open. Many calls in one interval paint one frame. |
|
teleporterMap:HandleKey(key) |
boolean |
The window's key handler. Keys pass through while the filter box, the area dropdown or one of the details boxes has focus, except Escape in the filter. With the map focused: Home and Shift+Home fit, Z zooms into a pile, PageUp/PageDown switch the area, comma and period step the height band, Delete and F2 act on the selected save, Escape clears the selection. |
teleporterMap:Palette() / Colors() |
table |
The Forms design palette, and the canvas colours derived from it, cached against the palette. Colors().Ramp is the height ramp, empty when the palette cannot carry one. |
teleporterMap:OnThemeApplied() |
boolean |
Drops the colour cache and repaints. Whether the window was open. |
teleporterMap:SetStatus(text) |
||
teleporterMap:EnsureUiState() |
table |
Geometry#
TeleporterMap.Geometry is pure arithmetic over plain tables and runs without Cheat Engine. A
view is { Width, Height, CenterX, CenterY, Scale, SignX, SignY }; Scale is pixels per world
unit and SignY is -1 unless the vertical axis is flipped.
| Function | Returns | Description |
|---|---|---|
Geometry.Project(view, wx, wy) |
sx, sy |
|
Geometry.Unproject(view, sx, sy) |
wx, wy |
|
Geometry.ZoomAt(view, factor, sx, sy, min, max) |
boolean |
Scales in place, keeping the world point under (sx, sy) where it is |
Geometry.NiceStep(scale, targetPixels) |
number |
1, 2 or 5 times a power of ten, so grid lines sit about targetPixels apart |
Geometry.Bounds(points) |
table|nil |
{ MinX, MaxX, MinY, MaxY } over { X, Y } points |
Geometry.CoreBounds(points, spread) |
table|nil, number |
The bounds of the points that sit together, and how many were left out. What Fit All uses so one far save cannot squeeze the rest into a corner. An axis whose middle half shares one value decides nothing, and a box that would drop more than a fifth of the points is refused in favour of the full bounds. |
Geometry.Fit(bounds, w, h, padding, minSpan, min, max) |
scale, cx, cy |
A box with no extent gets minSpan |
Geometry.Nearest(markers, sx, sy, radius) |
table|nil |
By the markers' SX, SY, each reaching radius plus its HitExtra; dimmed markers are skipped |
Geometry.HeightScale(value, low, high, maxScale) |
number |
1 at low, maxScale at high, linear between and clamped. The caller mirrors the value, so the lowest save is the largest disc. |
Geometry.HeightBandIndex(value, low, high, count) |
number |
Which of count bands a value falls in, for the colour ramp |
Geometry.FormatUnits(value) |
string |
Three decimals, no trailing zeros. The exact one: the clipboard, the details card, the status bar. |
Geometry.FormatRounded(value) |
string |
Whole numbers above ten, one decimal below. The short one, for what the canvas paints. |
Geometry.RoundUnits(value, span, up) |
number |
A human end value for the legend and the scale bar |
Geometry.Overlaps(a, b) |
boolean |
Rectangles { X1, Y1, X2, Y2 } |
Geometry.ClampToRect(x, y, w, h, margin) |
x, y, outside |
Manifold.Testing#
Manifold-Modules/Manifold.Modules/Manifold.Testing/Manifold.UnitTest.lua is a test runner rather
than a module, so it exposes no API. It loads each module named in its own MODULE_SPECS table,
checks the declared exports and runs a behaviour probe where one is safe to run. TEST_MODE is
"safe" or "deep" and gates the probes that touch files or memory. The runner prints to the
console, and Manifold.UnitTest.Output.txt next to it is a saved transcript of one such run.