/[adonthell]/doc/architecture/mod_event.tex
ViewVC logotype

Diff of /doc/architecture/mod_event.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.1 by ksterker, Mon Nov 15 09:05:15 2004 UTC revision 1.2 by ksterker, Tue Mar 8 09:46:02 2005 UTC
# Line 1  Line 1 
1  \section{Event Module}  \section{Event Module}
2  \thispagestyle{empty}  \thispagestyle{empty}
3    
4  For efficiency, all game related tasks performed by scripts or the engine itself should be event-driven. That way, actions -- which are usually written in Python -- are only executed when needed.. Given that it is rather costly to call a Python method from C++ only to check a condition or to increase a counter, an integrated event dispatcher is a must to improve overall performance.  For efficiency, all game related tasks performed by scripts or the engine itself should be event-driven. That way, actions -- which are usually written in Python -- are only executed when needed. Given that it is rather costly to call a Python method from C++ only to check a condition or to increase a counter, an integrated event dispatcher is a must to improve overall performance.
5    
6  \subsection{Event Handling}  \subsection{Event Types}
7  To make event handling even more efficient, there isn't a single event manager to take care of all events. Instead, one can write specialized manager classes for each type of event. These must be derived from {\tt manager\_base} and registered with the generic {\tt manager} that will pass on events accordingly. This generic manager also provides the interface other modules require to dispatch events, completely hiding the specialized managers to the outside.\\  Since events are closely connected to the module they come from (\texttt{map\_events} from the map module, \texttt{quest\_events} from the rpg module, etc. \ldots), they cannot be hard coded into the event module to avoid mutual dependencies. Instead, they have to be registered at runtime, when loading the module containing them. This is done by the \texttt{event\_type} class, which keeps track of all registered types of events and assigns them a unique id for faster access. To register events, they need a unique name, an event manager as described below and a method returning a new instance of this event. Latter can be created by the \texttt{NEW\_EVENT()} macro.
8    
9  In order to get notified of events, a {\tt listener} needs to be created and registered with the manager. If an event occurs, all matching listeners are activated, resulting in the execution of the Python callbacks they provide. Each callback will receive a pointer to the listener itself, to the triggering event and, optionally, further user defined arguments. Latter are specified when connecting the callback to the listener, but can be easily changed from within the callback -- as the callback itself. User defined arguments are currently limited to integers and strings, as more complex objects cannot be saved when serializing a listener.\\  \subsection{Event Handling}
10    To make event handling even more efficient, there isn't a single event manager to take care of all events. Instead, one can write specialized manager classes for each type of event. These must be derived from {\tt manager\_base} and registered with the event subsystem that will pass on events accordingly. This generic manager also provides the interface other modules require to dispatch events, completely hiding the specialized managers to the outside.\\
11  If an object does not want to receive any events temporariliy, it can pause its listeners, thus avoiding the need to destroy them completely. Listeners can further have a repeat count, meaning they will destroy themselves after receiving a certain number of events.  
12    In order to get notified of events, a {\tt listener} needs to be created and registered with the manager. If an event occurs, all matching listeners are activated, resulting in the execution of the Python callbacks they provide. Each callback will receive a pointer to the listener itself, to the triggering event and, optionally, further user defined arguments. Latter are specified when connecting the callback to the listener, but can be easily changed from within the callback -- as the callback itself. User defined arguments are currently limited to integers and strings, as more complex objects cannot be saved when serializing a listener.\\
13  Since objects will often have several listeners for different events, a {\tt factory} can be used to group them together. Via the factory, all listeners can be paused or resumed, saved and loaded, thus removing the need to keep track of each individual listener.  
14    If an object does not want to receive any events temporariliy, it can pause its listeners, thus avoiding the need to destroy them completely. Listeners can further have a repeat count, meaning they will destroy themselves after receiving a certain number of events.
15  \subsection{Date and Time}  
16  Closely related to the event system is the game time, because many events in the game will be time based -- especially those required for implementing NPC behaviour.  Since objects will often have several listeners for different events, a {\tt factory} can be used to group them together. Via the factory, all listeners can be paused or resumed, saved and loaded, thus removing the need to keep track of each individual listener.
17    
18  Time in the game will usually differ from real world time and is measured by game cycles. As the number of cycles per second is constant, game time will progress at a constant rate too. For that, a call to {\tt date::update} after each cycle is required. Whenever a second of game time has passed (which is currently defined as five game cycles), a time event is dispatched.\\  \subsection{Date and Time}
19    Closely related to the event system is the game time, because many events in the game will be time based -- especially those required for implementing NPC behaviour.
20  The date class also provides fixed conversion methods to get the current weekday, day, hour, minute and second, based on a 7 day week, 24 hour day. In future, custom conversion rules might be made available to allow more unusual in-game date and time.  
21    Time in the game will usually differ from real world time and is measured by game cycles. As the number of cycles per second is constant, game time will progress at a constant rate too. For that, a call to {\tt date::update} after each cycle is required. Whenever a second of game time has passed (which is currently defined as five game cycles), a time event is dispatched.\\
22    
23    The date class also provides fixed conversion methods to get the current weekday, day, hour, minute and second, based on a 7 day week, 24 hour day. In future, custom conversion rules might be made available to allow more unusual in-game date and time.

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26