Script Canvas Tutorial: Opening and Closing a Door with Trigger Areas and Variables

This feature is in preview release and is subject to change.

This topic references tools and features that are legacy. If you want to use legacy tools in Lumberyard Editor, disable the CryEntity Removal gem using the Project Configurator or the command line. To learn more about legacy features, see the Amazon Lumberyard Legacy Reference.

This tutorial builds on what you learned in the Script Canvas Tutorial: Creating a Controllable Entity. In the following tutorial you create a door that opens and closes when your controllable sphere enters and exits a trigger area. This involves several tasks:

Create a trigger area
Add event nodes
Add variables

This tutorial assumes that Samples Project is set as the default project. For more information about changing your default project, see Choosing a Game Project to Open.

If your Node Palette is missing nodes, you can update your preferences to show hidden nodes. For instructions, see Script Canvas Node Reference. To access diagnostic nodes, including the Log node, you must enable the Script Canvas Diagnostic Library gem and then build your game project. For more information, see Choosing a Game Project to Open.

Step 1: Create a Door and Trigger Area

To create a door and trigger area, you create an entity with child entities and add components to the child entities.

To create a door and trigger area

If you have not already done so, you must complete the Script Canvas Tutorial: Creating a Controllable Entity.
In Lumberyard Editor, create an entity: Right-click in the Perspective viewport near your controllable sphere and choose Create entity.
In the Entity Inspector, for Name, type Door Group.
Do the following to create a door:
1. In the Entity Outliner, right-click Door Group and choose Create child entity. This child entity is your door.
2. In the Entity Inspector, for Name, type Door Mesh.
3. In the Asset Browser, navigate to SamplesProject\Objects\Primitives.
4. With the Door Mesh entity selected in the viewport, drag box_1x1.cgf from the Asset Browser to the Entity Inspector to create a Mesh component.
5. In the Entity Inspector, click Add Component. Under Physics, click Static Physics. This adds a Static Physics component to the Door Mesh entity.
6. Click Add Component again. Under Physics, click Mesh Collider. This component defines the collision shape for the Door Mesh entity.
7. In the Entity Inspector, under Transform, for Scale, set X to 2.5, Y to 0.5, and Z to 4.0.
Do the following to create a trigger area:
1. In the Entity Outliner, right-click Door Group and choose Create child entity. This child entity is your trigger area.
2. In the Entity Inspector, for Name, type Door Trigger.
3. Click Add Component. Under Scripting, click Trigger Area.
4. Under Trigger Area, click Add Required Component. Under Shape, click Box Shape.
5. Under Box Shape, for Dimensions, set X to 3.0, Y to 9.0, and Z to 6.0.
6. Click Add Component again. Under Scripting, click Script Canvas.
7. In Lumberyard Editor, choose Tools, Script Canvas.
8. In the Script Canvas editor, choose File, New Script.
9. After the new canvas loads, choose File, Save As.
10. For File name, type door and then click Save. Note the directory path for your saved file, which you will need later.
11. In Lumberyard Editor, in the Entity Inspector, under Script Canvas, click the browse (...) icon and navigate to the door.scriptcanvas file. Select door.scriptcanvas and then click OK.

Step 2: Create a Script to Open and Close the Door

Now that you've set up your door and trigger area, you can create a script that opens and closes the door when another entity enters or leaves the trigger area.

To create a script that opens and closes the door

