With the level whitebox nearly complete, it's time to start thinking about those scripted events. Scripting level events can add immensely to any level and can be as simple as triggered sounds or particle effects, or as complicated as fully scripted cutscenes or minigames. Unreal 4 gives us the ability to visually program these sequences using the flexible Blueprint system. We've used Blueprint before for simple doors and elevators back in Chapter 2, Starting Our First Project. Now we will build on that knowledge to design and program flexible scripted events.
So how do we start? Designing a scripted event is not unlike our animations systems we have built before. Each one starts with an event that causes several different actions to fire in a sequence. The trick is to be able to logic out the sequence so that we get the desired effect with the player. For example, the average game explosion has a few different actions:
- Wait for the target object to take damage.
- Once damage reaches a certain amount, create a radius of damage and fire the smoke, spark, fire, and explosion particle emitters.
- Play explosion sound!
- Use the flying particles as cover to delete the original object.
- Spawn a damaged version of the original asset in its place.
Just like the explosion described here, any event can be broken down into specific events and simulated. So let's think about what our security checkpoint event needs. We need the player to feel threatened and to convey a sense of panic. I think we can do this by trying a few different things that together will have the desired effect. Here are some ideas in no particular order:
- Flash the lights
- Fill the room with smoke
- Sparks!
- Some kind of loud noise
- Slam the doors shut
- Slam the windows shut
- Fire!
Now there's a few great ideas! The next step is to arrange them into a logical order that can be programmed. Computers can't do anything we haven't specifically spelled out for them, so we have to be pretty clear about our instructions. Here is just one example of how I might order the instructions:
- Animate the doors and windows closed.
- Some kind of loud noise.
- Fire the smoke emitter.
- Fire the spark emitter.
- Play some clue to the player to let them know what to do to get out.
Seems like a pretty solid plan. The next step would be to add those additional elements to our level. Each entrance to the security checkpoint hallway needs a door, each window needs a shutter, and so on.
Let's build the doors first:
Building the first security door
- For the three security doors that slam down, I grabbed a Wall_400x200 piece from the Architecture folder and adjusted the Scale of the X to
0.4and the Z to1.1. I then changed the name for each toSec_Door1,Sec_Door2, andSec_Door3. Remember to also set the Mobility property toMovable. - I positioned each door above each door frame so that it can slam down during the event:
Building the security shutters
- For the two security window shutters, I used a Wall_400x400 piece and adjusted the Scale property of the x to
1.5and the z to0.5. I changed their names toSec_Win_Shutter1andSec_Win_Shutter2to make them easy to identify and set their Mobility to Movable.
Time to add a few more details to really make this area perfect:
Placing the particle emitters
- Particle emitters are points in space that emit light, sparks, or even static meshes if we want them to. They are created using Unreal's Cascade Particle Editor, though the Starter Content folder has some great ones we can use in the Particles sub-folder. Here I used a P_Smoke emitter at each door and one P_Sparks emitter near the window on the left. For all of them, I turned off the Auto Activate option in the Details panel to give us control of when they fire.
A trap like this is great, but we still need some way for the player to escape:
A view of the security office
- After a couple seconds, let's have the door to the security room malfunction and explode, allowing the player to reach the security override button! I have placed a couple of Point Lights above the door, one red and one green, that can indicate the door is opening (turn off the Visible property for the red light in the Details panel) and have built the override button using a Box Trigger and a SM_MatPreviewMesh_02 from the Props folder of the Content Browser. To make sure that clue is clear to the player I have placed a Text Render object above the button reading "Disengage Security Lockdown".
With all the pieces in place we are ready to script our event. Open the Level Blueprint by pressing the Blueprints button above the viewport and selecting Open Level Blueprint. For this level of scripting, we are also going to go up to the Window button in the toolbar and turn on the Palette window. This gives us access to a customizable Favorites list of nodes and the Find a Node search box, a great tool when constructing new Blueprint sequences:
Beginning the Level Blueprint
- Select both of the default nodes located in the Blueprint area and press Delete. We won't need them for this sequence.
- We need an event to start our sequence off. Back in the level, place a Box Trigger in the security checkpoint, about halfway down the hallway. Set its Box Extents property to be large enough to make missing it impossible. This will make the player trigger the security lockdown after they have completely entered the hallway. Inside the Level Blueprint, Right-click and select Add Event for Trigger Box, select Collision, and then select Add OnActorBeginOverlap. Remember that your trigger box number may vary from mine:
The complete Blueprint for swapping our colored lights
- Now, we need to change the warning light color. For this we are going to add a couple different nodes. In the search box of the Find a Node section of the Palette pane, type in
Do Once. This node works like a gate and ensures that anything after it only runs once. Here, we use it to make sure that the trigger we use to start the sequence cannot be set off more than once. Next, search for the Toggle Visibility node. Drag two of them into the Blueprint and connect them as shown. The targets for these nodes will be our red and green lights. We want to make sure we are showing the light we want and hiding the light we don't want:
Gathering our initial locations on our doors and windows
- Time to slam the doors and windows shut! This part looks a bit complicated but is actually just like something we did in Chapter 2, Starting Our First Project. We are going to use a Timeline to shut all of the security doors we created at the same time. The first thing we need to do is save the initial locations of all the things we are going to animate. Without this step, the doors and windows would slam down then keep going right through the floor! To stop that from happening, we animate the door's position from its initial position. First, create some vector variables to hold the data for the three security doors and two windows. Next, we will build a special sequence to handle collecting that data. Start with an Event BeginPlay event and connect it to a Set node for each variable. Then connect a Get Actor Location node to each Set, with each door and window as a target. This will get the location of each piece and then set it as the variable so that we can animate it in the next step:
The timeline that slides our doors and windows shut
- Now add the Timeline node and double click it to open it up. We want to slide our doors and window shutters down into place using a Vector Track. Remember that in a Vector Track, we can animate all three axes of movement, but we only want to use the Z axis here, so it will take a bit of sorting. Hold the Shift key and click on the red line. This will add a keyframe to the X-axis. Now click on the new keyframe and drag it out of the way. Now do the same on the green line and drag the Y-axis out of the way. This leaves us with the blue line, the z axis. Create a keyframe there and make sure its time and value are both set to
0. Add a second keyframe and set the time to something fast. I used0.25. Set the value to-210. This will slide them down into place, blocking our player's escape. After creating your keyframes for the Z-axis, feel free to delete the keyframes on the other two axes by clicking them and pressing the Delete key. You can also lock and hide these axes by using the buttons located in the upper left portion of the graph. Be sure to select the Last Keyframe checkbox as well. This tells the Timeline to stop at the last keyframe in the sequence:
Using the Set Actor Location node to move all of these doors and windows
- To finish off the animation, we need to connect a Set Actor Location node to the Update portion of our Timeline for each element that needs to be animated. Each of these nodes needs the appropriate target as well as a location to animate to. Just like in Chapter 2, Starting Our First Project, we will get the initial location of each element using our variables and add it with a Vector + Vector node to the Vector Track from the Timeline. Set each node up just like I have in the image. Near the bottom, I used a Reroute node to create all the connections to the Vector + Vector nodes. These can be used to redirect your connections if they start to get lost or separate out a connection into multiple wires so that it can be used multiple times. Right-click to open the menu and find the Reroute node near the bottom:
Activating all our particle effects with the Activate node
- Light the fireworks! Time to activate all of our particle effects. We do this using a… You guessed it! An Activate node! Search for this node using the Find a Node section and drag it into the Blueprint. The targets will be each of the particle effects. The targets can be created easily by going back to the level and holding the ctrl key while selecting each one. Back in the Blueprint, Right-click and select Create Reference to 4 Selected Actors. Plugging them in to the Activate node's Target will create the translation nodes (the nodes that say Target and Particle System Components):
Playing our sound effects using Play Sound at Location
- Next we will use Play Sound at Location to play our Sound Cue. This node is very straightforward and plays a sound chosen from the Content Browser at a location that we determine. Find this node and connect to our existing sequence. For my sound, I chose Collapse02 from the Audio portion of the Starter Content folder. For my location, I used one of the initial locations we had already stored in a variable:
Toggling security lights and destroying the door
- We are in the home stretch for this sequence. Using a Delay node, let's destroy the door to the security office and swap the lights. A Delay node will stop the execution of the sequence for a predetermined amount of time. Playtest the sequence to get a feel for how long you want the player to wait. The longer you have the Delay, the more tension and panic it creates! After much testing, I went with 12 seconds. More seemed too long. Less seemed too fast. Next, use a couple of Toggle Visibility nodes on our lights again to bring back our green light. This visual cue will let the player know where to go next. To give our player an audio cue, play the Explosion01 sound at the location of the door that leads to the security office. Finally, grab a Destroy node from the Find a Node section. In game terms, Destroy is just a fancy word for delete (I think it sounds better). Use this to delete the door:
Programming the security override button
- Lastly, let's program the button for the security override. The event is actually three events. The first two involve the trigger we created to make the button work. Select the level and create an OnActorBeginOverlap event and an OnActorEndOverlap event. The last event we need is a keyboard input for the E key. This can be found by typing
InputEinto the Find a Node search box. These will all be wired into a Gate node, just like we did for our elevator back on the cargo ship. This will require the player to stand within the trigger to open the Gate and make the E key work. To finish this sequence, wire the Exit part of the Gate into a Timeline Reverse node. The target can be found by dragging a wire off the target portion of the Reverse, opening up Class, then your level, and finally, selecting the Timeline used to control the security doors and windows.
Time to test! Playtest this section of the level and make sure everything is working. Feel the drama! Now it's time to script our elevator sequence. Compared to the security checkpoint, this one is easy!
Setting up the components for the elevator sequence
The elevator sequence works much like a shorter version of the security checkpoint sequence. When the player walks into a trigger, animate one elevator door, turn on a few particle emitters, and play a sound. Let's get started:
Getting the elevator door's initial position by adding onto our level initialization sequence
- Since we will be using a Timeline for this sequence, create a vector variable to hold the initial location of the door we plan to animate and set it using the same technique we used to get the initial location of the security doors.
Scripting the elevator sequence. Connect the nodes in this order: On Overlap, Timeline, Set Actor Location, Activate, Do Once, Play Sound at Location
- The event that kicks this one off is an OnActorBeginOverlap, using the trigger in front of the elevator buttons.
- Next, create a Timeline to move one of the doors just a bit, to make the player think they are opening.
- Use the Activate node to activate the smoke and sparks at the elevator door. I also added a fire emitter at the bottom of the elevator shaft and opened the doors down there a bit to give the player a view of what could have happened to them once they get down to the marketplace.
- I then used a Do Once and a Play Sound at Location node to have an explosion sound play. Do Once makes sure the audio doesn't try to loop and ruin the experience we are going for.
All done! Test the sequence to make sure it has the emotional effect that you want. Feel free to tweak the different particle effects, sounds, and timings until it feels right for you and your playtesters. In the next section, we will talk about win conditions and how to connect our two levels together.