What are Actions in a Procedure?

Get an overview of all Actions available in Procedures and how they determine how the system reacts to the user proceeding through a Procedure.

Introduction

Actions can be used to ensure the Procedure reacts to the trainee progressing through the Steps. Each Operation has a list of "Actions before" that are being executed concurrently when the trainee reaches the Step, and a list of "Actions after" that are being executed concurrently as soon as the trainee has completed the Operation.

If the user wants several Actions to play one after the other, the user can make use of the "Duration" and "Delay" parameters of individual Actions. These can be found under the "Show more" button of each Action.

If an Action offers "Complete before finishing Operation", set it to false when you want the trainee to continue while the effect plays in the background.

SynergyXR provides the following Actions:

• Change image
• Change material
• Change visibility
• Equip
• Make grabbable
• Move procedure panel
• Play animation
• Play audio
• Play video
• Toggle event
• Transform object

Change image

Used when a texture of a 3D model must be changed or to change the content of an image instance. Can be used to e.g., change the image of a PC screen to simulate the trainee progressing through the menus of the software running on the PC.

The following parameters can be set by the user:

• Object: Specify the object containing a Material using a texture that should be changed.
• Image: Use the drop-down menu to select between configured image content.
• Material: Specify the material using the texture that should be exchanged for the Image. The user can select from the drop-down menu of all materials contained in the Object.

Best practise

• Name your image assets consistently.

QA checklist

• Test that the image resolution is readable at typical viewing distance.

Change material

Used to change material parameters of a 3D model. Can be used to alter the appearance or for animated highlight of objects. The following parameters can be set by the user:

• Object: Specify the Object containing a Material that should have one or more parameters changed.
• Material: Specify the material that should have one or more parameters changed. The user can select from the drop-down menu of all materials contained in the Object.
• Base color: Change the base color of the Material. This color will be added on top of any texture applied to the material.
• Mode: Specify how the material change should happen. Select between "Once", "Loop" and "Ping pong". If "Loop" or "Ping pong" is chosen, the material change will be animated between the existing and the new settings over the Duration specified – see below.

There are also a few noteworthy parameters hidden under the "Advanced" button:

• Duration: Specify the duration of the material change. Used to animate the material changes over time.
• Emission HDR color: Sets an emissive color for a brighter result than just the base color. This can be used to dramatically highlight object.
• Surface type: Sets the surface to being either fully "Opaque" or "Transparent". If the type is set to "Transparent" any alpha value (the fourth value in the color attribute of "Base color" and "Emission HDR color") is taken into account resulting in the object being (partially) transparent.

Best practise

• Setting up the base colour on the object removes the texture from the model - use Emission HDR as an alternative.
• Brief white flash then return with Emission HDR, or a slow ping pong emission for attention.
• Pair with Override settings if highlight clutter is a risk.

QA checklist

• Ensure that emission is not set too high causing bloom and wash details on the model.

Change visibility

Used when a 3D model should be enabled, disabled, shown or hidden. The following parameters can be set by the user:

• Object: Specifies the object that will change visibility.
• Style: Choose between:
  • Enable object: Enable the Object. Child objects will resume their enable/disable state from before the parent Object was disabled.
  • Disable object: Disable the Object and all child objects. All child objects will remain disabled until their parent Object is enabled again.
  • Show mesh: Show the enabled Object and all children in the scene.
  • Hide mesh: Hide the enabled Object and all children in the scene.

Best practise

• Hide or disable objects that are currently not in use.
• Having a hidden object with a collider can be used to block the user's movement.

QA checklist

• Test that no hidden colliders are blocking the user unintendedly.

Equip

Used when the trainee must put on equipment (e.g., personal protection equipment). Often used as a reaction to the trainee completing an Operation that mimics the trainee picking up a piece of equipment and equipping it – e.g. by using a "Grab and place" Operation. The following parameters can be set by the user:

• Equipment: The equipment object in the scene that the trainee and all co-trainees should get equipped on their avatar.
• Unequip: As default, the Equip Action will ensure all trainees equip the Equipment. This parameter can be used to unequip the Equipment if that is desirable.

