6.12 Variables

Variables in ASAM OpenSCENARIO are similar to variables in programming languages. They have the following characteristics:

Variables are defined in the scope of the whole scenario. All variables that are used in a scenario shall be defined in a VariableDeclaration.
Variables are named and typed. The same naming rules apply to variables as to parameters (see Section 9.1, "Parameters").
Variables have an initialization value. They are set to their initialization value at load time of the simulation.

Unlike parameter values (see Section 9.1, "Parameters"), variable values can also change during runtime. This can be achieved in two ways:

From within the scenario (OSC Model instance) by using a VariableAction
From external side. For this, the Simulator Core needs to provide an interface to change variable values.

Variables are used in a scenario to trigger actions with a VariableCondition. A VariableCondition can also be used where the existing conditions cannot describe the value of the variable or the value needs to be injected from external side because it is not part of the scenario.

An example of a scenario action which is triggered by a VariableCondition could look like this:

<VariableDeclarations>
  <VariableDeclaration name="Trigger1" variableType="boolean" value="false"/>
</VariableDeclarations>
...
<Event name="ActivateControllerEvent" priority="overwrite">
  <Action name="ActivateControllerAction">
    <PrivateAction>
      <ControllerAction>
        <ActivateControllerAction controllerRef="Controller1" lateral="true" longitudinal="true"/>
      </ControllerAction>
    </PrivateAction>
  </Action>
  <StartTrigger>
    <ConditionGroup>
      <Condition name="ActivateControllerEventCondition" delay="0" conditionEdge="rising">
        <ByValueCondition>
          <VariableCondition variableRef="Trigger1" rule="equalTo" value="true"/>
        </ByValueCondition>
      </Condition>
    </ConditionGroup>
  </StartTrigger>
</Event>

Variables can also be read from external side during the scenario. For this, the Simulator Core needs to provide an interface to read variable values. An example of a VariableAction which triggers something on external side could look like this:

<Event name="SetTriggerEvent" priority="overwrite">
  <Action name="SetTrigger1">
    <GlobalAction>
      <VariableAction variableRef="Trigger1">
        <SetAction value="true"/>
      </VariableAction>
    </GlobalAction>
  </Action>
  <StartTrigger>
    <ConditionGroup>
      <Condition name="EgoReachSpeedCondition" delay="0" conditionEdge="rising">
        <ByEntityCondition>
          <TriggeringEntities triggeringEntitiesRule="any">
            <EntityRef entityRef="Ego"/>
          </TriggeringEntities>
          <EntityCondition>
            <SpeedCondition rule="greaterOrEqual" value="20"/>
          </EntityCondition>
        </ByEntityCondition>
      </Condition>
    </ConditionGroup>
  </StartTrigger>
</Event>

The standard defines a type inference check, which ensures that the variable value matches its type. The check is not ensured by the XML validator and therefore must be implemented by the simulator.

Variables can only be used in a VariableCondition to trigger actions during runtime of the scenario. They cannot replace any attribute value in the scenario or be used in expressions like parameters. This avoids unspecified behavior, e.g., changing the AbsoluteTargetSpeed of a SpeedAction during execution or changing the model3d of a Vehicle during runtime.

Interfacing with external modules can be achieved with UserDefinedValueCondition and UserDefinedAction in the same way.