sb0t Scripting: Event Callbacks Complete Reference

sb0t calls named global JavaScript functions in your script when server events occur. You define only the events you care about — any event function that is not defined in your script is silently ignored (a no-op stub is registered automatically for every event so the engine never throws a “function not found” error). Every event receives one or more arguments. Events that can cancel the default action do so by returning a falsy value or an empty string, depending on the event type. Events that are purely informational ignore their return value.

User lifecycle

`onJoinCheck(user)`

function onJoinCheck(user) { return true; }

Fired before a user is allowed to enter the room. Return false to reject the connection entirely.

user

JSUser

The connecting user. Because the user has not yet joined, they are not yet in the room user list.

Returns: boolean — false rejects the user.

`onJoin(user)`

function onJoin(user) { }

Fired after a user has successfully joined the room. The user is now present in the room user list.

user

JSUser

The user who joined.

`onRejected(user)`

function onRejected(user) { }

Fired when a user’s join attempt was rejected (e.g. by onJoinCheck returning false, or by a ban). The user object is a transient snapshot and is not in the room list.

user

JSUser

The rejected user.

`onPartBefore(user)`

function onPartBefore(user) { }

Fired just before a user is removed from the room. The user is still in the room list at this point.

user

JSUser

The departing user.

`onPart(user)`

function onPart(user) { }

Fired after a user has been removed from the room. The user is no longer in the room list.

user

JSUser

The user who left.

Text events

`onTextBefore(user, text)`

function onTextBefore(user, text) { return text; }

Fired before a public message is broadcast to the room. You can modify the text by returning a different string, or cancel the message entirely by returning an empty string or null.

user

JSUser

The user sending the message.

text

string

The raw message text as typed by the user.

Returns: string — the (possibly modified) text to broadcast. Return "" or null to suppress the message.

`onTextAfter(user, text)`

function onTextAfter(user, text) { }

Fired after a public message has been broadcast. The return value is ignored.

user

JSUser

The sender.

text

string

The text that was broadcast.

`onTextReceived(user, text)`

function onTextReceived(user, text) { }

Fired when the server receives a public chat message from the client but before the onTextBefore processing chain. Use this for logging or side-effects that should not interfere with message flow.

user

JSUser

The sender.

text

string

The raw received text.

Emote events

`onEmoteBefore(user, text)`

function onEmoteBefore(user, text) { return text; }

Fired before an emote action (/me ...) is broadcast. Return a modified string to change the text, or "" / null to cancel.

user

JSUser

The user sending the emote.

text

string

The emote text.

Returns: string — modified emote text, or empty to suppress.

`onEmoteAfter(user, text)`

function onEmoteAfter(user, text) { }

Fired after an emote has been broadcast.

user

JSUser

The sender.

text

string

The text that was broadcast.

`onEmoteReceived(user, text)`

function onEmoteReceived(user, text) { }

Fired when the server first receives an emote from the client, before the onEmoteBefore chain.

user

JSUser

The sender.

text

string

The raw received emote text.

PM events

`onPMBefore(user, target, pm)`

function onPMBefore(user, target, pm) { return true; }

Fired before a private message is delivered. Return false to cancel delivery.

user

JSUser

The user sending the PM.

target

JSUser

The user receiving the PM.

JSPM

A PM object (carries the message text and other metadata).

Returns: boolean — false cancels the PM.

`onPM(user, target)`

function onPM(user, target) { }

Fired after a private message has been delivered.

user

JSUser

The sender.

target

JSUser

The recipient.

`onBotPM(user, text)`

function onBotPM(user, text) { }

Fired when a user sends a PM directly to the bot (the room bot name).

user

JSUser

The user who messaged the bot.

text

string

The PM text.

User state

`onNick(user, newName)`

function onNick(user, newName) { return true; }

Fired when a user requests a nickname change. Return false to deny the nick change.

user

JSUser

The user requesting the name change.

newName

string

The requested new nickname.

Returns: boolean — false denies the name change.

`onAvatar(user)`

function onAvatar(user) { return true; }

Fired when a user sends a new avatar image. Return false to reject it.

user

JSUser

The user sending the avatar.

Returns: boolean — false rejects the avatar.

`onScribbleCheck(user, isPM)`

function onScribbleCheck(user, isPM) { return true; }

Fired when a user attempts to send a scribble (drawing). Return false to block it.

user

JSUser

The sender.

isPM

boolean

true if the scribble is a PM scribble.

Returns: boolean — false blocks the scribble.

`onPersonalMessage(user, text)`

function onPersonalMessage(user, text) { return true; }

Fired when a user updates their personal status message. Return false to reject the update.

user

JSUser

The user updating their status.

text

string

The new personal message text.

Returns: boolean — false rejects the update.

`onIdled(user)`

function onIdled(user) { }

Fired when a user transitions to idle status.

user

JSUser

The user who became idle.

`onUnidled(user, seconds)`

function onUnidled(user, seconds) { }

Fired when an idle user returns to active status.

user

JSUser

The user who returned from idle.

seconds

number

How many seconds the user was idle.

