The Objects Book for fuzzball 7.0 by raccoon! - Basic Attributes - Database References - Names - Owners - Locations - Timestamps - Flags - Types - Exits - Programs - Rooms - Players and things - Mucker Levels and Wizards - Realms Wizards - Exit Priority - Other Flags - Properties - Restricted Properties - Registered Names - Proplists - Value - Locks - Messages - Details - Substitutions - Propqueues - MPI ================================================================================ BASIC ATTRIBUTES --DATABASE REFERENCES----------------------------------------------------------- An object is identified by a unique database reference (dbref) which is assigned to it automatically upon creation. They're formatted as decimal numbers, often with a '#' in front, like '#12345'. They are assigned sequentially, but recycled if an object is destroyed. --NAMES------------------------------------------------------------------------- An object also has a human-readable name given to it (during its creation or with `@name`). Players' names cannot be the same as any other player's name, and cannot include spaces, but these restrictions don't apply to other objects. --OWNERS------------------------------------------------------------------------ An object is owned by its creator (by default) or whoever its ownership is given to (`@chown`). Many operations on objects can only be performed if you are its owner or are given control by its owner (`@ownlock`). --LOCATIONS--------------------------------------------------------------------- Objects have locations in the world. On the MUCK, spatial relationships are expressed in a hierarchy called the Environment Tree (`@teleport`, `@attach`). For example, an inventory item might be located 1. inside your player, who is 2. inside a room, which is 3. inside an Environment Room (a special room which acts as a "region" to organise real rooms in, like "The Outdoors", "Town", etc.), which is 4. inside Room Zero, the root of the hierarchy. You can see an item's full "Environment Chain" by `@trace`ing it. You can put things in rooms or your own player by default, but you'll need to `@conlock` other things (see "Locks"). --TIMESTAMPS-------------------------------------------------------------------- Whenever an object is created, modified, or used, it is reflected in a set of timestamps associated with the object. A player object is "used" when the player logs in, a room is used when it is entered or looked at, an exit is used when it is invoked or looked at, a program is used when it is run, and a thing is used when it is taken, dropped, or looked at. ================================================================================ FLAGS Flags, or "bits", can be added to objects to signify additional simple attributes (`@set`). They store no additional information apart from whether they are set, and they are identified by single characters. Often you'll see them displayed after an object's dbref (such as when you `examine` it), like '#12345PB' --TYPES------------------------------------------------------------------------- An object's type is a flag which can only be set when an object is created, and cannot be unset. It determines the effects of other flags and how the object interacts with other objects. The available object types are: [E]xit/Action (`@open`, `@action`) [F]orth (MUF) Program (`@program`) [P]layer (`@pcreate`) [R]oom (`@dig`) If an object doesn't have a type flag, it is simply a "thing" (`@create`), like a normal item in your inventory. ROOMS Rooms are objects which contain other objects and are interlinked with Exits. If a room is `@link`ed to another room or thing, objects will be moved to this location if they are dropped. This is referred to as the room's "drop-to" location. EXITS Exits, or "actions", are objects which bind other objects together. They are `@attach`ed to a "source" and `@link`ed to a "destination". An exit linked to a Room acts as a doorway to that room, and an exit linked to a Program acts as a way to run that program (this is why exits can also be called "actions"). A player can trigger an exit by typing its name as a command. If an exit's name is a semicolon-separated list, like "out;exit;ahead;north;n", any one of these words will trigger the exit. The server executes the exit with the highest priority, and, given more than one exit with the same priority, will execute the "closest" one, in the following order of preference: 1. exits on the current room 2. exits on objects in the player's inventory 3. exits on objects in the room's inventory 4. exits on the player 5. exits on any parent rooms, in environment chain order An unlinked exit can be stolen and linked by anyone, so you should reserve exits by e.g. linking them to `NIL`. PROGRAMS Programs are objects which contain code in Multi-User Forth. MUF is covered in detail in the MUF Reference Manual (`man`). PLAYERS AND THINGS Players are the objects which connected clients implicitly control. Otherwise, they are similar to things. If a thing is `@link`ed to a room, that room becomes its "home", which is which is where it naturally returns when it is sent there (like with `home`) --MUCKER LEVELS AND WIZARDS----------------------------------------------------- Certain flags, called Mucker levels, give players and programs additional permissions. Any Mucker level will allow you to create MUF programs with that level or lower, with differing restrictions. M[1] (apprentice) programs - can only interact with objects in the same room as the user running them - will always run with the permissions of their creator - have their creator's username prefixed to output from e.g. `NOTIFY` - cannot use `ADDPENNIES` - have an instruction limit (which is the same as the limit for programs in PREEMPT mode, usually around 20,000 instructions) M[2] (journeyman) programs remove most of M1's restrictions, but still have an instruction limit (usually around 80,000 instructions). M[3] (master) programs have no instruction limit at all. Additionally, some MUF primitives have specific Mucker level limitations, which are usually noted in their `man` section. [W]izard programs can use any primitives, including some very special and dangerous things. Wizard programmers still need any Mucker bit to create programs, but which one they are given doesn't matter. REALMS WIZARDS If the MUCK has the Realms Wizards feature enabled, the Wizard flag applied to a room will give the owner of the room Wizard-like control over objects within that room and its children. You should be wary of using this feature as a security measure. A Wizard inside a Realms Wizard's area can be given flags and locks, meaning they could set `X` on the Wizard, set their `@force_lock`, and then `@force` them, allowing the Realms Wizard to run arbitrary commands as a true Wizard. EXIT PRIORITY Mucker levels and Wizard can also be applied to exits, which increases their priority (if multiple exits have the same name, the highest priority exit will be used when that exit is invoked). --OTHER FLAGS------------------------------------------------------------------- Additional flags can be set on an object freely to impart special behaviours. They often do different things when applied to different object types. The flags are as follows: [A]bode (Room) allows the room to be a home for other objects [A]bate (Exit) lowers the priority of the exit [A]utostart (Fprogram) causes the program to be loaded and started with the MUCK [B]uilder (Player) allows the player to manipulate objects (`@create`, `@dig`, `@link`, `@open`) [B]ound (Room) disallows players from using exits attached to themselves [B]lock (Fprogram) causes the program to run to completion without multitasking (PREEMPT mode) [C]olor (Player) formats output given to the player's client with colours [C]hown_OK (other) allows anyone to take control of the object (`@chown`) [D]ebug (Fprogram) prints a stacktrace to anyone who uses the program [D]ark (Room) prevents players from seeing objects in the room that they don't own (does not apply to Wizards and the room owner) [D]ark (Player/thing) prevents players from seeing the object (Players are additionally removed from the `WHO` list) [G]uest (Player) signifies that the player is a guest [G]uest (Room) prevents Guests from entering the room [G]uest (Exit) prevents Guests from using the exit [H]aven (Room) prevents players from being killed in the room [H]aven (Player) prevents others from `page`ing the player [H]ardUID (Fprogram) causes the program to run as the owner of the trigger for the program rather than the user of the program. if the program is also SetUID, is owned by a Wizard, and its caller is another program, the program will run as the caller program. otherwise, SetUID simply overrides HardUID. [J]ump_OK (Room) allows players to `@teleport` to and from the room and use exits attached to objects in the room (as opposed to the room itself) [J]ump_OK (thing) allows the object to be moved by any program regardless of level [J]ump_OK (Player) allows the player to `@teleport` to and from rooms [K]ill_OK (Player) allows the player to be `@kill`ed [L]ink_OK (Room) allows exits to be linked to the room [L]ink_OK (Fprogram) allows the program to be triggered by any other program or action not owned by the owner of the program [O]vert (Room) bypasses Yield [Q]uell (Wizard) nullifies the effect of the Wizard flag [S]ilent (Player) prevents the player from seeing their owned objects' dbrefs, and their objects in Dark rooms [S]etUID (Fprogram) causes the program to run as the owner of the program rather than the user [S]ticky (Room) prevents the room from returning dropped items to its drop-to until all players leave [S]ticky (thing) causes the object to return to its home as soon as it is dropped [X]forcible (Player/thing) allows the object to be `@force`d by another object it is `@force_lock`ed to [X]press (Exit) allows the exit to match as a prefix to a player's command, like " and : [V]ehicle (thing) allows players to enter the object (by creating an exit linked to it) players inside the object will follow it when it moves between rooms [V]ehicle (Room) prevents Vehicles from entering the room [V]ehicle (Exit) prevents Vehicles from using the exit [V]iewable (Fprogram) allows the program to be `@list`ed even if you do not control it [Y]ield (Room) prevents matching exits higher in parent rooms, except for ones marked Overt [Z]ombie (thing) causes the object to relay messages it receives to its owner [Z]ombie (Room) prevents Zombies from entering the room [Z]ombie (Exit) prevents Zombies from using the exit ================================================================================ PROPERTIES Properties, or "props", (`@set`) are key-value pairs associated with objects and are organised into directories ("propdirs"). They're displayed like: 'path/to/key:value' Spaces can exist in property names, but by convention, underscores are usually used instead. ### Restricted Properties Properties whose directories or keys begin with certain sigils have different restrictions associated with them. Beginning with '_' or '%' may only be written by the object's owner. Beginning with '.' may only be written *or read* by the object's owner. Beginning with '~' may only be written by wizards. Beginning with '@' may only be written *or read* by wizards. All of these properties are only writeable by the object's owner: '_path/to/key:value' '_/path/to/key:value' 'path/to/_key:value' But this one is not restricted: 'path/_to/key:value' --REGISTERED NAMES-------------------------------------------------------------- Registered Names are aliases to dbrefs you can use to specify an object more quickly. They are stored in your player's '_reg' dir and can be created with `@register`. If your player has the property '_reg/test:#1234', you can use "$test" in commands to refer to the object '#1234'. "Global" Registered Names are given to #0 instead of a player. --PROPLISTS--------------------------------------------------------------------- Proplists (or simply "lists") are groups of properties which can be treated specially in programs as MUF arrays or MPI lists. When you make a list at e.g. 'path/to/list', it's stored as 'path/to/list#/1', 'path/to/list#/2', etc., with each numbered property corresponding to each line in the list. A value on 'path/to/list/' itself provides the list's length (i.e. 'path/to/list/:2') --VALUE------------------------------------------------------------------------- Objects can have a value (normally in "pennies"), stored in `@/value`. When you `@recycle` an object, its pennies are moved to your player. The number of pennies "in your inventory" is your player's value. Sometimes your character will find a penny on the ground while moving between rooms. Players can also be given money by other players or by programs. Commands can require pennies to use. Otherwise, they're mostly pointless. --LOCKS------------------------------------------------------------------------- Locks are properties that control who is permitted to interact with the object in certain ways. '_/lok' (`@lock`, `@unlock`) controls who can use the object (e.g. `get`ting a thing or moving through an Exit) '_/clk' (`@conlock`) controls who can `put` things in the object '_/chlk' (`@chown_lock`) controls who can `@chown` the object '_/lklk' (`@linklock`) controls who can `@link` to the object '@/flk' (`@force_lock`) controls who can `@force` the object '@/olk' (`@ownlock`) controls who can control the object '@/rlk' (`@readlock`) controls who can bypass read permissions for the object If you set a lock to 'me', only you (and objects owned by you, or a Vehicle that contains you) are allowed past the lock. If you set '*John', only the player John is allowed. (names are prefixed by *) If you set '~staff:yes', only objects with that property are allowed. The operators ! (not), | (or), & (and) may be used, parentheses may be used for precedence, and property values can contain * (wildcard). If a lock is set to a Program, the user will run the program on an attempt to pass the lock, and will be allowed if the program returns a truthy value. Since lock syntax lacks a simple "true" or "false", a common technique to set a lock that always fails or always succeeds is to set it to 'me&!me' or 'me|!me' respectively. --MESSAGES---------------------------------------------------------------------- Objects can be given various messages which appear to players for certain events. '_/de' (`@describe`) shown to players `look`ing at the object '_/ide' (`@idescribe`) shown to players `look`ing inside the object (as with a Vehicle) '_/sc' (`@success`) shown to players successfully using an object (e.g. `get`ting a thing or moving through an Exit) '_/osc' (`@osuccess`) shown to other players in the same Room '_/fl' (`@fail`) shown to players unsuccessfully using an object '_/ofl' (`@ofail`) shown to other players in the same Room '_/dr' (`@drop`) shown to players `drop`ping a thing, `drop`ping in a Room, arriving on the other end of an Exit, or being `kill`ed by a Player '_/odr' (`@odrop`) shown to other players in the same Room '_/do' (`@doing`) when applied to a player, shown next to the player in the `WHO` listing '_/pecho' (`@pecho`) when applied to a puppet, prefixes messages relayed from the puppet with the value '_/oecho' (`@oecho`) when applied to a vehicle, prefixes messages relayed from outside the vehicle with the value DETAILS Details ("looktraps") are "fake" objects in a Room. They can be looked at to get a message, but don't otherwise exist. They exist as properties inside the '_details' propdir of a room, and like Exits, they can have a semicolon-separated list of names in order to have multiple triggers. A Room containing the property '_details/tv;screen;television:The TV is showing nothing but static.' allows the player to ``` > look television The TV is showing nothing but static. ``` SUBSTITUTIONS Messages are dynamically formatted to include a player's name or pronouns if appropriate. The following specifiers are normally recognised: %a (absolute): 's, his, hers, theirs, its %s (subjective): , he, she, they, it %o (objective): , him, her, them, it %p (possessive): 's, his, her, their, its %r (reflexive): , himself, herself, themselves, itself %n (name): The first column is the default behaviour: using your player's name. The others are just examples. Other letters can be used for format specifiers, but they are neither defined by default nor likely to be used in messages you encounter. Capitalising the letter in the specifier will capitalise the first letter of the expanded pronoun. %% is always a literal %. --- For an example: if John (he/him) picks up a shiny rock which has the property: '_/osc:picks up the rock. It glimmers in %p hand.', the others in the room will see the pose: "John picks up the rock. It glimmers in his hand." --- Substitutions are supplied by properties attached to the player. A property (default 'sex', 'gender' on RaccMUCK) is assigned to your player to determine which set of pronouns to use. Then, substitutions can be placed in '_pronouns//'. For example, if your player has 'sex:male', you can set '_pronouns/male/%p:his' to customize the possessive substitution. If you set your 'sex' to male, female, or neuter, you will be assigned he/him, she/her, or it/its pronouns respectively unless you override these defaults. Additionally, if you don't want to set a 'sex', you can place substitutions directly on the root of your character (e.g. '%s:they') --PROPQUEUES-------------------------------------------------------------------- Propqueues are properties which can trigger programs (both MUF and MPI) when certain events occur. To trigger a single program, a specially named property can be set to either a dbref to a MUF program or a string containing an MPI program prefixed with "&" (the string may contain no other contents). To trigger several programs, the property can instead be a propdir which contains a number of properties. The programs are run in alphabetical order by the names you give the properties. When an object triggers an event, its own propqueues can be triggered, as well as the propqueues of any objects up the environment chain. The names of the propqueues and when they trigger are as follows: '_arrive' '_oarrive' when moving into the room '_connect' '_oconnect' when connecting '_depart' '_odepart' when moving out of the room '_disconnect' '_odisconnect' when disconnecting '_lookq' when `look`ing '_listen' '~listen' '~olisten' when notified of any event The "o" variants set their triggered MPI to public, so others in the room can hear the output. They have no effect for MUF programs. Due to the possibility of abuse, '_listen' and variants can only trigger MUF programs which are Link_OK and have a certain Mucker level (default 3). Only the wizard-writeable variants can trigger MPI at all. Propqueues can trigger recursively, but only to 8 levels. --MPI--------------------------------------------------------------------------- MPI (Message Parsing Interpreter) is a Lisp-like interpreted language that can be used to give messages and propqueues dynamic contents. Unlike MUF, it can be used by all players. In messages, MPI can be freely interspersed with normal text. In propqueues, a single MPI program can be its only content, and it must be prefixed with "&". MPI is covered in detail in the MPI Reference Manual (`mpi`).