Skip to content

DevJSRuntime

Jump to bottom
Bashar Astifan edited this page Apr 12, 2025 · 41 revisions

📜 ImMobile JSRuntime

The JSRuntime in ImMobile enables powerful scripting using QuickJS, giving developers access to internal APIs through a global object called imm. It allows you to create extensions, automation scripts, and interactive tools with familiar JavaScript syntax.

🔹 Getting Started

To use JSRuntime:

  • Your script should access ImMobile's APIs via the global imm object.
  • You can use functions like setTimeout, sleepAsync, and many others.

Example:

// Delay execution by 2.5 seconds
imm.setTimeout(startTest, 2500);

// Async sleep for 1 second
await imm.sleepAsync(1000);

Note: The imm object in ImMobile is equivalent to os in QuickJS-NG documentation.

Reset Runtime

It's very recommeneded to reset the runtime for your script before start using this code

imm.resetRuntime();

Check this file for more examples

🧩 Constant Substitutions

JSRuntime supports special string constants that are auto-replaced with paths to relevant folders:

Constant Description
$exts Extensions folder
$runs Runtime scripts folder
$updates Updates folder
$startup Startup scripts folder
$cfgs Configuration folder
$fonts Fonts folder
$temp Temporary files directory
$local Local app data folder
$music Music folder (ImMobile scoped)
$pics Pictures folder (ImMobile scoped)
$vids Videos folder (ImMobile scoped)
$data Root working data folder
$backups Backups folder
$downloads Downloads folder
$textures Cached textures
$tmpfiles Temporary files

Script-Specific Constants

Constant Description
$jsID Unique ID for the script
$jsIndex Index of the script in execution stack
$jsTime Timestamp of when the script started

📟 Console Output

You can use console.log(...) or similar functions, and output will appear in the script-specific console in ImMobile.

note that constants my not appear in the real full value in console but that's fine I forgot to replace the value for output print.

📘 API Reference (imm object)

Below is a categorized list of available API functions accessible through imm.

🔔 Notifications & Dialogs

  • imm.toast(title, message)
    Display a system notification.

  • imm.notify(message, type)
    Show an ImMobile in-app notification.
    type: "info", "success", "warn", "error"

  • imm.noticeDialog(title, text, onClose)
    Show an info dialog.

  • imm.confirmDialog(title, message, callback)
    Confirmation dialog with callback returning true/false.

  • imm.inputDialog(title, text, onClose)
    Prompt input dialog.

🌐 Network & GitHub Tools

  • imm.openURI(url)
    Open a URL in the default browser.

  • imm.quickDownload(url, dest)
    Download a file quickly to dest.

    dest expected as file name not a full path, file will be at downloads folder by default

  • imm.getOnlineFileName(url, defaultName)
    Get filename from a remote resource, it may return the string before '?' if fail, ensure to use your own way to cover fail case.

  • imm.getResponse(url)
    Fetch a remote response as string, return the response or undefined if fail.

  • imm.downloadResponse(url, dest)
    Download response to a file.

    dest expected as file name not a full path, file will be at downloads folder by default

  • imm.gitHubContent(user, repo, sub, callback)
    Load GitHub content (optionally from a subdirectory).

  • imm.gitHubLatestRelease(user, repo, callback)
    Get info about the latest release.

  • imm.showGitHubReadMeUI(url, token)
    Show UI to browse a GitHub README.

  • imm.showGitHubReleasesUI(url, token)
    UI for browsing and downloading GitHub releases.

  • imm.showGitHubFilesUI(url, token)
    UI for browsing and downloading repository content.

  • imm.isOnline()
    Returns true or false based on network availability.

📁 File System

  • imm.createFolder(parent, name)
    Create a folder under a given path, return the full path for folder or undefined if fail.

  • imm.filePutContents(path, content)
    Write text to a file.

  • imm.fileGetContents(path)
    Read the content of a file, return file content or undefined if fail.

  • imm.openFile(path)
    Open file with the default OS app.

  • imm.openFolder(path)
    Reveal folder in OS file explorer.

  • imm.unZip(file, dest, callback)
    Unzip archive with callback.

  • imm.zipFolder(folder, dest, callback)
    Zip folder with callback.

📦 Package Management

  • imm.installPackage(path)
    Install .appx, .msix, or similar package.

  • imm.registerPackage(path)
    Register a package via its manifest.

  • imm.removePackage(id)
    Remove installed package by ID or name.

🧩 Extensions

  • imm.loadExten(path, window, confirm)
    Load an ImMobile extension.

  • imm.unloadExten(path)
    Unload an ImMobile extension.

  • imm.extenToggleGUI(path)
    Toggle extension’s UI visibility.

  • imm.isExtenLoaded(path)
    Check if an extension is currently loaded.

📂 Pickers

  • imm.chooseFile(callback)
    File picker; returns selected path.

  • imm.saveFile(callback)
    Save-as file dialog.

  • imm.chooseFolder(callback)
    Folder picker; returns selected path.

📋 Clipboard & UI

  • imm.setClipboard(text)
    Set system clipboard text.

  • imm.getClipboard()
    Get current clipboard text.

  • imm.showKeyboard(state)
    Show or hide on-screen keyboard.

  • imm.changeBackground(path)
    Change ImMobile background.

    I forgot to apply constants replacement on path at this function so ensure to use proper full path

Path Issues

Some functions like change background has no constants replacement,

as solution for path constants you my do it like:

var downloadsFolder = "$downloads";
var bingWallpapers = "BingsWallpapers";

// Create if not exists
var folderPath = imm.createFolder(downloadsFolder, bingWallpapers);

// Now you have full resolved path: folderPath

same goes for path parts, most functions do replace / by \ for windows

but some like background change don't, so ensure to use \\ by default to avoid issues

📚 See Also

Clone this wiki locally