Scripting

Introduction

Polinex scripting lets you write your own modules, macros, and helpers in plain JavaScript. Your scripts get the same building blocks the client itself runs on (the macro state machine, combat bots, pathfinding, rotations, failsafes, every setting type, the HUD, Visuals etc) and they show up in the in-game GUI alongside the built-in features, with settings and keybinds that look and behave exactly like native ones.

Everything runs inside a sandboxed JavaScript engine embedded in the client. There is no nothing to compile, and no rebuilding the mod drop a .js file into your scripts folder, reload it in game, and its active. If you can write a little JavaScript, you can make scripts.

Getting Started

Scripts are plain JavaScript that define real Polinex modules and macros using the client's own building blocks. This page gets a first script running, where the files live, how to edit them, and the commands that load them.

Where scripts live

Every script lives under polinex/scripts/ in your Minecraft folder. A script is one of two shapes:

A single file: drop polinex/scripts/my_script.js and that file is the whole script. Or a folder: polinex/scripts/my_script/ with an entry file, which lets you split a bigger script across files that pull each other in with require(...). The folder name is the script's name.

For a folder, Polinex resolves the entry file in this order: main.js, then index.js, then <foldername>.js, and finally the only .js file if the folder contains exactly one. The in-game editor creates every new script as a folder that starts with a single main.js.

polinex/scripts/
├── polinex.d.ts          # shipped type definitions (rewritten on launch)
├── jsconfig.json         # editor config (rewritten on launch)
├── chat_logger.js        # a single-file script
└── auto_announcer/       # a folder script
    ├── main.js           # entry file
    └── messages.js       # required by main.js

Autocomplete & the type file

On launch Polinex writes polinex.d.ts and a jsconfig.json into the scripts folder. That type file describes the API shipped with that client version for external editor hints. Keep the website and your installed client version in sync.

The in-game editor

I know pretty much all of you will use VSC or something similar but i find this as a nice touch for just changing 1 variable or such without tabbing out especially without dual monitors, nothing wrong with using it as your main as it was built for that but again the convenience of modern IDEs will probably outweight anything this provides

Run .scripteditor (aliases .sedit and .pnedit) to open the built-in editor without leaving the game. It has a file-tree sidebar for browsing, creating, and renaming files, JS syntax highlighting, autocomplete, and format-on-save.

Ctrl+S saves the current file; Ctrl+Enter saves and reloads every script so your change takes effect immediately; Esc goes back. It does support terminal instances so u can spin up claude / codex inside minecraft if you wish to (i know 99% of users will be vibecoding so hf)

Managing scripts from chat

The /pnxscript command manages scripts from the chat box:

pnxscript reload          reload every script from disk
pnxscript list            list all discovered scripts
pnxscript info            show script stats
pnxscript run <name>      toggle a script on or off
pnxscript stop <name>     stop a specific script

reloadis the one you'll use most editing outside the game. It re-reads every file in polinex/scripts/. Inside the built-in editor, Ctrl+Enter does the same reload for you. or you can just use the reload button on the top right :D

External edits and developer mode

Local scripts are checked against the content you approved. If either editor changes a local script, reload asks for review before running the changed code unless developer mode is enabled. To skip that review during your own development loop, right-click an already-approved local script in the script picker and choose Enable developer mode. The confirmation explains that future external edits under that script folder execute when scripts reload. The picker marks enabled scripts and lets you disable the mode from the same menu.

Your first script

Here is a VERY simple script, it registers a module and logs every chat line it receives. Save it as polinex/scripts/chat_logger/main.js (or paste it into a new script in the editor).

/// <reference path="../polinex.d.ts" />

const mod = module.create({
  name: "Chat Logger",
  description: "Prints every chat line to the script console.",
});

on("chatReceive", (message) => {
  script.chat("chat> " + message);
});

Reload with .pnxscript reload, then find Chat Logger under the Scripts category in the ClickGUI and toggle it on. Your script is always loaded, but its hooks only fire while its main module is enabled (the first module you create is the main one by default), so nothing logs until the toggle is on. With it on, ull see it detect every chat message :)

From here, see Events for the full list of hooks, Settings for adding controls to your module, and Creating modules for the rest of the module API.

Events

You interact with the game by registering handlers with on(event, handler). Each event has a name and a fixed handler shape. You can register more than one handler for the same event. they run in registration order.

// ik this doesnt apply to sb lol
on("tick", () => {
  if (player.health() < 5) player.sendMessage("low hp");
});

on("chatReceive", (message, event) => {
  script.log("chat: " + message);
});

Available events

The full set of event names, grouped by what they cover:

Ticking & rendering: tick, motion, render2d, render3d, worldRenderLast.

Packets: packetReceive, packetSend (handler gets a ScriptPacketEvent; see the Packets section).

Chat: chatReceive (message, event), chatSend (command, event), actionBar (message, formatted).

World & player: worldLoad, death (message, formatted), entitySpawn / entityDeath (entity), serverDisconnect (reason, reasonFormatted).

GUI: guiOpen (name, title), guiClose.

Skyblock: purseChange (coins, purse, reason), itemGain (itemId, amount, source).

Module toggle: enable / disable. When your script exports a module these follow that module's toggle; otherwise they fire on script load/unload.

Cancellable events

Packet and chat events hand you an event object you can no-op. Call event.cancel() to stop the packet or message from going through, and event.isCanceled() to check whether an earlier handler already did. This works for packetReceive, packetSend, the event arg of chatReceive, and the event arg of chatSend.

// hide a spammy message
on("chatReceive", (message, event) => {
  if (message.includes("Explosion")) event.cancel();
});

// block one of your own outgoing commands idfk u can cancel packets too!!!
on("chatSend", (command, event) => {
  if (command === "/dangerous") event.cancel();
});

Hooks and your main module

Your script is always loaded, but its event hooks only fire while its main module is enabled. The first module you create is the main one by default; call module.export(handle)to choose a different one. Until that module's toggle is on, none of your on(...) handlers run.

Timers & sleep

Awaiting time

In an async function you can pause with await sleep(ms) (real milliseconds) or await sleepTicks(ticks) (20 ticks = 1 second). Both resolve on the client thread.

async function pulse() {
  player.sendMessage("start");
  await sleep(500);       // 500ms
  await sleepTicks(20);   // 1 second
  player.sendMessage("done");
}

Delayed and repeating callbacks

Use setTimeout(fn, ms?)(ms defaults to 0, with a 1 ms minimum) and setInterval(fn, ms?) (ms defaults to 50). Intervals have a 10 ms minimum. Each returns a numeric id you cancel with clearTimeout(id) or clearInterval(id)

The script. adds tick-based timers: script.after(ticks, fn) runs once after N × 50ms, script.every(ticks, fn) repeats until cleared, and both return an id you cancel with script.clearTimer(id).

const id = setInterval(() => script.log("tick"), 1000);
// later: clearInterval(id);

script.after(40, () => script.log("2s later"));   // 40 ticks
const loop = script.every(20, () => check());     // every 1s
// script.clearTimer(loop);

Pausing with your module

Timer deadlines use wall-clock time. Callbacks are deferred while the main module is off; elapsed time is not frozen. If a timer becomes due while disabled, it can run soon after re-enabling instead of waiting its original remaining delay. A pending sleep resumes when its deferred timer is allowed to run. Repeating callbacks do not replay every missed interval. Clear a timer on disable when that delayed action should be discarded rather than resumed.

Threading & performance

Tick, rendering, and script timer callbacks run on the client thread. Packet callbacks can run on the thread that posts the event, including the network thread. The script context serializes JavaScript execution; it does not move every callback onto the client thread.

Cancel packets synchronously

Call event.cancel() while handling the event, before the packet continues. An awaited sleep or timer is too late to cancel that original event. Keep packet handlers short, and copy the values you need before scheduling later work.

