[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Adonthell-commits] CVS: adonthell/doc/devel gametime.dxt,NONE,1.1.2.1 e
From: |
Kai Sterker <address@hidden> |
Subject: |
[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 |
Date: |
Mon, 17 Jun 2002 17:17:57 -0400 |
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 =
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [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> <=