MAJOR: 3.63 Pre-Release: Cedit Toggle for prot system, new skill, updated documentation, and more.

doc/dg_events.txt

@@ -2,12 +2,117 @@
 ************************************************************************
 *  File: events.doc *
 * *
+*  Usage: An explanation of how to use mud events *
+*  Written by Joseph Arnusch (Vatiken) (Joseph.Arnusch@gmail.com) *
+*
 *  Usage: An explanation of how to use events *
-* *
 *  Written by Eric Green (ejg3@cornell.edu) *
 ************************************************************************
 */
 
+Vatiken's MUD event system
+--------------------------
+
+Table of Contents
+-----------------
+1.  Purpose
+2.  Functions Related to MUD Events
+3.  Steps to Create a New MUD Event
+4.  Differences between the two systems
+
+1. PURPOSE
+
+I scribed a "MUD" event system using the "Death Gate Event" system already
+in place to allow for increased ease, and maintainability for both rookie
+and experienced programmers.
+
+2. FUNCTIONS RELATED TO MUD EVENTS
+
+ a) See EVENTFUNC() in the Death Gate Events documentation below
+ b) void init_events(void)
+    "init_events()" creates the global events list and is the allocated location
+    for placing any global events, these may include things like AI, Weather,
+    and Combat.
+ c) struct mud_event_data * char_has_mud_event(struct char_data * ch, event_id iId)
+    "char_has_mud_event()" returns an event in the characters event list that matches
+    the supplied "event_id", or NULL if none exists.
+ d) NEW_EVENT(event_id, struct, var, time)
+    "NEW_EVENT" creates a new event of the "event_id" type, with the supplied structure
+    (ch, desc, object, etc..), any addtional "var"s, and is set to activate in
+    this amount of "time".
+ e) struct mud_event_list[]
+    The mud_event_list[] is an array of all the events you've designed into your MUD.
+    The reason for this excessive step is primarily for organization and troubleshooting,
+    and it takes a mere couple seconds to add to mud_events.c.
+
+3. STEPS TO CREATE A NEW MUD EVENT
+
+ a) Add the new event_id to enum list in mud_events.h
+
+  typedef enum {
+    eNULL,
+    ePROTOCOLS, /* The Protocol Detection Event */
+    eWHIRLWIND, /* The Whirlwind Attack */
+
+    eNEWEVENT   /* A NEW EVENT */
+  } event_id; 
+
+ b) Create the event
+
+  EVENTFUNC(new_event)
+  {
+    struct char_data *ch, *tch;
+    struct mud_event_data *pMudEvent;
+    struct list_data *room_list;
+    int count;
+	
+    /* This is just a dummy check, but we'll do it anyway */
+    if (event_obj == NULL)
+      return 0;
+  
+    ...	  
+
+    return 0;
+  }
+
+ c) Add the event_id data to mud_event_list[]
+
+  struct mud_event_list mud_event_index[] = {
+    { "Null"         , NULL           , -1          },  /* eNULL */
+    { "Protocol"     , get_protocols  , EVENT_DESC  },  /* ePROTOCOLS */
+    { "Whirlwind"    , event_whirlwind, EVENT_CHAR  }   /* eWHIRLWIND */
+
+    { "A New Event"  , new_event      , EVENT_CHAR  }   /* eNEWEVENT */ 
+  };
+
+ d) Place a call for the new event
+
+  if (variableX > variableY)
+    NEW_EVENT(eNEWEVENT, ch, NULL, 60 * PASSES_PER_SEC);
+
+ e) Sit back and enjoy your event triggering in 60 seconds.
+
+4. DIFFERENCES BETWEEN THE TWO SYSTEMS
+
+The biggest differences between the two systems is that the MUD Event System 
+employs certain functions to make it more "dummy proof" without limiting
+functionality.
+
+For example:
+ a) all memory allocated for a MUD event will be freed when the event
+    is no longer in use.
+ b) the mud_event_index[] can/will log when events are called, allowing for an
+    easy way to debug any problems.
+ c) the mud_event structure allows for easy handling of memory that shouldn't
+    be freed with the event like the character him/herself.
+ d) when a character leaves the game, all mud_events will be cleared without
+    manually having to place checks in free_char().
+
+The "MUD Event" system should be adequate for 99% of all events that a developer
+may be interested in creating, and still allows access the dg_event event system
+for anything requiring more complicated procedures.
+
+========================================================================
 
   		  Death Gate Events
 
@@ -195,7 +300,3 @@ Tips for creating events:
  o Any place a game object is extracted from the game, any events it points to
    should be canceled and its pointer to the events set to NULL.
 
-
-
-
-