on("chatReceive", (message, event) => {
  if (message === "[example] hide this line") event.cancel();
  if (message.includes("[example] route ready")) {
    const text = message;
    setTimeout(() => script.log("On client thread: " + text), 0);
  }
});

Movement and path queries

Start or retarget navigation, drive Etherwarp, submit path queries, and read routes.selected() from a client-thread callback such as tick or a script timer. These APIs reject off-thread calls instead of waiting on the client while holding the script context lock. Use setTimeout to schedule from a packet or background capture callback.

Synchronous path queries and large JS loops can still stall their calling thread. A native search budget excludes worker queue and mutex waits. Submit once, poll on later ticks, and reuse cached scan results instead of scanning or replanning every tick.

Path queries

nav.findPathAsync and etherwarp.findPathAsync return the same PathQuery handle. Submit on the client thread, then poll without a busy loop.

At most eight queries can be in flight per script. Cancelled native calls keep their slot until they actually return. Disable, unload, world change, and disconnect invalidate old results. Keep local handles reset in lifecycle hooks so a re-enabled module can issue a fresh query.

The walking planner accepts allowEtherwarp, not budgetMs. The Etherwarp planner accepts etherOnly and budgetMs. Do not pass (target, options): the two-argument overload is (from, target); use (null, target, options) instead.

Example: replace a pending preview

// Call from tick or a script timer with a support-block goal.
let pending = null;
function previewWarpRoute(goal) {
  if (pending) pending.cancel();
  pending = etherwarp.findPathAsync(null, goal, {
    etherOnly: true,
    budgetMs: 150,
  });
}
on("tick", () => {
  if (!pending || !pending.finished()) return;
  const query = pending;
  pending = null;
  if (query.status() === "found") {
    const nodes = Array.from(query.result());
    script.log("Preview has " + nodes.length + " nodes");
    // Planning alone does not move you.
  } else {
    script.warn(query.status() + ": " + (query.error() || "no result"));
  }
});
function cancelPreview() {
  if (pending) pending.cancel();
  pending = null;
}
on("disable", cancelPreview);
on("worldLoad", cancelPreview);
on("serverDisconnect", cancelPreview);

Multi-file scripts

A script can be a single flat file, or a whole folder. Once it grows, split it into several files that import each other with require(...), just like NJS.

Folder scripts

Put your files in polinex/scripts/my_script/ and the folder name becomes the script's name. The engine picks the entry file: main.js, or index.js, or <foldername>.js, or the only .jsif there's just one.

require and module.exports

This is just basic JS you should know but. Inside the entry file, load a sibling with a relative path. require("./util.js") (or require("./util")) returns whatever that file assigned to module.exports. You can also set individual properties on exports.

// main.js  (folder entry point)
const messages = require("./messages.js");   // or "./messages"

on("chatReceive", (msg) => {
  if (msg === "!hi") player.sendMessage(messages.random());
});

// messages.js
const lines = ["hey", "yo", "hello"];

module.exports = {
  random: () => math.pick(lines),
};

Persistent store

Every script has its own small key/value store. It survives reloads and game restarts, so it's where you keep any state your script wants to remember.

The store API

script.get(key) returns the stored string or null if unset; script.getOr(key, fallback) returns the fallback instead of null. script.set(key, value) writes, script.has(key) checks existence, script.remove(key) deletes a key, and script.keys()lists every key you've stored.

script.set("greeting", "hello");
script.get("greeting");       // "hello"  (null if unset)
script.getOr("count", "0");   // fallback when the key is missing
script.has("greeting");       // true
script.keys();                // ["greeting"]
script.remove("greeting");

Values are strings

The store holds strings only, so encode anything else yourself. Parse a number back with parseInt / parseFloat, and turn an object into a string with JSON.stringify etc.

// keep a running counter across restarts
const n = parseInt(script.getOr("kills", "0"), 10) + 1;
script.set("kills", String(n));

// stash a small object as JSON (just an example, use the Settings instead section on that later)
script.set("cfg", JSON.stringify({ radius: 8, mode: "Fast" }));
const cfg = JSON.parse(script.getOr("cfg", "{}"));

Modules

module.create(config) builds a toggleable module that shows up in the client GUI under the Scripts category, exactly like a built-in feature. It returns a ModuleHandle you keep around to read the module's state and settings from your event hooks.

Module config

Pass a ModuleConfig object. Only name is required.

name is the display name and default setting id prefix. description is the tooltip shown on the card. category is any Polinex category such as "MINING" or "QOL", and defaults to "SCRIPTS" this only affects it once "Show in Main GUI" is on. subcategory groups the card within that well. subcategory. onEnable / onDisable run when the toggle flips. settings is an array of setting definitions (config objects) or builder-style ScriptSetting handles; see the settings section.

Module handle

module.create returns a ModuleHandle: enabled() reports whether the toggle is on, toggle(on) flips it from code, setting(id) reads a setting by id or name (or null when unknown), setSetting(id, value) writes one and returns false on a bad id or value, settings() lists every setting id, and addSettings(...) attaches more builder-style settings after creation.

Example

A module with settings that watches your purse and warns once when it drops below the threshold.

const mod = module.create({
    name: "Purse Alert",
    description: "Warns you when your purse drops below a threshold.",
    category: "QOL",              // also listed here once "Show in main GUI" is on
    subcategory: "Tracking",
    settings: [
        { type: "boolean", name: "Prefix",   default: true },
        { type: "slider",  name: "Threshold", min: 0, max: 1000000, default: 50000 },
    ],
    onEnable:  () => script.chat("Purse Alert on"),
    onDisable: () => script.chat("Purse Alert off"),
});

let warned = false;

on("tick", () => {   // only fires while the module toggle is on
    const low = skyblock.purse() < mod.setting("Threshold");
    const text = (mod.setting("Prefix") ? "[prefix] " : "") + "Purse is low!";
    if (low && !warned) {
        warned = true;
        script.chat(text);
    } else if (!low) {
        warned = false;
    }
});

module.export(mod);   // mark this as the main module that gates the hooks above

Macros

macro.create(config) builds a macro that shows up as a macro card under the Macros category, with a start/stop button and a keybind, grouped by the subcategory you give it. It returns a MacroHandle that drives everything below. The engine handles ticking, failsafes, the scheduler, the HUD, and stop/start for you.

The state machine

A macro is a state machine, and this is the core idea. You register a per-state handler with onState(name, fn), and the engine runs fn every client tick while the macro is in that state. You drive transitions with setState(name), and currentState() returns exactly the string you last set.

setState and onState accept any string. Built-in engine states like "TRAVEL", "MOVE", "ATTACK", "KILL", and "MINE" map to that native state and autocomplete in the editor through MacroState, but they are not a closed set. Any other name, such as "scanArea" or "moveToCrypt" yada yada becomes a custom state that works just the same. State names are matched case-insensitively!

m.onEnable(() => m.travelTo("DWARVEN_FORGE", 3000));     // -> TRAVEL state
m.onState("TRAVEL", () => { if (m.reachedDestination()) m.setState("mineVein"); });
m.onState("mineVein", () => { /* custom state, runs every tick */ });
m.hud(() => "State: " + m.currentState());

Macro config

Pass a MacroConfig: name (required), description, subcategory for grouping under the Macros category, and settings, an array of setting definitions or handles identical to a module's. Read and write(very not suggested) them at runtime with m.setting(id), m.setSetting(id, value), m.addSettings(...), and m.settings(). Call macro.export(m) to mark it as the script's main module as with the regular modules.

const m = macro.create({
    name: "lalala",
    subcategory: "Dwarven",
    settings: [
        { id: "oneTap", type: "boolean", name: "One Tap Mode", default: true },
    ],
});

// read and write settings at runtime by id
if (m.setting("oneTap")) { /* one-tap logic */ }
m.setSetting("oneTap", false);

macro.export(m);   // register this handle as the script's main module

