JsMacros

com.jsmacrosce.jsmacros.core.library.impl.FJsMacros

Script library for event listeners, script execution, and profile services.

Scripts access this library as JsMacros for event handling, script execution, and profile services.

const listener = JsMacros.on("Tick", JavaWrapper.methodToJava(function (event) {
  Chat.log(event.getEventName());  
}));  
JsMacros.off(listener);  
JsMacros.runScript("helper.js", null, JavaWrapper.methodToJava(function () {
  Chat.log("helper.js is done");  
}));

Accessible in scripts via the global JsMacros variable.

Nested types

Methods

assertEvent

assertEvent(BaseEvent event, String type): voidSince1.9.0#

Throws AssertionError unless the event's Event annotation value equals type; also narrows the event type in generated TypeScript declarations.

Parameters:

event: event to check
type: expected event name

createComposedEventFilterer

createComposedEventFilterer(EventFilterer initial): FiltererComposedSince1.9.1#

Creates a filterer that combines conditions as OR groups of AND conditions; use its and and or methods to add conditions.

Parameters:

initial: initial filterer in the first AND group

Returns: a composed filterer initialized with initial

createCustomEvent

createCustomEvent(String eventName): EventCustomSince1.2.8#

Creates a named event that can carry key-value arguments. Call EventCustom.registerEvent() to register its name for subscription and GUI visibility, then register listeners before calling EventCustom.trigger(), which dispatches immediately without queuing. Creation and storing arguments do not dispatch.

// Store arguments, register the name, then dispatch.
const ping = JsMacros.createCustomEvent("MyPluginPing");
ping.putString("from", "my-plugin");
ping.putInt("count", 1);
ping.registerEvent();
ping.trigger();

// Custom events can also be passed as script arguments.
const data = JsMacros.createCustomEvent("MyPluginJob");
data.putString("task", "rebuild-world");
data.putBoolean("urgent", true);
JsMacros.runScript("worker.js", data);

Parameters:

eventName: name used to dispatch the event

Returns: the event object

createEventFilterer

createEventFilterer(String event): EventFiltererSince1.9.1#

Creates a filterer for an event with a registered filterer class. Filterers are checked before the listener callback runs; available fields and setters depend on the event. Throws IllegalArgumentException if the event is unregistered or has no filterer.

// Narrow a block-update listener to a position and block id.
const near = JsMacros.createEventFilterer("BlockUpdate")
  .setPos(0, -60, 0)
  .setBlockId("minecraft:chest");
JsMacros.on("BlockUpdate", near, JavaWrapper.methodToJava(function (event) {
  const pos = event.block.getBlockPos();
  Chat.log(`the chest at ${pos.getX()}, ${pos.getY()}, ${pos.getZ()} changed`);
}));

// Change the filter without replacing the listener.
near.setBlockId("minecraft:furnace").setUpdateType("ENTITY");

// A modulus filterer can be used with any event.
JsMacros.on("Tick", JsMacros.createModulusEventFilterer(20),
  JavaWrapper.methodToJava(function () {
    Chat.log("about a second went by");
  }));

Parameters:

event: registered event name with an available filterer class

Returns: a new filterer for the event

createModulusEventFilterer

createModulusEventFilterer(int quotient): FiltererModulusSince1.9.1#

Creates a stateful filterer that passes every quotientth filter call; a fresh filterer rejects calls until the threshold is reached. The count is shared by listeners using the same filterer. The constructor applies Math.abs(int); zero and Integer.MIN_VALUE make every call pass.

Parameters:

quotient: threshold in filter calls; its absolute value is used except for Integer.MIN_VALUE

Returns: the new modulus filterer

disableAllListeners

disableAllListeners(String event): voidSince1.8.4#

Will also disable all listeners for the given event, including JsMacros own event listeners.

Parameters:

event: the event to remove all listeners from

disableAllListeners(): voidSince1.8.4#

Will also disable all listeners, including JsMacros own event listeners.

disableScriptListeners

disableScriptListeners(String event): voidSince1.8.4#

Removes script-created listeners for the given event, leaving built-in listeners untouched. Use disableAllListeners(String) to remove both kinds.

Parameters:

event: the event to remove all listeners from

disableScriptListeners(): voidSince1.8.4#

Removes script-created listeners for all events, leaving built-in listeners untouched.

getConfig

getConfig(): ConfigManager#

Returns: this script's configuration manager.

getOpenContexts

getOpenContexts(): List<BaseScriptContext<?>>Since1.4.0#

