Scripting

Your first script

PASSWORD = "my-password"

async def on_join(bot):
    bot.sleep(3)
    bot.send_chat(f"/login {PASSWORD}")

async def on_chat(bot, message):
    if "hello" in message.lower():
        message.reply("hi " + message.sender)

• A script is a set of handlers: functions named after an event (on_join, on_chat, on_kick, …). The bot runs a handler each time its event happens.
• The first parameter is always the bot. The others are what the event gives you, like message for on_chat or reason for on_kick.
• bot.send_chat(...) and send_chat(...) do the same thing. await is optional.
• Arguments go by position or by name: bot.find_block("oak_log", radius=16).
• Mistakes come back with the line number and a “did you mean” suggestion.

To run a script, pick it when you start an account, or assign it under Details → Behavior on the Accounts page. The assigned script runs every time the account starts. Its log.info(...) lines and errors appear in the editor's Output panel.

What functions give back

Functions return numbers, text, True/False, lists, None, or records you read with a dot. Records that stand for text act like text: "hi" in message, player == "Steve".

Inventory slots use Minecraft's numbers: 5–8 armor, 9–35 main inventory, 36–44 hotbar (hotbar slot 0 is 36), 45 off hand.

Settings and variables

Put settings at the top of the script (DELAY = 30, HOME = pos(0, 64, 0)). A variable set in a handler is shared with every other handler. New names inside a helper function stay inside that function.

kills = 0                       # shared by every handler

async def on_attack(bot, entity):
    kills += 1

def count_logs(bot):
    total = 0                   # only exists inside count_logs
    for item in bot.find_items("oak_log"):
        total += item.count
    return total

Helpers, timers, and background tasks

Any def that isn't named after an event is a helper. Call it yourself, or hand it to the bot without quotes or brackets. If its first parameter is bot, the bot is passed in for you.

def patrol(bot):
    bot.walk_to(10, 64, 10)
    bot.walk_to(-10, 64, -10)

async def on_join(bot):
    bot.every(60, patrol)            # every minute
    bot.after(5, patrol)             # once, in 5 seconds
    task = bot.run_task(patrol)      # in the background: task.pause(), .resume(), .cancel(), .wait()

Waiting

Every wait takes timeout= and returns None or False if time runs out.

msg = bot.wait_for_chat("Please log in", timeout=10)
if msg is None:
    log.warn("no login prompt")

bot.wait_for_health(15, timeout=30)
bot.wait_until(is_safe, timeout=60)   # is_safe is one of your functions

Errors

try:
    bot.break_block(10, 64, 10)
except Exception as e:
    log.warn("couldn't mine: " + e.message)

A failing handler never stops the others. The error is logged with its line number and on_error(bot, error) runs. bot.try_action(fn, retries=3) and bot.retry(fn) retry flaky steps; bot.restart_on_error(True) restarts the script after a crash.

Staying online 24/7

The account's Keep online setting (on by default) already rejoins after kicks and restarts. A script lives as long as its session: handlers keep listening, and a while True loop with a wait inside runs for as long as the bot does. During a reconnect, anything that needs the world (moving, looking, attacking) waits until the bot is back instead of failing, so loops carry on by themselves.

def guard(bot):
    while True:
        mob = bot.find_entity("hostile", radius=6)
        if mob:
            bot.attack(mob)
        bot.sleep(0.5)

async def on_start(bot):
    bot.run_task(guard)

async def on_chat(bot, message):     # keeps listening across every rejoin
    if message == "!pos":
        message.reply(str(bot.get_position()))

Variables, timers, and tasks survive a reconnect. on_reconnect runs after the rejoin and on_join runs again. To control reconnects from the script instead, use bot.auto_reconnect(True, delay=10, max_attempts=0) (0 = keep trying). A ban or mute takes the bot off the server and keeps it off.

Anti-AFK

