Create Step-by-Step Scenarios#
The Scenario builder allows users to configure scenarios by defining the required steps to complete a task or achieve a specific objective. With this feature, users can define a series of steps and actions to simulate real-world situations and guide trainees through specific tasks or workflows. This is especially valuable for applications such as maintenance procedures, assembly instructions, and operational guidelines.
Preparing your scene#
Before starting with scenario creation, ensure your scene is fully prepared:
- All necessary 3D models and environments should be imported and properly positioned,
- Make sure that all objects that will be manipulated throughout the scenario are interactable (physicalized) and correctly setup (Ex: limits, damping, parenting),
- Confirm that interactions with objects are correctly set up to allow smooth functioning during the scenario execution.
Accessing the Scenario Builder#
Each XRTwin project includes a Scenario element in the hierarchy. To begin creating or editing a scenario, follow these steps:
- Select the Scenario object in the hierarchy
, - In the Scenario property panel (right), click on the
button.
Alternatively, you can click the 
button next to the scenario object in the hierarchy for quicker access, - This will open the Scenario Builder pop-up, where you can configure and define the steps for your scenario.
Adding steps and actions to the Scenario#
A scenario is composed of a series of steps that must be completed to achieve a specific goal. Each step consists of multiple "elementary" actions that guide the user through the task.
For example, in an engine maintenance scenario, you might have the following steps that could include several actions:
| Steps | Step's Actions |
|---|---|
| First Step: "Perform engine inspection" |
"Watch video instructions" "Remove engine cover" "Inspect spark plugs" "Tighten bolts on cylinder head" |
| Other Step: "Check levels" |
"Listen to audio instructions" "Check oil level" "Check windshield washer fluid levels" |
During the execution of the scenario, the system will proceed to the next step only when all actions in the current step have been successfully completed.
Users can manage steps and add actions within the Scenario Builder popup.
To manage Steps#
- To add (or insert) a new step to the scenario: click on the + button left to the current step name. An empty step is added just after the current step.
- To navigate to a specific step: click on the "previous" or "next" arrows
, - To delete a step: click the "Trash" button
next to the current step name. Be careful: all the step's actions are also deleted. This action is not undoable.
To add an Action to a Step#
-
Select a Step using the arrows,
-
Dropdown the Add action... list
at the bottom of the Scenario Builder popup, -
Select an action, then complete its parameters (see more in the following sections).
Scenario Parameters#
When configuring your scenario, you can adjust various parameters to enhance the user experience and provide additional guidance during the simulation.
Select the Scenario in the hierarchy. Scenario's properties are displayed in the Inspector (right panel).
In-Editor Controls#
When in Editor mode, the available parameters include:
- Show Assistance: displays visual aids that guide users on where to place objects within the scene. You can toggle these visual aids on or off at any point during the scenario execution. This feature is composed of:
- A blue ghost visualization of where the part should be positioned in the final assembly,
- A blue guideline that links the part’s current position to its target destination,
- Loop After Completion: automatically restarts the scenario back to Step 1 after it has been completed,
- Show Task List: displays a list of the current action(s) in the 3D view, showing the tasks the user must perform. You can customize the names of these actions directly in the Scenario Builder.
In-Simulation Controls#
During the simulation, in addition to the ability to show/hide assistance so as in Editor mode, two additional buttons will appear in the Scenario property panel:
- Next Step: forces the scenario to skip the current step and move to the next one,
- Reset Scenario: restarts the scenario from the beginning and repositions all parts to their initial positions (only parts related to the scenario are concerned). This allows the simulation to be repeated as many times as needed.
Actions library#
There are 5 elementary action types you can add to a step:
- Placing: the user needs to grab and move a part to a specific position. For example, "Remove engine cover" could involve physically lifting the cover off the engine (see below Placing action),
- Animate Object: a motorized joint or part will move automatically to a designated position. For instance, a robot arm might move from one position to another (see below Animate Object action),
- Watch Media: users may be prompted to watch a video or view an image, such as a short video demonstrating how to inspect engine parts (see below Watch Media action),
- Listen to Audio: audio instructions, like detailed guidance can be provided at any point (see below Listen to audio action),
- Wait: sets a timer for a specific duration (for example waiting for a machine to complete a task before proceeding) (see below Wait action).
From these individual elements, users can create a linear sequence of actions that form a comprehensive scenario.
Additionally, users can manage actions within the Scenario Builder popup by:
- Disabling Action: toggle action On or Off as needed
, - Renaming Action: rename action for better clarity and organization
. The action name is displayed within the task list, - Identify Target: click to focus on the Target, which will blink three times
, - Identify Object: click to focus on the Object, which will blink three times
, - Edit Action: click to edit Action parameters
, - Display contextual menu: click on the three points
to display additional features in a contextual menu:- Move to...: move concerned Action to an other Step to refine the sequence and flow of the scenario,
- Duplicate: make a copy of the concerned Action,
- Delete: delete the concerned Action. This is not undoable.
1. Placing action#
Purpose: the user needs to move a part from its current position to the specified target position/rotation.
The Placing action requires two main elements: a part and a target:
- Select the part in the hierarchy and drop it in the Part to Place slot. The part must be physicalized first.
- Select the part's target in the hierarchy and drop it in the Target slot.
If the target is not already in the scene, you can create one by clicking the + icon next to the target field. A new object is added to the hierarchy. It will have the same name as the object with the "_Target" suffix.
While the target is selected, a blue ghost of the corresponding part is displayed. Move the target to the part's final position.
The target can be configured with the following parameters:
-
Tolerance section:
-
Distance: defines how close the origin of the part must be to the origin of the target for the action to be considered complete (in meters),
-
Axis: scroll down the list to select the two axes to be used for angle tolerance (XY, XZ, YZ),
-
Angle: tolerance for first axes and second axes. Defines how closely the object's first (respectively second) axes direction must match the target's for the action to be completed (in degrees),
-
Symmetry: enable this option if the part can be aligned in the axis direction and the opposite direction (symmetrical part). If only position is important, set 360° (in this case, 360° is identical to 180°+symmetry).
-
-
Action section:
-
Snap to Target: determines if the part automatically snaps to align with the target position and rotation once the distance and angle tolerance are met. If this option remains unchecked, the object remains where it is when the tolerance conditions are validated,
-
Weld to: option to "weld" the part to specified object after placement. For example, in an assembly process, the placed part can be permanently attached to another object. If "No object" is specified, the part will be welded to the world (fixed in place). Select the part in the hierarchy, and drop it in the "Weld to" slot. To go back to No object, next to the object name, clic the (X) to remove the part.
-
Movable targets
You can place a target anywhere in the hierarchy, especially as a child of another part. This can be especially useful for scenarios where targets are moving, such as assembling a part on a conveyor. Positioning the target dynamically in the hierarchy lets you adapt to changing positions or orientations within the scene.
2. Animate Object action#
Purpose: an object will move from its current position to the specified target position/rotation. The Animate Object action automatically moves a part to a defined target.
Similar to the placing action, Animate Object popup requires two main elements: a part and a target. Drop an object in the Part to Place slot (must be physicalized first) and, a target in the Target slot. Here too a target can be created by clicking on the + icon if one does not already exist and, the target will show a blue ghost. Move the target to part's final position/rotation.
The following parameters control the movement of the part:
-
Trajectory section:
-
Linear Speed: the speed at which the object moves along its trajectory toward the target (in meters per second).
-
Angular Speed: the speed at which the object rotates to align with the target's orientation (in degrees per second).
-
-
Tolerance section: Same as for Placing (see above).
-
Distance: defines how close the origin of the part must be to the origin of the target for the action to be considered complete (in meters),
-
Axis: XY, XZ or YZ,
-
Angle: tolerance for first axes and second axes. Defines how closely the object's first (respectively second) axes direction must match the target's for the action to be completed (in degrees),
-
Symmetry: if the part can be aligned in the axis direction and the opposite direction (symmetrical part).
-
3. Watch Media action#
Purpose: displays a picture or video in the project.
This action requires to import a media file first. The image or the video will be displayed for the user to watch. The user must look at the media for a specified duration to complete the action. Configuration options include:
- Media: select the media file (image or video) from the hierarchy and drop it in this slot.
- Hide when complete: enable this option to automatically hide the media once the action is completed. If the option is left unchecked, the screen will remain displayed.
- Time to Complete Task: the time for which the user must view the media (for images only; for videos it equals the video length).
4. Listen to Audio action#
Purpose: plays the sound of an audio clip in the project.
This action involves playing an audio file from the hierarchy. The user has to listen to the audio clip until the end to complete the action.
- Media: from the hierarchy, select the audio clip to be played and drop it in the "Media" slot.
- Hide when Complete: Enable this option to deactivate the audio clip when you have listened to it to the end.
5. Wait action#
Purpose: waits a moment before moving on to the next step.
This action adds a timer to the Step actions. Current Step can only be validated once the timeout you have specified has expired.
- Name: Add an explicit name for the wait action to be displayed in the task list.
- Timeout: Change the timeout value (sec) directly builder popup
.
Manage your Actions#
Additionally, users can manage actions within the Scenario Builder popup by:
- Disabling Action: toggle action On or Off as needed ,
- Renaming Action: rename action for better clarity and organization . The action name is displayed within the task list,
- Identify Target: click to focus on the Target, which will blink three times ,
- Identify Object: click to focus on the Object, which will blink three times ,
- Edit Action: click to edit Action parameters ,
- Display contextual menu: click on the three points to display additional features in a contextual menu:
- Move to...: move concerned Action to an other Step to refine the sequence and flow of the scenario,
- Duplicate: make a copy of the concerned Action,
- Delete: delete the concerned Action. This is not undoable.
Play the Scenario#
Once all your steps have been defined, test your scenario. To do this:
- Close the Scenario Builder popup,
- Check the User (manipulations are more intuitive in VR)
- Save your project,
- Run the simulation,
- The scenario starts immediately.