<trigger> ‐ A command trigger
The trigger element of a command defines an event or a date. The event triggers the execution of this command when it is received by the node that contains the script with this command. The date defines a deadline after which this command will be executed as soon as the browser is able to do it. The trigger can be controlled by an internal state definition that requires the receiving node to be in this state. If the value of the string attribute state is empty, the trigger is enabled whatever the internal state of the node.
There are two types of triggers: event-based triggers and time-based triggers.
The value of the type attribute of event-based triggers is message_event (a genuine message received from another node or from an external application) or keystroke for keystroke event. The message string or the keystroke is defined by the string value of the value attribute.
For time_limit type time-based triggers, the triggering time is defined by the float value of the value attribute. As for the cyclic_time and random_cyclic_time types the float values of the begin and period attributes define a set of dates. Last, the cyclic_time, varying_cyclic_time and varying_ random_cyclic_time define a set of dates from the float values of the begin, period, and variation attributes.
The message_event triggers can be controlled by the state of the node that carries the script. If the value S of the string attribute state is not empty, the execution of the action is controlled by a comparison between the internal state of the node and S. The value O of the string attribute operator defines the string comparison operator: ==, <=, <, >=, >, or !=. The internal state of a node can be modified through the action set_internal_state. The default internal state of the scene nodes is init.
Time-based triggers and keystrokes cannot be complemented by a state-based constraint (state attribute) because these commands are all relocated at the main node level. In order to use state-based constraints, these commands must be associated with a message posting to a node on which state-based control can be made. All the nodes are initialized to the state init.
None.
The following examples are correct triggers:
<trigger type="time_limit" value="{#duration}" />
<trigger type="varying_random_cyclic_time" begin="({#dur}/2)"
period="({#dur}/5)" variation="0.98" />
<trigger type="message_event" value="click" state="B_ongoing"
bool_operator="==" />
<trigger type="keystroke" value="A" />
In the next two subsections, we first describe event-based triggers of the following two types: keystroke and message_event. Then, we detail the computation of the triggering dates of the time-base triggers: triggers of one of the following types: time_limit, cyclic_time, varying_cyclic_time, random_cyclic_time, or varying_random_cyclic_time
This trigger responds to a keystroke event. In the current version of VC, only digits, uppercase and lower case letters, and wheel up or down events can be received as keystroke events.
The key is identified by the string value of value attribute. The keystroke triggers cannot be complemented by a state-based constraint given by a string value of the state attribute because these commands are all relocated at the main node level. In order to use state-based constraints, these commands must be associated with a message posting to a node on which state-based control can be made.
Wheel up or down events are associated with the wheel_up and wheel_down values of the value attribute.
The example below defines a command trigger bound to the uppercase key U:
<trigger type="keystroke" value="U" />
This trigger responds to a message event: it corresponds to the reception of a message by the node in which this event is defined. The event is identified by the string value of value attribute.
Events can be received from other internal nodes through the commands send_message or forward_message, or from external applications.
The example below defines a command trigger bound to the reception of the event labeled start rotate:
<trigger type="message_event" value="start rotate" />
The value of the state and bool_operator attributes are used to define the internal state restriction of a trigger. The value of the state attribute is a state (a string of characters) that defines the state in which the node must be in order to enable the trigger of the command.
The example below defines an action triggered by an event labeled level that requires the node to be in state enabled:
<trigger type="message_event" value="level"
state="enabled" bool_operator="==" />
<action>
<write_console value="Msg: Random config 3" />
</action>
If the message has an OSC-like syntax given by Equation 6-1, the arguments can be used as parameters for the actions contained in the command. The <address> is an identifier that begins with a '/' character followed by alphanumerical characters and the <parameter>s are chosen among f (float), i (integer), and s (string) (see the description of patterns in the aliasScript element).
The example below defines an action triggered by a message composed of an address /faceAnim and up to three integer parameters that are then referenced by: {$1}, {$2}, and {$3} in the embedded actions. If less than three parameters are received, the non-received parameters are null.
<command>
<trigger type="message_event" value="/faceAnim i i i" />
<action>
<write_console value="Index ({$1}) source ({$2}) target ({$3})" />
</action>
<action>
<set_node_scalar_value id="index" value="({$1})" operator="=" />
<target type="single_node" value="#root" />
</action>
</command>
A cyclic_time type trigger defines a repetitive time limit. It uses the float values of the begin and period attribute to calculate the triggering times. The deadlines are: begin+n×period with n a positive integer.
The example below defines a command trigger scheduled at times 70.0, 370.0, 670.0, etc.
<trigger type="cyclic_time" begin="70"
period="300" />
A time_limit type trigger defines a single time limit, the float value of the attribute value.
The example below defines a command trigger scheduled at time 44.0:
<trigger type="time_limit" value="44" />
A random_cyclic_time type trigger defines a repetitive time limit. It uses the float values of the begin and period to calculate the base time limits. The first deadline is at time begin. Then, each new deadline is randomly chosen between the preceding deadline d and d+period.
The example below defines command trigger scheduled at time 70.0, at a random time t1 between 70.0 and 370.0, at t2 a random time between t1 and t1+300.0, etc.
<trigger type="random_cyclic_time" begin="70"
period="300" />
A varying_cyclic_time type trigger defines a repetitive time limit. It uses the float values of the begin and period to calculate the base time limits. The period varies exponentially; it is multiplied by the float value variation of the variation attribute. If the variation is greater than 1, the period increases, if it is between 0 and 1, the period decreases. The deadlines are at the following times: begin+n×period×coefficientn with n a positive integer.
The example below defines a command trigger scheduled at times 70.0, 70.0+300×0.991, 70.0+300×0.992+300×0.993, etc.
<trigger type="varying_cyclic_time" begin="70"
period="300" variation="0.99" />
A varying_random_cyclic_time type trigger defines a repetitive time limit. It uses the float values of the begin and period to calculate the base time limits. The period varies exponentially; it is multiplied by the float value variation of the variation attribute. If the variation is greater than 1, the period increases, if it is between 0 and 1, the period decreases. The first deadline is at time begin. Then, each new deadline is randomly chosen between the preceding deadline d and d+period×coefficientn with n a positive integer.
The example below defines command trigger scheduled at time 70.0, at a random time t1 between 70.0 and 70.0+300×0.991, at t2 time between t1 and t1+300.0×0.992, etc.
<trigger type="varying_random_cyclic_time" begin="70"
period="300" variation="0.99" />