QA checklist

• Test that Equipment alignment looks correct and gets equipped to all users. 

Make grabbable

Used to make an object grabbable by the trainee. Also ensures the object is affected by gravity when dropped.

The following parameters can be set by the user:

• Object: Specify the object that the trainee should be able to grab and pick up.

Best practise

• Use when a user should attach a battery to a powerdrill using both hands - make powerdrill grabbable and use a Grab and place Operation on the battery allowing the user to attch the battery to the powerdrill.

QA checklist

• Test that the Object can be grabbed correctly with both hands.

Move procedure panel

Used to move the Procedure Panel – great to ensure the trainee always has the panel close at hand when progressing through the Procedure.

The following parameters can be set by the user:

• Position: Defines the new position of the Procedure Panel. Can be changed either by typing numbers directly into the input field or by dragging the 3D gizmo in the scene.
• Rotation: Defines the new rotation of the Procedure Panel. Can be changed either by typing numbers directly into the input field or by dragging the 3D gizmo in the scene.

Best practise

• Position the Procedure Panel in front of the trainee at eye height, and not too close. Keep a consistent offset across steps. Use Rotation to face the working area.
• After a Move to Operation, move the panel next to the user so the next step is visible and reachable.

QA checklist

• Moving the panel every step feels jumpy. Move it only when the user changes work area.
• Test that the panel is readable on spawn and after the user has moved.
• Test that the panel does not block targets and movement. 

Play animation

Used when the Procedure must play an animation embedded in a 3D model. The following parameters can be set by the user:

