Standard Library

Every builtin lives in the global scope. Argument counts are enforced; [x] marks an optional argument.

Console

Function	Returns	Description
print(...)	nil	Prints up to 16 values, space-separated, to the console. Long lines wrap at 256 columns.
clear()	nil	Clears the console for every viewer.
read()	string	Blocks until a line is typed into the terminal, then returns it.

print("what is your name?")
let name = read()
print("hello, " + name)

Timing

Function	Returns	Description
sleep(ticks)	nil	Blocks for ticks game ticks (20 = 1 second). Non-positive returns instantly.
gametime()	number	Total ticks the world has existed. Monotonic.
daytime()	number	Overworld clock time; 0–23999 per day cycle.
day()	number	floor(daytime() / 24000) — the current day number.
uptime()	number	Ticks since this program started (0 when not running).

if daytime() > 13000 and daytime() < 23000 { print("night time") }

Wifi networking

Pots reach each other by hostname across any distance and across dimensions, as long as both chunks are loaded. Names are lowercase, 1–16 characters of a-z 0-9 - _.

Function	Returns	Description
hostname()	string	This pot's name.
sethost(name)	bool	Renames the pot. false if invalid or already taken.
send(host, value)	bool	Sends to one host. false if the host is unknown/unloaded or its mailbox is full.
broadcast(value)	number	Sends to every other host; returns the delivery count.
peers()	list	Sorted hostnames of all reachable pots, including this one.
has_msg()	bool	Whether a message is waiting.
recv()	list	Blocks forever until a message arrives.
recv(timeout)	list or nil	Blocks up to timeout ticks; nil on timeout.

A received message is always a two-element list: [sender_hostname, payload].

Payloads may be nil, bools, numbers, strings and lists (nested up to 8 deep). Sending a function raises send: cannot send a function. Payloads are deep-copied on delivery.

# door controller
sethost("door")
while true {
    let msg = recv()
    let from = msg[0]
    let body = msg[1]
    if body == "open" {
        rs_set("north", 15)
        send(from, "ok")
    } else if body == "close" {
        rs_set("north", 0)
        send(from, "ok")
    }
}

Redstone

Sides are up, down, north, south, east, west. An unknown side is a runtime error.

Function	Returns	Description
rs_set(side, level)	nil	Emit level (clamped 0–15) out of that side. Both weak and strong power.
rs_get(side)	number	The redstone signal the neighbour on that side is feeding into the pot.
rs_reset()	nil	Set all six outputs to 0.

Output levels persist when the program stops and when the chunk unloads. reboot clears them.

# repeater with a delay: mirror the east input onto the west output, 1s later
while true {
    let level = rs_get("east")
    sleep(20)
    rs_set("west", level)
}

Inventories

Sides are up, down, north, south, east, west, same as redstone. Reads look at whatever inventory-holding block is on that side — chest, barrel, furnace, hopper, shulker box, even a chest minecart parked in the space. Double chests are merged into one 54-slot container. A side with no inventory reads as nil (or 0/-1 where the function returns a number).

Function	Returns	Description
block(side)	string	Registry id of the block on that side, e.g. "minecraft:chest", "minecraft:air".
inv_size(side)	number or nil	Slot count, or nil if the neighbour has no inventory.
inv_get(side, slot)	list or nil	[item_id, count], or nil for an empty slot, an out-of-range slot, or no inventory.
inv_count(side, item)	number	Total of item across every slot. 0 if there's no inventory.
inv_find(side, item)	number	First slot holding item, or -1 if not found / no inventory.
inv_move(from, to, [item], [max])	number	Moves items from one neighbour to another; returns how many actually moved.

Item names take the same shorthand as block ids — "coal" resolves to "minecraft:coal". A name that isn't in the item registry is a runtime error (inv_count: unknown item 'coal_ore', say), not a silent 0, so typos get caught instead of hidden.

inv_move moves through the same slot rules a hopper would: which slot it lands in depends on which face of the target block is touched, so feeding a furnace from the side fills fuel while feeding it from above fills the input, exactly like placing a hopper there. Omit item to move anything; omit max to move as much as fits. from and to must be different sides.

