Working With Trigger Volume

Working with trigger volumes

A trigger volume is an invisible, non-collidable area that generates a Trigger event whenever an object or avatar enters or exits the area. This can be useful for opening automatic doors, counting visitors, and many other applications.

Using trigger volumes

Here are some steps to set up a trigger volume. For the purpose of this guide, we will be using the example script triggerannounce.cs, which announces when something enters or exits the trigger volume.

Adding a trigger volume to a scene

• Create a new experience as described in Quick start: Creating experiences in Sansar. For simplicity, choose the Base Template scene as the experience's starting template.

• Remember that trigger volumes are invisible. You may want to consider using visible objects to identify the trigger location or not, depending on your desired outcome.

  In this example, place two or more visible objects in such a way that you can easily navigate between them. We have used the free Sansar Example Crate 1.0 from the Sansar Store. This step is to make sure we can find the trigger volume while visiting the scene.

• From the System Objects tab of your Inventory, drag a new Trigger Volume into the scene.

  In this example, position it between the visible objects you have placed, such that a visitor must pass through the trigger volume in order to walk between the visible objects.

The trigger volume is between the two visible objects in such a way that visitors must pass through the trigger volume when walking between the two crates.

---

• Choose a script that makes use of the Trigger event.

  For the purposes of this example, upload the triggerannounce.cs script.

• Drag the script onto the trigger volume, or add a script component on the trigger volume container.

• Save, then Build your scene.

• When the scene has finished building, click the Visit Now button that appears to visit your scene.

Testing the trigger volume

When visiting the scene, walk into the trigger volume to trigger the attached script. Remember that trigger volumes are invisible to visitors, so you should walk towards the visible object markers, if there is one.

In the exercise above, the example script, triggerannounce.cs, is added to the trigger volume in between two (visible) objects. Walk into the area indicated by the visible objects you placed earlier to trigger the script. When you enter or exit the trigger volume, example script causes the trigger volume to log your entry or exit in chat.

Note**:** In order to view chat messages from any script, you must have the Chat app open.

When entering the invisible trigger volume, triggerannounce.cs announces your entry in the Chat app.

---

Trigger volume main properties

To access the trigger volume's properties, find the trigger volume's name in the Scene Objects panel, right-click it, and choose Properties to open its Properties panel.

The Properties panel for a trigger volume.

---

The trigger volume properties include:

Position - The location of the trigger volume's center.

Rotation - The trigger volume's orientation in the scene.

Scale - Increases or decreases the size of the entire trigger volume; defaults to 1.0.

Movable From Script - Set to On to allow scripts to move, rotate, and scale the trigger volume.

Collides With - Determines what kinds of objects can activate the trigger volume. For the best performance, Avatars and Dynamic Bodies is selected by default, but you can allow additional object types by selecting Everything from the dropdown. For additional information about the types of movable objects, including dynamic objects, see Object motion types.

Extents / Radius - May show one or the other based on the VolumeType selected. Changing the VolumeType defines the shape of the trigger volume. See changing the volume type below for information on Extents and Radius and how to change the VolumeType between a Box or a Sphere.

Changing the Volume Type

You can change a trigger volumes shape by accessing the volume component within the trigger volume's container. To access this:

1. Find the trigger volume's name in the Scene Objects panel and click on the blue arrow beside the name to drop down the trigger volume's list of components.

2. Find the Volume component and right-click it to open a sub-menu of actions.

3. Then, choose Properties from the sub-menu to open the volume Properties panel.

The properties in the volume-specific properties panel include:

VolumeType - The volume properties panel allows you to set the shape of the trigger volume to either a Box or Sphere by using the drop down. Box is the default volume type. Keep in mind that this can only be set in the Volume properties panel.

Note: Mesh is currently a selectable VolumeType on the drop down list. However, it is currently not supported with trigger volumes.

Depending on whether you've chosen to use Box or Sphere as the VolumeType, you will see the following show up on the volume properties panel and the trigger volume's main properties panel:

Extents - For the Box VolumeType only; defines the proportions of the trigger volume in the X, Y, and Z coordinates.

Radius - For the Sphere VolumeType; defines the radius of a spherical trigger volume.

Note: While HasCollision appears on the volume properties panel, it is currently not supported with trigger volumes.

Selecting the VolumeType from the properties of the trigger volume's Volume component.

---

TriggerAnnounce Example Script

using Sansar.Simulation;

/// <summary>
/// TriggerAnnounce announces on chat when someone (or some thing) enters the volume the script is attached to.
/// </summary>
public class TriggerAnnounce : SceneObjectScript
{
    public override void Init()
    {
        RigidBodyComponent rigidBody;
        // Collision events are related to the RigidBody component so we must find it.
        // See if this object has a RigidBodyComponent and grab the first one.
        if (ObjectPrivate.TryGetFirstComponent(out rigidBody)
            && rigidBody.IsTriggerVolume())
        {
            // Subscribe to TriggerVolume collisions on our rigid body: our callback (OnCollide) will get called
            // whenever a character or character vr hand or dynamic object collides with our trigger volume
            rigidBody.Subscribe(CollisionEventType.Trigger, OnCollide);
        }
        else
        {
            // This will write to the script console
            Log.Write("Couldn't find rigid body, or rigid body is not a trigger volume!");
        }
    }

    // "Collision" events are really RigidBody events, and they get RigidBodyData.
    private void OnCollide(CollisionData data)
    {
        // Ignore hands:
        if (data.HitControlPoint != ControlPointType.Invalid) return;

        if (data.Phase == CollisionEventPhase.TriggerEnter)
        {
            ScenePrivate.Chat.MessageAllUsers($"Object {data.HitComponentId.ObjectId} has entered my volume!");
        }
        else
        {
            // HitObject might be null if the object or avatar is no longer in the scene, here we are just reporting the object id.
            ScenePrivate.Chat.MessageAllUsers($"Object {data.HitComponentId.ObjectId} has left my volume!");
        }
    }
}