API Documentation

Script Metadata

Every script must declare these global variables before any logic. They are parsed by ScriptDescription.java at load time.

// ==UserScript==
var display_name  = "My Script";
var register_name = "my_script";            // unique, lowercase_snake_case
var author        = "YourName";
var version       = "1.0.0";
var description   = "Does something useful.";
var available_version = "*";                // * = all versions
var hard_dependencies = ["base_library"];   // required
var soft_dependencies = ["optional_lib"];   // optional
var requireNativeAccess = false;
var requireNativeAccessDescription = "";
// ==/UserScript==

Event System

saMacros uses a priority-ordered event bus. In JavaScript, register listeners with mm.on().

mm.on('...BeforePlaybackStartEvent',
  function(event) {
    if (shouldBlock) {
      event.setCancelled(true);
    }
  }
);

mm — IScriptAPI

The global mm object is the sole entry point to the saMacros API, injected into every script at load time.

mm.on(
  'io.github.samera2022.samacros.api.event.events.OnAppLaunchedEvent',
  function(event) {
    mm.log('Hello! App version: ' + event.getAppVersion());
  }
);

var ctx = mm.getContext();
ctx.showToast('Ready', 'Script loaded.');

mm.getContext() — IScriptContext

Provides direct interaction with the runtime. Obtain once and reuse: var ctx = mm.getContext();

ctx.getSystemInfo() — ISystemInfo

Operating system and JVM details.

var sys = mm.getContext().getSystemInfo();
mm.log(sys.getOSName() + ' / Java ' + sys.getJavaVersion());
var scale = sys.getScale();
mm.log('DPI: ' + scale[0] + 'x' + scale[1]);
mm.log('Dark mode: ' + sys.isSystemDarkMode());

ctx.getScreenInfo() — IScreenInfo

Screen geometry and multi-monitor coordinate helpers.

var scr = mm.getContext().getScreenInfo();
mm.log(scr.getWidth() + 'x' + scr.getHeight() + ' (' + scr.getScreenCount() + ' monitors)');
// Convert stored coordinate for Robot on secondary monitor
var pt = scr.denormalizeFromVirtualOrigin(-1920, 540);
mm.log('Robot coords: ' + pt.x + ',' + pt.y);

ctx.getMacroInfo() — IMacroInfo

Real-time, read-only snapshot of the macro engine state.

var m = mm.getContext().getMacroInfo();
mm.log('recording=' + m.isRecording() + ' playing=' + m.isPlaying() + ' actions=' + m.getActionsCount());

ctx.getMouseInfo() — IMouseInfo

Real-time mouse cursor position.

var pos = mm.getContext().getMouseInfo().getPosition();
if (pos !== null) mm.log('cursor at (' + pos.x + ', ' + pos.y + ')');

ctx.getI18n() — II18n

Access the application's built-in localisation strings.

var i18n = mm.getContext().getI18n();
mm.log('UI lang: ' + i18n.getCurrentLanguage());
if (i18n.hasKey('main_frame')) mm.log(i18n.get('main_frame'));

IConfig — Application Configuration

Read-only access to config.cfg. Obtained via ctx.getAppConfig().

Known Configuration Keys

IMouseAction / MouseAction

The concrete MouseAction is what you receive in event callbacks and pass to ctx.simulate().

Public Fields

var ctx = mm.getContext();

// Left mouse click at (960, 540)
ctx.simulate({ x:960, y:540, type:1, button:1, delay:0 });
ctx.simulate({ x:960, y:540, type:2, button:1, delay:80 });

// Scroll down 3 notches
ctx.simulate({ x:960, y:540, type:3, button:0, delay:50, wheelAmount:3 });

// Press 'A'  (AWT KeyEvent.VK_A = 65)
ctx.simulate({ x:0, y:0, type:10, button:0, delay:100, wheelAmount:0, keyCode:0, awtKeyCode:65 });
ctx.simulate({ x:0, y:0, type:11, button:0, delay:50,  wheelAmount:0, keyCode:0, awtKeyCode:65 });

🚀 App Lifecycle Events

mm.on('...OnAppLaunchedEvent', function(e) {
  mm.log('saMacros ' + e.getAppVersion() + ' on ' + e.getRuntimeEnv());
});

mm.on('...OnConfigChangedEvent', function(e) {
  mm.log(e.getConfigKey() + ' changed: ' + e.getOldValue() + ' -> ' + e.getNewValue());
});

⏺ Recording Events

