CODE RFC Room Programming Design

From: Gary Barnett (gbarnett@polarnet.com)
Date: 10/08/96


I am creating a room programming system for AntaresMUD.
Here is the design document.

I am soliciting ideas, suggestions or constructive criticism.

The source will be posted to the circle ftp site when it is completed.

Please no flames on modeling it after BASIC.. I needed simple.. So it could
be finished in this lifetime :-)

Design Requirements: Interpreted language for rooms (and later mobs and objs)
that would be flexible, simple to learn (and debug), and as fast as possible.
This system must allow online entry via OLC.. and dynamic program replacement,
so a reboot will not be required. Also a means of reporting syntax errors at
the time of entry will be included.

Room Program Types:

ENTER  -- Fires every time a mob or PC enters the room
LEAVE  -- Fires every time a mob or PC leaves the room
TIME   -- Fires every time_tick (every second)
SPEECH -- Fires whenever something is said in the room
           (must be a public command: say, talk, shout, lsay, ltalk)

Program Structure Keywords

 IF             - The standard decision support. Can test for equality
 THEN             '=', greater than '>', less than '<' or not equal '!'
 ELSE           
 ENDIF 
                -- examples -- 
    (boolean)   IF QBIT(CAUSER, 1) = TRUE THEN    
    (greater)   IF CHARS[CAUSER].MaxHit > 25 THEN
    (equal)     IF CHARS[CAUSER].Level = 4 THEN
    (Not equal) IF CHARS[CAUSER].MaxHit ! CHARS[CAUSER].CURR_HP THEN

 FOR I = ? to ? - Used primarily to step through a list of people
 EXIT             to do some nasty effect to them.. or just move
 NEXT             them around..or step through a list of items to
                  damage them *grin*

 INTERVAL  - Used to set how often the program runs. (one second granularity)
             The first line of a TIME proram must be:
             INTERVAL <val>  Val must be in the range of 1-99.
             This is the number of seconds between 'runs'.
             NOTE: Setting the number too low will probably waste more CPU
             cycles than the rest of your programs combined.. Set it as high
             as possible, while still allowing your program to do what you 
             intend. Don't use this for repopping items.. Wait for the zone
             programs.

 RETURN    - Done.. End the program. Not required at the end of the program.

 RESTART   - Clear all local vars and start at the top.

 RUN       - End this program, and Run another room's room program. 
 CALL      - Run another room's room program, then restart this
             program when it finishes (this will clear local vars)
             (I know .. it's lame.. but it will fill the bill.. Plenty of
             ABITS .. and they are cheap.. at one bit each )

