[Adonthell-commits] CVS: adonthell/doc/devel gametime.dxt,NONE,1.1.2.1 event.dxt,1.1,1.1.2.1 mainpage.dxt,1.3,1.3.2.1 mapcharschedules.dxt,1.1.2.1,1.1.2.2 reference.cfg,1.3.2.1,1.3.2.2

[Kai Sterker <address@hidden>]

Update of /cvsroot/adonthell/adonthell/doc/devel
In directory subversions:/tmp/cvs-serv19409

Modified Files:
      Tag: Branch_road_to_0-4
        event.dxt mainpage.dxt mapcharschedules.dxt reference.cfg 
Added Files:
      Tag: Branch_road_to_0-4
        gametime.dxt 
Log Message:
UPDATED event docs
ADDED gametime docs
FIXED character schedule docs


***** Error reading new file: [Errno 2] No such file or directory: 
'gametime.dxt'
Index: event.dxt
===================================================================
RCS file: /cvsroot/adonthell/adonthell/doc/devel/event.dxt,v
retrieving revision 1.1
retrieving revision 1.1.2.1
diff -C2 -r1.1 -r1.1.2.1
*** event.dxt   15 Oct 2001 15:00:06 -0000      1.1
--- event.dxt   17 Jun 2002 21:17:54 -0000      1.1.2.1
***************
*** 2,6 ****
     $Id$
  
!    Copyright (C) 2001   Kai Sterker
     Part of the Adonthell Project http://adonthell.linuxgames.com
  
--- 2,6 ----
     $Id$
  
!    Copyright (C) 2001/2002 Kai Sterker <address@hidden>
     Part of the Adonthell Project http://adonthell.linuxgames.com
  
