User Object — sb0t JavaScript Scripting API Reference

User objects are passed directly to event callbacks (such as onUserJoin, onChat, and so on) and are also returned by the global user() lookup helper. Each instance wraps an internal IUser record and exposes the complete user interface to scripts — from read-only identity fields to writable state toggles and action methods like banning, redirecting, and sending messages.

The owner of the room (the admin account that started the server) is protected: ban(), disconnect(), redirect(), and level changes are silently ignored for that account.

Properties

Identity & Network

int

The numeric session ID assigned to this connection. Returns -1 for users connected via a linked leaf server. Read-only.

guid

string

The 16-byte GUID that uniquely identifies the Ares client installation, formatted as a standard UUID string. Read-only.

name

string

The user’s current display name. Assigning a new value renames the user for the duration of the session. Read/write.

orgName

string

The original name the user had when they first joined the room. This value never changes, even if name is overridden. Read-only.

externalIp

string

The user’s externally visible IP address as a dotted-decimal string. Read-only.

localIp

string

The user’s local (LAN) IP address as a dotted-decimal string. Read-only.

localEP

string

The user’s full local endpoint in address:port notation. Returns "0.0.0.0:0" if the endpoint is unavailable. Read-only.

dns

string

The DNS hostname resolved for the user’s IP address. Read-only.

port

int

The data transfer port advertised by the Ares client. Read-only.

version

string

The Ares client version string reported at connection time. Read-only.

joinTime

number

Unix timestamp (seconds since epoch) for when the user joined this session. Read-only.

Profile

age

int

The age value self-reported by the user in their Ares profile. Read-only.

gender

string

The gender self-reported by the user. Returns "Male", "Female", or "Unknown". Read-only.

country

string

The two-letter country code string resolved from the user’s country byte. Read-only.

region

string

The regional location string reported by the Ares client. Read-only.

fileCount

int

The number of files the user is currently sharing. Read-only.

personalMessage

string

The user’s personal status message. Can be overridden by scripts. Read/write.

avatar

object

A JSAvatarImage object containing the user’s avatar image data. Assigning a JSAvatarImage value replaces the avatar; assigning any other value clears it.

font

object

A UserFont object describing the user’s custom chat font. The object exposes four read-only sub-properties:

Sub-property	Type	Description
`font.enabled`	bool	Whether the custom font is active.
`font.family`	string	Font family name (maps to `FontName` in the source).
`font.nameColor`	string	Hex colour applied to the username.
`font.textColor`	string	Hex colour applied to chat text.

Admin & Room State

level

int

The user’s current admin level. Valid values:

Value	Meaning
`0`	Regular user
`1`	Moderator
`2`	Administrator
`3`	Host

Assigning a value in the range 0–3 changes the level, subject to the ScriptCanLevel server setting. The owner’s level cannot be changed. Read/write.

vroom

int

The virtual room (channel) the user is currently in. Accepts values 0–65535. Assigning a value moves the user to the specified virtual room. Read/write.

muzzled

bool

Whether the user is currently muzzled (prevented from sending public chat). Setting to true muzzles; false unmuzzles. Read/write.

customName

string | null

An override display name applied on top of the user’s real name. Set to null to remove the override and restore the original name. Read/write.

cloaked

bool

Whether the user is hidden from the user list. Setting to true hides the user; false makes them visible again. Read/write.

visible

bool

Derived visibility flag. Returns true if the user is not cloaked (for local users) or is marked as visible by the link layer (for linked users). Read-only.

Boolean Status Flags

browsable

bool

true if the user is sharing files and accepts browse requests. Read-only.

fastPing

bool

true if the client uses the keep-alive (fast-ping) protocol extension. Read-only.

ghost

bool

true if the user entry is a linked ghost (connected via a leaf server). Read-only.

customClient

bool

true if the user is connecting with a third-party Ares-compatible client. Read-only.

webClient

bool

