Menu
Lumberyard
User Guide (Version 1.14)

Script Canvas Tutorial: Creating a Controllable Entity

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

This tutorial walks you through the steps to create a simple sphere that you can control with keyboard input, as in the following image.

Example


                Example controllable sphere in Script Canvas.

In addition to node basics, input, movement, and logging, you learn the following key concepts:

  • Adding nodes

  • Creating execution and data connections

  • Adding event nodes

  • Adding action nodes

Note

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 Print node, you must enable the Script Canvas Diagnostic Library gem and then build your game project. For more information, see Enabling Gems.

Prerequisites

Step 1: Create a Level

Before you create a sphere that you can control with keyboard input, you need to create a level.

To create a level

  1. In Lumberyard Editor, choose File, New.

  2. In the New Level dialog box, type firstscriptcanvas and then click OK.

  3. In the Generate Terrain Texture dialog box, choose 512x512 and then click OK.

Step 2: Create an Entity and Add Components to Create a Controllable Entity

To create a sphere that you can control with keyboard input, you create an entity and add the Mesh, Rigid Body Physics, Mesh Collider, and Input components. You also create an input mapping that converts WASD keyboard input into movement in the x and y directions.

To create a controllable entity

  1. In Lumberyard Editor, create an entity: Right-click in the Perspective viewport and choose Create entity.

  2. In the Entity Inspector, do the following:

    1. For Name, type Player.

      
                                Create an entity for the sphere in Script Canvas.
    2. Click Add Component.

    3. Under Rendering, click Mesh.

    4. Under Mesh, for Mesh asset, click the browse (...) button and navigate to the \SamplesProject\Objects\default directory. Select primitive_sphere.cgf and then click OK.

      
                                Select the sphere asset for the Mesh
                                    component.
  3. In the viewport, use the Move tool to select the z-axis and move the entity off the ground.

  4. In the Entity Inspector, click Add Component. Under Physics, click Rigid Body Physics.

  5. Click Add Component again. Under Physics, click Mesh Collider.

  6. Click Add Component again. Under Gameplay, click Input.

  7. In the Entity Inspector, under Input, click the Input Bindings Editor icon . This opens the Asset Editor.

  8. In the Asset Editor, choose File, New, Input Bindings and for File name, type player and then click Save.

  9. In the Edit Asset window, do the following:

    1. For Input Event Groups, click + to add a new input event group.

    2. Expand the input event group. For Event Name, type move_x.

    3. For Event Generators, click + to add an event generator.

    4. In the Class to create dialog box, click OK to add an input class.

    5. Expand move_x, Event Generators, gamepad_button_a. For Input Device Type, select keyboard.

    6. For Input Name, select keyboard_key_alphanumeric_A.

    7. For Event value multiplier, type -1.

    8. Repeat steps C – E. For Input Name, select keyboard_key_alphanumeric_D. For Event value multiplier, use the default value of 1.

    9. Expand the keyboard_key_alphanumeric_A event generator and and verify that your settings appear like the following image:

      
                                Creating the inputbindings for the
                                        Input component.
  10. In the Edit Asset window, do the following:

    1. For Input Event Groups, click + to add a new input event group.

    2. Expand the input event group. For Event Name, type move_y.

    3. For Event Generators, click + to add an event generator.

    4. In the Class to create dialog box, click OK to add an input class.

    5. Expand move_y, Event Generators, gamepad_button_a. For Input Device Type, select keyboard.

    6. For Input Name, select keyboard_key_alphanumeric_W. For Event value multiplier, use the default value of 1.

    7. Repeat steps C – E. For Input Name, select keyboard_key_alphanumeric_S. For Event value multiplier, type -1.

    8. Expand keyboard_key_alphanumeric_W and verify that your settings appear like the following image:

      
                                Example player.inputbindings
                                    file.
    9. Choose File, Save.

  11. In the Entity Inspector, under Input, click the browse () button and navigate to the player.inputbindings file. Select player.inputbindings and then click OK.

Step 3: Create an Input Script with Script Canvas

Now that you set up a sphere with physics and input mapping, you can create your first script with the Script Canvas editor.

To create an input script

  1. In Lumberyard Editor, choose Tools, Script Canvas.

  2. In the Script Canvas editor, choose File, New Script.

  3. After the graph loads, choose File, Save As.

  4. In the Save As dialog box, for File name, type player and then click Save.

  5. In the Node Palette, type input in the search box.

    Note

    You can also access the list of nodes by right-clicking in an empty area on the graph.

  6. Under Gameplay, Input, drag Input Handler from the Node Palette to the graph. Input Handler is an event node. When an event occurs, the event node sends a message to the graph.

  7. For Event Name, type move_y. This tells the node to listen for the input event.

    
                        Example Input Handler node in
                            Script Canvas.
  8. In the Node Palette, type Print in the search box.

  9. Under Utilities, Debug, drag Print from the Node Palette to the graph. Print is an action node. When you execute an action node, it completes actions such as request data, set data, manipulate data, and trigger functions. Action nodes also print data to the editor console, allowing you to check values as the script is being executed.

  10. From Input Handler, drag the Held pin to connect it to the In pin of the Print node. This connection tells the Print node to execute after the input handler receives a held event.

    Note

    Node execution always flows from the left side to the right side of a node. For more information, see Pins and Connections.

  11. From Input Handler, drag the Value pin to connect it to the Value pin of the Print node. This connection tells the Input Handler node to pass the input event value from the input handler to the first argument on the Print node.

    Note

    Data is always input on the left side of a node and output from the right side of the node. For more information, see Pins and Connections.

  12. Verify that your script looks like the following image:

    
                        Example Input Handler and
                                Print nodes in Script Canvas.

