<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Created by texi2html 1.76 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Many creative people <dev@texi2html.cvshome.org>
Send bugs and suggestions to <users@texi2html.cvshome.org>
-->
<head>
<title>Crystal Space 1.2.1: 4.15.5 Sequence Manager</title>
<meta name="description" content="Crystal Space 1.2.1: 4.15.5 Sequence Manager">
<meta name="keywords" content="Crystal Space 1.2.1: 4.15.5 Sequence Manager">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.76">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Sequence-Manager"></a>
<a name="0"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="GenMesh-Animation.html#0" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="ProcTextures.html#0" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="Using-Crystal-Space.html#0" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="Animation.html#0" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="Working-with-Engine-Content.html#0" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="cs_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="cs_Index.html#0" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="cs_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<hr size="1">
<h3 class="subsection"> 4.15.5 Sequence Manager </h3>
<p><em>Written by Jorrit Tyberghein,
<a href="mailto:jorrit.tyberghein@gmail.com">jorrit.tyberghein@gmail.com</a>. Last updated 16 August 2003.</em>
</p>
<p>When you define geometry in a map file this usually define a static
representation of the world. Using the sequence manager it is possible
to define specific events that trigger on certain conditions. Using these
events (sequences) you can move or animate objects, control lights, fog,
<small class="dots">...</small>.
</p>
<p>The sequence manager is actually divided in two plugins. First there is
the basic sequence manager itself. This is nothing more then a schedular
that can schedule certain actions that should happen at certain times.
Applications can use this sequence manager for their own purposes if they
want.
</p>
<p>On top of the sequence manager there runs the engine sequence manager. This
plugin predefines several operations and triggers which make it a lot easier
to do engine related things like moving objects, controlling lights, <small class="dots">...</small>.
We will discuss mainly the engine sequence manager in this section.
</p>
<p>A sequence represents a small script with commands that operate on objects
in the world. A trigger represents a series of conditions which will cause
the sequence to be executed. The important thing of the sequence manager
is that it is very time based. Operations don't all execute at once but
at specific times relative to the start of the sequence. Note that all times
in the sequence manager are specified in milli-seconds.
</p>
<a name="1"></a>
<h4 class="subsubheading"> Basic Example </h4>
<p>The easiest way to explain the engine sequence manager is to look at a simple
example as how it can be used from a map file:
</p>
<table><tr><td> </td><td><pre class="example"><world>
...
<sector name="hall">
<light name="roomlight">
<center x="10" y="4" z="10" />
<radius>20</radius>
<color red="0" green="0" blue="0" />
<dynamic />
</light>
...
</sector>
...
<sequences>
<sequence name="turn_on_light">
<setlight light="roomlight" red="1" green="1" blue="1" />
<delay time="50" />
<setlight light="roomlight" red="0" green="0" blue="0" />
<delay time="80" />
<setlight light="roomlight" red="1" green="1" blue="1" />
</sequence>
</sequences>
<triggers>
<trigger name="trig_turn_on_light">
<sectorvis sector="hall">
<sphere x="10" y="4" z="10" radius="5" />
</sectorvis>
<fire delay="0" sequence="turn_on_light" />
</trigger>
</triggers>
</world>
</pre></td></tr></table>
<p>This is a simple example where we turn on a light as soon as we are
in a certain radius of the light. Let's explain how it works. First we
define a sequence which is called <samp>‘turn_on_light’</samp>. This sequence
has three <samp>‘setlight’</samp> operations and two delays. Internally this is
compiled to something which looks like this:
</p>
<table><tr><td> </td><td><pre class="example">time 0ms: setlight 'roomlight',1,1,1
time 50ms: setlight 'roomlight',0,0,0
time 130ms: setlight 'roomlight',1,1,1
</pre></td></tr></table>
<p>Basically there are three operations here and the delays are only used to
indicate when these operations are executed relative to the start of the
entire sequence. So for example, if the sequence is fired at time 10050 then
immediatelly at that point the first operation is executed. 50 milliseconds
later the second operation is executed and finally, 130 milliseconds later
the last operation is executed.
</p>
<p>There are a few important observations to be made about this. First, as soon
as a sequence is executed or fired <small>ALL</small> operations in that sequence will
execute at the correct relative time no matter what happens otherwise. This
also means that if you fire another sequence then that sequence will also get
fired at the same time and depending on the relative timing of the operations
some of those operations might happen at the same time.
</p>
<p>Also note that there are operations that themselves have a duration. For
example, there is a <samp>‘fadelight’</samp> operation which fades a light to some
color. It has a <samp>‘duration’</samp> parameter. But this duration does <small>NOT</small>
influence the relative timing in the sequence itself. So for example if
you have this:
</p>
<table><tr><td> </td><td><pre class="example"><fadelight light="somelight" red="0" green="0" blue="0"
duration="1000" />
<fadelight light="somelight" red="1" green="1" blue="1"
duration="1000" />
</pre></td></tr></table>
<p>Then this will execute two fade operations on the same light at exactly
the same time which is probably not what you want. This example is probably
better written as:
</p>
<table><tr><td> </td><td><pre class="example"><fadelight light="somelight" red="0" green="0" blue="0"
duration="1000" />
<delay time="1000" />
<fadelight light="somelight" red="1" green="1" blue="1"
duration="1000" />
</pre></td></tr></table>
<p>This will place the two operations at a time distance of 1000 milliseconds.
</p>
<p>The reason that using <samp>‘duration’</samp> does not automatically advance the
internal relative time is that it is sometimes useful to start several
fade operations (or other operations that have a duration) at the same time.
For example, two fade operations on two different lights.
</p>
<p>A sequence as such is not useful. It needs to be fired at some point.
You can fire sequences manually from code or you can define a trigger
to fire the sequence if a certain condition is true. In this case we
have a trigger which is called <samp>‘trig_turn_on_light’</samp>. This trigger
will fire if the sector <samp>‘hall’</samp> is visible and the camera is in the
sphere defined by the center <samp>‘10,4,10’</samp> and radius <samp>‘5’</samp>. As soon
as this condition is valid the <samp>‘turn_on_light’</samp> sequence will be
fired immediatelly. Note that this automatically implies that the trigger
is disabled. This is to prevent the sequence from being fired several times
while the trigger condition remains valid. If you want a trigger that keeps
firing you have to re-enable it in the sequence.
</p>
<a name="2"></a>
<h4 class="subsubheading"> Second Example </h4>
<table><tr><td> </td><td><pre class="example"><sequences>
<sequence name="animlight">
<fadelight light="l1" red="0" green="0" blue="0"
duration="1000" />
<delay time="1000" />
<fadelight light="l1" red="1" green="1" blue="1"
duration="1000" />
<delay time="1000" />
<fadelight light="l1" red="1" green="0" blue="0"
duration="1000" />
<delay time="1000" />
<fadelight light="l1" red="0" green="1" blue="0"
duration="1000" />
<delay time="1000" />
<fadelight light="l1" red="0" green="0" blue="1"
duration="1000" />
<delay time="1000" />
<enable trigger="animlight" />
</sequence>
</sequences>
<triggers>
<trigger name="animlight">
<sectorvis sector="large" />
<fire sequence="animlight" />
</trigger>
</triggers>
</pre></td></tr></table>
<p>In this example there is a trigger called <samp>‘animlight’</samp> that fires as
soon as the sector named <samp>‘large’</samp> is visible. Here is what happens
as soon as the condition of the trigger (in this case <samp>‘sectorvis’</samp>)
is true:
</p>
<ol>
<li>
First the firing of the trigger will cause the trigger itself to be
disabled. This is to avoid the trigger firing again next frame.
</li><li>
Then the <samp>‘animlight’</samp> sequence will be executed. What this basically
means is that all operations of that sequence are scheduled in the engine
sequence manager at the appropriate times relative to the current time.
The <samp>‘delay’</samp> operation in the sequence is responsible for tagging
every operation with the specified time. So in this particular example six
operations will be scheduled: five <samp>‘fadelight’</samp> operations (of which
one is scheduled to execute immediatelly) and one <samp>‘enable’</samp> operation.
</li><li>
The first operation that is executed is <samp>‘fadelight’</samp>. This operation
will fade the light color of the light named <samp>‘l1’</samp> from whatever
color it has now to black. <samp>‘l1’</samp> must be a pseudo-dynamic light for
this to work.
</li><li>
One second later (due to the <samp>‘delay’</samp>) the second <samp>‘fadelight’</samp>
gets executed. And so on.
</li><li>
Finally the <samp>‘enable’</samp> operation will execute which means that the
<samp>‘animlight’</samp> trigger is enabled again. If the <samp>‘large’</samp> sector
is still visible this will cause the trigger to fire immediatelly again.
</li></ol>
<p>It is important to note that the <samp>‘duration’</samp> parameter that is given
in some of the operations does <small>NOT</small> imply that the next operation will
execute after that operation has finished. The <samp>‘duration’</samp> parameter
has no effect on the internal relative time that is maintained for the
sequence operations. To influence that you must use <samp>‘delay’</samp>.
</p>
<a name="3"></a>
<h4 class="subsubheading"> Last Example: Using Parameters </h4>
<p>If you want to use the same sequence for different lights you can
use parameters like in the following example:
</p>
<table><tr><td> </td><td><pre class="example"><sequences>
<sequence name="animlight">
<args>
<arg name="l" />
<arg name="trig" />
</args>
<fadelight light_par="l" red="0" green="0" blue="0"
duration="1000" />
<delay time="1000" />
<fadelight light_par="l" red="1" green="1" blue="1"
duration="1000" />
<delay time="1000" />
<fadelight light_par="l" red="1" green="0" blue="0"
duration="1000" />
<delay time="1000" />
<fadelight light_par="l" red="0" green="1" blue="0"
duration="1000" />
<delay time="1000" />
<fadelight light_par="l" red="0" green="0" blue="1"
duration="1000" />
<delay time="1000" />
<enable trigger_par="trig" />
</sequence>
</sequences>
<triggers>
<trigger name="animlight_l1">
<sectorvis sector="large" />
<fire sequence="animlight">
<light name="l" light="l1" />
<light name="trig" light="animlight_l1" />
</fire>
</trigger>
<trigger name="animlight_l2">
<sectorvis sector="large" />
<fire sequence="animlight">
<light name="l" light="l2" />
<light name="trig" light="animlight_l2" />
</fire>
</trigger>
</triggers>
</pre></td></tr></table>
<p>Here you see how the same sequence (<samp>‘animlight’</samp>) is used by
two different triggers for two different lights. It is not only the
light that has to be given as a parameter but also the trigger that
needs to be enabled again. That's why two parameters are used.
</p>
<p>A lot more is possible here. I will give a short summary of all commands
(that are not operations) that are supported in sequences here:
</p>
<dl compact="compact">
<dt> <code>args</code></dt>
<dd><p>Use this to enumerate all arguments to this sequence. You
only have to specify the name of the arguments here.
</p>
</dd>
<dt> <code>delay</code></dt>
<dd><p>Increase the relative time for following operations. The
relative time starts at 0 in the beginning of the sequence. Using <samp>‘delay’</samp>
you can increase relative time. If you don't use <samp>‘delay’</samp> between two
consecutive operations then they will execute at the same time. You can
use <samp>‘delay’</samp> with the <samp>‘time’</samp> parameter in which case a constant
amount will be added. Or you can use <samp>‘delay’</samp> with the <samp>‘min’</samp> and
<samp>‘max’</samp> parameters in which case a random amount between the two given
values will be added. This amount is truely random in the sense that it will
be reevaluated every time the sequence fires.
</p>
</dd>
</dl>
<a name="4"></a>
<h4 class="subsubheading"> Supported Operations </h4>
<p>Here is a list of all operations that you can use in a sequence. Note that
every operation is tagged with a relative time (relative to the start
of the sequence). If you want to use a parameter for an operation that
uses an argument to the sequence then you have to add <samp>‘_par’</samp> to the
parameter name like this: <samp>‘light_par’</samp>.
</p>
<dl compact="compact">
<dt> <code>run</code></dt>
<dd><p>This operation will run the given sequence. Parameter is
<samp>‘sequence’</samp>.
</p>
</dd>
<dt> <code>move</code></dt>
<dd><p>Move the specified object from the current position to the
specified position in the given time (duration). Parameters are
<samp>‘mesh’</samp>, <samp>‘duration’</samp>, <samp>‘x’</samp>, <samp>‘y’</samp> and <samp>‘z’</samp>.
</p>
</dd>
<dt> <code>rotate</code></dt>
<dd><p>Rotate the specified object from the current orientation
to the new orientation in the given time (duration). Parameters are
<samp>‘mesh’</samp> and <samp>‘duration’</samp>. As children you can specify rotation
matrix and vector using <samp>‘rotx’</samp>, <samp>‘roty’</samp>, <samp>‘rotz’</samp> and
<samp>‘v’</samp>.
</p>
</dd>
<dt> <code>material</code></dt>
<dd><p>Change the material on some object. Parameters are
<samp>‘mesh’</samp>, <samp>‘material’</samp>, and optionally a <samp>‘polygon’</samp> parameter
if you only want to change the material for one polygon.
</p>
</dd>
<dt> <code>fadecolor</code></dt>
<dd><p>Fade the color of a mesh from the current value to the
new value. This only works on some types of meshes. Parameters are
<samp>‘mesh’</samp>, <samp>‘red’</samp>, <samp>‘green’</samp>, <samp>‘blue’</samp> and <samp>‘duration’</samp>.
</p>
</dd>
<dt> <code>setcolor</code></dt>
<dd><p>Set the color of a mesh. This only works on some types of
meshes. Parameters are <samp>‘mesh’</samp>, <samp>‘red’</samp>, <samp>‘green’</samp> and <samp>‘blue’</samp>.
</p>
</dd>
<dt> <code>fadelight</code></dt>
<dd><p>Fade the color of a light from the current value to the new value. Parameters
are <samp>‘light’</samp>, <samp>‘red’</samp>, <samp>‘green’</samp>, <samp>‘blue’</samp> and <samp>‘duration’</samp>.
</p>
</dd>
<dt> <code>setlight</code></dt>
<dd><p>Set the color of a light.
Parameters are <samp>‘light’</samp>, <samp>‘red’</samp>, <samp>‘green’</samp> and <samp>‘blue’</samp>.
</p>
</dd>
<dt> <code>fadeambient</code></dt>
<dd><p>Fade the color of a dynamic ambient from the current value to the new
value. Parameters are <samp>‘sector’</samp>, <samp>‘red’</samp>, <samp>‘green’</samp>, <samp>‘blue’</samp>
and <samp>‘duration’</samp>.
</p>
</dd>
<dt> <code>setambient</code></dt>
<dd><p>Set the color of dynamic ambient.
Parameters are <samp>‘sector’</samp>, <samp>‘red’</samp>, <samp>‘green’</samp> and <samp>‘blue’</samp>.
</p>
</dd>
<dt> <code>fadefog</code></dt>
<dd><p>Fade the color and density of fog from the current value to the new
value. Parameters are <samp>‘sector’</samp>, <samp>‘red’</samp>, <samp>‘green’</samp>, <samp>‘blue’</samp>,
<samp>‘density’</samp> and <samp>‘duration’</samp>.
</p>
</dd>
<dt> <code>setfog</code></dt>
<dd><p>Set the color and density of fog.
Parameters are <samp>‘sector’</samp>, <samp>‘red’</samp>, <samp>‘green’</samp>, <samp>‘blue’</samp>
and <samp>‘density’</samp>.
</p>
</dd>
<dt> <code>enable</code></dt>
<dd><p>Enable the given trigger. Parameter is <samp>‘trigger’</samp>.
</p>
</dd>
<dt> <code>disable</code></dt>
<dd><p>Disable the given trigger. Parameter is <samp>‘trigger’</samp>.
</p>
</dd>
<dt> <code>check</code></dt>
<dd><p>Enable checking of trigger state every <samp>‘delay’</samp> milliseconds
(or disable if 0). Use this in combination with <samp>‘test’</samp> below. Parameters
are <samp>‘trigger’</samp> and <samp>‘delay’</samp>.
</p>
</dd>
<dt> <code>test</code></dt>
<dd><p>Test the stated of the given trigger and execute the right
sequence depending on the result. For this to work you should use
<samp>‘check’</samp> to enable testing of the trigger at regular times. Parameters are
<samp>‘trigger’</samp>, <samp>‘truesequence’</samp> and <samp>‘falsesequence’</samp>. Both
<samp>‘truesequence’</samp> and <samp>‘falsesequence’</samp> are optional. <em>Warning!</em>
This operation does not cause the current sequence to stop. All operations
that follow this test operation will still execute at their dedicated times
regardless of the outcome of this test!
</p>
</dd>
<dt> <code>setvar</code></dt>
<dd><p>Set a shared variable to some value. The only required parameter is <samp>‘var’</samp>
which is the name of the variable you want to set. Then there are various
other parameters that you can use to set the variable:
</p><ul class="toc">
<li>
<samp>‘value’</samp>: set the variable to the given floating point value.
</li><li>
<samp>‘add’</samp>: add the given floating point value to the variable.
</li><li>
<samp>‘value_var’</samp>: set the variable to the value in the given other variable.
The other variable doesn't have to be a float.
</li><li>
<samp>‘add_var’</samp>: add the other variable to this variable.
</li><li>
<samp>‘x’</samp>, <samp>‘y’</samp>, <samp>‘z’</samp>: set the variable to the given vector.
</li><li>
<samp>‘red’</samp>, <samp>‘green’</samp>, <samp>‘blue’</samp>: set the variable to the given color.
</li></ul>
</dd>
</dl>
<a name="5"></a>
<h4 class="subsubheading"> Supported Conditions </h4>
<p>Here is a list of all conditions that are supported in a trigger:
</p>
<dl compact="compact">
<dt> <code>onclick</code></dt>
<dd><p>True when the given mesh is clicked on. Parameter is
<samp>‘mesh’</samp>.
</p>
</dd>
<dt> <code>lightvalue</code></dt>
<dd><p>True when the given light has a color which satisfies some condition.
Parameters are <samp>‘light’</samp>, <samp>‘operator’</samp>, <samp>‘red’</samp>, <samp>‘green’</samp> and
<samp>‘blue’</samp>. <samp>‘operator’</samp> can be <samp>‘less’</samp> or <samp>‘greater’</samp>.
</p>
</dd>
<dt> <code>manual</code></dt>
<dd><p>For manual trigger (from application code). No parameters.
</p>
</dd>
<dt> <code>sectorvis</code></dt>
<dd><p>True when the sector is visible. Parameter is <samp>‘sector’</samp>.
There are also some optional children that this trigger supports:
</p><ul class="toc">
<li>
<samp>‘insideonly’</samp>: only trigger when camera is inside the sector as opposed
to the sector being visible.
</li><li>
<samp>‘box’</samp>: only trigger if camera is in box. This has two children:
a <samp>‘min’</samp> and a <samp>‘max’</samp> vector.
</li><li>
<samp>‘sphere’</samp>: only trigger if camera is in the sphere. Parameters are
<samp>‘x’</samp>, <samp>‘y’</samp>, <samp>‘z’</samp> and <samp>‘radius’</samp>.
</li></ul>
</dd>
<dt> <code>fire</code></dt>
<dd><p>This is not a trigger. It just indicates the sequence that will be executed
when the trigger is valid. Parameters are <samp>‘sequence’</samp> and <samp>‘delay’</samp>
(optional). In addition you can also specify parameters for the called
sequence.
</p>
</dd>
<dt> <code>disable</code></dt>
<dd><p>Normally a trigger is enabled by default. With this keyword
you can disable the trigger initially and let some other sequence (or the
application) enable the trigger.
</p>
</dd>
</dl>
<hr size="1">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="GenMesh-Animation.html#0" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="ProcTextures.html#0" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="Using-Crystal-Space.html#0" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="Animation.html#0" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="Working-with-Engine-Content.html#0" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="cs_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="cs_Index.html#0" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="cs_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
<font size="-1">
This document was generated using <a href="http://texi2html.cvshome.org/"><em>texi2html 1.76</em></a>.
</font>
<br>
</p>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
bad97183153701b09df5fae1052b1c30
>
files
>
4299
