Tutorial: Script a trigger

BeginnerDesigner

In this tutorial, we'll create a trigger that doubles the size of a ball when the ball passes through it.

Note

The screenshots and videos in this tutorial were made using an earlier version of Xenko, so some parts of the UI, and the default skybox and sphere, might look different from your version.

1. Create a bouncing ball

Follow the instructions in the Create a bouncing ball tutorial. This creates a simple scene in which a ball falls from mid-air, hits the ground, and bounces.

2. Set the restitution

For this tutorial, we'll set the restitution of both the ground and the sphere to 0.9, which makes the ball very bouncy. This makes it easier to see the effect of the trigger later, as the ball will bounce in and out of the trigger area repeatedly.

  • Select the Sphere entity.

  • In the Property Grid, under Rigidbody, set the Restitution to 0.9.

Set restitution for a sphere

  • Select the Ground entity.

  • In the Property Grid, under Static Collider, set the Restitution to 0.9.

Set restitution for the ground

3. Add a trigger

Now we'll add a trigger between the ball and the ground, so the ball passes through it.

  • In the Scene Editor, click the white plus button (Create new entity) and select Empty entity.

Create new entity

Game Studio adds an entity to the scene with the default name Entity.

  • This entity will be our trigger, so rename it Trigger to make it easy to identify.

  • Since we don't need the trigger to move, we'll make it a static collider. In the Property Grid, click Add component and select Static Collider.

Add Static collider component

  • In the Property Grid, expand the Static Collider component to view its properties.

  • Select the Is Trigger checkbox.

Check 'Is trigger'

This makes the collider a trigger. This means objects can pass through it, but are still detected in the code.

  • We need to give the trigger a shape. Next to Collider Shapes, click Green plus button (Add) and select Box.

Add collider shape

This gives the trigger a box shape.

Added trigger

  • Let's make the trigger a larger area. In the Property Grid, under the Transform component properties, set the scale to: X:2, Y:2, Z:2

Scale a trigger

This doubles the size of the trigger.

Added trigger

4. Give the trigger a model

Right now, the trigger is invisible at runtime. To better show how the trigger works, we'll make it a transparent box. This has no effect on how the trigger works; it just means we can easily see where it is at runtime.

  • Create a new procedural model asset. To do this, in the Asset View, click Add asset, and select Models > Cube.

Add a model asset

  • Create a new empty material asset. To do this, in the Asset View, click Add asset, and select Materials > Material.

Add a material asset

  • Let's rename the material to make it easy to identify. To do this, right-click, select Rename, and type a new name (eg Transparent).

  • Select the Trigger entity. In the Property Grid, click Add component and select Model.

Add a model component

Game Studio adds a model component to the entity.

  • Under Model, click Hand icon (Select an asset).

Pick an asset up

  • Select the Cube model we created in step 1 and click OK.

Select Cube model

  • In the Property Grid, under Model > Materials, click Hand icon (Select an asset).

Select material

  • Select the Transparent material we created in step 2 and click OK.

Select material

  • In the Asset View, select the Transparent material asset.

Select material in Asset View

  • In the Property Grid, under Misc > Transparency, select Blend.

Select Blend

  • By default, the Alpha is set to 1. This makes the material completely opaque. To set it to 50% opacity, set the Alpha to 0.5.

Select Blend

Now the trigger area will be visible at runtime.

5. Position the trigger

We need to position the trigger between the ground and the sphere, so the ball falls through it.

In the Property Grid, under Transform, set the Position to: X:0, Y:3, Z:0

Now the trigger entity is between the ground and the sphere:

Trigger between ground and sphere

6. Change the sphere size with script

If we run the project now (F5), the ball falls through the trigger, but nothing happens.

Let's write a script to change the size of the ball when it enters the trigger.

Note

For more information about scripts, see Scripts.

  • In the Asset View, click Add asset and select Scripts > Async Script.

Use a script

  • In the Create a script dialog, name your script Trigger and click Create script.

    2a. If Game Studio asks if you want to save your script, click Save.

    2b. If Game Studio asks if you want to reload the assemblies, click Reload.

  • Open the script, replace its content with the following code, and save the file:

  1. using Xenko.Engine;
  2. using Xenko.Physics;
  3. using System.Threading.Tasks;
  4. using Xenko.Core.Mathematics;
  5. namespace TransformTrigger
  6. // You can use any namespace you like for this script.
  7. {
  8. public class Trigger : AsyncScript
  9. {
  10. public override async Task Execute()
  11. {
  12. var trigger = Entity.Get<PhysicsComponent>();
  13. trigger.ProcessCollisions = true;
  14. // Start state machine
  15. while (Game.IsRunning)
  16. {
  17. // 1. Wait for an entity to collide with the trigger
  18. var firstCollision = await trigger.NewCollision();
  19. var otherCollider = trigger == firstCollision.ColliderA
  20. ? firstCollision.ColliderB
  21. : firstCollision.ColliderA;
  22. otherCollider.Entity.Transform.Scale = new Vector3(2.0f, 2.0f, 2.0f);
  23. // 2. Wait for the entity to exit the trigger
  24. await firstCollision.Ended();
  25. otherCollider.Entity.Transform.Scale= new Vector3(1.0f, 1.0f, 1.0f);
  26. }
  27. }
  28. }
  29. }

This code doubles the size (scale) of any entity that enters the trigger. When the entity exits the trigger, it returns to its original size.

  • Reload the assemblies.

7. Add the script

Finally, let's add this script to the trigger entity as a component.

  • In Game Studio, select the Trigger entity.

  • In the Property Grid, click Add component and select the Trigger script.

Add script component to entity

8. Run the project

Run the project (F5) to see the trigger in action.

The ball falls through the trigger, doubles in size, exits the trigger, and returns to its normal size.

More ideas

You can alter the script to make other changes when the sphere enters the trigger.

For example, you can switch the material on the sphere entity. This script switches the material on the Sphere entity from the Sphere Material to the Ground Material and back again:

  1. using Xenko.Engine;
  2. using Xenko.Physics;
  3. using System.Threading.Tasks;
  4. using Xenko.Core.Mathematics;
  5. using Xenko.Rendering;
  6. namespace TransformTrigger
  7. // You can use any namespace you like for this script.
  8. {
  9. public class Trigger : AsyncScript
  10. {
  11. private Material material1;
  12. private Material material2;
  13. public override async Task Execute()
  14. {
  15. var trigger = Entity.Get<PhysicsComponent>();
  16. trigger.ProcessCollisions = true;
  17. // Make sure the materials are loaded
  18. material1 = Content.Load<Material>("Sphere Material");
  19. material2 = Content.Load<Material>("Ground Material");
  20. // Start state machine
  21. while (Game.IsRunning)
  22. {
  23. // 1. Wait for an entity to collide with the trigger
  24. var firstCollision = await trigger.NewCollision();
  25. var otherCollider = trigger == firstCollision.ColliderA
  26. ? firstCollision.ColliderB
  27. : firstCollision.ColliderA;
  28. // 2. Change the material on the entity
  29. otherCollider.Entity.Get<ModelComponent>().Materials[0] = material2;
  30. // 3. Wait for the entity to exit the trigger
  31. await firstCollision.Ended();
  32. // 4. Change the material back to the original one
  33. otherCollider.Entity.Get<ModelComponent>().Materials[0] = material1;
  34. }
  35. }
  36. public override void Cancel()
  37. {
  38. Content.Unload(material1);
  39. Content.Unload(material2);
  40. }
  41. }
  42. }

See also