Returns: an immutable snapshot of currently open script contexts

getProfile

getProfile(): BaseProfile#

Returns: this script's profile.

getServiceManager

getServiceManager(): ServiceManagerSince1.6.3#

Returns the manager for this profile's background services.

Returns: the service manager

invertEventFilterer

invertEventFilterer(EventFilterer base): EventFiltererSince1.9.1#

Inverts a filterer's test result; inverting an already inverted filterer returns its base. Throws IllegalArgumentException if base is null.

Parameters:

base: filterer to invert

Returns: the inverted filterer, or its base if already inverted

listeners

listeners(String event): List<IEventListener>Since1.2.3#

Parameters:

event: event name

Returns: listeners for this event other than built-in BaseListener instances

off

off(IEventListener listener): booleanSince1.2.3#

Parameters:

listener: listener to remove

Returns: true if it was removed from an event, or false if it was not registered

See:

FJsMacros.off(String, IEventListener)

off(String event, IEventListener listener): booleanSince1.2.3#

Removes a IEventListener from an event.

Parameters:

event: event name under which the listener is registered
listener: listener to remove from that event

Returns: true if it was removed from that event, or false if it was not registered there

See:

IEventListener

on

on(String event, MethodWrapper<BaseEvent, EventContainer<?>, Object, ?> callback): IEventListenerSince1.2.7#

Registers a listener for an event.

Parameters:

event: registered event name; script subscriptions are not remapped from old aliases
callback: calls your method as a BiConsumer<BaseEvent, EventContainer>

Returns: the registered listener, or null if the callback is null

See:

IEventListener

on(String event, boolean joined, MethodWrapper<BaseEvent, EventContainer<?>, Object, ?> callback): IEventListenerSince1.9.0#

Registers a listener for an event. joined asks a joinable event to wait for this listener; cancellable events wait regardless. Joined handling needs the listener to belong to another script, because a script cannot wait on a listener in its own run.

Parameters:

event: registered event name; script subscriptions are not remapped from old aliases
joined: whether to request waiting for this listener on a joinable event; the request does nothing if the event is not joinable
callback: calls your method as a BiConsumer<BaseEvent, EventContainer>

Returns: the registered listener, or null if the callback is null

See:

IEventListener

on(String event, EventFilterer filterer, MethodWrapper<BaseEvent, EventContainer<?>, Object, ?> callback): IEventListener

Since1.9.1#

Registers a listener for an event, optionally filtering which events reach the callback.

Parameters:

event: registered event name; script subscriptions are not remapped from old aliases
filterer: filterer that must support this event; null accepts events without filtering
callback: calls your method as a BiConsumer<BaseEvent, EventContainer>

Returns: the registered listener, or null if the callback is null

See:

IEventListener

on(String event, EventFilterer filterer, boolean joined, MethodWrapper<BaseEvent, EventContainer<?>, Object, ?> callback): IEventListener

Since1.9.1#

Registers a listener for an event, optionally filtering which events reach the callback. joined asks a joinable event to wait for this listener; cancellable events wait regardless. Joined handling needs the listener to belong to another script, because a script cannot wait on a listener in its own run.

Parameters:

event: registered event name; script subscriptions are not remapped from old aliases
filterer: filterer that must support this event; null accepts events without filtering
joined: whether to request waiting for this listener on a joinable event; the request does nothing if the event is not joinable
callback: calls your method as a BiConsumer<BaseEvent, EventContainer>

Returns: the registered listener, or null if the callback is null

See:

IEventListener

once

once(String event, MethodWrapper<BaseEvent, EventContainer<?>, Object, ?> callback): IEventListenerSince1.2.7#

Registers a listener that is removed when the event triggers.

Parameters:

event: registered event name; script subscriptions are not remapped from old aliases
callback: calls your method as a BiConsumer<BaseEvent, EventContainer>

Returns: the registered listener, or null if the callback is null

See:

IEventListener

once(String event, boolean joined, MethodWrapper<BaseEvent, EventContainer<?>, Object, ?> callback): IEventListenerSince1.9.0#

Registers a listener that is removed when the event triggers; joined requests joined handling when supported.

Parameters:

event: registered event name; script subscriptions are not remapped from old aliases
joined: whether to request joined handling for a joinable event
callback: calls your method as a BiConsumer<BaseEvent, EventContainer>

Returns: the registered listener, or null if the callback is null

See:

IEventListener

runScript

runScript(String file): EventContainer<?>Since1.1.5#

Runs a script file without supplying an event or completion callback.

Parameters:

file: path of the script file