bot.anti_afk(interval=30, jump=True, rotate=True, move=False, swing=False, sneak=False, command=None, no_fly=True) does a small random action every interval (±25%). With no_fly the bot also lands whenever the server has it flying, like ranked players in Hypixel lobbies. It is the same as the account's Anti-AFK setting: calling it replaces that setting for this session, bot.anti_afk(False) turns it off, and bot.afk_settings() shows what is running.

Webhooks

async def on_kick(bot, reason):
    bot.webhook(reason, title="Kicked", level="error")

async def on_whisper(bot, message):
    bot.webhook(f"{message.sender}: {message.text}", webhook="dms")

bot.webhook(message, title=None, level="info", webhook=None) posts to a webhook you added under Webhooks (Discord, Slack, or any URL that accepts JSON). webhook= picks one by name; otherwise your default is used. Scripts never see the URL. Each bot can send 20 per minute.

Raw packets

bot.send_raw_packet("swing", ["varint", 0])                  # main hand
bot.send_raw_packet("chat_command", ["string", "spawn"])     # unsigned command
bot.send_raw_packet(0x3F, "00")                               # id + hex body

For experts: sends a serverbound play packet by name (or numeric id) with a body given as hex text or type/value pairs (bool, byte, ubyte, short, ushort, int, long, float, double, varint, varlong, angle, string, uuid, position, bytes). The body isn't checked, so a wrong one gets the bot kicked — use the normal functions when one exists. At most 50 per second.

The language

Supported: numbers, text and f-strings (f"hp={hp:.1f}"), True/False/None, lists with indexing, slicing and .append(), if/elif/else, while, for, break, continue, return, try/except/finally, and/or/not, in, is None, += -= *= /=, and helper functions.

Not supported, on purpose: imports, files, network, classes, lambdas, decorators, dictionaries, comprehensions, and a def inside another def. Scripts are sandboxed: they can only affect their own bot.

Limit: each handler gets about 200,000 steps of work between waits. Any wait (like bot.sleep) refills it, so a loop that never waits is stopped, while a loop that waits can run for days.

Block builder

• Every function and event below is also a block. Drag an event (like When joined server) onto the canvas, then drag blocks under it until they snap.
• If, Repeat, Forever, and the other loop blocks hold blocks inside them.
• Dragging a block takes the blocks under it along. Drop it back on the block list to delete it; Ctrl+Z undoes.
• A stack that isn't under an event is kept on the canvas but doesn't run.
• Type values right on the block. Click a block to see all its options. The { } switch next to a field lets you type code instead of a plain value — a variable like message or an expression like bot.get_health() < 10.
• Script variables holds the settings at the top of a script (COUNT = 3); they're set once when the script starts and every flow can read them.
• The Code block holds lines of Python for anything the other blocks can't show, like items.append(x). Tab indents inside it.
• Saving turns the blocks into the script's code (press Code to read it). Code written in the code editor opens here as blocks, with any line that has no matching block kept in a Code block; it runs exactly the same. Saving from the builder drops comments.

API reference

Functions are called as bot.name(...). Events are handled with async def on_event(bot, ...).

Not available

• on_packet_send — Azalea does not surface outgoing packets as events at the pinned version; `log_packets()` logs packets sent with `send_raw_packet`, and `log_events(commands=True)` logs chat and commands.
• Event cancellation of server events — Incoming server events cannot be cancelled. Listener chains can stop early by returning False.
• Environment variables — Scripts are sandboxed and cannot read the worker's environment. Use top-level constants instead.
• Secrets store — None. Keep secrets out of scripts you share with others.
• Sound notifications — None. `notify()` reaches the dashboard bell and browser notifications; `webhook()` reaches Discord, Slack, or your own URL.
• Breakpoints and step debugging — None. Use `event_history()`, `stats()`, `log_packets()`, and `log.debug()`.
• Hot reload on save — None. Saving a script applies on the next session start; `reload_script()` restarts the running copy.

Known limitations

• Pathfinding never digs or places blocks unless allow_mining=True, and never crosses lava or long drops.
• on_block_break reports what a block became, not what it was.