***************
*** 15,28 ****
  /*! \page page3 The Event System
   
!  The %event system is divided into three parts. The %event handler
!  keeps track of all registered %event scripts. Whenever an
!  %event occurs, the %event handler is notified and executes
!  all scripts registered for that particular %event. The %event
!  list keeps track of the %events registered by a certain %object,
!  (e.g. a NPC, a maptile or item) and automatically unregisters
!  these %events when this %object is deleted. Finally, there
!  are the %events themself, used both as message sent to the
!  %event handler whenever an %event occurs and to register an
!  %event script. Each %event has its own data structure with
   parameters corresponding to its type. These parameters are
   passed to the %event script, so all infomation regarding
--- 15,28 ----
  /*! \page page3 The Event System
   
!  The %event system is divided into three parts. The \ref event_sec1 
!  keeps track of all registered %event scripts. 
!  Whenever an %event occurs, the %event handler is notified and executes
!  all scripts registered for that particular %event. The \ref event_sec2
!  keeps track of the %events registered by a certain
!  %object, (e.g. a NPC, a maptile or item) and automatically unregisters
!  these %events when this %object is deleted. Finally, there are the 
!  \ref event_sec3 themself, used both as  message 
!  sent to the %event handler whenever an %event occurs and to register 
!  an %event script. Each %event has its own data structure with
   parameters corresponding to its type. These parameters are
   passed to the %event script, so all infomation regarding
***************
*** 31,44 ****
   reacts to a smaller range of %events.
  
!  \section event_usage Using the Event System
   
   The %event handler is implemented in the event_handler class.
   It totally consists of static members and methods, to make it
   easily accessible from any part of the code. Just include
!  the event.h file. To register a script with the handler that,
!  for example, is executed whenever the player arrives at the
!  coordinates (20, 20) of a map, you'd write:
  
!  \code
  // Create the filter and set it's parameters
  event *filter = new enter_event;
--- 31,147 ----
   reacts to a smaller range of %events.
  
! 
!  \section event_sec1 Event Handler
! 
!  The %event handler is the core component of the %event system.
!  It provides a method to initilize the %event system and allows
!  global access to the specialized handlers for individual events.
!  For that purpose, it stores a list of event_handler_base %objects,
!  the virtual base class for the specialized handlers, and passes
!  any %event it recieves to the right handler.
!  
!  The %event_handler_base class provides three pure virtual methods
!  that need to be implemented by each specialized handler:
!  
!  - register_event() to pass a new %event to the handler. %Events
!    need to be registered with the handler before they can take
!    place
!    
!  - remove_event() to remove a previously registered %event from
!    the handler
!     
!  - raise_event() to send a message to the handler that will trigger
!    matching events. 
!  
!  
!  \section event_sec2 Event List
! 
!  The event_list is a convenience class for %objects that register
!  events with the handler. As it is up to each object to save the
!  events it registers, and to load and re-register them, the %event
!  list has been written to take care of that.
!  
!  To make the %event list independent from specific %event types,
!  it only works on pointers to the %event base class. That works fine
!  in all cases, except one. When loading events, the %event list needs
!  to instanciate the proper %event class. For that purpose, the %event
!  list stores a list of callbacks that return a newly instanciated 
!  %event of a given type. Two macros have been written that take care
!  of most of the work.
! 
! \code
! NEW_EVENT(evt)
! REGISTER_EVENT(type,evt)
! \endcode
! 
!  %NEW_EVENT() provides the function that will return a newly allocated 
!  %event. %REGISTER_EVENT() will pass this function to the %event list.
!  For each %event type, these two macros should be added to 
!  event_handler::init(), the %event system's init method. 
! 
!  The %event list provides the following methods:
!  
!  - event_list::add_event() adds an %event to the list and registers it 
!    with the %event handler.
!  
!  - event_list::put_state() saves the list with all events inside.
!  
!  - event_list::get_state() restores the list with all events and registers 
!    them with the %event handler.
!  
!  
!  \section event_sec3 Events
!  
!  Events have two main purposes. Registered with the %event handler,
!  they allow to execute either a %python script, a %python or a C/C++
!  callback in case that %event takes place. But they are also sent
!  as messages to the handler, to trigger matching events.
!  
!  Each specific %event may have its own %data fields and methods,
!  depending on its purpose. However, all events share a number of
!  common features, which are implemented by the %event base class.
!  
!  The first feature is the %event's action, i.e. what happens if that
!  %event is triggered. The %event class allows to attach a \link py_object
!  python script \endlink, a \link py_callback python callback \endlink 
!  or a C/C++ callback.
!  
!  C/C++ callbacks are only useful when the %game engine wants to make
!  use of the %event system internally. %Python callbacks allow scripts
!  like \link schedule character schedules \endlink to use the %event 
!  system. %Event scripts usually define the action of a certain class of 
!  events. For example an %event script might implement a trap that is 
!  activated whenever a %character steps on it. This 'trap' script can then 
!  be used by traps all over the place.
!   
!  Apart from the %event's action, the base %event class also provides
!  means to repeat events or prevent them from repeating. For example,
!  a trap might only work once. event::set_repeat() allows to specify
!  how often a %event repeats, while event::repeat() will decrease the
!  repeat count and return the number of repeats left.
!  
!  Further, the %event class has two pure virtual functions that need
!  to be implemented by the specific events. They are provided so
!  that (not so) specialized %event handlers may take care of different
!  %event types.
!  
!  - equals() is used to compare two events for 'equality'. The message
!    sent to the handler is compared to all registered events to see if
!    they match.
!    
!  - execute() is used once the %event is triggered and should executed
!    the %event's action.
!  
!  
!  \section event_sec4 Using the Event System
   
   The %event handler is implemented in the event_handler class.
   It totally consists of static members and methods, to make it
   easily accessible from any part of the code. Just include
!  the event_handler.h file. To register a script with the handler 
!  that is executed whenever the player arrives at the coordinates 
!  (20, 20) of a map, you'd write:
  
! \code
  // Create the filter and set it's parameters
  event *filter = new enter_event;
***************
*** 48,83 ****
  filter->c = data::the_player;
  
- // Create our arguments list that will be passed to the script
- // constructor
- PyObject * args = PyTuple_New (2);
- PyTuple_SetItem (args, 0, PyInt_FromLong (10));
- PyTuple_SetItem (args, 0, PyString_FromString ("2nd argument"));
- 
  // Set the script to be executed when the event occurs
! filter->set_script ("a_script", args);
  
- // We don't use our reference to the tuple anymore
- Py_DECREF (args);
- 
-  
  // Finally add the filter to the event list. This will register it with the 
event handler
  add_event (filter);
!  \endcode
   
   For a list of available events with their corresponding parameters
   see the \link event API documentation \endlink.
  
!  As you can see, you have the possibility to pass extra parameters
! (only integers or strings) to the script constructor. This list is
! customizable and you can define yourself which arguments should your
! event receive. Of course, when you set the arguments list from C++,
! you have to manually create a Python tuple, and don't forget to
! decrement it's reference count when you don't need it anymore. If you
! set your script from Python, things are of course much easier:
! 
  \verbatim
! filter.set_script ("a_script", (10, "2nd_argument"))
  \endverbatim
  
   Now we have registered an %event with the %event handler. But that alone
   won't get the %event triggered. So depending on its type, you'll have to
--- 151,205 ----
  filter->c = data::the_player;
  
  // Set the script to be executed when the event occurs
! filter->set_script ("a_script");
  
  // Finally add the filter to the event list. This will register it with the 
event handler
  add_event (filter);
! \endcode
   
   For a list of available events with their corresponding parameters
   see the \link event API documentation \endlink.
  
!  The %event script in that example could look as follows:
!  
  \verbatim
! class a_script:
!     # -- constructor
!     def __init__ (self, event, <additional arguments>):
!         # -- the event the script belongs to
!         self.myself = event
!         ...
! 
!     # -- method called when the event occurs, the parameters
!     #    depend on the type of the event
!     def run (self, submap, x, y, direction, character):
!         print "%s arrived at %i, %i" % (character, x, y)
  \endverbatim
  
+  As you can see, you have the possibility to pass extra parameters
+  to the script constructor. This is limited to strings and integers
+  though. When you set the arguments list from C++, you have to manually 
+  create a %Python tuple, and you should not forget to decrement its 
+  reference count when you are done with it. The following code could
+  be used for the example above:
+ 
+ \code
+ // Create our argument tuple that will be passed to the script constructor
+ PyObject * args = PyTuple_New (2);
+ PyTuple_SetItem (args, 0, PyInt_FromLong (10));
+ PyTuple_SetItem (args, 0, PyString_FromString ("2nd argument"));
+ 
+ // Set the script to be executed when the event occurs
+ filter->set_script ("a_script", args);
+ 
+ // We don't use our reference to the tuple anymore
+ Py_DECREF (args);
+ \endcode
+  
+  The script constructor would then recieve two additional arguments. 
+  This is useful to create generic scripts that can be customized at
+  runtime. To return to our old trap example, the amount of damage the
+  trap does could be specified for each trap in this way.
+  
   Now we have registered an %event with the %event handler. But that alone
   won't get the %event triggered. So depending on its type, you'll have to
***************
*** 101,141 ****
  
  The %event handler will then compare all %events of the given type with the
! message it recieved and execute the %event script of the matching %events.    
     
  
- \section event_new Defining new Events        
- Now that you know how events principly work, you might want to define your 
own.
- Doing so is quite easy. Take event as the base class, override it's methods 
with
- your own, and you're nearly done.
- 
- There is only one problem remaining: loading your %event from a file. The 
%event
- list is taking care of that. But to avoid additional dependencies between the
- %event system and your code, the %event list cannot know about your %event at
- compile time. Otherwise, each part of the engine using the %event system had 
to
- #include every other part doing so, which we'd like to avoid. Basically, this 
is
- no restriction, since the %event list knows the base class and, thanks to 
virtual
- methods, can handle any derived %event without problem. The only situation 
where
- this fails is when a serialized %event list needs to be loaded from disk 
again.
- To do so, the \link event_list::load loader \endlink needs to be able to
- instanciate every possible %event. The way to go is pretty clear now: we need
- a function that returns a newly allocated %event structure, and we have to
- pass that function to the %event list at runtime, before loading an %event of
- that type. Since these steps are the same for each %event, two macros have 
been
- defined:
  
! \code
! NEW_EVENT(evt)
! REGISTER_EVENT(type,evt)
! \endcode
  
! %NEW_EVENT() provides the function that will return a newly allocated %event,
! and %REGISTER_EVENT() will pass this function to the %event list. The only
! information the %event system needs to know apart from that is the numerical
! %event ID, i.e. its type. 
! 
! \section event_types List of existing events and their specificities
! Various types of events are defined in the %game engine, all
! inheriting from the event class.
  
- \subsection mapevents Map events
  There are 3 types of map events:
  \li enter_event, which are triggered whenever a %character enter a
--- 223,235 ----
  
  The %event handler will then compare all %events of the given type with the
! message it recieved and execute the %event action of events that match.       
  
  
  
! \section event_sec5 The Different Event Types
! Various types of events are defined by the %game engine, all
! inheriting from the event class defined in event.h.
  
! \subsection mapevents Map Events
  
  There are 3 types of map events:
  \li enter_event, which are triggered whenever a %character enter a
***************
*** 155,160 ****
      is triggered.
  
! When a map %event is triggered, the run () method of the Python script
  is called, with the arguments \e submap, \e x, \e y and \e name, which
  is the name of the mapcharacter that triggered the %event.
  */