Find and control registered macros

macro.list() returns the names of registered native and script macros. macro.get(name) looks up a name case-insensitively, and macro.active() returns the current session’s MacroRef or null. A reference exposes name(), state(), isPaused(), isRunning(), isBeta(), plus start(), stop(), and toggle(). A paused macro still owns the session, so active() can return it while isRunning() is false.

script.log("Macros: " + macro.list().join(", "));
const mining = macro.get("Gemstone Macro");
if (mining?.isBeta()) script.log(mining.name() + " is a beta macro");

// Starting/stopping is routed through the shared macro session.
const current = macro.active();
if (current?.name() === "My Script Macro") current.stop();

Built-in states and locations

A macro starts in NONE. The MacroState lists the engine's built-in states purely for autocomplete: NONE, TRAVEL, HELPER, RETURN, DEATH, MINE, MOVE, ATTACK, KILL, WALK, WAIT, and many more. its open, passing a name that isn't in it is fine and just makes a custom state you can use :).

The SkyblockLocation array is the set of places you can travel, reset, or warp to: "HUB", "DWARVEN_MINES", "DWARVEN_FORGE", "CRYSTAL_HOLLOWS", "GARDEN", "CRIMSON_ISLE", and so on. Unlike states, this array is strict: unknown location names are rejected at runtime for obvious reasons!

// setState takes a built-in name...
m.setState("MINE");        // maps to the MINE state
// ...or any string you like, that just becomes a custom state
m.setState("scanArea");    // custom, ticks exactly the same

// travelTo locations are strict: only SkyblockLocation names are accepted
m.travelTo("DWARVEN_FORGE", 3000);   // ok so a known Location
m.travelTo("MyBase", 3000);          // rejected at runtime as its not a Location

Lifecycle and HUD

onEnable(fn) runs when the macro starts (a good place to kick off a travelTo) or such and onDisable(fn) runs when it stops (clean up with nav.stop() and bot.stop() here). Register HUD lines with hud(fn). Each callback returns a string that the macro HUD renders, and you can add as many as you like.

// for example on start go to hub with a 1500ms timeout
m.onEnable(() => m.travelTo("HUB", 1500));

// clean up stuff
m.onDisable(() => { nav.stop(); bot.stop(); }); 

// each hud() callback returns a line the MacroHUD renders
m.hud(() => "State: " + m.currentState());
m.hud(() => "Kills: " + kills);

Travelling and resetting

travelTo(location, delayMs) warps and pathfinds to a SkyblockLocation and puts the macro into the TRAVEL state. reachedDestination() is true once you have arrived, and travelTarget() returns the current travel target as a string (handy for stuck-check fingerprints).

reset(location, resume) is your recovery lever: it warps back to a safe location and then calls your resume callback to put the macro back into a known state. Call it from stuck checks and from onDeath to get unstuck cleanly.

// travelTo warps + pathfinds, and drops the macro into the TRAVEL state
m.onEnable(() => m.travelTo("DWARVEN_FORGE", 3000));

// sit in TRAVEL until we arrive, then advance into our own state
m.onState("TRAVEL", () => {
    if (m.reachedDestination()) m.setState("mineVein");
});

// reset() is the recovery lever: warp somewhere safe, then resume a known state
function recover() { m.setState("mineVein"); }
m.onDeath(() => m.reset("DWARVEN_FORGE", recover));

Stuck checks

addStuckCheck(check) registers a active loop for a state. The StuckCheck object has:

name is a label for the check. state is which state it watches (built-in or custom). timeoutMs fires onStuck if progress() hasn't changed within this window. minimumStateMs (optional) is a grace period after entering the state before the check actually goes into effect. active (optional) is a predicate that gates the check, so it only runs while it returns true. progress is called to track progress, as long as its return value keeps changing you are considered to be making progress. onStuck is the recovery callback, usually an m.reset(...).

// fires onStuck if progress() HASN'T CHANGED within timeoutMs while in "MOVE"
m.addStuckCheck({
    name: "route",
    state: "MOVE",
    timeoutMs: 20000,
    minimumStateMs: 3000,                    // grace period before the check arms
    progress: () => routeIndex + ":" + nav.finished(),
    onStuck: () => m.reset("DWARVEN_FORGE", () => m.setState("MOVE")),
});

Resume hooks and interruptions

When something interrupts the macro, you get a chance to put it back on track. onHelperEnd(fn) fires after a helper finishes, onReturn(fn) after a return-warp interruption ends, and onDeath(fn) after a death. onResume(fn) is the general fallback that also fires after the macro resumes from a pause caused by breaks or failsafes.

function resume() { m.setState("mineVein"); }   // put the macro back on track

m.onHelperEnd(resume);                    // after a native helper (autoSell...) finishes
m.onReturn(resume);                       // after a return-warp interruption ends
m.onDeath(() => m.reset("HUB", resume));  // warp to hub, then resume
m.onResume(resume);                       // general fallback (after break/failsafe)

Helpers, combat bots, and failing

addHelper(helper, when, updateFrequent?) runs a side-task whenever when() is true; helper is a helper.create(...) handle of your own or a native helper name. The condition is checked during the macro's HELPER state, or every tick when updateFrequent is true (see helpers). createCombatBot(config) gives you the same combat engine our macros use (see combat bots). And fail(reason) stops the macro with an error message when something has gone unrecoverably wrong.

// run the native autoSell helper whenever the inventory is nearly full
m.addHelper("autoSell", () => player.getEmptyInventorySlots() <= 2);

// createCombatBot is the same targeting/attacking engine the built-in macros use
const bot = m.createCombatBot({
    areas: [[-36, 126, 129, 82, 152, 192]],
    names: ["Glacite Walker"],
    weapon: ["Drill", "Pickaxe"],
});

// fail() stops the macro with an error when something is unrecoverable
m.onEnable(() => {
    if (!skyblock.hasMiningTool()) m.fail("No drill/pickaxe found.");
});

Full example: Glacite Walker Macro

This is a script that mirrors the built-in Glacite Walker Macro, so it lands under the Macros category with its own start/stop button and keybind. It ties together everything above in one runnable file: a custom TRAVEL → MOVE → KILL flow, a createCombatBot that does the actual fighting, kill counting off the entityDeath event, three stuck checks that fingerprint progress and recover through reset, and clean start-up and tear-down. The inline comments explain why each piece is shaped the way it is, especially the bot.enabled guard that keeps KILL from restarting the bot every tick.

/// <reference path="../polinex.d.ts" />

const GLACITE_AREA = [-36, 126, 129, 82, 152, 192]; // minX,minY,minZ,maxX,maxY,maxZ
const ROUTE = [{ x: 0, y: 127, z: 137 }];

// Build the macro. The one boolean setting is exposed to the user and read later
// with m.setting("oneTap").
const m = macro.create({
    name: "Glacite Walker",
    description: "Walks the Glacite Tunnels and one-taps Glacite Walkers.",
    subcategory: "Dwarven",
    settings: [
        {
            id: "oneTap", type: "boolean", name: "One Tap Mode",
            description: "Only disable this if you can't one tap Glacite Walkers.", default: true,
        },
    ],
});

// The combat bot is the SAME targeting/attacking engine the built-in combat macros use.
// Here we only describe WHAT to hit — where, which entity types, by name, with which weapon —
// and later start() it. 
const bot = m.createCombatBot({
    areas: [GLACITE_AREA],
    entityTypes: ["RemotePlayer"],           // Glacite Walkers are player-type mobs
    names: ["Glacite Walker", "Ice Walker"],
    weapon: ["Drill", "Pickaxe"],            // equipped automatically before attacking
});

let kills = 0;
let routeIndex = 0;

// Two HUD lines
m.hud(() => "Macro State: " + m.currentState());
m.hud(() => "Glacite Walkers Killed: " + kills);

