7.8.4 Action Section
This section describes the action section.
Sequences and Triggers
With the sequences and triggers section you can define actions and
interactions on objects in your map file. These sections are used to drive
the engine sequence manager (internal note: add link when documentation
on that plugin is available).
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.
The easiest way to explain what you can do with the engine sequence
manager is with a few examples:
| <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>
|
In this example there is a trigger called `animlight' that fires as
soon as the sector named `large' is visible. Here is what happens
as soon as the condition of the trigger (in this case `sectorvis')
is true:
-
First the firing of the trigger will cause the trigger itself to be
disabled. This is to avoid the trigger firing again next frame.
-
Then the `animlight' 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 `delay' 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 `fadelight' operations (of which
one is scheduled to execute immediatelly) and one `enable' operation.
-
The first operation that is executed is `fadelight'. This operation
will fade the light color of the light named `l1' from whatever
color it has now to black. `l1' must be a pseudo-dynamic light for
this to work.
-
One second later (due to the `delay') the second `fadelight'
gets executed. And so on.
-
Finally the `enable' operation will execute which means that the
`animlight' trigger is enabled again. If the `large' sector
is still visible this will cause the trigger to fire immediatelly again.
It is important to note that the `duration' parameter that is given
in some of the operations does NOT imply that the next operation will
execute after that operation has finished. The `duration' parameter
has no effect on the internal relative time that is maintained for the
sequence operations. To influence that you must use `delay'.
If you want to use the same sequence for different lights you can
use parameters like in the following 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>
|
Here you see how the same sequence (`animlight') 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.
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:
-
`args': use this to enumerate all arguments to this sequence. You
only have to specify the name of the arguments here.
-
`delay': increase the relative time for following operations. The
relative time starts at 0 in the beginning of the sequence. Using `delay'
you can increase relative time. If you don't use `delay' between two
consecutive operations then they will execute at the same time. You can
use `delay' with the `time' parameter in which case a constant
amount will be added. Or you can use `delay' with the `min' and
`max' 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.
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 `_par' to the
parameter name like this: `light_par'.
-
`run': this operation will run the given sequence. Parameter is
`sequence'.
-
`move': move the specified object from the current position to the
specified position in the given time (duration). Parameters are
`mesh', `duration', `x', `y', and `z'.
-
`rotate': rotate the specified object from the current orientation
to the new orientation in the given time (duration). Parameters are
`mesh' and `duration'. As children you can specify rotation
matrix and vector using `rotx', `roty', `rotz', and
`v'.
-
`material': change the material on some object. Parameters are
`mesh', `material', and optionally a `polygon' parameter
if you only want to change the material for one polygon.
-
`fadecolor': fade the color of a mesh from the current value to the
new value. This only works on some types of meshes. Parameters are
`mesh', `red', `green', `blue', and `duration'.
-
`setcolor': set the color of a mesh. This only works on some types of
meshes. Parameters are `mesh', `red', `green', and `blue'.
-
`fadelight': fade the color of a light from the current value to the
new value. Parameters are
`light', `red', `green', `blue', and `duration'.
-
`setlight': set the color of a light.
Parameters are `light', `red', `green', and `blue'.
-
`fadeambient': fade the color of a dynamic ambient from the current value
to the new value. Parameters are
`sector', `red', `green', `blue', and `duration'.
-
`setambient': set the color of dynamic ambient.
Parameters are `sector', `red', `green', and `blue'.
-
`fadefog': fade the color and density of fog from the current value
to the new value. Parameters are
`sector', `red', `green', `blue', `density',
and `duration'.
-
`setfog': set the color and density of fog.
Parameters are `sector', `red', `green', `blue',
and `density'.
-
`enable': enable the given trigger. Parameter is `trigger'.
-
`disable': disable the given trigger. Parameter is `trigger'.
-
`check': enable checking of trigger state every `delay' milliseconds
(or disable if 0). Use this in combination with `test' below. Parameters
are `trigger' and `delay'.
-
`test': test the stated of the given trigger and execute the right
sequence depending on the result. For this to work you should use `check'
to enable testing of the trigger at regular times. Parameters are
`trigger', `truesequence', and `falsesequence'. Both
`truesequence' and `falsesequence' are optional. Warning! 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!
Here is a list of all conditions that are supported in a trigger:
-
`onclick': true when the given mesh is clicked on. Parameter is
`mesh'.
-
`lightvalue': true when the given light has a color which satisfies
some condition. Parameters are `light', `operator', `red',
`green', and `blue'. `operator' can be `less'
or `greater'.
-
`manual': for manual trigger (from application code). No parameters.
-
`sectorvis': true when the sector is visible. Parameter is `sector'.
There are also some optional children that this trigger supports:
-
`insideonly': only trigger when camera is inside the sector as opposed
to the sector being visible.
-
`box': only trigger if camera is in box. This has two children:
a `min' and a `max' vector.
-
`sphere': only trigger if camera is in the sphere. Parameters are
`x', `y', `z', and `radius'.
-
`fire': this is not a trigger. It just indicates the sequence
that will be executed when the trigger is valid. Parameters are `sequence'
and `delay' (optional). In addition you can also specify parameters
for the called sequence.
-
`disable': 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.
This document was generated using
texi2html