--- 249,270 ----
      is triggered.
  
! When a map %event is triggered, the run ()method of the Python script
  is called, with the arguments \e submap, \e x, \e y and \e name, which
  is the name of the mapcharacter that triggered the %event.
+ 
+ Map events are repeated forever by default.
+ 
+ \subsection timeevent Time Event
+ 
+ The time_event can be used to track relative or absolute %game time.
+ Relative means, the %event will be triggered after a given amount of time
+ has passed, starting at the moment it is created. Absolute means a fixed
+ point in time, i.e. a certain hour at a certain day.
+ 
+ Time events are not repeated by default. They can be told to repeat though,
+ and it is also possible to specify the delay between two occurances.
+ 
+ Time events pass no arguments to the run() method of the Python script.
+ The script can easily get the current %game time from the gamedate class. 
+ 
  */

Index: mainpage.dxt
===================================================================
RCS file: /cvsroot/adonthell/adonthell/doc/devel/mainpage.dxt,v
retrieving revision 1.3
retrieving revision 1.3.2.1
diff -C2 -r1.3 -r1.3.2.1
*** mainpage.dxt        30 Dec 2001 12:11:40 -0000      1.3
--- mainpage.dxt        17 Jun 2002 21:17:54 -0000      1.3.2.1
***************
*** 48,51 ****
--- 48,52 ----
   these chapters are there to give a first overview how they work and interact.
        - \ref page3
