Overview (Programming)

This is currently under construction. It may be a little while before it's done. I'll make a post when it is.

References

Being a MOO, Hell is written in the MOO programming language.

There's a reference at http://www.hayseed.net/MOO/manuals/ProgrammersManual_toc.html written by the creator of it all himself. It is good to bookmark this if you aren't intimately familiar with it all, to look up things when you inevitably forget them. Even if you are intimately familiar with it all, it's handy.

Utilities

There are a number of handy objects that serve no purpose other than containing utility verbs to use in your programming. For more information on any of these, check the in-MOO help for each object. e.g. help $su.

Everyday

• $string_utils ($su): convert things to strings, parse strings, match strings, format strings, mess them around.
• $list_utils ($lu): arrange lists, mapping functions, assocation lists
• $match_utils: matches objects from strings, verbs from strings, e.g. "bob" > #808 (Bob Johnson)=
• $command_utils ($cu): handling match failures, reading input, suspending
• $code_utils: substitute (multiple string substitutions at once), corify_object (see if something has an $alias), task_valid (check if a task is running), check task owner, and verb & preposition stuff.

Less Common

• $building_utils: make exits, set names, :recreate
• $perm_utils: permissions checking and modification
• $english_utils: :quote(who, text) => 'who says, "text"', :article_for(string) > "a" | "an"
• $math_utils: trig, power, stats, fraction stuff, :random(n), bitwise arithmetic.
• $time_utils: convert times to and from different formats.
• $gender_utils: the standard genders, pronouns and conjugations. usually you don't need this; use $su:ps.
• $set_utils: treats lists as sets. does things like union, intersection, xor.

Rare

• $seq_utils: treats lists of integers as sequences. works better than $set_utils, for lengthy integer sets.
• $biglist: as the name implies, this is for working with representations of really, really big lists.
• $matrix_utils: treats lists as vectors or matrices
• $convert_utils: converts units to other units, degrees to decimal, rectangular to polar coordinates.

Internal

• $wiz_utils: mess with programmers, players, owners of objects.
• $object_utils ($ou): information on objects. parents, children, verbs, props, contents.
• $quota_utils: measuring objects, changing quotas, getting quota info, :bi_create() (a wrapper for create())
• $object_quota_utils: further quota stuff (no help, use @d)

Obsolete/Unused

• $lock_utils: old system of locking objects

The Hell Object Tree

The @tree command shows all descendants of an object in high-tech ASCII graphics. ObjectTree, on this wiki, shows the @tree of #1, the root class. You could open it in another window while you read this, if you like. It may be a little daunting, but if you follow the lines you'll notice that #1 itself doesn't actually have very many direct descendants. In fact, there are only about 60 of them. But first let's start with this, the object from which everything is descended.

The Root Class ($root_class)

Everything inherits the root class. If you understand the verbs (51) and properties (10) here, you have a jump start on everything else.

Server-called Verbs

• #1:initialize() - After every object is created, its initialize verb is called.
• #1:recycle() - After every object is recycled (deleted), its recycle verb is called.
• #1:match(STR string) => this, if string matches it. (see ProgMatching)
• #1:match_object(STR string [, OBJ who = player]) => OBJ this if string matches it or if string == "here", or who if string == "me". (see ProgMatching)
• #1:accept(OBJ enteringobj) => 1|0. check to see if this will accept enteringobj. :accept is always called by movement into an object. (see ProgMovement)
• #1:huh(STR verb, LIST args) - called when a player tried to use a verb that wasn't found anywhere. last-chance matching can be done here. (see ProgMatching)
• #1:init_for_core() - deletes any verbs with the word '(old)' in them; moves ":initialize(core)" to ":initialize". (I'm not sure why.)
• #1:_www() => *LIST* HTML describing <tt>this.

Verbs called by other automatic processes

• #1:on_spawn() => 0. does nothing. overridden by things like $npc. (see ProgNPC)

Output Verbs

• #1:notify(STR s) - send this non-VR (not in-game) output.
• #1:tell(STR s), #1:tell_lines(LIST strings) - send this VR (in-game) output. (if you can't decide what's VR output or not, post somewhere or ask someone.)
• #1:room_announce(args), #1:room_announce_all(args), #1:room_announce_all_but(args) - call the same verb minus 'room_' on this.location.
• #1:announce(), #1:announce_all(), #1:announce_all_but() - do nothing. this is overridden by things like $room.
• #1:tell_lines_suspended(LIST|STR lines) - call :tell for each line, suspend if needed

Player-Notifying Verbs

• #1:look_self() - tells player the description of this.
• #1:do_examine(OBJ examiner) - sends the details about this to examiner. relies on the examine_* verbs.
• #1:examine_names(OBJ examiner) => *STR* names/aliases of this in english. (see ProgExamine)
• #1:examine_verbs(OBJ examiner) => *LIST* strings that describe the verbs, in english, that examiner can use at the command line. (i.e. non-programatically). (see ProgExamine)
• #1:tell_stat() - tell player detailed information about this.

Transitive Verbs

