coding.doc (no, wait!)

From: George (greerga@DRAGON.HAM.MUOHIO.EDU)
Date: 09/10/97

Got bored, decided to write something for coding.doc, what do you think?

diff -u ../doc/coding.doc ./coding.doc
--- ../doc/coding.doc   Tue Feb  6 15:24:02 1996
+++ ./coding.doc        Wed Sep 10 23:25:27 1997
@@ -299,7 +299,115 @@

 3. Adding Features
 3.1. Adding Commands
+       Adding commands to extend the CircleMUD world is extremely easy with a
+basic set of utility functions already created.  The first step is to decide
+what you want your function to actually do.  Once you've decided what you're
+going to have it do, you'll need a unique command word to type that will be
+used to invoke that function.  When you pick a word (we'll use 'test' for this
+example) you place it on a line as so in any existing CircleMUD .c file:
+       These three simple lines are currently your entire command.  The
+first line allows access to four variables, only two of which we need to
+be concerned with for this example.  'ch' is a pointer to the character
+who has invoked this command whether it be a switched mob or a player
+character.  The other useful variable is 'argument', a string containing
+whatever the character typed after the command.  If the person types
+'test this function' (don't worry about how we figured out test is this
+function, we'll go over that in a bit) then the variable 'argument' has
+" this function" in it, NOT "this function".
+       Once we have the basic framework up, we need to actually do
+something with this command.  The most typical thing we need to do here is
+to parse the arguments to figure out what they mean, assuming we have a
+function such as 'give' that expects something else, some do not.  To do
+that, we havee a handy function called skip_spaces() which strips all
+leading spaces from the string given.
+       Now that we have the argument, we want to split up the string into
+something manageable.  We do not have just one function for this, but three.
+If we only care about the first space-delimited field, then we use:
+one_argument(argument, buf);
+       or if we want two fields:
+two_arguments(argument, buf, buf2);
+       to get more than that, we use half_chop().  That isn't covered
+in this document but you can find an example on line 803 of act.wizard.c
+       Now that we have what was typed in the CircleMUD buffers (buf,
+buf1, buf2, or arg), we need to make sure there is something in there.
+if (!*buf) {
+  send_to_char("What should I do?\r\n", ch);
+  return;
+       If there is nothing in the variable 'buf' then we print a message to
+the character (ch) with the function send_to_char() and then exit.
+       For this example, we're just going to take the first word that
+the character types and send it back to them, saying hello.  So far we have:
+  skip_spaces(&argument);
+  one_argument(argument, buf);
+  if (!*buf) {
+    send_to_char("What should I do?\r\n", ch);
+    return;
+  }
+  /* Do stuff. */
+       To create the string, we're going to use sprintf() and think of
+send_to_char() as a puts() to that person. So using the global buffers:
+sprintf(buf1, "Hello, %s.  You typed %s!\r\n", GET_NAME(ch), buf);
+send_to_char(buf1, ch);
+       Notice the GET_NAME(ch), it is one of many helpful macros in utils.h
+to access various information about a character.  Then we send the string
+to the character and we're done with the function!
+       To actually let people access the command, we need to modify the
+master command list found at about line 196 of interpreter.c.  This is the
+structure searched everytime someone types a command.  Commands are
+searched in such a way that if you were to put 'lookie' above 'look' in
+the chart, you could never get to 'look' because the interpreter would
+always find 'lookie' first because it is an abbreviation of 'look' that
+the player typed.  Here, find a good spot to add the command, between
+teleport and thank looks good.
+  { "teleport" , POS_DEAD    , do_teleport , LVL_GOD, 0 },
+  { "test"     , POS_SLEEPING, do_test     , LVL_IMMORT, 0 },
+  { "thank"    , POS_RESTING , do_action   , 0, 0 },
+       The first entry is the name of the command.  It does not have to
+correspond with the name of the function although it is usually a good
+idea.  The POS_ entry means that we can only use this command if we are
+asleep, resting, sitting, or standing, we cannot use it when incapaciated
+or mortally wounded.  Most immortal commands are set to POS_DEAD so that
+they are always available.  The third entry is the name of the function
+you just added.  The fourth entry contains the lowest level allowed to use
+this command, here immortals.  The last field is used to allow one
+function to do many commands but it is normally not used and left at 0.
+Now just add a prototype for your function in the huge block of them at
+the top of interpreter.c and you have made a new command!
 3.2. Adding Socials
 3.3. Adding Spells
 3.4. Adding Skills

George Greer  -   | Genius may have its limitations, but stupidity | is not thus handicapped. -- Elbert Hubbard

     | Ensure that you have read the CircleMUD Mailing List FAQ:  |
     | |

This archive was generated by hypermail 2b30 : 12/08/00 PST