+     - \ref page10
        - \ref page4
        - \ref page5

Index: mapcharschedules.dxt
===================================================================
RCS file: /cvsroot/adonthell/adonthell/doc/devel/mapcharschedules.dxt,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.2
diff -C2 -r1.1.2.1 -r1.1.2.2
*** mapcharschedules.dxt        16 Jun 2002 23:18:26 -0000      1.1.2.1
--- mapcharschedules.dxt        17 Jun 2002 21:17:54 -0000      1.1.2.2
***************
*** 18,23 ****
  \page page8 Writing character schedules
  
- \section mcharsched0 Introduction
- 
  Character schedules provide the means to give life to characters. 
  They define what NPCs will do all day long, allow them to dynamically
--- 18,21 ----
***************
*** 25,35 ****
  with as little work as possible, there are two kinds of schedules.
  
! The first kind will be called \e manager schedule. This schedule is
  unique for most, if not all NPCs. It describes what they should do
  in a given situation. However, it does not describe how to do it.
  
! This is the purpose of the second kind, the so-called \e activity
! schedule. Activity schedules describe a single activity as generic
! as possible, so it can be reused by all the different manager scripts.
  
  
--- 23,32 ----
  with as little work as possible, there are two kinds of schedules.
  
! The first kind is the so-called \ref mcharsched2 . This %schedule is
  unique for most, if not all NPCs. It describes what they should do
  in a given situation. However, it does not describe how to do it.
  
