common/runtime

Provides a thin runtime bridge to the Sigma-RT scripting engine (Total Control),
exposing common script primitives such as metadata definition, blocking delays, execution checks,
and configuration retrieval.

The runtime module wraps engine-bound capabilities via global.sigmaScriptParameter,
offering a small, predictable API you can use across legacy JavaScript hosts
(e.g., Rhino/RingoJS–style environments embedded by the engine).

Core Features:

• Script metadata (define): Declare script versioning, recording resolution, required engine version,
  log verbosity, script path, and screen orientation.
• Blocking delay (delay): Pause the script synchronously for a given number of milliseconds.
• Execution guard (checkScriptExit): Probe engine state to gracefully stop work if the script
  has been requested to exit (useful in long loops/polls).
• Configuration lookup (getSetting): Read Total Control properties and device-scoped settings
  (e.g., path bundle, build country code) with automatic JSON parsing when appropriate.

Usage Overview:

1. Import the module: const runtime = require("sigma/common/runtime");
2. Define script metadata with runtime.define(...) before doing any work.
3. Use runtime.delay(ms) to coordinate timing with UI/ADB actions.
4. Call runtime.getSetting(tcConst.*) to obtain environment/device configuration.
5. Optionally call checkScriptExit() inside loops to honor user-initiated cancellations.

API Highlights:

• define(name, value): Declare engine-recognized properties such as:
  • version, resolution, requireVersion, scriptPath, orientation, verbose
• delay(timeOut): Synchronous millisecond delay (blocking).
• checkScriptExit(): No-throw guard that returns early if the engine requests termination.
• getSetting(type): Query settings via tcConst.*.
  • Parses JSON payloads when returned by the engine (e.g., tcConst.Pathname → { installPath, workingPath, adbPath }).
  • Falls back to raw string/primitive when the payload is not JSON (e.g., tcConst.BuildCountryCode → "cn").

Examples:

var { define, delay, getSetting } = require("sigma/common/runtime");

// 1) Declare script metadata
define("version", "6.1.0.20966");
define("resolution", "1080*1920");
define("requireVersion", "1.0.0.1666");
define("verbose", 2); // full logging
define("orientation", "v"); // portrait

// 2) Blocking delay between actions
delay(1500); // wait 1.5s

// 3) Read Total Control path bundle
var paths = getSetting(tcConst.Pathname);
// -> { installPath, workingPath, adbPath }

// 4) Read device build country code
var device = Device.getMain();
var region = device && device.getSetting
  ? device.getSetting(tcConst.BuildCountryCode)
  : null;

Notes & Best Practices:

• Always check for null and use lastError() for diagnostics after engine calls.
• Prefer define("requireVersion", "...") to pin minimum engine compatibility.
• Use checkScriptExit() in polling loops to keep scripts responsive to user cancels.
• delay(ms) is blocking; keep delays short and purposeful.

Functions

// Define the script version
define("version", "6.1.0.20966");

// Define the script recording device resolution
define("resolution", "1080*1920");

// Define the minimum required script engine version to run this script
define("requireVersion", "1.0.0.1666");

// Define the log output mode:
// 2 - All information (default)
// 1 - Script execution information only
// 0 - User input information only
define("verbose", 2); // Full logging
define("verbose", 1); // Execution logging
define("verbose", 0); // User input only

// Define the user script path
define("scriptPath", "c:\\abc");

//Define the screen orientation of the device when recording the script (landscape or portrait)
define("orientation", "v"); // portrait
define("orientation", "h"); // landscape

// Example: Get the height of the main device and delay 2 seconds before checking the result.
var device = Device.getMain();

if (device != null) {
    const ret = device.getHeight();

    // Wait for 2000 milliseconds (2 seconds) before proceeding
    delay(2000);

    if (ret != 0) {
        print("Congratulations, this API executes successfully.\nReturn value: " + ret);
    } else {
        print("Sorry! " + lastError() + "\nReturn value: " + ret);
    }
} else {
    print("Failed to get the master device object");
}

// Operation Result (if successful):
Congratulations, this API executes successfully.
Return value: 1280

// Example 1: Get installation, working, and ADB paths (global call; returns an object)
var ret = getSetting(tcConst.Pathname);
if (ret != null) {
    print("Get the properties of Total Control successfully, the value is:\n" + JSON.stringify(ret));
} else {
    print("Failed to get. The error is : " + lastError());
}

// Operation Result (if successful):
// Get the installation, working address and adb path of Total Control successfully, the value is:
{ "installPath":"C:\\Program Files\\Sigma-RT\\Total Control",
  "workingPath":"C:\\Users\\xiaofu\\Documents\\Scripts",
  "adbPath":"C:\\Program Files\\Sigma-RT\\Total Control\\adb\\adb2.exe"}


// Example 2: Get build type / region code (device call; returns a string)
var device = Device.getMain();
var ret = device.getSetting(tcConst.BuildCountryCode);
if (ret != null) {
    print("Get build type successfully, the value is: " + ret);
} else {
    print("Failed to get. The error is : " + lastError());
}

// Operation Result (if successful):
// Get build type successfully, the value is: cn