Stability: 2 - Stable

The engines module provides functions related to script environments, script execution, and script engines, such as running other scripts and stopping scripts.

Example: get the script working directory:

toast(engines.myEngine().cwd());

engines.execScript(name, script[, config])

• name {string} Script name shown in task manager. It is not related to the file name.

• script {string} Script source code to run.

• config {Object} Run configuration

  • delay {number} Delay before starting in milliseconds. Default 0.
  • loopTimes {number} Loop count. Default 1. 0 means infinite loop.
  • interval {number} Interval between loops in milliseconds. Default 0.
  • path {Array} | {string} Script working directory(ies). Used to resolve modules when calling require.

Run script in a new script environment. Returns a ScriptExecution object.

A “new script environment” means variables are not shared with the original script, and the script runs on a new thread.

The simplest example:

engines.execScript("hello world", "toast('hello world')");

To run in a loop:

// Run once every 3 seconds, loop 10 times
engines.execScript("hello world", "toast('hello world')", {
  loopTimes: 10,
  interval: 3000,
});

Writing scripts as strings is inconvenient. You can combine it with Function.toString() to execute a specific function:

function helloWorld() {
  // Note: variables here are not shared with the original script
  toast("hello world");
}
engines.execScript("hello world", "helloWorld();\n" + helloWorld.toString());

To pass variables, wrap them into a function:

function exec(action, args){
    args = args || \{\};
    engines.execScript(action.name, action.name + "(" + JSON.stringify(args) + ");\n" + action.toString());
}

// The function to execute: a simple addition
function add(args){
    toast(args.a + args.b);
}

// Execute 1 + 2 in a new script environment
exec(add, \{a: 1, b:2\});

engines.execScriptFile(path)

Added in Auto.js Advanced

• path {string} Script path to run.

In a new script environment, supports running local or remote JS, snapshot, and project zip files, greatly improving deployment and hot-update flexibility. Returns a ScriptExecution object.

📂 Run a local snapshot file

engines.execScriptFile("/sdcard/Pictures/xxxx.snapshot"); // Suffix must be .snapshot

☁️ Run a remote resource file
Supports these resource types:
📄 JS file (JavaScript script)

engines.execScriptFile("https://xxxbeijing.aliyuncs.com/PMTT3.js");

📦 Snapshot file (.snapshot)

engines.execScriptFile("https://xxxxxxg.aliyuncs.com/PMTT3.snapshot");

🧳 Project.zip archive

engines.execScriptFile("https://xxxxxxg.aliyuncs.com/PMTT3.zip");

💡 Auto-detect file type (example: LanZou parsing)

engines.execScriptFile(
  "https://lz.qaiu.top/parser?url=https://apkxxxxxx.lanzouo.com/iPuxxxxxmkmkj",
);

⚠️ Notes:

Debugging: JS files in the Zip package must be plaintext.
Packaged APK: fully encrypted Project Zip is supported to protect logic and enable hot updates.

engines.execScriptFile(path[, config])

• path {string} Script path to run.

• config {Object} Run configuration

  • delay {number} Delay before starting in milliseconds. Default 0.
  • loopTimes {number} Loop count. Default 1. 0 means infinite loop.
  • interval {number} Interval between loops in milliseconds. Default 0.
  • path {Array} | {string} Script working directory(ies). Used to resolve modules when calling require.

Run the script file path in a new script environment. Returns a ScriptExecution object.

engines.execScriptFile("/sdcard/scripts/1.js");

engines.execAutoFile(path[, config])

• path {string} Record file path to run.

• config {Object} Run configuration

  • delay {number} Delay before starting in milliseconds. Default 0.
  • loopTimes {number} Loop count. Default 1. 0 means infinite loop.
  • interval {number} Interval between loops in milliseconds. Default 0.
  • path {Array} | {string} Script working directory(ies). Used to resolve modules when calling require.

Run the record file path in a new script environment. Returns a ScriptExecution object.

engines.execAutoFile("/sdcard/scripts/1.auto");

engines.stopAll()

Stop all running scripts, including the current script itself.

engines.stopAllAndToast()

Stop all running scripts and show how many were stopped, including the current script itself.

engines.myEngine()

Returns the current script engine object (ScriptEngine).

[Added in v4.1.0] In particular, you can read its runtime arguments via execArgv, including external args, injected intent args, etc. For example:

log(engines.myEngine().execArgv);

Runtime args for normal scripts are usually empty; scripts started by a scheduled-task broadcast can get the launching intent.

engines.all()

• Returns {Array}

Returns an array of ScriptEngine for all currently running scripts.

log(engines.all());

engines.startFloatingController(path[, config, options])

[Added in Pro 9.1.10]

• path {string} Script path to run.

• config {Object} Run configuration (optional)

  • delay {number} Delay before starting in milliseconds. Default 0.
  • loopTimes {number} Loop count. Default 1. 0 means infinite loop.
  • interval {number} Interval between loops in milliseconds. Default 0.
  • path {Array} | {string} Script working directory(ies). Used to resolve modules when calling require.