! This is the purpose of the second kind, the so-called \ref mcharsched3 . 
Activity schedules describe a single activity as generic as possible, 
! to be reused by different manager scripts and %characters.
  
  
***************
*** 62,66 ****
      # <description of parameters>
      def __init__ (self, character, <parameters>):
!         self.myself = character
          <initialisation>
  
--- 59,63 ----
      # <description of parameters>
      def __init__ (self, character, <parameters>):
!         self.myself = base.gamedata_get_character (character)
          <initialisation>
  
***************
*** 73,115 ****
  
  
! \section mcharsched2 The Manager Schedule
  
! The manager schedule is responsible for telling a character what to do
  in a given situation. When an activity has finished (and only then), 
! the manager schedule will be usually executed to decide upon the 
! character's next activity. Therefore, it's \c run method should consist 
  of a number of conditions that decide upon the activity script to use.
  
! Note that the current schedule is cleared before the manager schedule
  is executed. Therefore, it \b must set a new activity, otherwise the
! character will freeze (and the manager script will be called over and
  over again). The new activity can be set with the schedule::set_schedule ()
  method.
  
! The only way run the manager schedule is to quit the current activity.
  Everything else is taken care of automatically then.
   
  
! \section mcharsched3 The Activity Schedule
  
! The activity schedule tells a character how to accomplish its current
! task. Unlike the manager schedule, which is only executed to select a
  new activity, activity schedules are executed periodically; once per
! game cycle, i.e. about 75 times per second. Therefore, activity scripts
  should be made as efficient as possible. 
  
! For example, state variables of the character should be copied to local 
! variable in the __init__ method and written back by __del__ instead of 
! accessing them directly while the script runs. As long as those state 
  variables are only accessed by the manager script or a different 
! activity of the same character, this won't cause any problems.
  
  
  \section mcharsched4 Changing the current Activity
  
! Before a character's activity can be changed, the current one needs to
! be stopped first. Since life-like behaviour of characters depends on the
! interaction of many different activities, there are several ways to switch
! them.
  
  One thing all of them have in common is that the current activity must be
--- 70,123 ----
  
  
! The first argument passed to the class constructor is the name of
! the character the %schedule is assigned to. The following arguments
! are optional and can be different for each %schedule. All arguments
! passed to \c __init__ have to be integers or strings. More complex
! %objects are not allowed, as they cannot be saved (yet).  
! 
! No arguments are passed to the \c run and \c __del__ methods.
! 
  
! \section mcharsched2 Manager Schedule
! 
! The manager %schedule is responsible for telling a %character what to do
  in a given situation. When an activity has finished (and only then), 
! the manager %schedule will be usually executed to decide upon the 
! %character's next activity. Therefore, its \c run method should consist 
  of a number of conditions that decide upon the activity script to use.
  
! Note that the current %schedule is cleared before the manager %schedule
  is executed. Therefore, it \b must set a new activity, otherwise the
! %character will freeze (and the manager script will be called over and
  over again). The new activity can be set with the schedule::set_schedule ()
  method.
  
! The only way to run the manager %schedule is to quit the current activity.
  Everything else is taken care of automatically then.
   
+ Note that the manager %schedule can be exchanged any time by a call to
+ schedule::set_manager(). This won't have any effect on the current
+ activity %schedule at all.
+ 
  
! \section mcharsched3 Activity Schedule
  
! The activity %schedule tells a %character how to accomplish its current
! task. Unlike the manager %schedule, which is only executed to select a
  new activity, activity schedules are executed periodically; once per
! %game cycle, i.e. about 75 times per second. Therefore, activity scripts
  should be made as efficient as possible. 
  