Admin and authentication

`onLoginGranted(user)`

function onLoginGranted(user) { }

Fired when a user successfully logs in with an admin password.

user

JSUser

The user who logged in.

`onInvalidLoginAttempt(user)`

function onInvalidLoginAttempt(user) { }

Fired when a user submits an incorrect admin password.

user

JSUser

The user who made the failed attempt.

`onLogout(user)`

function onLogout(user) { }

Fired when a user voluntarily logs out of their admin session.

user

JSUser

The user who logged out.

`onAdminLevelChanged(user)`

function onAdminLevelChanged(user) { }

Fired whenever a user’s admin level changes (promotion or demotion).

user

JSUser

The user whose level changed. Check user.level for the new value.

`onRegistering(user)`

function onRegistering(user) { return true; }

Fired when a user attempts to register a name. Return false to deny registration.

user

JSUser

The user attempting to register.

Returns: boolean — false blocks the registration.

`onRegistered(user)`

function onRegistered(user) { }

Fired after a user has successfully registered their name.

user

JSUser

The newly registered user.

`onUnregistered(user)`

function onUnregistered(user) { }

Fired when a user’s name registration is removed.

user

JSUser

The user who was unregistered.

Room events

`onVroomJoinCheck(user, vroom)`

function onVroomJoinCheck(user, vroom) { return true; }

Fired when a user tries to enter a virtual room (vroom). Return false to deny entry.

user

JSUser

The user requesting to join the vroom.

vroom

number

The vroom number (0–65535).

Returns: boolean — false blocks entry.

`onVroomJoin(user)`

function onVroomJoin(user) { }

Fired after a user has successfully entered a virtual room. Check user.vroom for which room they joined.

user

JSUser

The user who changed vrooms.

`onCommand(user, cmd, target, args)`

function onCommand(user, cmd, target, args) { }

Fired when a user types a /command. Built-in script management commands are intercepted before this event fires.

user

JSUser

The user who issued the command.

cmd

string

The full command string (lowercase, without the leading /).

target

JSUser | null

The targeted user, if any was resolved from the command. null otherwise.

args

string

Any trailing arguments after the command and target.

`onHelp(user)`

function onHelp(user) { }

Fired when a user types /help. Use print(user, "...") here to add your own help lines. If the user is at or above ScriptLevel, the built-in scripting help lines are also printed.

user

JSUser

The user who requested help.

`onFileReceived(user, filename)`

function onFileReceived(user, filename) { }

Fired when a user sends a file to the room.

user

JSUser

The sender.

filename

string

The name of the file as reported by the client.

`onIgnoring(user, target)`

function onIgnoring(user, target) { return true; }

Fired when a user attempts to add another user to their ignore list. Return false to prevent the ignore.

user

JSUser

The user doing the ignoring.

target

JSUser

The user being ignored.

Returns: boolean — false blocks the ignore action.

`onIgnoredStateChanged(user, target, ignored)`

function onIgnoredStateChanged(user, target, ignored) { }

Fired after a user’s ignore state for another user has changed.

user

JSUser

The user whose ignore list changed.

target

JSUser

The user affected.

ignored

boolean

true if target was added to the ignore list; false if removed.

Flood events

`onFloodBefore(user, msgByte)`

function onFloodBefore(user, msgByte) { return true; }

Fired when a flood condition is detected for a user, before the flood action is taken. Return false to cancel the flood action.

user

JSUser

The flooding user.

msgByte

number

The message-type byte that triggered the flood detection.

Returns: boolean — false suppresses the flood action.

`onFlood(user)`

function onFlood(user) { }

Fired after a flood action has been applied to the user.

user

JSUser

The user who triggered flood protection.

`onProxyDetected(user)`

function onProxyDetected(user) { return false; }

Fired when the server detects that a connecting user may be using a proxy. The default stub returns false (allow anyway), because the built-in proxy check can produce false positives. Return true to reject the connection.

user

JSUser

The connecting user.

Returns: boolean — true rejects the connection.

Linking events

`onLinked()`

function onLinked() { }

Fired when this server successfully establishes a link hub connection.

`onUnlinked()`

function onUnlinked() { }

Fired when the link hub connection drops.

`onLinkError(msg)`

function onLinkError(msg) { }

Fired when a link error occurs.

msg

number

An integer error code representing the link error type.

`onLeafJoin(leaf)`

function onLeafJoin(leaf) { }

Fired when a leaf server connects to this hub.

leaf

JSLeaf

The leaf server that connected.

`onLeafPart(leaf)`

function onLeafPart(leaf) { }

Fired when a leaf server disconnects from this hub.

leaf

JSLeaf

The leaf server that disconnected.

`onLinkedAdminDisabled(leaf, user)`

function onLinkedAdminDisabled(leaf, user) { }

Fired when a linked user’s admin privileges are revoked via the hub.

leaf

JSLeaf

The leaf the user belongs to.

user

JSUser

The user whose admin was disabled.

Script lifecycle

`onLoad()`

function onLoad() { }

