Chapter 6. VC Command Syntax

This chapter and the next one provide a detailed definition of the syntax of VC scripting language. A script is made of a sequence of commands.

6.1. Command (script elements)

<command> ‐ A script command

6.1.1. Attributes

NameTypeDefaults
patternSTRINGNone (required for alias script commands)

6.1.2. Description

VC scripting commands are made of three components: a trigger, a structured action (action, repeatAction, whileAction, or ifAction elements), and a target:

  • The trigger defines the event or the schedule that will cause the action to be executed. A single trigger can apply to more than one action if more than one action follows the trigger.

  • The elementary actions define the output of the command processing. Elementary actions divide into two categories: element modification and message emission. They are referenced in Chapter 7. Actions can be structured in sequences of action, repeat and while actions, and test actions through the use of the action, repeatAction, whileAction, or ifAction elements. Structured actions are described in the remainder of this chapter.

  • The target defines the node(s) in the virtual scene to which the action applies or the udp_hosts that will receive the output messages of the actions. There can be more than one target node if the target id is ambiguous (if more than one node has the target id).

If the command is part of an aliasScript the string value of the pattern attribute is used to link the values of the parameters in the input OSC messages (see udp_remote_client) with the values in the actions that build up the command. See the aliasScript element for a description of the pattern syntax.

The trigger and target elements are presented in this chapter. The description of all the elementary actions is made in Chapter 7.

The syntax of scripts is described by the following grammar in which non terminals are given between double quotes:

"script" -> <script> "commands" </script>
"commands" -> (<command> "command" <command>)*
"command" -> (<trigger />)? ("StructuredAction")+
"StructuredAction" -> <repeatAction> ("StructuredAction")+ </repeatAction>
"StructuredAction" -> <ifAction> ("StructuredAction")+ </ifAction>
"StructuredAction" -> <whileAction> ("StructuredAction")+ </whileAction>
"StructuredAction" -> <action> ("StructuredAction")+ </action>
"StructuredAction" -> <action> ("elementaryAction")+ <target </action>
"elementaryAction" -> <add_node> | <crowd_delete_obstacles> | ...

6.1.3. Expected child

A trigger if the command is not part of an aliasScript, initializationScript, a termination script, a completionScript, or an updateScript. A sequence of structured actions: action, repeatAction, whileAction, or ifAction elements. A target if the actions in the sequence require one.

6.1.4. Example

The example below defines a command triggered by the reception of the event start rotate. The action is executed only if the node is in the internal state B. The action is set_schedule_attribute_value with two arguments. It replaces the begin time of the first schedule in the target node by the current time. The target node is the node with id interpolator rotate cylinder #{#n} ({#n} is replaced by the current value of the parameter n).

The second command is triggered by the Y key and performs three actions on the target node with id sphere 1. The first action activates a sound, and the last two actions modify the material properties of the object.

<command>
  <trigger type="message_event" value="start rotate" 
           state="B" bool_operator="==" />
  <action>
    <set_schedule_attribute_value index="1" operator="=">
      <schedule begin="now"/>
    </set_schedule_attribute_value>
    <target type="single_node" value="#interpolator rotate cylinder #{#n}" />
  </action>
</command>
<command>
  <trigger type="keystroke" value="Y" />
  <action>
    <set_sound_attribute_value  operator="=" />
       <sound begin="now" end="1000000"/>
    </set_sound_attribute_value>
    <set_material_attribute_value  operator="=" />
       <diffuse r="0.7" g="0.0" b="0.0"/>
    </set_material_attribute_value>
    <set_material_attribute_value  operator="=" />
       <emission r="1.0" g="0.0" b="0.0"/>
    </set_material_attribute_value>
    <target type="single_node" value="#sphere 1" />
   </action>
</command>

The * meta-character can be used in reference strings in order to compare strings that have substrings in common. This facility can be used to define a trigger that can receive a set of events, or that is constrained by a set of states. It can also be used to send a message to a set of nodes. The following command accepts any event prefixed by the string start. This trigger is valid if the state of the node is a string prefixed by lo and terminated by active. The action is a message posting to all the nodes whose ID is prefixed by sphere.

<command>
  <trigger type="message_event" value="start*" 
           state="lo*active" bool_operator="==" />
  <action>
    <send_message value="start scale" />
    <target type="multiple_nodes" value="#sphere*" />
  </action>
</command>