Scripting API#

Scripts are JavaScript (Rhino, interpreter mode). Most of ES5 and a good part of ES6 work (var, function, regular expressions, JSON, Math, arrays, strings). If you hit an unsupported ES6 feature, use the plain ES5 form.

There is no access to Java. Scripts can only use the objects documented here.

Conventions#

• Item ids are strings: "minecraft:iron_ingot". NBT is ignored (items are matched by type). An unknown id throws unknown item: <id>.
• Counts are integers. Optional counts default to "as many as possible"; negative or NaN values become 0.
• Methods that move items return how many items were moved.
• Moving is limited by the per-run budgets (see Administration).

Globals#

net#

If the bus has no network storage available, methods that need it throw network is offline (which stops the bus).

Reservation, energy and statistics#

Planning (does not order anything)#

Order queue#

The four control methods can be disabled by the server (allowControl).

stock — stock rules#

The same rules as the Controller's Stock tab (8 rules).

recipes — Recipe Library settings#

The same settings as the Controller's Recipes tab (9 slots per list).

These can be disabled by the server (allowControl).

journal and alert#

Identical consecutive journal lines from the same bus are merged into x2, x3, …

side(dir) and side(dir, id)#

dir is one of "down", "up", "north", "south", "west", "east", relative to the Logic Bus the inventory is read from.

• side(dir) — the neighbour of this bus on that side.
• side(dir, id) — the neighbour on that side of every Logic Bus in the network whose ID is id (this bus included, if it has that ID). All matching inventories are merged into one endpoint: slots are numbered one after another, push fills the inventories in turn (buses are ordered by position), pull and list cover all of them.

Both return null if no matching inventory exists (no bus has that ID, or nothing with an inventory sits on that side). Network devices (cables, terminals, …) are not inventories.

var own     = side("up");               // above this bus
var furnace = side("north", "smelters"); // north of ALL buses called "smelters"

The inventory you get is the one the block exposes to the bus's face. Machines such as furnaces expose different slots on different faces (for example the top feeds input, the bottom gives output). Place the bus on the face you need.

buses(id) and busId#

log("I am", busId || "(no id)");
if (buses("smelters") === 0) log("no smelter buses!");

buses(id) is a cheap way to check that a group exists. It counts buses in the script's own network.

Endpoint#

An endpoint is the same object whether it comes from one bus or from a group.

Budgets per run#

Every run of tick() gets a fresh budget:

• Instructions and wall-clock time
• Items moved
• API calls: side, buses, every net.* method except usedBytes/freeBytes, stock.*, recipes.*, journal.*, alert, ep.list/count/pull/push/move each use one call. ep.slots, net.usedBytes, net.freeBytes, log, time are free.
• Craft calls: at most 4 net.craft calls per run.
• Journal writes: at most 4 journal.write/warn calls per run; alerts: at most 1 alert per run.

Exceeding a budget stops the bus with an error such as instruction limit exceeded. Items moved are clamped silently; pull/push simply return a smaller number once the item budget is used.

Removed built-ins#

To avoid one-call memory bombs, String.prototype.repeat, padStart, padEnd and Array.prototype.fill are removed.

Errors#

try/catch can handle ordinary script errors (like a bad item id). Budget violations cannot be caught.

Found a mistake? This page is generated from docs/wiki/Scripting-API.md in the mod repository.