// onEnable runs once when the macro starts. Fail loudly if we have no mining tool otherwise
// jump straight into combat if we're already there, or travel to the forge + follow path first.
m.onEnable(() => {
    skyblock.findMiningTools();
    if (!skyblock.hasMiningTool()) { m.fail("No drill/pickaxe found."); return; }
    if (skyblock.location() === "DWARVEN_MINES" && skyblock.inArea(GLACITE_AREA)) beginCombat();
    else m.travelTo("DWARVEN_FORGE", 3000);  // -> puts the macro into the TRAVEL state
});

// The custom-state flow is TRAVEL -> MOVE -> KILL. Each onState handler runs every tick while
// the macro sits in that state; we advance by calling setState (via the two helpers below).

// TRAVEL: travelTo already warps and pathfinds for us, so we just wait for arrival, then walk.
m.onState("TRAVEL", () => {
    if (m.reachedDestination()) startMove();
});

// MOVE: walk the route one waypoint at a time. nav.finished() is the "am I idle?" check —
// arrive within 1.5 blocks to advance the index, otherwise (re)issue the walk.
m.onState("MOVE", () => {
    if (routeIndex >= ROUTE.length) { beginCombat(); return; }
    const wp = ROUTE[routeIndex];
    if (nav.failed()) { m.fail("Walking to the waypoint failed"); return; }
    if (nav.finished() && player.distanceFlat(wp) < 1.5) routeIndex++;
    else if (nav.finished()) nav.walkTo(wp);
});

// KILL: start the bot ONCE and let it run itself. bot.enabled is the guard without it we would
// call start() again every single tick. We push the live setting onto the bot right before starting.
m.onState("KILL", () => {
    if (!bot.enabled) {
        bot.oneTap = m.setting("oneTap");
        bot.allowSneaking = false;
        if (!bot.start()) m.fail("Combat bot failed to start.");
    }
});

// tiny transition helpers so the state names live in exactly one place.
function startMove() { routeIndex = 0; m.setState("MOVE"); }
function beginCombat() { m.setState("KILL"); }

// count kills from the global entityDeath event
on("entityDeath", (e) => {
    if ((e.name.includes("Glacite Walker") || e.name.includes("Ice Walker")) &&
        player.distance(e.pos) < 8) {
        kills++;
    }
});

// reset() warps back to the forge, then re-runs startMove to re-enter a known state.
const resetToForge = () => m.reset("DWARVEN_FORGE", startMove);

// stuck checks
m.addStuckCheck({ name: "travel", state: "TRAVEL", timeoutMs: 18000,
    progress: () => m.travelTarget() + ":" + skyblock.location(), onStuck: resetToForge });
m.addStuckCheck({ name: "route", state: "MOVE", timeoutMs: 20000,
    progress: () => routeIndex + ":" + nav.finished(), onStuck: resetToForge });
m.addStuckCheck({ name: "combat", state: "KILL", timeoutMs: 60000,
    active: () => bot.enabled, progress: () => kills + ":" + bot.snapshot(), onStuck: resetToForge });

// always clean up whatever you started, stop the bot and nav.
m.onDisable(() => { bot.stop(); nav.stop(); });

macro.export(m);

Combat bots

macro.createCombatBot(config)gives you the same targeting and attacking engine the built-in macros use. It returns a CombatBot you configure and start from inside a macro's onState, so the bot handles combat while your macro does everything around it.

Combat bot config

Pass a CombatBotConfig. Only areas is required.

areas is a list of [minX, minY, minZ, maxX, maxY, maxZ] boxes the bot hunts inside. entityTypes lists the entity class names to target, e.g. ["RemotePlayer", "ArmorStand"]. names sets name filters for valid targets. weapon is an item-name priority list for the weapon slot. ignoreAreas lists boxes never to target inside. ignoreOneTap lists names excluded from one-tap behaviour. ignoreCompletely lists names never targeted at all.

Combat bot handle

The returned CombatBot exposes: oneTap toggles one-tap behaviour, allowSneaking lets it sneak, enabled is a read-only flag for whether it is running, start() begins the bot and returns false if it couldn't start, stop() halts it, and snapshot() returns a debug string of its current state, perfect for stuck-check progress()

Mining bots

mining.bot(type) hands you the same mining engine the built-in mining macros run. It returns a MiningBot you start from inside a macro's onState, so the bot mines while your macro does everything around it.

Bot types

Self-driving bots: "mithril", "gemstone", "ore", "oreV2", "tunnel". Route bots: "cobblestone", "crimson", "endstone", "sand", "obsidian". An unknown type throws. mining.botTypes() lists them all.

Starting and the handle

Self-driving bots take a start position: start({ x, y, z }), or start() to use the block you're standing on. Route bots take start({ waypoints }), an array of {x,y,z} or [x,y,z] points that become MINE waypoints. The handle exposes enabled, finished, start(opts) and stop().

const bot = mining.bot("mithril");

macro.onState("MINE", () => {
  if (bot.enabled) return;
  if (bot.finished) return macro.setState("DONE");
  bot.start();
});

macro.onDisable(() => bot.stop());

Helpers

A helper is a side-task that runs alongside a macro: sell a full inventory, take a scheduled break, refuel, warp to safety. Each one has a lifecycle (start when it activates, tick every client tick while it runs, stop when it ends) plus a when() condition that decides when it should fire. There are three ways to get one going.

helper.register: a toggleable helper (recommended)

helper.register(config) is the recommended path for a standalone helper. It drops a first-class toggle card into the Scripts GUI, right beside the cards module.create and macro.create make. Flip it on and the helper runs globally on its own, it polls its when() on the client tick and activates during any active macro. You don't author a macro or module to host it. The toggle is the whole feature, and its on/off state config-persists like any module.

HelperModuleConfig fields: name (required, the card's display name), description, subcategory (grouping header, default "Helpers") and category (where it lands when its injected "Show in main GUI" row is on). when / shouldActivate is required. Skip it and the card just warns and never fires. The lifecycle callbacks each accept aliases: start/onStart, tick/onTick, stop/onStop. The h they receive is the run handle, not the module. updateFrequent polls when every tick instead of ~once a second. onEnable/onDisable fire when the toggle itself flips (distinct from a run's start/stop; disabling also force-ends any live run), and settings attaches setting rows to the card.

The returned HelperModule handle lets you drive the card from code: enabled() / toggle(on) read and flip the toggle, running() reports whether a run is live, finish() ends the current run early (the toggle stays on and can fire again), and setting(id) / setSetting(id, value) / settings() / addSettings(...) read, write, list, and attach its settings.

const LOW_HP = 5;
const COOLDOWN_MS = 8000;
const WARP_TIMEOUT_MS = 5000;
let cooldownUntil = 0;
let warpDeadline = 0;

helper.register({
  name: "Low HP Warp",
  description: "Warp to the hub when your health gets dangerously low.",
  subcategory: "Safety",

  // polled while the toggle is on to decide when to run
  when: () => client.isInSkyblock()
    && player.isAlive()
    && player.health() <= LOW_HP
    && Date.now() >= cooldownUntil,
  updateFrequent: true,            // a health drop is time-critical but if using updateFrequent keep it a cheap check

  // a run begins. `h` is the RUN handle (finish/running/travelTo/...), not the toggle.
  start: (h) => {
    warpDeadline = Date.now() + WARP_TIMEOUT_MS;
    player.stopAllMovement();
    player.sendCommand("warp hub");
    script.info("Low HP Warp: warping to hub.");
  },

  // every tick while the run is active. end it once we're safe, or on the timeout.
  tick: (h) => {
    if (skyblock.inLocation("HUB") || Date.now() >= warpDeadline) h.finish();
  },

  // always runs when a run ends. arm the cooldown so we don't loop-warp.
  stop: (h) => { cooldownUntil = Date.now() + COOLDOWN_MS; },
});

helper.create + registerGlobal: a global helper object