• #1:set_name(STR newname) => *STR* the name set. Sets name of this to newname.
• #1:set_aliases(LIST alias_list) => 1|0, sets this.aliases to alias_list. 1 on success, 0 if not.
• #1:set_description(STR newdesc) => 1 or an error. sets this.description to newdesc. 1 on success. Used by @describe.
• #1:set_message(STR msg_name, STR new_value) 1|0|*STR*, sets the property this.(msg_name)_msg to new_value. Returns 1 if set, 0 if cleared, *STR* if there was some error. Used by @(msg_name).
• #1:moveto(OBJ newlocation) - wrapper for the server builtin function, move(). Moves this to newlocation. (see ProgMovement)
• #1:eject(OBJ victim) (aka #1:eject_nice(victim)) expels victim from this. sends the victim to its home, or if it has no home, $nothing, or $player_start if it's a player.
• #1:eject_basic(OBJ victim) same as above, but doesn't screw around (doesn't call moveto, just does it.)

Value-Retrieving Verbs

• #1:title() => *STR* the title of the object. (This currently returns the name of the object, but that can change.)
• #1:titlec() => *STR* the title of the object, capitalized.
• #1:description() => *STR* or *LIST* the descrption of the object. (Always call this instead of looking at .description, if you're getting a description to present to a player. It is handy and overridable.)
• #1:acceptable(OBJ enteringobj) => 1|0. returns the value that *:accept(enteringobj)* would return, but without triggering any messages. (see ProgMovement)
• #1:get_message(STR msg_name) => *STR* or *LIST* the contents of this.(msg_name)_msg.
• #1:contents() => *LIST* things inside of this, in-game (VR).
• #1:is_listening() => 1 if this can hear tells, 0 otherwise.
• #1:hidden_verbs(OBJ who) => *LIST* verbs defined on this and its parents that should not be listed by examine.
• #1:name() => *STR* this.name.
• #1:dname() => *STR* the name of this with a definite article attached. e.g. 'the thing'.
• #1:iname() => *STR* the name of this in indefinite form. e.g. 'a thing'.
• #1:area() => *OBJ* the area this is in. see $area.
• #1:aliases() => *LIST* this.aliases.
• #1:weight() => *INT* total weight of this.
• #1:controlled_by(OBJ who) => 1 if who owns this or is a member of a $gang that owns it. (see ProgGangs)
• #1:dnamec() => *STR* definite article + the name of this, all capitalized.
• #1:inamec() => *STR* indefinite article + this name of this, all capitalized.
• #1:plural_name([INT howmany 1]), aka #1:pname() > *STR* plural name of this, along with a number if howmany > 1.
• #1:occupants(OBJ what) => *LIST* the contents of this that are what. e.g. occupants($player) => players in this.

Message Verbs

• #1:wiki_msg() => *STR* the wiki url for more information on this object, if any.
• #1:look_place_msg() => *STR* this.look_place_msg, after being run through $string_utils:pronoun_sub.

Message Properties

• #1.phelp_msg *LIST* or *STR* Text to be shown to players when they type 'phelp this'.
• #1.wiki_msg *STR* A URL to a wiki entry about this.

Other Properties

• #1.aliases *LIST* The list of names other than the this.name (a built-in property) that this may be referred to as.
• #1.description *LIST* or *STR* A description of this.
• #1.object_size *LIST*, format {*INT* size_in_bytes, *INT* time_measured}, for keeping track of database size and usage.
• #1.hidden_verbs *LIST*, format {*STR* verbname1, *STR* verbname2, ..., *STR* verbnameN}, a list of verbs that should not be displayed to players when they use the 'examine' command. Verbs whose arguments are 'this none this' are hidden automatically and do not need to be in this list. (see ProgExamine)
• #1.weight *INT* the weight of this object in grams.
• #1.owner_verbs *LIST*, format same as .hidden_verbs, a list of verbs that should only be displayed to players who own the object. If verbs are listed in both properties, .hidden_verbs takes precedence. (see ProgExamine)
• #1.plural_name *STR* The plural name of this object. If "", an 's' is tacked on to the end of this.name.

Deprecated, Obsolete, and Unused Verbs and Properties

• #1:examine_desc(OBJ examiner) *(DEPRECATED)* > *LIST* description of this= as seen by someone examining it. (see ProgExamine)
• #1:examine_contents(OBJ examiner) *(DEPRECATED)* => sends examiner the contents of this as seen while examining. (see ProgExamine)
• #1:examine_verb_ok(OBJ loc, INT index, LIST info, LIST syntax, INT commands_ok, LIST hidden_verbs) *(UNUSED?)* => 1|0. I have no idea. Refers to a non-existent verb ':commands_ok'.
• #1:is_unlocked_for(OBJ what) *(OBSOLETE)* - checks to see if what passes this.key.
• #1.key - *(OBSOLETE)* - used for old-style locking.

The Generic Room ($room)

Every room in the MOO is descended from the Generic Room. It contains 84 verbs and 62 properties. Much important code is stored here.