In the Script Canvas editor, open the door.scriptcanvas file, if it's not still open from Step 1: Create a Door and Trigger Area.
In the Node Palette, type vector3 in the search box.
Under Variables, Create Variable, drag Vector3 from the Node Palette to the canvas. You can use variables to store and modify persistent values in your script.
In the #Variable 1 node, for Display Name, type opened_position. The open position can use the default value of 0, 0, 0.
Drag another Vector3 from the Node Palette to the canvas.
In the #Variable 2 node, for Display Name, type closed_position.
In the #Variable 2 node, for Default Value, set Z to -2. A negative value for the z-axis slides the door down. Because the door entity is a child of Door Group, you can use local relative positions to control the open and closed positions of the door.
Drag another Vector3 from the Node Palette to the canvas.
In the #Variable 3 node, for Display Name, type current_position. This variable sets the door's current position.
Drag another Vector3 from the Node Palette to the canvas.
In the #Variable 4 node, for Display Name, type destination_position. This variable sets the door's destination position when the entity enters and exits the trigger area.
In the Node Palette, type trigger in the search box.
Under Gameplay, Trigger Area, drag On Area Entered from the Node Palette to the canvas. With this event node you can easily use the Lumberyard EBus messaging system.
In the Trigger Area node, click Add/Remove Events and then select the On Area Exited check box. This exposes the entered and exited events from the Trigger Area EBus.
In the Node Palette, type position in the search box.
Under Variables, Local Variables, #destination_position, drag two Set #destination_position nodes from the Node Palette to the canvas. Get and Set nodes are available in the Node Palette after you create a variable. These nodes enable you to work with dynamic variable values. The core variable node initializes the variable.
In the canvas, make the following connections:
1. From On Area Entered, drag the Out pin to connect it to the In pin of a Set #destination_position node.
2. From On Area Exited, drag the Out pin to connect it to the In pin of the other Set #destination_position node.
3. From #opened_position, drag the Get pin to connect it to the Vector 3 pin of the Set #destination_position node that is connected to On Area Entered.
4. From #closed_position, drag the Get pin to connect it to the Vector 3 pin of the Set #destination_position node that is connected to On Area Exited.
5. Verify that your script looks like the following image:
Do the following to get the Door Mesh entity's position and interpolate to the destination:
1. In the Node Palette, type get local in the search box.
2. Under Entity, Transform, drag Get Local Translation from the Node Palette to the canvas. You can use this node to get the current position of the Door Mesh entity and interpolate to the destination. A local translation applies to the translation of the entity relative to its parent.
3. In the Get Local Translation node, pause on the Source text box and click the target button. When selected, the target button has an orange outline.
4. In the Entity Outliner, select Door Mesh to assign the Door Mesh entity to the Source property in the Get Local Translation node.
  
  Note
  
  To reset an entity reference, right-click twice on the Source text box and choose Set to Self.
5. In the Script Canvas editor, make the following connections:
  1. From a Set #destination_position node, drag the Out pin to connect it to the In pin for Get Local Translation.
  2. From the other Set #destination_position node, drag the Out pin to connect it to the In pin for Get Local Translation.
    
    When multiple connections enter a single logic pin, the node is executed each time either execution is triggered. The node is executed more than once in the same game tick if multiple executions are triggered simultaneously.
Do the following to execute nodes for a specified amount of time, in seconds:
1. In the Node Palette, type current_position in the search box.
2. Under Variables, Local Variables, #current_position, drag Set #current_position from the Node Palette to the canvas.
3. From Get Local Translation, drag the Out pin to connect it to the In pin of the Set #current_position node.
4. From Get Local Translation, drag the Translation pin to connect it to the Vector3 pin of the Set #current_position node.
5. In the Node Palette, type duration in the search box.
6. Under Timing, drag Duration from the Node Palette to the canvas.
7. From Set #current_positon, drag the Out pin to connect it to the Start pin of the Duration node. Triggering the Duration node resets the time.
8. In the Duration node, for Duration, type 1.0 (seconds).
Do the following to set up interpolation between the current position and the destination:
1. In the Node Palette, type lerp in the search box.
2. Under Math, Vector3, drag Lerp from the Node Palette to the canvas. This node blends two values based on the Percentage property.
3. From Duration, drag the Out pin to connect it to the In pin of the Lerp node.
4. From Duration, drag the Elapsed pin to connect it to the Percentage pin of the Lerp node.
5. In the Node Palette, type current_position in the search box.
6. Under Variables, Local Variables, #current_position, drag get #current_position from the Node Palette to the canvas.
7. From Get #current_position, drag the Vector3 pin to connect it to the Start pin of the Lerp node.
8. In the Node Palette, type destination in the search box.
9. Under Variables, Local Variables, #destination_position, drag Get #destination_position from the Node Palette to the canvas.
10. From Get #destination_position, drag the Vector3 pin to connect it to the End pin of the Lerp node.
11. Verify that your script looks like the following image:
Do the following to set the position of the door when the Duration node blends between the current and destination positions:
1. In the Node Palette, type set local translation in the search box.
2. Under Entity, Transform, drag Set Local Translation from the Node Palette to the canvas.
3. From Lerp, drag the Out pin to connect it to the In pin of the Set Local Translation node.
4. From Lerp, drag the Vector3 pin to connect it to the Translation pin of the Set Local Translation node.
5. In the Set Local Translation node, pause on the Source text box and click the target button. When selected, the target button has an orange outline.
6. In the Entity Outliner, select Door Mesh to assign the Door Mesh entity to the Source property in the Set Local Translation node.
Verify that your script looks like the following image:
In the Script Canvas editor, choose File, Save. You can also press Ctrl+S.
In Lumberyard Editor, press Ctrl+G to enter game mode and test your script.
To move the sphere forward into the door trigger area and slide open the door, press the W, A, D keys.
To move the sphere backwards out of the trigger area and slide the door closed, press S.
When you are done testing your script, press Esc.