helper.create(config) builds a helper object but doesn't wire it up on its own. Call registerGlobal() on the returned handle to make it fire globally during any active macro for as long as the script is loaded. No toggle card, just an always-registered helper. This requires a when set in the config, since that's what decides when it activates. The config accepts the same lifecycle (start/tick/stop) and updateFrequent as above. Because a global helper can re-fire the instant when is true again, gate it behind a cooldown so it doesn't tweak.

const PANIC_MS = 1500;
const COOLDOWN_MS = 5000;
let panicUntil = 0;
let cooldownUntil = 0;

// this is lowk AI'd i ran out of ideas LOL
// helper.create does nothing until you register it.
const firePanic = helper.create({
  name: "Fire Panic",
  when: () => player.isAlive() && player.burning() && Date.now() >= cooldownUntil,
  start: (h) => {
    panicUntil = Date.now() + PANIC_MS;
    player.stopAllMovement();
    player.setKey("sneak", true);
  },
  tick: (h) => {
    if (Date.now() >= panicUntil || !player.burning()) h.finish();
  },
  stop: (h) => {
    player.setKey("sneak", false);
    player.resetWASD();
    cooldownUntil = Date.now() + COOLDOWN_MS;
  },
});

firePanic.registerGlobal();  // needs `when` set above; runs during any macro while the script is loaded

macro.addHelper & helper.useNative: attach a helper

macro.addHelper(handle, when) attaches a helper to one macro. It runs only while that macro is running, whenever when() holds. The handle can be your own helper.create(...) object or a built-in helper referenced by name.

helper.useNative(name, when) drives one of the client's built-in helpers globally on your own trigger: it activates during any active macro whenever when() is true. The valid HelperName values are autoSell, scheduler, autoReconnect, interruptionFixer, playerNotifier, autoRefuel, autoForge, and slayerStarter. Both macro.addHelper and helper.useNative take an optional trailing updateFrequent to poll every tick. A script's global helpers (from register, registerGlobal, and useNative) are all removed automatically when the script unloads.

// Custom helper tied to ONE macro — runs only while that macro runs.
const restock = helper.create({
  name: "Restock",
  start: (h) => h.travelTo("HUB", 2000),
  tick:  (h) => { if (h.reachedLocation()) { buyStuff(); h.finish(); } },
});
mac.addHelper(restock, () => myItem.value < 10);

// Or drive one of the client's built-in helpers globally on your own trigger.
helper.useNative("autoSell", () => player.getEmptyInventorySlots() === 0);

player

Read and control your own player, including position, motion, rotation, keys/clicks, inventory, and live state.

world

Query the world around you, including block ids, light, biomes, line-of-sight raytraces, surface sample points, and geometry helpers. Positions in / out are Vec. See World snapshots for saved captures and recorders.

const { x, y, z } = player.blockPos();
const state = world.blockState({ x, y, z });
if (state !== null) {
  script.log(state.id);
  script.log(JSON.stringify(state.properties));
}

World snapshots

The world namespace can capture or load snapshots for offline queries. Snapshots do not replace the live native pathfinding cache. Missing data is UNKNOWN, not a promise that a block is air.

Capture callbacks may originate from a worker. Schedule gameplay actions with setTimeout rather than starting movement from a capture callback. Saving on unload is attempted for an active recorder, but explicit module cleanup is clearer.

Example: record and save while enabled

const mod = module.create({ name: "Record nearby world" });
const snapshot = world.loadOrBlank("local-walk", {
  name: "local-walk", minY: -64, maxY: 320, blocks: true,
});
on("enable", () => snapshot.record(2, 30));
on("disable", () => snapshot.stopRecording(true));
module.export(mod);
// snapshot.code(x,y,z) reads the capture, not the live world.
// snapshot.save(error => script.log(error || "Saved"));

scan

Background block scanning with declarative block IDs. JavaScript predicates do not run on scanner worker threads. Results are cached and may lag world changes.

Example: react to changed scan results

const mod = module.create({ name: "Nearby diamond blocks" });
const scanner = scan.create({ name: "diamonds", blocks: ["minecraft:diamond_ore"], range: 2, height: 32 });
let version = -1;
on("enable", () => { version = -1; scanner.start(); });
on("disable", () => scanner.stop());
on("tick", () => {
  const current = scanner.version();
  if (current === version) return;
  version = current;
  script.log("Cached blocks: " + scanner.count());
  const nearest = scanner.nearest(player.pos());
  if (nearest) script.log(nearest.block + " at " + nearest.x + ", " + nearest.y + ", " + nearest.z);
});
module.export(mod);

gui

Create script-owned panels and HUD elements using the existing render namespace. UI objects are disposed on script unload. Manage visibility explicitly for module toggles.

Example: a navigation HUD

const mod = module.create({ name: "Navigation status HUD" });
const hud = gui.hud({
  id: "navigation", width: 220, height: 24,
  onDraw: () => {
    const text = nav.awaitingPath() ? "Planning…" : "Nodes left: " + nav.remainingNodes();
    render.drawText(text, 0, 0, "BODY_MEDIUM", 0xffffffff);
  },
});
on("enable", () => hud.show());
on("disable", () => hud.hide());
module.export(mod);

entity

Find and inspect nearby entities. Every result is an Entity ({ id, name, type, x, y, z, dist, yaw, pitch, headYaw, player, health, maxHealth, customName, nametagLines, equipment }), and lists come back nearest-first. Reading yaw/pitch/headYaw from a tick handler is the recommended way to watch another player's look (your own look is player.yaw()/player.pitch()).

for (const mob of Array.from(entity.near(24))) {
  if (mob.health !== null) {
    script.log(mob.type + " health=" + mob.health + "/" + mob.maxHealth);
  }
}

for (const stand of Array.from(entity.armorStands(24))) {
  if (stand.customName) script.log("Armor stand: " + stand.customName);
}

nav

Walking and path queries use support-block coordinates. A PathNode also contains its precise standing point. Start movement and submit async queries from tick or script timers.

See Path queries for handle states, cancellation, and world-change behavior. Do not restart walkTo or followPath every tick. Native macros still share player keys and rotation; avoid running competing movement.

Example: plan once, then walk

// Replace this with a support block in your current area before enabling.
const goal = { x: 0, y: 70, z: 0 };
const mod = module.create({ name: "Plan then walk" });
let query = null;
let walking = false;
let done = false;

function stop() {
  if (query) query.cancel();
  query = null;
  nav.stop();
  walking = false;
  done = true;
}
on("enable", () => { stop(); done = false; });
on("disable", stop);
on("worldLoad", stop);
on("serverDisconnect", stop);
on("tick", () => {
  if (done) return;
  if (!query && !walking) {
    query = nav.findPathAsync(null, goal, { allowEtherwarp: false });
  }
  if (query) {
    if (!query.finished()) return;
    const status = query.status();
    const nodes = query.result();
    const reason = query.error();
    query = null;
    if (status !== "found" || !nodes || !nav.followPath(nodes)) {
      script.warn("Could not start walk: " + status + " " + (reason || ""));
      done = true;
      return;
    }
    walking = true;
  }
  if (nav.failed()) {
    script.warn("Walk failed");
    stop();
  } else if (walking && nav.finished()) {
    script.log("Walk ended; distance to goal: " + player.distanceFlat(goal));
    stop();
  }
});
module.export(mod);

Example: choose by travel cost

// Call from tick with a known support block and candidate support blocks.
function cheapestReachable(from, targets) {
  const costs = nav.distances(from, targets, 200);
  if (costs === null) return null; // native/cache unavailable
  let best = -1;
  for (let i = 0; i < costs.length; i++) {
    if (costs[i] >= 0 && (best < 0 || costs[i] < costs[best])) best = i;
  }
  return best < 0 ? null : { target: targets[best], cost: costs[best] };
}

routes

