This guide follows along with this video, which you can use as a reference. I recommend opening the video on YouTube instead of watching it embedded here since some of the menus can be small and hard to read in the embedded player.

To get started, grab the "base" map in this folder:
https://drive.google.com/open?id=1c15JuOYrOUs3yPazxr2hCieU7pU2wd2A

Once you download it, place it in:

• Windows - "..\Documents\My Games\Distance\Levels\MyLevels\"
  
• Mac - "~/Library/Application Support/Refract/Distance/Levels/MyLevels/"
  
• Linux - "~/.config/refract/Distance/Levels/MyLevels/"

This map will be the starting point for this guide, and should look like this when you first open it:

You don't necessarily need to download the map. All it has in it is just a startzone, two roads, a road end cap, one large CubeGS at the end of the road, and two small transparent CubeGS on the road. You can set this up yourself if you prefer.

Now you're ready to begin!

Note that this guide assumes you already know the basics of using the editor, such as how to move the camera, place and select objects, edit object properties, and some basic hotkeys like copy and paste.

Jump to video time - 1:02

First, select the large cube on the far right. From there, look at the bottom of the properties window and hit Add Component and then choose the Animator component.








Now you should see this Animator property added to the cube. We want to get the cube to move down so it's level with the road. Let's see how to do that.

















Change Motion to Advanced so we get more options to use.




Disable Rotate and change Translate Type to Global. We don't need to rotate for this example, and global will ensure the units you use to translate match your position units. While we're at it, go ahead and change the Translate Vector Y amount to -60, to get the cube moving down.




Now we can set the Delay to 0 and the Duration to 4 seconds as well as disable Loop; we only want the cube to move down once.




From there we're almost done, just set Default Action to Play and that's it! You've got a cube that moves down 60 units when the map starts.

Jump to video time - 3:34

The first thing you need to do if you want to use an event trigger to trigger an animation is to make sure that the animation doesn't play automatically. To do this, change the Default Action of the large cube's animator from Play to None.

Now on to the event triggers.

Event Triggers are in the Events folder of the library and there are two variations of event triggers - box and sphere. Since we've got two small transparent cubes on our map here, we're going to use the box variation. Go ahead and place an EventTriggerBox somewhere near the first green transparent cube.



Now edit the Scale of the EventTriggerBox to match the size of the CubeGS - I've found that around 6.5 works well.

Then copy the Position values from the CubeGS to the EventTriggerBox so they are in the same spot.

Now we want to select both the EventTriggerBox and the CubeGS (hold Ctrl to select multiple objects), and then hit Ctrl+G to group the two objects together. You should see something like this after grouping them:



Inspect Children of the group and select All children so we can see the properties of both the EventTriggerBox and the CubeGS. From here, we'll want to give the EventTriggerBox an Event Name (not a Custom Name). We'll just call it "Box1" for now.

Now we're done setting up the event trigger. Time to move back to the animated cube.

Go select the larger animated cube, hit Add Component again, but this time select the Event Listener component.




You'll notice that adding the Event Listener component added Event Options to the bottom of the Animator property and added an Event Listener property.







We need to make the large cube's animator listen for the "Box1" event to happen (when you touch the "Box1" trigger). To do this, set the Event Name of the Event Listener property to "Box1" by either typing it in, or by using the PickEventName button.

We will also need to set the Off Action to None so the animator doesn't do anything after the animation gets played.





Time to playtest! Now your animation should play when you touch the first transparent box!

If you just want the very basics of using Animators and event triggers, this is where you can stop, play around on your own with all the properties, and find some cool animations that you want to use in your maps. However, if you want to do more complex actions like being able to listen for multiple event triggers in order to trigger a single animator, then continue on.

Jump to video time - 6:55

This is where animators and event triggers start to get a little more complicated and where it can begin to be hard to follow what's going on. We want to add another animation to our large cube (say we want it to move away from the road after moving down), but if you try to add another animator component to the large cube, you will notice that the animator component in the drop-down is marked red, telling you that you can't have more than one animator on an object.

