------------------------------------------------------------------------------
Title......: Mumps Scripting
Author.....: Axel (the Implementor 'of Code')
Started....: 2001-Jul-13
Last Change: 2003-Dec-16
------------------------------------------------------------------------------


conditions:
===========

  You are one of the few to be above or equal level 108 (Coder), or ...

  your character is above or equal level 104 (builder) and in addition is
  marked as a scripter. You are marked as a scripter, if '/access list' shows
  a '[mumps]' besides your name.



mumps quick:
============

  Mumps :) It is evil... and ugly :) But once you got to know it, you love it.
  Once you love it, you do not want to miss it. It is virtually the worst,
  which could happen to you, but now that you are here - sorry .)



you want it?
============

  It is easy really. Build a zone in our MUD, so we get to know you. Yes we
  all agree that is a waste for a coder. But then again, how else should we
  be able to decide to trust someone? At least he/she should show some basic
  interest in our game. And basic interest is best reflected in building .)

  Also you learn features of our MUD - good and bad. You learn what is annoying
  and what to watch out for. You see what is important when building rooms,
  mobiles and objects. A scripter is only half as good, if he did not get that
  experiences.

  In addition - go download mumps from http://www.freem.net and compile it.
  If you are not able to do so. Well sorry, but you are not the one we are
  looking for!

  Seriously I (Axel) would love to build some zones, but I am mostly stuck
  with stupid C coding. (and of course I dislike writing descs as most
  of you :)

  We try to promise you one thing - if you are done building your zone and
  are accepted as scripter, you can do the scripts for your own zone first.
  Of course scripts should fit into our scheme and they shall not be totally
  insane :)



your responsibilities:
======================

  So you are a scripter!

  You can rule the mud! If you are good, you can do virtually everything!
  Close to noone will be able to track down what you did. Well, that is the
  trust we put into _you_. Please do not disappoint it.
  
  Then again - you will be the one to code superb quests or situations. You
  will deliver a huge contribution to bring our MUD to life.

  If you are missing function-calls or anything else, contact Axel and we
  will try to find a solution as soon as possible.

  

mumps (long):
=============

  Mumps is the short for 'Massachusetts General Hospital Utility Multi-
  Programming System.' It is old and dates back to the 70ies, when PDP-11
  and IBM ruled.

  Mumps is a procedural, interpreted general-purpose programming language
  oriented towards database applications.  Its characteristic features
  are:
  - untyped variables, converted automatically between numeric and string;
  - multi-dimensional associative arrays;
  - persistent variables ("globals")
  - good string handling capabilities: better than BASIC,
    not as good as SNOBOL4 (e.g. no full regular expressions;)
  - "indirection:" can use strings computed at runtime as part of
    M program text;
  - built-in multiuser/multitasking support.


  Even if MUMPS is technically structured, it goes against the spirit of
  structured programming with commands reduced to a single letter whenever 
  possible, short variable names encouraged, and no white space.

  Syntactically MUMPS has only one data-type: strings. Semantically, the
  language has many data-types: Text strings, binary strings, floating point
  values, integer values, Boolean values. Interpretation of strings is done
  inside functions, or implicitly while applying mathematical operators. The
  conversion is done on-the-fly.



introduction:
=============

  Now that you are a scripter you got access to the '/mumps' command. Among
  several subcommands, the '/mumps'-command will take you into the mumps
  environment mode.

  Here, for instance, you can check the global variables by typing 'w', which
  is the abbreviation for 'write'. Per standard definition, write without
  arguments shows you the current set of variables, while write with an
  argument, shows you the value of the specified variable.

  Above was only for a start - at the beginning you will be mostly searching
  for available interface functions. You are able to do this by using the
  '/mumps grep <string>' command.

  Lets say, we want a character to do something. So after a lot of searching
  we try the keyword 'force':
  
  * 120> /mum gre force
  force^%char(ch,text)
         force player/mobile <ch> to execute command <text>

  movedly^%char(ch,dir,script)
         delayed-move character <ch> into the direction <dir>.
         (just as if the character would have been forced)
         Delayed in this context means, that it will be sent ASAP,
         but after the script has ended. That has the nice advantage, that
         an enter event is sent to the room.
         If given the mumps-<script> is executed just after moving the char.
         In this case, variables <who>, <dir> and <room> will be set.
         Returns the cookie pointer, or -1 on error.


  So for a test and while being in the mumps interpreter mode, we could do:

  d force^%char(me,"sit")

  and you will sit down. Oh btw, while being in the interactive interpreter
  mode and only there, <me> will always contain the instance number to your
  own character instance.



instances:
==========

  One of the key factors in implementing a scripting language in your MUD is
  the import/export of character/object/room instance pointers between your
  MUD's C-Code and the scripting language. (BTW, this is also the biggest
  possibility for nasty segmentation faults, but that we have mostly taken
  care of.) 
 
  An instance pointer is a number representing the absolute address in
  memory. It is usually refering either to a character or an object, in some
  few cases it could also refer to a room.
  
  Now everytime you want to tweak a player, a mobile, an object or a room, you
  need to give its instance number.

  It is possible to store variables to such instances, which is very useful
  for locks or state-identifiers. For instance:

  	mumps> s result=$$var^%char(ch,"name","axel")

  	mumps> /stat (mobile)
  	:
  	:
  	Master is: <none>, Followers are: <none>
  	AFF: SWIM
  	Move-cost-modifier: 0%.

  	Instance specific data:
	       name: "axel"

	mumps> w $$var^%char(ch,"name")
	==> "axel"

  Same works for objects and rooms. ($$var^%obj(), $$var^%room())