print(block("north"))                    # minecraft:chest
print(inv_count("north", "coal"))

while true {
    if inv_count("east", "coal") < 8 {
        inv_move("north", "east", "coal", 8)   # feeds the furnace's fuel slot, hopper-style
    }
    sleep(20)
}

World sensors

Function	Returns	Description
pos()	list	[x, y, z] of the pot.
dim()	string	Dimension id, e.g. "minecraft:overworld".
biome()	string	Biome id, e.g. "minecraft:plains".
weather()	string	"clear", "rain" or "thunder".
light()	number	Light level (0–15) of the block directly above the pot.

Players and sound

Function	Returns	Description
players([range])	list	Names of players within range blocks (default 16, clamped 0–64).
say(text, [range])	number	Sends <hostname> text to nearby players' chat; returns how many were reached. Text is truncated at 256 chars.
beep([pitch])	nil	Plays a note block "bit" sound. pitch is a semitone 0–24, default 12 (F#4, the natural pitch).

# greeter
let seen = []
while true {
    let here = players(8)
    let i = 0
    while i < len(here) {
        if find(seen, here[i]) < 0 {
            say("welcome, " + here[i])
            beep(18)
            push(seen, here[i])
        }
        i = i + 1
    }
    sleep(40)
}

Persistent disk

A string-to-string key/value store saved with the block. Values are stringified on write, so what you read back is always a string — use num() to convert numbers back.

Function	Returns	Description
store(key, value)	nil	Writes. Errors if the key is over 64 chars, the value over 4,096, or the disk is at 256 keys.
load(key)	string or nil	Reads; nil if the key is absent.
delkey(key)	bool	Deletes; false if the key was absent.
keys()	list	All keys, in insertion order.

let runs = num(load("runs") or "0")
runs = runs + 1
store("runs", runs)
print("run number " + str(runs))

Note that a list written with store comes back as its printed form ("[1, 2, 3]"), not as a list. To round-trip a list, use join/split:

store("items", join(["axe", "rope"], ","))
let items = split(load("items") or "", ",")

Math

Function	Returns	Description
random()	number	Uniform in [0, 1).
randint(a, b)	number	Uniform integer, inclusive of both ends. Errors if b < a.
floor(x) ceil(x) round(x)	number	Rounding. round returns the nearest integer (halves go up).
abs(x) sqrt(x)	number	Absolute value, square root.
pow(a, b)	number	a to the power b.
min(a, b) max(a, b)	number	Exactly two arguments.

Values and conversion

Function	Returns	Description
str(x)	string	The printed form of any value.
num(x)	number or nil	Parses a string (whitespace trimmed); passes numbers through; returns nil if unparseable. Errors on bools, lists and nil.
type(x)	string	"nil", "bool", "number", "string", "list" or "function".
len(x)	number	Length of a string or list. Errors on anything else.

Strings

Function	Returns	Description
upper(s) lower(s)	string	Case conversion.
trim(s)	string	Strips leading/trailing whitespace.
split(s, sep)	list	Splits on a literal separator (not a regex). An empty separator splits into single characters.
join(list, sep)	string	Joins stringified elements.
sub(s, from, [to])	string	Substring; both bounds are clamped into range, so it never errors. to defaults to the end.
find(s, needle)	number	Index of the first occurrence, or -1.
chr(n)	string	The character with code n.
ord(s)	number	Code of the first character. Errors on an empty string.

Lists

Function	Returns	Description
push(list, value)	list	Appends and returns the same list (so calls chain).
pop(list)	value	Removes and returns the last element. Errors when empty.
remove(list, i)	value	Removes and returns index i; negative indices count from the end.
find(list, value)	number	Index of the first equal element, or -1.
range([from,] to)	list	[from, from+1, ..., to-1]; from defaults to 0. The end is exclusive.
len(list)	number	Element count.

find dispatches on its first argument: given a list it searches by equality, given a string it searches for a substring.

---

See also: Errors & Gotchas · Examples · Wiki Home