Users Object — Iterate the User Pool in sb0t Scripts

Users is a static singleton that provides iterator methods over different slices of the server’s user pool. Rather than returning arrays, each method accepts a callback function and invokes it once per matching record — the same pattern as Array.prototype.forEach. This design avoids creating heavyweight JavaScript arrays for large populations and keeps iteration logic in C#, where it is safe to execute under locks. The four iterators cover locally connected users, users from linked leaf servers, the active ban list, and the full join-history log for the current server session.

Users.local() iterates only users who are directly connected to this server. Users who joined via a linked leaf server are not included. Use Users.linked() separately, or call both iterators, to cover the full visible population.

Methods

Users.local(fn)

function

Calls fn(user) once for every locally connected user (Ares and web clients). The user argument is a full User object.

Parameter	Type	Description
`fn`	function	Callback invoked with a `User` object for each local user.

Users.linked(fn)

function

Calls fn(user) once for every user who is connected via a linked leaf server. This iterator only yields results when this server is operating in hub mode and at least one leaf is connected. The user argument is a full User object.

Parameter	Type	Description
`fn`	function	Callback invoked with a `User` object for each linked user.

Users.banned(fn)

function

Calls fn(bannedUser) once for each entry in the current ban list. The bannedUser argument is a BannedUser object with the following properties:

Property	Type	Description
`name`	string	The username at the time of the ban.
`version`	string	The Ares client version string.
`guid`	string	The banned client’s GUID.
`externalIp`	string	The banned external IP address.
`localIp`	string	The banned local IP address.
`port`	int	The data port at ban time.

BannedUser also exposes an unban() method that removes the entry from the ban list immediately.

Parameter	Type	Description
`fn`	function	Callback invoked with a `BannedUser` object for each ban entry.

Users.records(fn)

function

Calls fn(record) once for each user that has connected to the server during the current session (including users who have since disconnected). This is useful for building audit logs or retrospective lookups. The record argument is a Record object with the following properties:

Property	Type	Description
`name`	string	The username at join time.
`joinTime`	number	Unix timestamp when the user joined.
`externalIp`	string	External IP address.
`localIp`	string	Local IP address.
`dns`	string	DNS hostname.
`version`	string	Ares client version string.
`port`	int	Data port.
`guid`	string	Client GUID.

Record also exposes a ban() method that adds the record’s IP/GUID to the ban list.

Parameter	Type	Description
`fn`	function	Callback invoked with a `Record` object for each session record.

Examples

function onChat(user, text) {
  if (text === "!count") {
    var count = 0;
    Users.local(function(u) { count++; });
    print(user, "Local users: " + count);
  }
}

Core Objects

Utilities

Users Object — Iterate the User Pool in sb0t Scripts

Methods

Examples

Build docs developers (and LLMs) love

Core Objects

Utilities

Documentation Index

​Methods

​Examples

Build docs developers (and LLMs) love

Methods

Examples