events:
=======

  Now the question is - 'How and when does the C-code call a script?'  We got 
  several events. Basically events trigger when 'stuff' happens. Events trigger
  when a character moves, an object gets dropped or the time changes. It is a
  complicated issue with many special cases.

  The are room-events and global-events. Room-events trigger to all instances
  in the room (like smth entering the room), while global-events cannot be
  tied to a certain room, but could basically trigger anything. (e.g. change
  of time) Therefore global-events should be used with care.

  Anyways, events are the interface between C-code and script. (for reference
  check: http://www.warpmud.org/download/scripting/event-hook-example.html)

  A short description, conditions and imported variables of events are decribed
  in (http://http://www.warpmud.org/download/scripting/mumps-events.txt)

  

scripting and editing:
======================

  For the scripter there three different script groups. Rooms, mobiles and
  objects.

  Each of them you can edit by their relating command. So if you want to edit
  the current room you type '/room script', if you want to edit mobile 15, you
  type '/mobile 15 script' and if you want to edit object 11, you type '/object
  11 script'.

  In a script we got labels and code. Labels are at the beginning of each
  line. If there is no label in a line, at least a space, better a tab, should
  be there instead. (labels should not be longer than 8 chars)
  
  The label in the first line should be the same as the script name. Mumps
  people also call the script a 'routine'. The script name is a composition of
  a keyword and the virtual number. For instance, mobile 15 got the script name
  'mob15', while object 11 got the script name 'obj11' and the room 120, got 
  the script name 'ro120'.

  All other labels are either an entry for an event or solely used by the
  current script. It is up to you not to mess up normal labels and those,
  which represent events.
  
  I pasted an example script below. It is the script to object 809 - a broom.
  You are able to edit it by doing '/obj 809 script'


  obj809  ; broom script ; Axel 2003-Jan-21
        q
  tryflee;
	n room,err
	;--- quit, if you are not wearing/holding it
        i who'=$$wornby^%obj(me) q
	;--- put broom on the floor
	s room=$$room^%char(who)
	s err=$$toroom^%obj(me,room)
	;--- messages
	d sendchar^%comm(who,"You panic and attempt to flee!"_$c(10,13))
	d sendchar^%comm(who,"Not being able to keep your..."_$c(10,13))
	d room^%act("$n panics and attempts to flee.",1,who,0)
	d room^%act("$n is unable to hold to %s broom and falls down.",1,who,0)
	s override=1
	q
	[...]


  So the first line showed the name of the script and the label 'tryflee',
  represents an event. By saving, the script is parsed and eventually events
  (labels), are added to the relating instances. If a saved script is empty,
  the relating code is removed from the disc!

  Anyways, if someone tries to flee and the relating object is in the room -
  the C-code will call the label 'tryflee' and execute the cide. After the 'q'    for quit, the code will return to the MUD C-code.

  We got some special variables. Most important is the variable 'override'. If
  an event is overridable and the variable 'override' is set to one, the
  relating event is overridden. That means, after return from the script, the
  C-code will take care that all the follow-ups code after the script execution   will not take part - e.g. moving a character.


conventions/ specialities/ oddities:
====================================

  - max size of strings is 255 chars; we have to live with it.
  
  - First line of a script should consist of the scriptname and some additional
    information: scriptname<tab>;<your_name> <date>: <info> <debuginfo?>

    Example: (first line of a script)

	mob699	; Axel 2003-Mar-11: Hunter mobile $axel$


    Normal scripts (room, object, mobile) are saved to disk in following way:

    description          |  filename                |  scriptname 
    ---------------------+--------------------------+------------
    room with vnum 121   |  mumps/rooms/ro121.m     |  ro121
    object with vnum 9   |  mumps/objects/obj9.m    |  obj9
    mobile with vnum 699 |  mumps/mobiles/mob911.m  |  mob699

    This is interesting, because the first 8 characters in the first line of a
    script should represent the script name. (the extension .m is disregarded)

    So 'mob699' is the scriptname in our example above. A <tab> follows to
    fill up the 8 first chars and then a semicolon ';', which signalizes that
    the following text is a comment and shall not be interpreted.

    Next is character name of the scripter. Following this we got the creation
    date in YYYY-MON-DD notation. After that comes a short description.

    The $<charname>$ in the first line of a script signalizes that if an
    error occurs, no global error warning is shown (everyone would see it),
    but instead it is only sent to the relating character, if that person is
    online. 
    
  - first 8 chars (first tab) of each script should be either:

	* script name (e.g. mob699)
	* a label (e.g. loop)
	* empty (tab)

  - This is very important! Make sure, that you do not mess up 'normal'-labels
    and event-hooks. Check 'help mumps-events' or the relating file on our
    website to find out what labels should be reserved as event-hooks.
    
    This is important, because if you use an event-hook-keyword as label
    (e.g. enter, extract), then the given event would be hooked and next time
    it occurs, your script will be called, eventhough you did not want that.

  - limit the line size to 80 chars! It is ok, if it sometimes gets a few
    chars longer, but in general you should stick to 80 chars max per line!


the end:
========
  
  That it is for now! This text is meant as a quick intro to scripting and of
  course cannot come up to the level of a verbal introduction, but it should be
  able to give a first impression.


-Axel