Scripting Guide

Logging

Write messages to the application log panel:

mm.log("Hello from my script!");

Listening to Events

Use mm.on(eventClassName, callback) to react to application events. The first argument is the full Java class name of the event:

// Log a message when the app launches
mm.on('io.github.samera2022.samacros.api.event.events.OnAppLaunchedEvent',
  function(event) {
    mm.log("App started! Version: " + event.getAppVersion());
  }
);

// Log the number of actions when recording stops
mm.on('io.github.samera2022.samacros.api.event.events.AfterRecordStopEvent',
  function(event) {
    mm.log("Recording stopped. Actions captured: " + event.getActionCount());
  }
);

Cancelling Events

Some events are cancellable — calling event.setCancelled(true) prevents the default action from occurring:

// Prevent recording from starting when a condition is not met
mm.on('io.github.samera2022.samacros.api.event.events.BeforeRecordStartEvent',
  function(event) {
    if (!isReadyToRecord()) {
      event.setCancelled(true);
      mm.log("Recording blocked: system not ready.");
    }
  }
);

Showing Notifications

var ctx = mm.getContext();

// Show a system tray notification
ctx.showToast("Task Complete", "Your macro finished successfully!");

Simulating Mouse Clicks

Pass an action object with the same fields used in recorded macros:

var ctx = mm.getContext();

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

// Right click
ctx.simulate({ x: 200, y: 300, type: 1, button: 2, delay: 100 });
ctx.simulate({ x: 200, y: 300, type: 2, button: 2, delay: 60 });

Reading Pixel Colors

Use getPixelColor(x, y) to read a screen pixel and make conditional decisions:

var ctx = mm.getContext();
var color = ctx.getPixelColor(500, 300);

mm.log("R=" + color.getRed() + " G=" + color.getGreen() + " B=" + color.getBlue());

// Example: only click if the button is green
if (color.getGreen() > 200 && color.getRed() < 50) {
  ctx.simulate({ x: 500, y: 300, type: 1, button: 1, delay: 0 });
  ctx.simulate({ x: 500, y: 300, type: 2, button: 1, delay: 50 });
}

Reading App Configuration

var ctx = mm.getContext();
var config = ctx.getAppConfig();

var lang = config.getString("lang");
var darkMode = config.getBoolean("enableDarkMode");
mm.log("Language: " + lang + ", Dark mode: " + darkMode);

What Happens at First Load

1. 1saMacros detects requireNativeAccess = true in the script file.
2. 2The script file is renamed to .js.disabled and marked as disabled.
3. 3The Script Manager shows the script with a warning icon and your requireNativeAccessDescription.
4. 4The user reviews the description and manually enables the script in Settings → Script Manager.
5. 5The script is added to white_list.json (by script name or author) and loads on next startup.