Read existing route managers, or create a script-owned route editor with its own route folder. Existing manager reads do not change selection or files. IDs come from routes.managers(); names and folder paths are relative to that manager.

Example: discover managers and routes

// Run once to discover the exact manager IDs and folders.
for (const manager of Array.from(routes.managers())) {
  script.log(manager.id + ": " + manager.name);
  script.log("Files: " + Array.from(routes.list(manager.id)).join(", "));
  script.log("Folders: " + Array.from(routes.folders(manager.id)).join(", "));
}

Example: create and edit a script route

A script-owned editor keeps its files separate from built-in route managers. Add custom waypoint names when creating it; the native picker stores those names unchanged, and the script decides what they mean. Open editor.edit only while the attached macro is disabled.

const editor = routes.createEditor({
  id: "leave_return",
  name: "Leave and return route",
  waypointTypes: ["WALK", "WARP", "AREA", "STOP"],
});

const m = macro.create({
  name: "Leave and return route",
  description: "Runs a script-owned route with AREA and STOP markers.",
  settings: editor.settings,
});
macro.export(m);

// Run once during setup while the macro is disabled.
if (editor.create("mine_route")) editor.edit("mine_route");

// These are custom names: the native editor preserves them, but only this
// script assigns their behavior.
function handleRouteMarker(point) {
  if (point.type === "AREA") {
    const returnAnchor = point; // leave the route for work, then walk back here
    startAreaTask(() => nav.walkTo(returnAnchor));
  } else if (point.type === "STOP") {
    nav.stop();
    etherwarp.stop();
    const active = macro.active();
    if (active?.name() === m.name()) active.stop();
  }
}

The next example executes only WALK and WARP on the saved main path. It intentionally rejects other actions and raw grotto templates. For a currently selected, resolved route, read routes.selected(id).route in tick and interpret its runtime waypoints instead.

Example: execute saved travel waypoints

// Set Manager and Route before enabling. Route is relative, e.g. folder/name.
const mod = module.create({
  name: "Saved travel route",
  settings: [
    { type: "string", name: "Manager", default: "" },
    { type: "string", name: "Route", default: "" },
    { type: "boolean", name: "Blatant", default: false },
    { type: "slider", name: "Budget", min: 1, max: 2000, default: 150, increment: 1 },
  ],
});
let points = null;
let index = 0;
let walking = false;
let done = false;
function stop() {
  nav.stop();
  etherwarp.stop();
  points = null;
  walking = false;
  done = true;
}
on("enable", () => { stop(); index = 0; done = false; });
on("disable", stop);
on("worldLoad", stop);
on("serverDisconnect", stop);
on("tick", () => {
  if (done) return;
  if (!points) {
    const id = String(mod.setting("Manager") ?? "");
    const name = String(mod.setting("Route") ?? "");
    if (!id || !name) { script.warn("Set Manager and Route first"); stop(); return; }
    let saved;
    try { saved = routes.load(id, name); }
    catch (error) { script.warn(String(error)); stop(); return; }
    if (!saved || saved.grotto) {
      script.warn("Missing route or relative grotto template"); stop(); return;
    }
    points = Array.from(saved.waypoints);
    if (points.some(p => p.type !== "WALK" && p.type !== "WARP")) {
      script.warn("This example only executes WALK and WARP"); stop(); return;
    }
    // Deliberately follows the saved main path; it does not choose branches.
  }
  if (index >= points.length) { script.log("Route finished"); stop(); return; }
  const point = points[index];
  if (point.type === "WALK") {
    if (!walking) {
      if (!nav.walkTo(point)) { script.warn("Walk rejected"); stop(); return; }
      walking = true;
    }
    if (nav.failed()) { script.warn("Walk failed"); stop(); return; }
    if (nav.finished()) {
      if (!world.isOnBlock(world.topCenter(point), 1.5)) {
        script.warn("Walk ended away from waypoint"); stop(); return;
      }
      walking = false;
      index++;
    }
  } else {
    const arrived = etherwarp.pathfindTo(point.x, point.y, point.z, {
      blatant: mod.setting("Blatant") === true, budgetMs: Number(mod.setting("Budget")),
    });
    if (arrived) index++;
    else if (etherwarp.failed()) { script.warn("Warp failed"); stop(); }
  }
});
module.export(mod);

skyblock

The skyblock namespace surfaces live Hypixel SkyBlock state: where you are, what you're holding, your economy, the scoreboard and tab list, buffs, and session skill XP.

Use chStructures() to consume scanner results without triggering a scan. If a structure is not currently detected, it will not appear in this snapshot.

// Call on the client thread, for example from tick.
for (const structure of skyblock.chStructures()) {
  script.log(structure.name, structure.pos.x, structure.pos.y, structure.pos.z);
  if (structure.bounds) {
    const [minX, minY, minZ, maxX, maxY, maxZ] = structure.bounds;
    // Bounds describe the no-bomb zone, not the structure's footprint.
  }
}

mining

The mining namespace drives the native mining bots, exposes the low-level toolkit those bots are built from (scanning, reach, ability control, stand-spot search), and reads live mining state (fuel, heat, powder, ability, counters).

combat

The combat aim engine (humanized melee rotation): aim at a point (e.g. entity.aimPointOn) then leftClick. Call track each tick to follow a moving mob.

etherwarp

Warp onto a support block using the configured handler or blatant follower. Travel methods must be called each tick until they return true or failed() becomes true. Pure planning never starts movement.

Budgets cover native search time, not worker queues, mutex waits, retries, or total travel duration. Null native output cannot distinguish budget exhaustion/no route from an internal native failure. No new native entry point is required.

Example: configurable blatant travel

// Replace this support block before enabling.
const goal = { x: 0, y: 70, z: 0 };
const mod = module.create({
  name: "Blatant travel",
  settings: [{ type: "slider", name: "Budget", min: 1, max: 2000,
               default: 150, increment: 1 }],
});
let done = false;
function stop() { etherwarp.stop(); done = true; }
on("enable", () => { stop(); done = false; });
on("disable", stop);
on("worldLoad", stop);
on("serverDisconnect", stop);
on("tick", () => {
  if (done) return;
  const arrived = etherwarp.blatantTo(goal.x, goal.y, goal.z, {
    budgetMs: Number(mod.setting("Budget")),
  });
  if (arrived) {
    script.log("Arrived");
    done = true;
  } else if (etherwarp.failed()) {
    script.warn("Travel failed; toggle off/on to retry");
    done = true;
  }
});
module.export(mod);

esp

World box ESP (the same renderer the macros use). One verb per effect; colors are ARGB ints. The per-frame verbs draw for a single frame (call them from a tick / render3d hook); the keep* / remove verbs are persistent across frames.

render

2D / HUD drawing backed by NanoVG. Call these from a render or HUD hook. Coordinates are in GUI-scaled pixels and colors are ARGB ints (createColor packs them).

World-space example

World-space methods are available only inside worldRenderLast; calling them from tick, render2d, or render3d throws. Coordinates must be finite and within ±30,000,000, colors are signed or unsigned 32-bit ARGB values, and at most 256 draw operations are accepted per callback. The frame scope clears after each callback, so these methods do not keep persistent render objects.

on("worldRenderLast", () => {
  render.worldText("Target", target.x, target.y + 1, target.z, 0xFFFFAA00, 16);
  render.worldLine(player.x(), player.y() + 1, player.z(), target.x, target.y, target.z, 0xFF55CCFF, 2, true);
  render.worldTracer(target.x, target.y, target.z, 0xFFFF5555);
  render.worldBeam(target.x, target.y, target.z, 0xFF55AAFF);
});

rotation

The rotation namespace exposes the four rotation engines (general / mining / etherwarp / pathfind) plus planning helpers: lookTo returns an absolute {yaw,pitch}, changeTo returns the signed delta {yaw,pitch}, and distanceTo returns a scalar.

math

