Built-in functions

Built-in operations are all invoked as ordinary command calls (Expressions).

Some built-in commands validate their argument shapes at compile time (the specific checks are listed in Error conditions). They are still ordinary command calls, not separate syntax.

Each entry below lists arity as min/max (a + maximum means variadic). Argument and result types use the names from Types.

Reserved, non-functional. The player name is reserved: it is accepted (and passes arity checks) but does nothing and returns null at run time. It is listed under Reserved / non-functional and should be treated as not part of the language.

Predicates → bool

Name Arity Args Description
exists 1/1 any the value is not null; for entity references, the entity is still live
isnull 1/1 any the value is null
ismob 1/1 creature the creature is an NPC
isplayer 1/1 creature the creature is a player
isobj 1/1 object the object resolves
isfighting 1/1 creature the creature has a living opponent
isholding 2/2 creature|object|room, int vnum the entity holds/contains an object of that vnum
iswearing 2/2 creature, int vnum worn equipment or implants include that vnum
hastag 2/2 player creature, string the player has the named marker tag
random 1/1 int pct true pct% of the time (a random percentile roll ≤ pct)
keyword 2/+ iterable, string… any word in the iterable equals (case-insensitive) any of the keyword args
abbrev 2/+ iterable, string… any word in the iterable is a case-insensitive prefix abbreviation of any of the args
streqi 2/2 string, string case-insensitive string equality
isabbrev 2/2 string needle, string hay needle is a prefix abbreviation of hay
location 2/2 object, string the object is at the named location (carried, container, worn, wielded, held, implanted, room)
cansee 2/2 creature, creature|object the creature can perceive the target

Entity queries / accessors

Name Arity Args Result Description
name 1/1 creature|object|room string display name
vnum 1/1 npc|object|room int vnum / room number (players error)
level 1/1 creature int level
room 1/1 creature|object|room|int room the entity's room; an int resolves a room vnum
class 1/1 creature string class name
alignment 1/1 creature string good / evil / neutral
gen 1/1 creature int remort generation
position 1/1 creature string position name (standing, sleeping, …)
carrier 1/1 object creature who carries the object, else null
he / him / his 1/1 creature string subject / object / possessive pronoun
hour 0/0 — int current game hour
moonphase 0/0 — string current lunar phase

Collection producers → iterable

Name Arity Args Element Description
creatures 1/1 room|creature creature living creatures in the room
people 1/1 room|creature creature alias of creatures
objects 1/1 room|creature|object object objects in room / carried / contained
contents 1/1 object|room object container contents / room contents
inventory 1/1 creature object carried objects
equipment 1/1 creature object worn equipment slots
implants 1/1 creature object implant slots
tattoos 1/1 creature object tattoo slots
fighting 1/1 creature creature living combatants
alias 1/1 creature|object string name aliases as words
words 1/1 string string whitespace-split words of the string
list 0/+ any… (mixed) an iterable over the arguments

words converts a string to a word iterable (Types — iterables).

Math / string / conversion

Arithmetic and comparison operators (+ - * / %, eq ne, gt lt ge le, and or not) are documented in Expressions — Operator builtins.