true if the user is connecting via the web-browser client interface. Read-only.

canHTML

bool

true if the client supports receiving HTML-formatted messages. Read-only.

owner

bool

true if this user is the room owner (the host account that started the server). Read-only.

registered

bool

true if the user is logged in to a registered account. Read-only.

captcha

bool

true if the user has passed the captcha challenge. Read-only.

idle

bool

true if the user is currently marked as idle. Read-only.

linked

bool

true if this user record originates from a linked leaf server rather than a direct local connection. Read-only.

leaf

object | null

The Leaf object representing the linked server this user came from. Returns null for locally connected users. Read-only.

Methods

user.ban()

function

Bans the user by IP address and GUID, then disconnects them. The ban entry persists in the ban list until manually removed. Has no effect on the room owner.

user.disconnect()

function

Disconnects the user from the room without adding a ban entry. Has no effect on the room owner.

user.redirect(hashlink)

function

Sends the user an Ares redirect to the room identified by hashlink. The client will automatically attempt to join the target room.

Parameter	Type	Description
`hashlink`	string	An `arlnk://` deep-link or IP:port string for the destination room.

user.sendText(text)

function

Broadcasts a public chat line into the room attributed to this user’s name. All users in the room see the message.

Parameter	Type	Description
`text`	string	The message text to broadcast.

user.sendHTML(text)

function

Sends an HTML-formatted message to this specific user. Only clients where canHTML is true will render the markup.

Parameter	Type	Description
`text`	string	HTML string to deliver.

user.sendEmote(text)

function

Sends an emote action line attributed to this user. The text is broadcast to the room in the emote style (e.g. * Username text).

Parameter	Type	Description
`text`	string	The emote text.

user.setTopic(text)

function

Sends a virtual topic that is visible only to this individual user without changing the global room topic.

Parameter	Type	Description
`text`	string	Topic text to display. Pass `undefined` to restore the real room topic.

user.setUrl(address, text)

function

Sends a URL tag visible only to this user, overriding the room-wide URL tag for their session. Pass two empty strings to clear it.

Parameter	Type	Description
`address`	string	The URL to display.
`text`	string	The link label.

user.nudge(sender)

function

Sends a nudge notification to this user. Only works for custom clients (customClient === true).

Parameter	Type	Description
`sender`	string	The name to display as the nudge sender. If omitted, defaults to `Room.botName`.

user.scribble(sender, img)

function

Sends a scribble drawing to the user. Only works for custom clients. The first argument may be either a JSScribbleImage object (sender defaults to Room.botName) or a sender name string followed by a JSScribbleImage.

Parameter	Type	Description
`sender`	string \| JSScribbleImage	Sender name, or the scribble image itself.
`img`	JSScribbleImage	Scribble image (only required when `sender` is a string).

user.restoreAvatar()

function

Restores the user’s original avatar, discarding any script-assigned replacement.

user.getASN()

function

Returns the Autonomous System Number (ASN) associated with the user’s current IP address as an unsigned 32-bit integer. Useful for network-level access controls.

Examples

function onUserJoin(user) {
  // Send a private welcome message visible only to the joining user
  print(user, "Welcome to " + Room.name + ", " + user.name + "!");

  // Muzzle users who have not passed the captcha
  if (!user.captcha) {
    user.muzzled = true;
    print(user, "You are muzzled until you complete the captcha.");
  }
}

Core Objects

Utilities

User Object — sb0t JavaScript Scripting API Reference

Properties

Identity & Network

Profile

Admin & Room State

Boolean Status Flags

Methods

Examples

Build docs developers (and LLMs) love

Core Objects

Utilities

Documentation Index

​Properties

​Identity & Network

​Profile

​Admin & Room State

​Boolean Status Flags

​Methods

​Examples

Build docs developers (and LLMs) love

Properties

Identity & Network

Profile

Admin & Room State

Boolean Status Flags

Methods

Examples