JS's built-in Math is available too; this namespace adds randomness helpers and a few numeric utilities that Math lacks.

util

Miscellaneous helpers: a pausable stopwatch, number and duration formatting, color stripping, and OS-level notifications.

inventory

Open-container automation. The usual flow: open a menu (entity.interact or use an item), read openItems(), clickSlot(...), then close().

for (const item of Array.from(inventory.items())) {
  const data = inventory.itemData(item.slot);
  script.log(item.name + " x" + item.count);
  if (data?.ExtraAttributes) {
    script.log(JSON.stringify(data.ExtraAttributes));
  }
}

client

Client-level state: framerate, smoothed server TPS, raw mouse / keyboard, the player’s saved key mappings, the current server, and Skyblock location checks.

keybind

Create script-owned keyboard and mouse bindings without registering vanilla KeyMappings. A binding stays with its script and is removed when that script unloads.

Call create and setKey on the client thread.

Pass a GLFW keyboard code from 32 through 348, or a mouse button code from 1 through 7. Code 0 means unbound, so the left mouse button (button code 0) cannot be assigned through this API. The callback runs once on a press; repeats are ignored.

const pingKey = keybind.create("ping", 66, () => {
  script.chat("B pressed");
});

pingKey.key();       // 66
pingKey.isDown();    // currently held?
pingKey.setKey(0);   // unbind
pingKey.setKey(66);
pingKey.remove();

notification

In-client toast notifications. Use push with a style constant for full control, or one of the convenience methods for a preset style.

action

A read-only constants proxy of raw protocol action ids (numbers). Pass or compare these where a low-level packet / interaction helper expects an action id.

script

Per-script logging, scoped JSON reads, a persistent key/value store, and tick-based timers. Terse reference below. The narrative guides (logging, persistent store, timing) live under Core Concepts.

const settings = script.readJson("settings.json") ?? {};
const radius = settings.radius ?? 6;
script.log("Using scan radius " + radius);

Packets

Register a handler with on("packetReceive", handler) or on("packetSend", handler) to see raw protocol traffic before the client (or server) acts on it. Both hooks hand you a single ScriptPacketEvent: read its stable name, pull curated fields out of data(), and optionally cancel() the packet. See the Events section for how hooks are gated by your module.

The ScriptPacketEvent

Every packetReceive / packetSend handler (and the second argument to chatReceive / chatSend) receives this object:

on("packetReceive", (e) => {
  // compare the STABLE name to packet.* constants — never e.type
  if (e.name === packet.CLIENTBOUND_SET_HEALTH) {
    const d = e.data();            // { health, food, saturation }
    script.log("health " + d.health + " / food " + d.food);
    return;
  }

  if (e.name === packet.CLIENTBOUND_SOUND) {
    const d = e.data();            // { sound, source, x, y, z, volume, pitch }
    if (d.sound === "minecraft:block.note_block.pling") {
      e.cancel();                  // stop it before the client plays it
    }
  }
});

// outgoing packets work exactly the same on packetSend
on("packetSend", (e) => {
  if (e.name === packet.SERVERBOUND_SWING) script.debug("swing");
});

The packet.* constants

packet is a read-only object holding a constant for every packet in the modern protocol, all clientbound and serverbound, roughly 229 of them. It also carries a set of 1.8-era name aliases (for example C03PacketPlayer and S2FPacketSetSlot) that map one-to-one onto their modern equivalents, for about 264 constants in all. Each value equals the matching event.name. You do not need to memorize them. The script editor autocompletes the full list as you type packet.. A representative slice:

packet.CLIENTBOUND_SYSTEM_CHAT
packet.CLIENTBOUND_SET_HEALTH
packet.CLIENTBOUND_SOUND
packet.CLIENTBOUND_CONTAINER_SET_SLOT
packet.CLIENTBOUND_OPEN_SCREEN
packet.CLIENTBOUND_DISCONNECT
packet.CLIENTBOUND_ADD_ENTITY
packet.CLIENTBOUND_BLOCK_UPDATE

packet.SERVERBOUND_SWING
packet.SERVERBOUND_USE_ITEM
packet.SERVERBOUND_PLAYER_ACTION
packet.SERVERBOUND_CONTAINER_CLICK

// 1.8-era aliases — same value as the modern name
packet.C03PacketPlayer
packet.S2FPacketSetSlot

Packet delivery: three tiers

Not every packet reaches packetReceive. The receive hook runs synchronously on the network thread, so the very high-rate types are held back. Delivery falls into three tiers.

data() shapes: clientbound

Roughly three dozen high-value packets have curated extractors. Calling data() on any other packet returns an empty object {}, so guard on the fields you expect. Incoming packets:

CLIENTBOUND_SYSTEM_CHAT            { text, overlay }
CLIENTBOUND_PLAYER_CHAT            { sender, text }                      // sender = UUID string
CLIENTBOUND_SET_HEALTH            { health, food, saturation }
CLIENTBOUND_SET_EXPERIENCE        { progress, level, total }
CLIENTBOUND_SET_ENTITY_MOTION     { id, x, y, z }                       // own player = default; OTHER entities = auto-detect (reference packet.CLIENTBOUND_SET_ENTITY_MOTION)
CLIENTBOUND_TELEPORT_ENTITY       { id, x, y, z, yaw, pitch, onGround }  // default-delivered
CLIENTBOUND_ENTITY_POSITION_SYNC  { id, x, y, z, yaw, pitch, onGround }  // auto-detect (reference packet.CLIENTBOUND_ENTITY_POSITION_SYNC)
CLIENTBOUND_PLAYER_POSITION       { id, x, y, z, yaw, pitch }            // your own absolute position — default-delivered
CLIENTBOUND_ADD_ENTITY            { id, type, x, y, z }                  // default-delivered; type = "minecraft:zombie"
CLIENTBOUND_REMOVE_ENTITIES       { ids }                               // default-delivered; ids: number[]
CLIENTBOUND_UPDATE_MOB_EFFECT     { id, effect, amplifier, duration }   // effect = "minecraft:speed"
CLIENTBOUND_REMOVE_MOB_EFFECT     { id, effect }
CLIENTBOUND_SET_EQUIPMENT         { id, slots }                         // default-delivered; slots: {slot, item:{name,id,count}|null}[]
CLIENTBOUND_UPDATE_ATTRIBUTES     { id, count }                         // default-delivered
CLIENTBOUND_DAMAGE_EVENT          { id, sourceType }
CLIENTBOUND_RESPAWN               { dimension }
CLIENTBOUND_GAME_EVENT            { event, param }                      // event = "START_RAINING" / "UNKNOWN"
CLIENTBOUND_SET_TITLE_TEXT        { text }
CLIENTBOUND_SET_SUBTITLE_TEXT     { text }
CLIENTBOUND_SET_ACTION_BAR_TEXT   { text }
CLIENTBOUND_BOSS_EVENT            { operation }                         // ADD / REMOVE / UPDATE_PROGRESS / ...
CLIENTBOUND_PLAYER_INFO_UPDATE    { count }
CLIENTBOUND_SET_OBJECTIVE         { name, displayName }
CLIENTBOUND_SET_SCORE             { owner, objective, value }
CLIENTBOUND_SET_DISPLAY_OBJECTIVE { slot, objective }
CLIENTBOUND_BLOCK_UPDATE          { x, y, z, block }                    // default-delivered; block = "minecraft:stone"
CLIENTBOUND_SOUND                 { sound, source, x, y, z, volume, pitch }
CLIENTBOUND_CONTAINER_SET_SLOT    { containerId, slot, stateId, item }  // item: {name,id,count} | null
CLIENTBOUND_OPEN_SCREEN           { containerId, menuType, title, titleFormatted }
CLIENTBOUND_CONTAINER_CLOSE       { containerId }
CLIENTBOUND_DISCONNECT            { reason, reasonFormatted }

data() shapes: serverbound