Name Arity Args Result Description
int 1/1 string int base-10 parse; parse failure is a run-time error
randrange 2/2 int min, int max int random integer in [min, max]
substr 3/3 string, int start, int len string up to len characters from 0-based start (clamped to the string's end; negative start/len treated as 0)
upper 1/1 string string ASCII upper-cased copy
lower 1/1 string string ASCII lower-cased copy

Prototype retrieval

Name Arity Args Result Description
object 1/1 int vnum obj_proto object prototype, or null if none
mob 1/1 int vnum mob_proto mobile prototype, or null if none

Iterable consumers

These take an iterable (a list, or a value of the iterable type; not a bare string) and, for the block-taking forms, a block. The block is invoked per element; the body's break, continue, and return govern iteration (see Run-time).

Name Arity Args Result Description
empty 1/1 iterable bool true if the iterable yields nothing
first 1/1 iterable value|null first element, or null if empty
nth 2/2 iterable, int n value|null element at 0-based index n, or null if the iterable has fewer than n+1 elements (non-positive n selects the first)
count 1/1 iterable int number of elements
ismember 2/2 value, iterable bool the value equals some element (eq)
hasabbrev 2/2 string, iterable bool the string abbreviates some element
choose 1/1 iterable value a uniformly-random element
each 2/2 iterable, block null invoke the body per element (arg = element)
every 2/2 iterable, block bool predicate holds for all (vacuously true if empty); predicate must yield bool
some 2/2 iterable, block bool predicate holds for any (false if empty); predicate must yield bool
select 2/2 iterable, block iterable deferred filter of elements where the predicate returns true; predicate must yield bool
slice 2/3 iterable, int start [, int end] iterable a bounded sub-iterable (default end unbounded)

The break, continue, and return propagation rules in consumer bodies are specified in Run-time.

Action commands (side effects → null)

These exist for their effects and return null. A successful effect causes the handle phase to suppress the default action (Program initialization and execution). Many require the owner to be a mobile; the "owner" column notes the constraint.

Name Arity Args Owner Description
do 1/1 string mob run the text as a command typed by the owner; splits on newlines
force 2/2 creature, string any make a creature execute a command
silently 1/1 string mob run a command with output suppressed
damage 3/3 creature, int, spell-name any* deal damage (attacker = owner if mob)
spell 3/3 creature, int level, spell-name any cast a spell (level capped)
giveexp 2/2 creature, int any grant experience
oload 1/3 int vnum [, target] [, int max] any load an object (default target follows owner)
mload 1/3 int vnum [, room] [, int max] any load a mobile into a room (default = owner room)
opurge 1/1 int vnum any extract matching objects held by the owner
selfpurge 0/0 — mob remove the owner mobile
trans 2/2 creature|object, room any move an entity to a room
stepto 1/1 room mob take one movement step toward a room
walkto 2/3 int vnum [, int pause] mob walk step-by-step to a room
driveto 2/3 int vnum [, int pause] mob drive a vehicle to a room
tag 2/2 player creature, string any add a marker tag to the player
untag 2/2 player creature, string any remove a marker tag from the player
doorset 4/4 room, dir, +|-, flags any set/clear exit flags
doorexit 3/3 room, dir, room|"none" any set or remove an exit's destination
ldesc 1/1 string mob/obj set the long description
mobflag 2/2 +|-, flags mob set/clear NPC action flags
echo 2/2 creature|room|"room"|"zone", string any send text to a target, the owner's room, or every player in the owner's zone
emit 2/4 type, string [, actor] [, victim] any act-style message (room/char/vict/notvict/zone)
award 2/3 creature, label [, int amount] any record challenge progress (players only)

* damage and several others run for any owner but attribute the attacker/caster to the owner only when it is a mobile.

Statement-shaped commands

These are not value-producing in normal use; they direct control flow or binding (Variables, Declarations and scope, Program initialization and execution):

Name Description
let / set / const introduce / mutate / introduce-immutable a local binding
store / recall write / read persistent entity state
if (block) conditional execution (see Expressions)
return / break / continue control-flow exits (see Run-time)
require / unless (guard) handler guards (see below)
pause suspend the script for n ticks, resuming later
nuke cancel every other script running on the same owner
halt stop the script immediately

require / unless guards

require [cond]      # advance to the next matching handler if cond is false
unless  [cond]      # advance to the next matching handler if cond is true

Both require a bool argument and take no body. Their handler-chaining semantics are specified in Program initialization and execution.

do versus interpolation

To build a command from variables, interpolate them in an ordinary double-quoted string — do "tell $actor hi" — which evaluates $actor by the normal lookup rules, so an unbound name is the usual run-time error (Variables).

Reserved / non-functional

The player name is reserved but non-functional: it is accepted without error but silently returns null at run time. Do not rely on it.

concat is likewise not callable: string building is done by interpolation, not by a concat command (Properties of types and values).

Names beginning with _ are reserved; their behavior is undefined.