Commands
 OBJ      - Create an object on the ground.
 MOB      - Create a mob.
 OBJTOPC  - Create an object and give to PC X
 OBJTOMOB - Create an object and give to Mob X
 OBJEQ    - Create an object and make Mob X wear it.
 OBJREM   - Remove an Object from a player or the ground.
 MOBREM   - Remove a mob from the game.
 KILLPC   - Kill a Player (DT)

 MOVE     - Move a mob or player to room x. (RNUM)

 FORCE    - Send a command, as the MOB/PC.. (This command is used
            to 'make the game think the player typed something'
            e.g. FORCE CAUSER "LOOK" With creative use of this and
            timed events, the mud can do a good bit of the work
            for us..
 SET      - Used to change information in the ABIT, QBIT and the
            rest of the data structures. e.g. SET CHARS[CAUSER].MAXHIT +=100
            (C style +=, -= is only supported in the SET command)
            (Set cannot be used to change the value of the index
             variable (I%). Only a for/next loop modifies the value of I%)

 CVTRV    - Convert Real Number to Virtual number RNUM->VNUM
 CVTVR    - Convert Virtual Number to Real number RNUM<-VNUM

 SPRINT   - Build a string from text and character/player info
            -- example --  
            SET A$ = CHARS[CAUSER].name
            SPRINT H$, "Your name is A$") 
            ECHOPC CAUSER H$

 ECHO      - Send a string to all chars in the room. (A$-H$)
 ECHOXMOBS - Send a string to everyone in the room except mobs.
 ECHOXPCS  - Send a string to eveyone in the room except Players.
 ECHOBUTM  - Send a string to everyone except mob X
 ECHOBUTP  - Send a string to everyone except player X
 ECHOMOB   - Send a string to a particular MOB in the room.
             Handy to fire a mob's speech program.. Basic method
             for room->mob interaction.
 ECHOPC    - Send a string to a particular Player in the room.
 INFO      - Send a string to the INFO channel.

 Constants:
 TIME      - The current time (0 - 28)
 THISROOM  - The number of the room.. Used for ROOM[] structure. (rnum)
 NUMCHAR   - The number of players  in the room.
 NUMMOB    - The number of mobs in the room
 PCCAUSED  - A PC caused the event.. True/False
 CAUSER    - The number in the list of the mob/PC that caused the event.
 NUMPOBJS  - The number of objects the event causer has in inventory.
 NUMEOBJS  - The number of objects the event causer is wearing.
 LANGUAGE  - If this is a SPEECH program this will contain the language
             used, otherwise it will contain -1. 

 Data Structures:

 MOBS[] A list of the mobs in the room.
        .NAME     -- (RO) Mob's short description
        .VNUM     -- (RO) Mob's vnum
        .MAXHIT   -- (RO) Mob's max HP
        .MAXMANA  -- (RO) Mob's Max Mana
        .MAXMOVE  -- (RO) Mob's Max Move
        .HIT      -- (RW) Mob's current HP
        .MANA     -- (RW) Mob's Current Mana
        .MOVE     -- (RW) Mob's Current Move
        .DEFPOS   -- (RO) Mob's Default Position (standing, etc) 
        .POS      -- (RW) Mob's Current Position (standing, etc) 
        .FIGHTING -- (RW) True/False (setting to true will not do anything)
        .LEVEL    -- (RO) Mob's Level

 CHAR[] A list of all players in the room.
        .NAME     -- (RO) PC's Name (short desc if it's on)
        .CNUM     -- (RO) PC's Connection #
        .MAXHIT   -- (RW) PC's Max Hit Points
        .MAXMANA  -- (RW) PC's Max Mana
        .MAXMOVE  -- (RW) PC's Max Move
        .HIT      -- (RW) PC's Current HP
        .MANA     -- (RW) PC's Current Mana
        .MOVE     -- (RW) PC's Current Move
        .POS      -- (RW) PC's Current Position
        .FIGHTING -- (RW) True/False (setting to true will not do anything)
        .CURR_STR -- (RW) PC's Current Strength (as reported in Score)
        .REAL_STR -- (RW) PC's Native Strength (w/o equipment, str spell, etc)
        .LEVEL    -- (RO) PC's Level

 SKILLSM[] - The skill-list for the mobs in the room.
        .BACKSTAB   -- (RW) % learned (0 is not learned)
        ...
        .TRACK      
  
 SKILLSP[] - The skill-list for the players in the room.
        .BACKSTAB   -- (RW) % learned (0 is not learned)
        ...
        .TRACK      

 ROOM[] A list of all rooms in the game. 
       .NAME    - (RO) The name.. or title.. of the room.
       .VNUM    - (RO) The Room's VNUM
       .NORTH   - (RO) The RNUM of the room to the North
       .EAST    - (RO) The RNUM of the room to the East
       .SOUTH   - (RO) The RNUM of the room to the South
       .WEST    - (RO) The RNUM of the room to the West
       .UP      - (RO) The VNUM of the room to the Up
       .DOWN    - (RO) The VNUM of the room to the Down
       .DOOR_N  - (RW) Door Flag for North (-1 is no door,
       .DOOR_E  - (RW) Door Flag for East    0 is open,
       .DOOR_S  - (RW) Door Flag for South   1 is closed)
       .DOOR_W  - (RW) Door Flag for West
       .DOOR_U  - (RW) Door Flag for Up
       .DOOR_D  - (RW) Door Flag for Down
       .DARK    - (RO) The room is dark.
       .INDOORS - (RO) The room is Indoors.

 OBJ[]  A list of all the objs lying on the ground.
       .Name
       .Action
       .VNUM
       .VAL1
       .VAL2
       .VAL3
       .VAL4  

 WOBJS[] A list of all the objs the event causer is wearing. 
       .Name
       .Action
       .VNUM
       .VAL1
       .VAL2
       .VAL3
       .VAL4  

 EOBJS[] A list of all the objs the event causer is wearing. 
       .Name
       .Action
       .VNUM
       .VAL1
       .VAL2
       .VAL3
       .VAL4  

 ABIT() Players and mobs. Used to record information about mobs and
        player actions of a repetitive or temporary nature.. Designed
        as a temporary scratch pad for transport rooms, etc. Either
        ON or OFF. Values range from 1 to 16, 384. You must use the
        web page to get an ABIT assigned to your program. 
        Example: IF ABIT(CAUSER, 1) = FALSE THEN
                    SET ABIT(CAUSER, 1) = TRUE
                 ENDIF
     
 QBIT() Players only.. Quest Bits. Used to record a player's having
        completed a noteworthy event. Either ON or OFF
        Values range from 1 to 16,384. You must use the web page
        to get a QBIT assigned to your program. 
        Example:   IF PCCAUSED = FALSE THEN RETURN ENDIF 
                   IF QBIT(CAUSER, 1) = FALSE THEN RETURN ENDIF
                   IF QBIT(CAUSER, 2) = TRUE THEN RETURN ENDIF
                   IF NUMPOBJS = 0 THEN RETURN ENDIF
                   FOR I = 1 to NUMPOBJS
                      IF POBJS[I].vnum = 1101 THEN 
                         OBJREM 1101 I
                         OBJTO  1102 I
                         SET QBIT[CAUSER, 2] = TRUE
                         SET H$ = "Thanks for doing the quest!"
                         ECHOPC CAUSER H$                 
                         EXITFOR
                      ENDIF
                   NEXT
                 
       This is an example of a one time quest.. The player starts the
       quest via a different program and gets QBIT #1 set as a result
       The quest tells them to get obj 1101 and go to this room. 
       When they do, the room takes obj 1101 and gives them 1102
       and sets QBIT #2 true, so they can't do the quest over and
       over. Some QBITs will be reset when a player DTs and has the
       quest item(s) on them.

  RANDOM  -- Used to create a random number between x and y
          -- example -- A hidden trap.. ENTER_PROG
          IF PCCAUSED = FALSE THEN RETURN ENDIF
          IF ABIT[CAUSER, 3] = TRUE THEN RETURN ENDIF
          IF RANDOM[1,101] > CHARS[CAUSER].PERCEPTION THEN
              SET A$ = CHARS[CAUSER].Name
              SPRINT H$, "A$ fell into a hidden trap!"
              SPRINT G$, "You fell into a hidden trap!"
              ECHOALLBUTP CAUSER H$
              ECHOPC CAUSER G$
              SET ABIT[CAUSER, 3] = TRUE
          endif
          -- 
          In this program, a trap that you can fall in sets a bit on
          your character so that you can only fall into it once between
          renting.. Presumably you'd know where it was.. until it was
          moved... Players in the room could be set to know it was there
          as well.. 

