<html>
<head>
<title>The Daleken Event System</title>
<link rel="stylesheet" type="text/css" href="doc.css"
title="Documentation Standard Style">
</head>
<body bgcolor="#ffffff">
<table class="main" width="600" border="0">
<tr><td>
<div align="right">
DalekenMUD 1.12 documentation.
<br>Updated 7 June 2000.
<br>Symposium <<a href="mailto:mwt02@uow.edu.au">mwt02@uow.edu.au</a>>
</div>
</td></tr>
<tr><th class="heading">
<h1>The Daleken Event System - Coders Reference</h1>
</th></tr>
<tr><td>
<p>Events are a means of performing delayed actions on any object in the game.
The current system allows the addition of events onto the following objects:</p>
<ul>
<li>characters,</li>
<li>objects,</li>
<li>rooms,</li>
<li>areas,</li>
<li>planes,</li>
<li>voids (no type associated, you have to do the work)</li>
</ul>
<p>An event is a small object that contains a little information, after a
determined period, the event triggers and a callback function is called and
given the event information.</p>
<p>Events have three data fields for use of the callback function:</p>
<blockquote><code>
char *text;
<br></br>int data[ MAX_EVENT_DATA ];
<br></br>TARGET_TYPE extra;
</code></blockquote>
<p>Events are linked into two lists, one on the target object and the other on a
global list. The global list is actually a hash table which allows faster
access to events when they are to trigger, (events are hashed on the time
that they are to trigger).</p>
</td></tr>
<tr><th class="heading">
<h2>Current Event Flags</h2>
</th></tr>
<tr><td>
<p>These modify the event somewhat, determining when it is saved and removed
etc...</p>
<dl>
<dt><code>EVENT_LOADING</code></dt>
<dd>
- this event is loading and not yet entered into the global hash table.
</dd>
<dt><code>EVENT_TEMPORARY</code></dt>
- this event doesn't save.
<dt><code>EVENT_DEATH_REMOVE</code></dt>
<dd>
- this event disappears when the target dies (at the moment this only applies
to characters/ mobiles).
</dd>
<dt><code>EVENT_NO_QUIT</code></dt>
<dd>
- the target cannot quit with this event on.
</dd>
<dt><code>EVENT_STACKABLE</code></dt>
<dd>
- multiple events of this type can be added.
</dd>
</dl>
<p>Each event type has flags that are added in the event_table, however
individual events may have different values for these flags. The final value
that is used is found by doing an exclusive OR (<code>^</code>) on the event
flags and the default flags from the table.</p>
<p>There are exceptions:</p>
<dl>
<dt><code>EVENT_LOADING</code></dt>
<dd>- shouldn't ever be on the table.</dd>
<dt><code>EVENT_STACKABLE</code></dt>
<dd>- only ever on the table as it is used to create events.</dd>
</dl>
</td></tr>
<tr><th class="heading">
<h2>Main Functions Used By Events</h2>
</th></tr>
<tr><td>
<dl>
<dt><code>int get_time_left args( ( EVENT *e, int type ) );</code></dt>
<dd>
Goes through the events from e and returns the time left on the first one
with the specified type, returns -1 if the type doesn't exist.
</dd>
<dt><code>void strip_events args( ( EVENT **list, int type ) );</code></dt>
<dd>
Removes all events of type 'type' from the list.
</dd>
<dt><code>EVENT *create_char_event args( ( CHAR_DATA *ch, int type,
int delay ) );</code></dt>
<dt><code>EVENT *create_obj_event args( ( OBJ_DATA *obj, int type,
int delay ) );</code></dt>
<dt><code>EVENT *create_room_event args( ( ROOM_INDEX_DATA *room, int type,
int delay ) );</code></dt>
<dt><code>EVENT *create_area_event args( ( AREA_DATA *area, int type,
int delay ) );</code></dt>
<dt><code>EVENT *create_plane_event args( ( PLANE_DATA *plane, int type,
int delay ) );</code></dt>
<dt><code>EVENT *create_typeless_event args( ( EVENT **list, void *vo,
int type, int delay ) );</code></dt>
<dd>
Creates a new event for the target with the specified type and delay.
This also adds the event into the global hash, use this function to
create the event, then you can modify the returned event's extra data
fields to suit.
</dd>
</dl>
</td></tr>
<tr><th class="heading">
<h2>Creating A New Type Of Event</h2>
</th></tr>
<tr><td>
<ol>
<li>Add to event.h:
<blockquote><code>
extern int evn_***;
<br></br>DECLARE_EVENT_CALLBACK( ecb_*** );
</code></blockquote></li>
<li>Add the event number global to callback.c
<blockquote><code>
int evn_***;
</code></blockquote>
<li>Add a row to event_table in callback.c
<blockquote><code>
{ "name", &evn_***, ecb_***, <flags> },
</code></blockquote>
<flags> is an OR'ing of any flags you require for all events.</li>
<li>Define the function <code>ecb_***()</code> somewhere in
<code>callback.c</code>. here are examples in this file of how events can
be used.</li>
<li>Now all you have to do is create events, using
<code>create_***_event()</code> at the right times.</li>
</ol>
</td></tr>
</table>
</body>
</html>