Server-called Verbs

• #3:confunc() - player calls this verb automatically when they connect. It shows them their status and announces the connection.
• #3:disfunc() - as above, for disconnections. announces the disconnection to the room.
• #3:match_exit(STR text) => *OBJ* an exit in this that has a name or alias that matches text. (see ProgMatching)
• #3:enterfunc(OBJ thing) - called whenever an object enters this. shows a description, handles tracking, biohazards, etc. (see ProgMovement)
• #3:exitfunc(OBJ thing) - called whenever an object exits this. handles tracking etc. (see ProgMovement)
• #3:recycle() (passes to #1:recycle()) - moves objects out of this before it is recycled, and recycles exits along with this.
• #3:match(STR text) => *OBJ* an object in this that has a name or alias that matches text. (see ProgMatching)
• #3:here_huh(STR verb, LIST args) => 1|0, called when a player in the room types something that is not a verb, returns 1 if an exit was found that matches the input, or 0 otherwise. (see ProgMatching)

Verbs called by other automatic processes

• #3:broadcast_event(INT is_start, OBJ action, OBJ source, LIST callback_args) - tells all event-listening objects in this about an event. (see ProgEvents)

Player Verbs

• #3:say any any any - calls player:say with the same arguments.
• #3:emote any any any - announces emotes to the room.
• #3:go any any any - moves player in the specified direction, if possible.
• #3:"e east w west s south n north ne northeast nw northwest se southeast sw southwest u up d down in out" none none none - moves player in the direction specified or adds the move to his/her queue.
• #3:"cover hide" none none none - queues the cover action for players. (see ProgActions)

Player-Notifying Verbs

• #3:announce(*STR* or *LIST* text) - tells text to each object in the room *except* player.
• #3:announce_all(*STR* or *LIST* text) - tells text to every object in this.
• #3:announce_all_but(*LIST* ignore, *STR* or *LIST* text) - tells text to every object in this that is not in ignore.
• #3:look_self(*INT* brief) - tells player what this looks like. furniture, exits, contents, map, and description are all included, if brief, then show only a short form of the description.
• #3:tell_contents() - tells player about the objects in this.
• #3:room_announce*_all_but(args) - calls the verb on this by the same name as this verb minus 'room_', e.g., room_announce(args) results in announce(args).
• #3:list_exits() - tells player a brief list of exit names in this.

Transitive Verbs

• #3:add_exit(*OBJ* exit) => 1|0, 1 if the exit was successfully added, 0 otherwise.
• #3:remove_exit(*OBJ* exit) => *LIST* the list of exits of this after the removal of exit.
• #3:recalc_next_hops() => *LIST* the areas other than this:area() that exits in this will go to. Recalculates all next hop data for each exit in this. (see ProgMapping)

Value-Retrieving Verbs

• #3:exits() aka :entrances() => *LIST* the exits in this.
• #3:acceptable() => *INT* 1. Supposedly returns what :accept() _would_ return, but just returns 1.
• #3:obvious_exits() aka :obvious_entrances() => *LIST* the obvious exits in this.
• #3:examine_commands_ok(*OBJ* x) => 1|0, 1 if x is in this. (see ProgExamine)
• #3:examine_contents(*OBJ* who) => *LIST* the contents of this, if this called the verb. (see ProgExamine)
• #3:player_integration_msg([*LIST* who]) => *STR* an english sentence describing the players/creatures in the room and what they're doing, or if provided, a sentence describing only the creatures in who. used by :look_self.
• #3:next_hop_to(*OBJ* where) => *OBJ* exit that you can take to get to where (a room or area), or #-1 if there's no way. Does not work for places that are more than two areas away. (see ProgMapping)
• #3:destinations() => *LIST* all destinations that can be arrived at via exits in this.
• #3:title() (overrides #1:title()) => The name of this room and, if valid, the area it is in, in color.
• #3:building() => *OBJ* this.location if it is a $building, otherwise #-1.
• #3:description() (overrides or passes to #1:description()) => *LIST*. if this.outdoor or this.windows, returns the description plus this:time_msg() or this:time_windows_msg() as appropriate, as a list. otherwise returns this.description as a list.
• =#3:track_strength(*OBJ* who) (see ProgTracking)

Message Verbs

• #3:who_location_msg(*OBJ* who) - *STR* what the 'who' command should display as the location for players in this, run through $su:ps.
• #3:go_fail_msg() - *STR* this.go_fail_msg
• #3:time_msg() - *STR*, selects the proper day message from $time.day_segments. if this.[day_segment]_msg is a list, selects something randomly from the list to return; if it is a string, returns the string.

Deprecated, Obsolete, and Unused Verbs and Properties

• #3:old_look_self()
• #3:$room:forbid_action_old()
• #3:add_stub_room()

Object Name ($corified_name)

Description of the object.

Server-called Verbs

• #N:verbname() - Description of a verb that returns nothing.
• #N:otherverbname(*TYPE* variable) => *TYPE* description of return value(s), other notes.

Other Properties

• #N.propertyname *TYPE* description.