Temporary Variables... used for program scratchpad and text output. 

(Integers are initialized to 0, and strings are initialized to "NULL")

 Variables: 

    string variables. (each string may store up to 255 chars):
    --- A$, B$, C$, D$, E$, F$, G$, H$
            
    I% is reserved for FOR/NEXT loops.

    integer variables. (Values range from -32K to 32K):
    --- J%, K%, L%, M%, N%, O%, P%, Q%, R%, S%, T%, U%, V%, W%, X%, Y%, Z%
    

Restrictions on code.

1) For Loops. 
   a) Cannot be nested
   b) Cannot be inside of an if/then construct.
2) If/then/else/endif statements.
   a) Cannot be nested.
   b) Can be inside a for/next loop.
2) No ability to store anything other than a TRUE/FALSE.. i.e. can't
   store the fact that 24 peaches have been bought.. at least w/o
   using 24 QBITS. The good news is that we can support around 50K QBITs
   per player before memory use starts to get excessive. (And PFILE size)
3) Recursion, Parenthesis, multiplication, division and the like are
   not supported.. If we identify a need for such, I will add it.
-- http://www.polarnet.com/Users/gbarnett/ -- telnet://mud.polarnet.com 4000 --

+-----------------------------------------------------------+
| Ensure that you have read the CircleMUD Mailing List FAQ: |
|   http://cspo.queensu.ca/~fletcher/Circle/list_faq.html   |
+-----------------------------------------------------------+



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