In order to accomplish this, let's select our large animated cube and hit Ctrl+G. What this will do is group the cube with itself - creating a group with only one object in it. Your properties window should now look something like this.

This now allows us to add another Animator to the cube. The reason for this is because the animator is being added to the group, not to the cube itself. The cube itself still retains our original (first) animator and event listener, and the group will contain our second animator.


Notice you are now able to add an Animator component - because it is being added to the group, not to the cube itself. So let's add this second animator component, and just as before we'll set the Motion to Advanced, disable Rotation, and set Translate Type to Global.

From here, we need to change the Y amount on the Translate Vector from the default 10 to 0 and the Z amount (third value) to something like -60. We also need to consider the Delay this time because we want it to play after our first animator. Remember that our first animation has a Duration of 4s, so if we want our second animation to play after the first one, then we need to set the Delay of the second animation to the same amount as our first animation's Duration, 4s. This time let's set the Duration to something a bit quicker, maybe 2s, and then just like we did previously, we want to disable Loop, make sure Animate Physics is enabled and Always Animate is disabled, and then set the Default Action to Play.






If you playtest now, you'll notice that our cube moves backward as soon as we start the map, just like our first animation did before we added the event listener. We need to do the same thing here with our second animator, but first thing's first - make sure to change the Default Action from Play to None!

Now let's add our Event Listener, and set it up exactly the same as before, listening for the same "Box1" event. Playtesting now will show you that the animated cube no longer moves as soon as you start the map, and when you touch the "Box1" trigger, the large cube will move down first and then backward after that.





Now you've stacked an animator! You can group this large cube with itself again and add a third animator if you want, and then group it again and add a fourth, etc.

To keep track of which animators are in what order you can use the Custom Name property every time you group again and then Inspect Children to view all your animations. You can also use the Test Animation button (and then hit Z to simulate touching the trigger) to view the animation in the editor without having to go to playtest mode. This can be extremely helpful to view your animation timings, especially from different angles. After the animation plays, you can hit Esc or just select the object again to reset the animation.

Jump to video time - 9:57

Here is where things can get quite a lot more complicated and it combines everything taught up until this point.

The first thing we're going to want to do is ungroup our large animated cube, to get rid of the second animator (on the group) and only keep the first animator (on the cube itself). This will just simplify things going forward. To do this, select the cube and hit Shift+G. Ensure the very top of the properties window says "CubeGS" in orange right above the transform property. If it still says "Group" then you'll need to ungroup again. Depending on how many groups and animators you added previously, continue ungrouping until you're left with just the cube itself and one animator. Now we can begin.


What we want to accomplish here is to require the player to hit both of the small transparent cubes in order to get the large cube to move down. Let's see how to accomplish this.

Select and delete this second small transparent cube since it doesn't have an event trigger set up for it yet. Now select the first transparent cube (which does have an event trigger), copy it and paste it somewhere near where the second cube used to be. Now we have two small transparent cubes with event triggers on each.

Don't forget to give the second cube a unique Event Name - I'm just going to call it "Box2"


Here is where things can start to get confusing. First, select the large animated cube again and clear the Event Listener name. We don't want to listen for just this single event, we want to listen for both "Box1" and "Box2" events to trigger.

We can't add another Event Listener to the cube without grouping it and adding another animator, and it isn't a second animation that we want to trigger - we want both events to trigger a single animation after hitting both triggers.

Stay with me here because this is just going to be "follow along" for the time being and it'll make sense what we're doing after we've done it.

