Overview (Programming)

<h1>Hell: a programmer's guide</h1>

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

%TOC%

---++ 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.

---+++#1 *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)= => ==OBJ== =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 =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.

---+++#3 *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)

  * *Output Verbs*
  * *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.

  * *Message Properties*
  * *Other Properties*
  * *Deprecated, Obsolete, and Unused Verbs and Properties*
     * =#3:old_look_self()=
     * =#3:$room:forbid_action_old()=
     * =#3:add_stub_room()= 

---+++#N *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.
  * *Verbs called by other automatic processes*
  * *Output Verbs*
  * *Player-Notifying Verbs*
  * *Transitive Verbs*
  * *Value-Retrieving Verbs*
  * *Message Verbs*

  * *Message Properties*
  * *Other Properties*
     * =#N.propertyname= *TYPE* description.
  * *Deprecated, Obsolete, and Unused Verbs and Properties*