Fired once when the script is first loaded (or reloaded). Use this to set up initial state, read configuration files, or print a startup message. This is the earliest point at which all static objects (Room, Users, Stats, etc.) and global functions are available.

Timer and maintenance events

`onTimer()`

function onTimer() { }

Fired once per second for every loaded script. Use this for polling, countdowns, or any recurring task that does not require fine-grained precision.

For intervals shorter than one second, or for one-shot delayed actions, use the Timer constructor object instead of onTimer.

`onBansAutoCleared()`

function onBansAutoCleared() { }

Fired when the server automatically clears its ban list (e.g. on a scheduled auto-clear).

Practical examples

Join greeter

function onJoin(user) {
    print(user, "Welcome to the room, " + user.name + "! Type /help for commands.");
}

Text censor

var banned = ["badword", "otherword"];

function onTextBefore(user, text) {
    var lower = stripColors(text).toLowerCase();
    for (var i = 0; i < banned.length; i++) {
        if (lower.indexOf(banned[i]) !== -1) {
            print(user, "Your message contained a banned word and was not sent.");
            return ""; // cancel the message
        }
    }
    return text; // pass through unchanged
}

Command handler

function onCommand(user, cmd, target, args) {
    if (cmd === "roll") {
        var result = Math.floor(Math.random() * 6) + 1;
        print(user.name + " rolled a " + result + "!");
        return;
    }

    if (cmd === "topic" && user.level >= 1) {
        Room.topic = args;
        print("Topic updated by " + user.name + ": " + args);
    }
}

Get Started

Administration

Features

Scripting

Documentation Index

​User lifecycle

​onJoinCheck(user)

​onJoin(user)

​onRejected(user)

​onPartBefore(user)

​onPart(user)

​Text events

​onTextBefore(user, text)

​onTextAfter(user, text)

​onTextReceived(user, text)

​Emote events

​onEmoteBefore(user, text)

​onEmoteAfter(user, text)

​onEmoteReceived(user, text)

​PM events

​onPMBefore(user, target, pm)

​onPM(user, target)

​onBotPM(user, text)

​User state

​onNick(user, newName)

​onAvatar(user)

​onScribbleCheck(user, isPM)

​onPersonalMessage(user, text)

​onIdled(user)

​onUnidled(user, seconds)

​Admin and authentication

​onLoginGranted(user)

​onInvalidLoginAttempt(user)

​onLogout(user)

​onAdminLevelChanged(user)

​onRegistering(user)

​onRegistered(user)

​onUnregistered(user)

​Room events

​onVroomJoinCheck(user, vroom)

​onVroomJoin(user)

​onCommand(user, cmd, target, args)

​onHelp(user)

​onFileReceived(user, filename)

​onIgnoring(user, target)

​onIgnoredStateChanged(user, target, ignored)

​Flood events

​onFloodBefore(user, msgByte)

​onFlood(user)

​onProxyDetected(user)

​Linking events

​onLinked()

​onUnlinked()

​onLinkError(msg)

​onLeafJoin(leaf)

​onLeafPart(leaf)

​onLinkedAdminDisabled(leaf, user)

​Script lifecycle

​onLoad()

​Timer and maintenance events

​onTimer()

​onBansAutoCleared()

​Practical examples

​Join greeter

​Text censor

​Command handler

Build docs developers (and LLMs) love

User lifecycle

`onJoinCheck(user)`

`onJoin(user)`

`onRejected(user)`

`onPartBefore(user)`

`onPart(user)`

Text events

`onTextBefore(user, text)`

`onTextAfter(user, text)`

`onTextReceived(user, text)`

Emote events

`onEmoteBefore(user, text)`

`onEmoteAfter(user, text)`

`onEmoteReceived(user, text)`

PM events

`onPMBefore(user, target, pm)`

`onPM(user, target)`

`onBotPM(user, text)`

User state

`onNick(user, newName)`

`onAvatar(user)`

`onScribbleCheck(user, isPM)`

`onPersonalMessage(user, text)`

`onIdled(user)`

`onUnidled(user, seconds)`

Admin and authentication

`onLoginGranted(user)`

`onInvalidLoginAttempt(user)`

`onLogout(user)`

`onAdminLevelChanged(user)`

`onRegistering(user)`

`onRegistered(user)`

`onUnregistered(user)`

Room events

`onVroomJoinCheck(user, vroom)`

`onVroomJoin(user)`

`onCommand(user, cmd, target, args)`

`onHelp(user)`

`onFileReceived(user, filename)`

`onIgnoring(user, target)`

`onIgnoredStateChanged(user, target, ignored)`

Flood events

`onFloodBefore(user, msgByte)`

`onFlood(user)`

`onProxyDetected(user)`

Linking events

`onLinked()`

`onUnlinked()`

`onLinkError(msg)`

`onLeafJoin(leaf)`

`onLeafPart(leaf)`

`onLinkedAdminDisabled(leaf, user)`

Script lifecycle

`onLoad()`

Timer and maintenance events

`onTimer()`

`onBansAutoCleared()`

Practical examples

Join greeter

Text censor

Command handler