mm.on('...OnInputCapturedEvent', function(e) {
  if (e.getInputType() === 10 || e.getInputType() === 11) {
    e.setCancelled(true); // filter out keyboard inputs
  }
});

mm.on('...AfterRecordStopEvent', function(e) {
  mm.log('Recorded ' + e.getTotalActions() + ' actions.');
});

▶ Playback Events

mm.on('...OnLoopCompleteEvent', function(e) {
  mm.log('Loop ' + e.getCompletedIterations() + ' done, ' + e.getRemainingIterations() + ' left.');
});

💾 File I/O Events

🖼 UI Events

mm.on('...OnTooltipDisplayEvent', function(e) {
  e.setModifiedText(e.getRawText() + ' [from script]');
});

Hello World

// ==UserScript==
var display_name  = "Hello World";
var register_name = "hello_world";
var author        = "Developer";
var version       = "1.0.0";
var description   = "Minimal working script.";
var available_version = "*";
// ==/UserScript==

var ctx = mm.getContext();

mm.on('io.github.samera2022.samacros.api.event.events.OnAppLaunchedEvent', function(e) {
  mm.log('saMacros ' + e.getAppVersion() + ' on ' + e.getRuntimeEnv());
  ctx.showToast('Hello World', 'Script loaded!');
});

mm.on('io.github.samera2022.samacros.api.event.events.AfterRecordStopEvent', function(e) {
  mm.log('Recorded ' + e.getTotalActions() + ' actions.');
});

Input Filter — Drop Keyboard Events

// ==UserScript==
var display_name  = "Keyboard Filter";
var register_name = "keyboard_filter";
var author        = "Developer";
var version       = "1.0.0";
var description   = "Prevents keyboard events from being recorded.";
var available_version = "*";
// ==/UserScript==

mm.on('io.github.samera2022.samacros.api.event.events.OnInputCapturedEvent', function(e) {
  var t = e.getInputType();
  if (t === 10 || t === 11) {   // KEY_PRESS or KEY_RELEASE
    e.setCancelled(true);
    mm.log('Filtered keyboard event (keyCode=' + e.getKeyCode() + ')');
  }
});

Pixel Guard — Abort Playback on Colour Mismatch

// ==UserScript==
var display_name  = "Pixel Guard";
var register_name = "pixel_guard";
var author        = "Developer";
var version       = "1.0.0";
var description   = "Stops playback when an expected pixel colour is not present.";
var available_version = "*";
// ==/UserScript==

var ctx = mm.getContext();

// Expect a green button (#00cc00) at (200, 300) with ±30 tolerance
var CHECK_X = 200, CHECK_Y = 300;
var TARGET_R = 0, TARGET_G = 204, TARGET_B = 0, TOLE = 30;

function close(a, b) { return Math.abs(a - b) <= TOLE; }

mm.on('io.github.samera2022.samacros.api.event.events.BeforeStepExecuteEvent', function(e) {
  var c = ctx.getPixelColor(CHECK_X, CHECK_Y);
  if (!c) return;
  if (!close(c.getRed(), TARGET_R) || !close(c.getGreen(), TARGET_G) || !close(c.getBlue(), TARGET_B)) {
    mm.log('Pixel guard triggered at step ' + e.getStepIndex() + '. Cancelling.');
    e.setCancelled(true);
  }
});

Progress Notifications

// ==UserScript==
var display_name  = "Progress Notifier";
var register_name = "progress_notifier";
var author        = "Developer";
var version       = "1.0.0";
var description   = "Toast notifications every 25% of loops.";
var available_version = "*";
// ==/UserScript==

var ctx = mm.getContext();
var totalLoops = 0;

mm.on('io.github.samera2022.samacros.api.event.events.BeforePlaybackStartEvent', function(e) {
  totalLoops = e.getRepeatCount();
  ctx.showToast('Playback Started',
    e.getMacroData().size() + ' actions x ' + totalLoops + ' loops'); // Java List: use .size(), not .length
});

mm.on('io.github.samera2022.samacros.api.event.events.OnLoopCompleteEvent', function(e) {
  if (totalLoops <= 0) return;
  var pct = Math.round((e.getCompletedIterations() / totalLoops) * 100);
  if (pct % 25 === 0) {
    ctx.showToast('Progress',
      pct + '% done (' + e.getCompletedIterations() + '/' + totalLoops + ')');
  }
});

mm.on('io.github.samera2022.samacros.api.event.events.OnPlaybackAbortedEvent', function(e) {
  ctx.showToast('Aborted',
    'Stopped at step ' + e.getAtStepIndex() + ': ' + e.getAbortReason());
});