• Object: Defines the 3D object with the embedded animation to be played. Only objects with animations are valid for this parameter – indicated by the animation icon found in the Objects hierarchy.
• Animation name: Defines the animation to be played. The user can select between valid animations via the drop-down menu.
• Action: Defines if the animation should start playing ("Play") or if it should be stopped ("Stop").
• Mode: Defines how the animation should be played. Choose between:
  • "Once" (only play the animation once from beginning to end);
  • "Loop" (repeatedly play the animation from beginning to end until the "Stop" Action is chosen in a subsequent "Play" animation Action); or
  • "Ping-pong" (repeatedly play the animation from beginning to end and reverse back to beginning until the "Stop" Action is chosen in a subsequent "Play" animation Action.

There are also a few noteworthy parameters hidden under the "Advanced" button:

• Duration: Defines the duration in seconds of the animation by playing the animation faster/slower - overrules Speed below.
• Speed: Adjusts the speed of the animation - ignored if a Duration is set.
• Start frame: Defines the start frame of the animation. Can be used to crop the beginning of the animation, or to split the animation track into several smaller clips used at specific steps.
• End frame: Defines the end frame of the animation. Can be used to crop the end of the animation, or to split the animation track into several smaller clips used at specific steps.
• Frame rate: Defines the rate of which frames are evaluated. Normally this should match the frame rate of the recorded animation, but this parameter can also be used to speed up the animation (setting the "Frame rate" higher than the recorded frame rate) or slow down the animation (setting the "Frame rate" lower than the recorded frame rate).
• Complete before finishing Operation: When this is set to true (default) the Operation is not marked as finished allowing the trainee to proceed to the next Step in the Procedure until the animation has played to the end. Set this parameter to false if you want to allow the trainee to proceed through the Procedure, while the animation keeps playing in the background.

Best practise

• Combine animation with Play audio Actions with delays.

QA checklist

• Test that the correct animation is playing on the right object and stops as intended.
• Test that skipping forward and backward does not brake the animation.
• Test that the model was made with correct animation that can loop.
• Ensure multiple animations are not played on the same model simultaneously.

Play audio

Used when the Procedure must play an audio file already configured.

The following parameters can be set by the user:

• Audio clip: Use the drop-down menu to select between configured audio files.
• Action: Choose between "Play", "Pause", "Resume" and "Stop".
• Location: Can be used to specify a position in the scene defining the source of the audio (played as a 3D spatial audio file). If not specified, the audio is played omnipresent without a specific position.

There are also a few noteworthy parameters hidden under the "Advanced" button:

• Volume: Change the volume of the ‘Audio clip’. This must be value between ‘0’ and ‘1’ representing 0% to 100% of the original volume.
• Loop: Specify if the "Audio clip" should continue playing continuously, until paused or stopped using another "Play audio" Action with the "Action" set to "Pause" or "Stop" respectively.
• Play count: Specify how many times the "Audio clip" must be played.
• Interrupt guidance: Specify if the "Audio clip" should interrupt any audio guidance currently playing. Especially useful for Events that could be triggered while guidance for another Step is playing, but the user wants the Event audio take precedence. If audio guidance is interrupted by this Action, it will start playing the audio guidance once this Action is done playing.

Best practise

• Use short completion audio cues for success and distinct error audio cue for invalid actions.
• Create audio content using "Build sound from text" and use these as introduction when  the trainee enters a new area or sections of the training.

QA checklist

• Test that audio plays once or loops as intended.
• Test that the audio mixes well with voice guidance and stops on Step change.
• Test that proper delays are added if there are multiple sounds in sequence.
• Test that the volume is not set too high - above 0.8 may dominate voice guidance.

Play video

Used when the Procedure must play a video file already configured and added to the 3D scene. The following parameters can be set by the user:

• Target: Defines the video object to be played.
• Action: Choose between "Play" and "Stop".
• Mute: Option to mute the video.

There are also a few noteworthy parameters hidden under the "Advanced" button:

• Start time: Defines the start time of the video defined in seconds. Can be used to crop the beginning of the video, or to split the video into several smaller clips used at specific steps.
• End time: Defines the end time of the video defined in seconds. Can be used to crop the end of the video, or to split the video into several smaller clips used at specific steps.
• Loop: Option to continuously loop the video (optionally defined be the start/end time).
• Volume: Adjust the volume of the video. This must be value between ‘0’ and ‘1’ representing 0% to 100% of the original volume.
• Complete before finishing Operation: When this is set to true (default) the Operation is not marked as finished allowing the trainee to proceed to the next Step in the Procedure until the video has played to the end. Set this parameter to false if you want to allow the trainee to proceed through the Procedure, while the video keeps playing in the background.

Best practise

• Play only a single video at the same time.

QA checklist

• Test that video playback starts reliably and loops or ends as configured on all clients. 

Toggle event

Controlling when a trainee should be able to interact with an Event (enabled) and when the trainee should no longer be able to interact with an Event (disabled).

The following parameters can be set by the user:

• Enable: List of Events to enable – select from the drop-down menu listing all defined Events.
• Disable: List of Events to disable – select from the drop-down menu listing all defined Events.

Best practise

• Enable an Event when users should be able to activate it, and disable it once no longer relevant to prevent unintended activations.
• Chaining Toggle events can cause broken flows. Keep logic simple and avoid circular toggles.

QA checklist

• Test that Events are enabled/disabled correctly.
• Test activating/deactivating Events in all Step they are enabled to avoid issues with certain user interaction sequences.
• Test that disabled Events cannot be triggered.

Transform object

Used when an object should be moved, rotated and/or scaled.

The following parameters can be set by the user:

• Object: Specifies the object to be moved, rotated and/or scaled.
• Position: Specifies the new position of the Object. Can be changed either by typing numbers directly into the input field or by dragging the 3D gizmo in the scene.
• Rotation: Specifies the new rotation of the Object. Can be changed either by typing numbers directly into the input field or by dragging the 3D gizmo in the scene.
• Scale: Specifies the new scale of the Object. Can be changed either by typing numbers directly into the input field or by dragging the 3D gizmo in the scene.

There are also a few noteworthy parameters hidden under the "Advanced" button:

• Duration: Specify the duration (in seconds) of the transform action. Used to animate the transformation over time. Overrides the default 0.75 seconds duration.
• New parent: Defines the new parent of the Object. The Action will result in the Object becoming a child object to the "New parent" object if this parameter is set.

Best practise

• Do not transform the same object while it is being grabbed.
• Avoid moving colliders away from their authored position. 

QA checklist

• Test the smoothness of the motion.
• Make sure that there are sufficient delays if multiple actions.