Step 4: Assign the Script to Your Entity and Test the Script

The script that you made outputs the value of the input event. Now you can assign the script to your entity and test the script.

To assign and test your script

  1. In the Script Canvas editor, choose File, Save. You can also press Ctrl+S.

  2. In Lumberyard Editor, select the Player entity that you created.

  3. In the Entity Inspector, click Add Component.

  4. Under Scripting, click Script Canvas.

  5. Under Script Canvas, click the browse (...) button and navigate to the player.scriptcanvas file. Select player.scriptcanvas and then click OK.

  6. Press ` to open the console window or choose Tools, Console.

  7. Press Ctrl+G to enter game mode.

  8. To trigger your input event, press W and then press S. The Console pane in Lumberyard Editor outputs the value of the input event when the move_y event is triggered. In this case, the Console pane outputs 1 when you press W and outputs -1 when you press S.

  9. When you are done testing your script, press Esc.

Step 5: Create a Script to Move Your Sphere

Now that you've successfully created your first script, you can add nodes to move your sphere. You also modify the input event value to control the movement speed.

To move your sphere

  1. In the Script Canvas editor, in the Node Palette, type multiply in the search box.

  2. Under Math, drag Multiply from the Node Palette to the graph.

    
                        Example Script Canvas Multiply node.
  3. From Input Handler, drag the Held pin to connect it to the In pin of the Multiply node. This connection executes the Multiply node after the input handler receives a held event.

  4. From Input Handler, drag the Value pin to connect it to the Value A pin of the Multiply node.

  5. In the Multiply node, for Value B, type 0.1. This smaller value for the input event throttles the movement speed.

  6. In the Node Palette, type move in the search box.

  7. Under Entity, Transform, drag Move Entity from the Node Palette to the graph.

  8. In the Node Palette, type vector3 in the search box.

  9. Under Math, Vector3, drag Construct from the Node Palette to the graph. You use this node to build a vector 3 from a number.

  10. From Multiply, drag the Out pin to connect it to the In pin of the Construct node.

  11. From Multiply, drag the Result pin to connect it to the Y pin of the Construct node. You only need a y direction, so use the default value (0) for X and Z.

  12. From Construct, drag the Out pin to connect it to the In pin of the Move Entity node.

  13. From Construct, drag the Vector 3 pin to connect it to the Direction pin of the Move Entity node.

  14. Verify that your script looks like the following image.

    
                        Example Script Canvas graph to move a sphere  across the
                            y-axis.
  15. Choose File, Save. You can also press Ctrl+S.

  16. In Lumberyard Editor, press Ctrl+G to enter game mode and test your script.

  17. To move the sphere forward, press W. To move the sphere backwards, press S.

  18. When you are done testing your script, press Esc.

Step 6: Add Movement on the X-Axis for Your Sphere

Now that you've converted your input event value to a direction that moves the entity on the y-axis, you can add movement on the x-axis.

To add movement on the x-axis

  1. In the Script Canvas editor, drag on the graph to select the Input Handler, Multiply, Construct, and Move Entity nodes. An orange outline appears around the selected nodes.

    
                        Example Script Canvas graph to add movement on the x-axis for the
                            sphere.
  2. Press Ctrl+C to copy the selected nodes.

  3. Press Ctrl+V to paste the copied nodes and their connections. This allows you to clone the existing script and modify the cloned version with the appropriate settings for movement on the x-axis.

  4. While still selected, move the nodes so they don't overlap the copied nodes.

  5. In the duplicate Input Handler node, for Event Name, type move_x.

    Example

    Your graph should look like the following image.

    
                            Copy the nodes in the Script Canvas graph to move the sphere
                                up and down and side to side.
  6. For the duplicate Multiply node, move the connection from the Y pin to the X pin on the duplicate Construct node.

    Note

    To disconnect a connection, drag it to an empty part of the canvas. To delete a connection, press Alt and click the connection.

    
                        Example Multiply and
                                Construct nodes in Script Canvas.
  7. Verify that your script looks like the following.

    Example

    
                            Example Script Canvas graph to control your sphere
                                movement.
  8. Choose File, Save. You can also press Ctrl+S.

  9. In Lumberyard Editor, press Ctrl+G to enter game mode and test your script.

  10. Do the following:

    1. To move the sphere forward, press W.

    2. To move the sphere backwards, press S.

    3. To move the sphere from side to side, press A and D.

  11. When you are done testing your script, press Esc.