• options {Object} Floating controller options (optional)

  • runImmediately {boolean} Whether to start the script engine immediately

Start a floating controller (with start/pause/log buttons) to control the script engine for the given path.

ScriptExecution

Object returned when executing a script. You can use it to get the engine/configuration or stop the execution.

To stop the script execution, call execution.getEngine().forceStop().

ScriptExecution.getEngine()

Returns the script engine object that runs this execution (ScriptEngine).

ScriptExecution.getConfig()

Returns the run config for this execution (ScriptConfig).

ScriptEngine

Script engine object.

ScriptEngine.forceStop()

Stop the script engine execution.

ScriptEngine.cwd()

• Returns {string}

Returns the execution working directory. For a script file, this is the folder containing the script; for other scripts (e.g. string scripts), it may be null or the configured value.

ScriptEngine.getSource()

• Returns {ScriptSource}

Returns the script source object being executed by this engine.

log(engines.myEngine().getSource());

ScriptEngine.getId()

• Returns {number}

Returns the unique engine id (runtime identifier).

log(engines.myEngine().getId());

ScriptEngine.id

• {number}

Shortcut property for the engine id, equivalent to ScriptEngine.getId().

log(engines.myEngine().id);

ScriptEngine.isDestroyed()

• Returns {boolean}

Returns whether the engine has been destroyed.

log(engines.myEngine().isDestroyed());

ScriptEngine.getThread()

• Returns {java.lang.Thread}

Returns the thread object associated with this engine.

log(engines.myEngine().getThread());

ScriptEngine.thread

• {java.lang.Thread}

Shortcut property for the engine thread, equivalent to ScriptEngine.getThread().

log(engines.myEngine().thread);

ScriptEngine.getExecArgv()

• Returns {Object}

Returns the runtime arguments object (e.g. external args, injected intent args).

log(engines.myEngine().getExecArgv());

ScriptEngine.execArgv

• {Object}

Shortcut property for runtime args, equivalent to ScriptEngine.getExecArgv().

log(engines.myEngine().execArgv);

ScriptEngine.setExecArgv(execArgv)

• execArgv {Object} Runtime arguments object to set

Set the runtime arguments object for this engine.

let e = engines.myEngine();
e.setExecArgv({ taskId: "A001", retry: 1 });
log(e.getExecArgv());

ScriptEngine.getEngineArgs()

• Returns {Object}

Returns the engine-layer args map (low-level args view).

log(engines.myEngine().getEngineArgs());

ScriptEngine.getEngineArg(key[, defaultValue])

• key {string} Argument name
• defaultValue {any} Default value (optional)
• Returns {any}

Read one engine arg by name; returns default value when absent.

let e = engines.myEngine();
log(e.getEngineArg("not-exist", "default"));

ScriptEngine.setTag(key, value)

• key {string} Tag name
• value {any} Tag value

Set a temporary tag value on this engine. Read it with getTag().

let e = engines.myEngine();
e.setTag("scene", "demo");

ScriptEngine.getTag(key)

• key {string} Tag name
• Returns {any}

Read a tag value set via setTag().

let e = engines.myEngine();
e.setTag("scene", "demo");
log(e.getTag("scene"));

ScriptEngine.getConsole()

• Returns {Object}

Returns the console object bound to this engine (low-level implementation object).

log(engines.myEngine().getConsole());

ScriptEngine.getContext()

• Returns {Object}

Returns the underlying context object of this engine.

log(engines.myEngine().getContext());

ScriptEngine.getScriptable()

• Returns {Object}

Returns the scriptable/global object for this engine.

log(engines.myEngine().getScriptable());

ScriptEngine.hasFeature(name)

• name {string} Feature name
• Returns {boolean}

Returns whether the engine has the specified feature enabled.

log(engines.myEngine().hasFeature("x"));

ScriptEngine debugging & compatibility notes

• getConsole(), getContext(), and getScriptable() return low-level implementation objects, mainly for debugging, troubleshooting, and low-level adaptation.
• Their concrete types and output formats may change across versions. For normal scripts, prefer stable module APIs (e.g. app, device, threads, images).
• Do not rely on their string representation (toString()) for business logic. If you must, check null first and then do capability probing (e.g. typeof obj.xxx === "function").

ScriptEngine.emit(eventName[, ...args])

• eventName {string} Event name
• ...args {any} Event args

Send an event to the engine. The event can be listened to by the target script via the events module and handled on the script main thread.

Example receiver.js:

// Listen for "say"
events.on("say", function(words){
    toastLog(words);
});
// Keep script running
setInterval(()=>\{\}, 1000);

Another script in the same directory can start it and send events:

// Run script
var e = engines.execScriptFile("./receiver.js");
// Wait for script start
sleep(2000);
// Send event
e.getEngine().emit("say", "hello");

ScriptConfig

Configuration used when running a script.

delay

• {number}

Delay before starting in milliseconds

interval

• {number}

Interval between loop runs

loopTimes

• {number}

Loop count

getPath()

• Returns {Array}

Returns a string array of module lookup paths used at runtime.