! For example, state variables of the %character should be copied to local 
! variable in the \c __init__ method and written back by \c __del__ instead 
! of accessing them directly while the script runs. As long as those state 
  variables are only accessed by the manager script or a different 
! activity of the same %character, this won't cause any problems.
  
  
  \section mcharsched4 Changing the current Activity
  
! Since life-like behaviour of characters depends on the interaction of 
! many different activities, there are several ways to switch them.
  
  One thing all of them have in common is that the current activity must be
***************
*** 118,125 ****
  for activities with a well defined outcome. Once that outcome is reached,
  a call to schedule::set_running (false) will stop the activity during the
! next game cycle.
  
  An activity without end (especially one that loops) can't be stopped that
! easily. In that case, the manager schedule (or the activity itself) can 
  set an alarm that will quit the script after a certain period. This is 
  done with the schedule::set_alarm () method, which offers two possibilites:
--- 126,133 ----
  for activities with a well defined outcome. Once that outcome is reached,
  a call to schedule::set_running (false) will stop the activity during the
! next %game cycle.
  
  An activity without end (especially one that loops) can't be stopped that
! easily. In that case, the manager %schedule (or the activity itself) can 
  set an alarm that will quit the script after a certain period. This is 
  done with the schedule::set_alarm () method, which offers two possibilites:
***************
*** 138,143 ****
  
  The probably most advanced technique to stop an activity is to catch a
! certain event. This could be a character entering a certain room (for 
! a guard for example) or any other possible game event. The following code
  snippet demonstrates how to do this:
  
--- 146,151 ----
  
  The probably most advanced technique to stop an activity is to catch a
! certain event. This could be a %character entering a certain room (for 
! a guard for example) or any other possible %game %event. The following code
  snippet demonstrates how to do this:
  
***************
*** 182,186 ****
  
  The easiest way is letting the manager script do it's job. Once the 
! current activity has stopped, the manager script will run to set a the
  new activity.
  
--- 190,194 ----
  
  The easiest way is letting the manager script do it's job. Once the 
! current activity has stopped, the manager script will run to set a
  new activity.
  
***************
*** 191,196 ****
  equivalent to set_schedule, schedule::queue_alarm () that of set_alarm. 
  Whenever the current activity stops and another activity is queued, 
! it will be made the next activity and the manager schedule will not 
! be executed. Note that only one schedule/alarm may be queued at a time.
  
  */
--- 199,204 ----
  equivalent to set_schedule, schedule::queue_alarm () that of set_alarm. 
  Whenever the current activity stops and another activity is queued, 
! it will be made the next activity and the manager %schedule will not 
! be executed. Note that only one %schedule/alarm may be queued at a time.
  
  */

Index: reference.cfg
===================================================================
RCS file: /cvsroot/adonthell/adonthell/doc/devel/reference.cfg,v
retrieving revision 1.3.2.1
retrieving revision 1.3.2.2
diff -C2 -r1.3.2.1 -r1.3.2.2
*** reference.cfg       9 Mar 2002 10:14:52 -0000       1.3.2.1
--- reference.cfg       17 Jun 2002 21:17:55 -0000      1.3.2.2
***************
*** 58,63 ****
  RECURSIVE              = NO
  EXCLUDE                = ../../src/py_adonthell_wrap.cc \
-                          ../../src/yarg.cc \
-                          ../../src/yarg.h \
                           ../../src/lex.prefs.cc \
                           ../../src/callback.h \
--- 58,61 ----
***************
*** 83,87 ****
                           ../../src/test-inventory.cc \
                           ../../src/test-item.cc
! EXCLUDE_PATTERNS       = 
  EXAMPLE_PATH           = 
  EXAMPLE_PATTERNS       = 
--- 81,86 ----
                           ../../src/test-inventory.cc \
                           ../../src/test-item.cc
! EXCLUDE_PATTERNS       = ../../src/*_wrap.cc \
!                          ../../src/*test.cc
  EXAMPLE_PATH           = 
  EXAMPLE_PATTERNS       =