Outgoing packets you can read (and cancel) on packetSend:

SERVERBOUND_SWING            { hand }                          // "MAIN_HAND" / "OFF_HAND"
SERVERBOUND_USE_ITEM         { hand }
SERVERBOUND_PLAYER_ACTION    { action, x, y, z, direction }
SERVERBOUND_CHAT             { message }
SERVERBOUND_CHAT_COMMAND     { command }
SERVERBOUND_CONTAINER_CLICK  { containerId, slot, button }
SERVERBOUND_SET_CARRIED_ITEM { slot }

Cancel a packet inside its handler, before it continues. See Synchronous cancellation for an example and how to schedule follow-up work on the client thread.

Settings

Modules, macros, and helpers all take the same settings: [...]array on their config object. Each entry uses one of the client's own setting types, so a script's settings look and behave exactly like the ones the client ships with.

There are two ways to author an entry, and you can mix them freely in the same array: config objects (a plain { type, name, ... } literal) and builder constructors (SliderSetting(...), BooleanSetting(...), …) that return a live handle you can read and write from anywhere.

Config-object settings

Every entry shares a small base: a required name, an optional id (defaults to name, which is the key you read and write by), an optional description, and an optional visible (alias shouldRender) predicate that hides the row when it returns false. The remaining keys depend on the type.

const h = module.create({
  name: "Demo",
  category: "QOL",
  settings: [
    { type: "boolean",       name: "Enabled",   default: true,
        onChange: (v) => script.log("enabled = " + v) },
    { type: "slider",        name: "Radius",    min: 1, max: 20, default: 8, increment: 1,
        onChange: (v) => {} },
    { type: "decimalSlider", name: "Speed",     min: 0, max: 1,  default: 0.5, increment: 0.05 },
    { type: "plusMinus",     name: "Count",     min: 0, max: 9,  default: 3 },
    { type: "range",         name: "Levels",    min: 0, max: 100, defaultMin: 10, defaultMax: 60,
        onChange: (lo, hi) => {} },
    { type: "decimalRange",  name: "Window",    min: 0, max: 5,   defaultMin: 0.5, defaultMax: 2.5 },
    { type: "dropdown",      name: "Mode",      options: ["Fast", "Safe"], default: "Safe",
        onChange: (opt, idx) => {} },
    { type: "color",         name: "Highlight", default: 0xFF00FFAA, allowAlpha: true },  // 0xAARRGGBB
    { type: "string",        name: "Label",     default: "hi",
        onChange: (text) => {} },
    { type: "button",        name: "Reset",     buttonText: "Reset Now", onClick: () => doReset() },
    { type: "multiBool",     name: "Filters",   options: ["Ore", "Gem"], defaults: [true, false],
        onChange: (opt, on) => {} },
  ],
});

Builder-style settings

Each type also has a global constructor (the same names the client uses internally). The first two arguments are always the display name and description; the name doubles as the id. Each returns a ScriptSetting handle with a read/write .value and a chainable .onChange(fn). Pass the handles straight into settings: [...] (mixed with config objects) or attach them later with addSettings(...).

const interval    = SliderSetting("Interval (s)", "How often to check", 1, 30, 5);
const onlyChanges = BooleanSetting("Only On Change", "Only report changed values", true);
onlyChanges.onChange(v => script.log("now " + v));   // chainable change hook

const mod = module.create({ name: "Purse Tracker", settings: [interval, onlyChanges] });

// attach more after creation (works on module / macro / helper handles):
const mode = DropdownSetting("Mode", "How the tracker runs", ["Fast", "Safe"], "Safe");
mod.addSettings(mode);

on("tick", () => {
  if (interval.value >= 5) onlyChanges.value = false;   // read AND write via .value
});

Setting types

Every type, with its constructor signature, the extra keys its config object accepts (defaults in parentheses), and its onChange signature.

color and button are native final types: they are always shown, so their visible / shouldRender (and builder visibleWhen / dependsOn) predicates are ignored.

The setting handle & runtime access

A builder constructor returns a ScriptSetting handle you can hold onto and read or write live. Separately, the handle returned by module.create / macro.create / helper.register lets you reach any setting (config-object or builder) by its id.

const h = module.create({ name: "Demo", settings: [
  { id: "radius", type: "slider",   name: "Radius", min: 1, max: 20, default: 8 },
  { id: "mode",   type: "dropdown", name: "Mode",   options: ["Fast", "Safe"] },
]});

h.setting("radius");          // -> 8 (current value)
h.setSetting("radius", 12);   // set it; runs the setting's normal onChange
h.setSetting("mode", "Fast"); // dropdown accepts an option string or an index
h.settings();                 // -> ["radius", "mode"]

Conditional visibility

A setting can hide its row until a condition holds. The predicate is re-checked every frame while the GUI is open, so keep it cheap, just read another setting. Builder handles offer three chainable options: .visibleWhen(fn) (any predicate), .dependsOn(other) (visible while other is truthy) or .dependsOn(other, value) (visible only when it equals value), and .if(condition) which accepts another setting, a () => boolean, or a plain boolean.

const advanced = BooleanSetting("Advanced", "Show extra controls", false);
const tuning   = SliderSetting("Tuning", "Advanced tuning amount", 0, 10, 5).dependsOn(advanced);

const mode  = DropdownSetting("Mode", "Execution mode", ["Fast", "Safe"], "Safe");
const speed = DecimalSliderSetting("Speed", "Fast-mode speed", 0, 1, 0.5).dependsOn(mode, "Fast");

const fancy = BooleanSetting("Fancy", "Fancy look", false);
const color = ColorSetting("Color", "Highlight", 0x55FFFFFF).visibleWhen(() => fancy.value);
// .if(fancy) would do the same as .visibleWhen(() => fancy.value)

module.create({ name: "Demo", settings: [advanced, tuning, mode, speed, fancy, color] });

Config objects use a visible function instead (alias shouldRender), returning a boolean:

const h = module.create({ name: "Demo", settings: [
  { id: "advanced", type: "boolean", name: "Advanced", default: false },
  { type: "slider", name: "Tuning", min: 0, max: 10, default: 5,
      visible: () => h.setting("advanced") === true },   // hidden until Advanced is on
]});

Limits & gotchas

The scripting engine is deliberately locked down and shares the client with everything else running in the game. Most of these rules exist to keep a misbehaving script from taking the whole client down with it. Read them before you ship anything nontrivial.

The sandbox is sealed

Anything heavy lives in the kotlin (player, nav, world, skyblock, and friends). Your script orchestrates them; it does not reach outside the game on its own. If a script needs to persist a little data across reloads, use the persistent store on script. The routes and world facades provide specific saved-route and snapshot operations without granting arbitrary filesystem access.

Runaway and blocking loops

The engine runs interpreter-only inside Minecraft (no JIT), so per-tick JavaScript needs to stay light: orchestrate the facades, don't loop over the world in JS. When you need to wait, use the async timing helpers (sleep, sleepTicks, setTimeout) or the tick hook, which return control to the client between turns.

// wrong — busy-waits on the event thread
// while (!player.onGround()) {}

// right — yields back to the game each tick
on("tick", () => {
  if (player.onGround()) doThing();
});

Packet delivery is tiered

So a packet whose data() shape the type file advertises may still need an opt-in (or never arrive at all). See Packet delivery for the exact tier of each packet.

For the packets you do receive, always compare event.name against a packet.* constant. Never compare event.type. That is the packet's raw runtime class name, which is obfuscated in production builds and only kept around for debugging. See Packets for the full list of mapped names and their curated data shapes.

Timer callbacks wait for their module

Timer callbacks and pending sleeps are deferred while the main module is off, but their deadlines keep using wall-clock time. An overdue callback can run soon after re-enabling; it does not preserve its old remaining delay. Unload/reload cancels timers outright. Clear timers on disable if the delayed action should not resume. See Timer lifecycle.