---(Only do this part if you're in a test map to better visualize what's happening; do not do this part in an actual map)---
Place down a new CubeGS (found in the Simples folder of the library) somewhere near the middle of the map. Edit the properties of this cube to enable Disable Collison and enable Additive Transparency. Then, you want to edit the scale so it covers the area where your small triggers are. Set the scale values to x=300/65, y=100/65, and z=500/65 (you can type in the full "300/65" without quotes in the scale input value and it'll do the math for you).

You should now have something like this:


---(Rejoin the guide here for an actual map)---
Now place down a new EventTriggerBox (in the same location you placed down the CubeGS, so you don't have to copy any position values), and use the scale values of x=300, y=100, z=500. Notice that these values are the exact same as the values used for the CubeGS, but without dividing by 65. This is because the CubeGS scale is about 65 times the size of the EventTriggerBox. It's not exact, but it's close enough for what we want to use it for here.

Just as we did with the small cubes, we want to select both the EventTriggerBox and the CubeGS and group them with Ctrl+G.

Once you've done that, Inspect Children of the group and set the Event Name to something like "LargeTrigger"









Now we want to select our animated cube and listen for the "LargeTrigger" event.


You can playtest if you want and notice that the animated cube moves down when you enter the large trigger, nothing new there. What we need to do next is move the large trigger down below the killgrid and make it animate upward into the play area of your map. We will use each of our small triggers to trigger the upward animation of this large trigger.

Now we need to determine how far down the large trigger needs to be moved as well as how far up each animation needs to move it - becasue it needs to stay below the killgrid after hitting your first small trigger and then move up into your play area after hitting the second one.

If this is confusing, you can check out the video at the top of the guide which demonstrates how it works and further explains it, and I'm going to walk through it here as well so you will hopefully have a better understanding of how it works by the end.

Jump to video time - 15:20

In order to determine how far down you need to move the large trigger, here is a formula:

-(((LargeTriggerHeight/2)+abs(RoadYPos-KillgridYPos))*2)*(n-1)

• LargeTriggerHeight is the scale Y value we set on the large trigger before grouping it, which was 100.
  
• RoadYPos is the Y position of the platform you're driving on. The default height is 0, but this will change in any actual (non-test) map.
  
• KillgridYPos is the Y position of the killgrid at the bottom of the map. The default is -100, but again, this will change in any actual (non-test) map.
  
• abs() is the absolute value.
  
• n is the number of small triggers we have, 2 in this case.

So let's fill those values in and complete the formula:
-(((100/2)+abs(0--100))*2)*(2-1)
-((50+abs(100))*2)*(1)
-((50+100)*2)
-(150*2)
-300

This tells us that we need to set our large trigger Y position to -300, so let's do that:


If you had trouble following along there, please go watch the video, it goes much more in-depth.

Now let's give our large trigger an Animator, and do the exact same as we did previously with our animated cube.




Set the Motion to Advanced, disable Rotate, and set Translate Type to Global. For now, let's just set the Translate Vector amounts to 0 - we'll come back to this in a moment.

Let's set the Delay to 0, and also set the Duration to 0 (which changes to 0.01).

Also just as we did with our animated cube, disable Loop. However, this time we want to set the Curve Type to Linear so it moves as fast as it can for the entire duration of the animation, disable Animate Physics because it isn't a collidable object and enable Always Animate because it's large and most likely going to be offscreen.

We also need to set Default Action to None, add an Event Listener component, set the Off Action to None, and set the Event Name to our first small trigger box, "Box1"










Now we need to figure out how far to translate this large trigger when you hit the first small trigger. So, here's another formula:

(abs(LargeTriggerYPos)-(5*n))/n

• abs() is absolute value.
  
• LargeTriggerYPos is the Y position of the large trigger that we determined with the previous formula, -300.
  
• n is the number of small triggers we have, 2.

As before, let's fill it in and go through it:
(abs(-300)-(5*2))/2
(300-10)/2
290/2
145

Now we can see we need to translate by 145, so let's put that in.

If you playtest now, you can jump off the edge and see how far down the large trigger is. Then you can hit your first box and jump off the edge to see where that large trigger animated up to. This is why we set up a transparent CubeGS for the large trigger - You wouldn't do this in an actual map, just for testing! In an actual map, you would just use a large EventTriggerBox on it's own, and group it to itself (similar to what we did with stacking Animators on the animated cube).

A quick note here - Using playtest mode can be helpful to visualize what's going on, but don't forget you can also use the Test Animation button (and then hit Z) to see where your large trigger moves to. This can be extremely useful when making an actual map, where you don't have a CubeGS grouped to the large EventTriggerBox in order to visualize it in playtest mode.

From here, you can see that the large trigger moves up about halfway when we hit our first trigger. The reason it doesn't move up exactly halfway (150 units) is because you sink into the killgrid slightly when you hit it, so it's best to be safe and keep the large trigger a few units below the killgrid just in case the player rams into the killgrid at high speed and clips into it for a few units.

Now we need to set up our second animator on the large trigger, so let's do what we did previously in the Stacking Animators section and group the large trigger with itself.










Then add another Animator and do exactly the same as we did with the first animator on the large trigger.




By this point, you shouldn't need a screenshot, since we're doing the exact same thing as before; set Motion to Advanced, disable Rotate, set Translate Type to Global, change the Translate Vector Y amount to 145, set Delay and Duration to 0, disable Loop, change Curve Type to Linear, disable Animate Physics, enable Always Animate, and set Default Action to None.

Then add an Event Listener component, set Off Action to None, and set the Event Name to the second box, "Box2"

If all that went by too quick, you can scroll back up and look at the screenshot from the first animator we set up on the large trigger. It's exactly the same with the one exception being the Event Name, which we set to "Box2" instead of "Box1" this time.

Now everything's hooked up! You can playtest and see that your animated cube doesn't move until after you hit both smaller cubes. You can also hit your smaller cubes in either order (1 and then 2, or 2 and then 1) because the Translate Vectors for the large trigger animations are both the same amount.

Jump to video time - 27:00

Now that you've got this system set up, what if you want to expand it? Maybe you've got some collectibles in your map to unlock an easter egg or open up the path to the finish and you want to add one more. How do you add another small trigger to this system?

First, let's copy one of our small boxes and paste it a little further down the road. Don't forget to give it a unique Event Name after pasting - I'm going to call it "Box3"


Now we need to go back through our formulas again to determine how far down our large trigger needs to be placed.

-(((LargeTriggerHeight/2)+abs(RoadYPos-KillgridYPos))*2)*(n-1)

And fill it out:
-(((100/2)+abs(0--100))*2)*(3-1)
-((50+100)*2)*(2)
-(150*2)*2
-300*2
-600

So we need to change the Y position of our large trigger to -600.


We also need to re-determine how far each translation should move it, so let's do that with the second formula:

(abs(LargeTriggerYPos)-(5*n))/n

And fill it out:
(abs(-600)-(5*3))/3
(600-15)/3
585/3
195

So we need to Inspect Children on our large trigger and change both of our Animators to translate 195 units instead of 145.

From there we need to group our large trigger with itself again, add an Animator, set it up just the same as we did before (only change being our new 195 unit translation), add an Event Listener with the same setup as before and the Event Name set to our third box, "Box3"
Again, you shouldn't need a screenshot for this by this point, but if you do, scroll up to when we added our first animator to the large trigger. It's exactly the same with the two differences I noted just above.

If you playtest now, you will see that you have to hit all three of your small triggers to get the large trigger to move into the play area of your map above the killgrid, which, in turn, triggers the animated cube to move down.

And we're done! That's how you stack event triggers to trigger a single animation, and how to add on to that system after you've set it up.

If you want to quickly get rid of the CubeGS visuals on your large trigger, Inspect Children on it and change all the color values to transparent (make sure the slider on the right side of the color picker is at the bottom for each color value). As long as it has Additive Transparency enabled and Multiplicative Transparency disabled, this will make the CubeGS completely transparent.

However, do take note, you are still inside of the CubeGS at this point and it can mess up how your skybox looks (it doesn't render quite as far when you're inside the cube), so I highly recommend not using a CubeGS in your actual maps, and only for testing so you can easily visualize in playtest mode where your large trigger is.
In your actual maps, you will want to use the Test Animation button (and hit Z to simulate hitting the trigger) to view where your large trigger moves to within the editor itself instead of using a transparent CubeGS and playtest mode.

And here is the final product:




















With the locations of the objects after they've finished animating: