Lumberyard
User Guide (Version 1.15)

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.

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

Prerequisites

  • Set the Samples Project as the default project. For more information, see Choosing a Game Project to Open.

  • If your Node Palette is missing nodes, you can update your preferences to show hidden nodes. For more information, 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.

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, enter 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, right-click in the Perspective viewport and choose Create entity.

  2. In the Entity Inspector, do the following:

    1. For Name, enter Player.

      
                                Create an entity for the sphere in Script Canvas.
    2. Click Add Component and then choose the Mesh component.

    3. In the Mesh component, for Mesh asset, click the browse (...) button, select the \SamplesProject\Objects\default\primitive_sphere.cgf file 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 and then add the following components:

    • Rigid Body Physics

    • Mesh Collider.

    • Input

  5. In the Input component, click the Input Bindings Editor icon . This opens the Asset Editor.

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

  7. 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, enter 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, enter -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 verify that your settings appear like the following.

      
                                Creating the inputbindings for the
                                        Input component.
  8. 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, enter 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, enter -1.

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

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

  9. In the Input component, click the browse () button, select the player.inputbindings file, 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, enter player and then click Save.

  5. In the Node Palette, enter 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, enter move_y. This tells the node to listen for the input event.

    
                        Example Input Handler node in
                            Script Canvas.
  8. In the Node Palette, enter 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.

  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

    • Node execution always flows from the left side to the right side of a node.

    • 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 player.scriptcanvas file looks like the following.

    
                        Example Input Handler and
                                Print nodes in Script Canvas.
  13. In the Script Canvas editor, choose File, Save or press Ctrl+S.

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.

Note

The tutorial's keyboard input doesn't work in a remote desktop session.

To assign and test your script

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

  2. In the Entity Inspector, click Add Component, and then choose the Script Canvas component.

  3. Under Script Canvas, click the browse (...) button, select the player.scriptcanvas file, and then click OK.

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

  5. Press Ctrl+G to enter game mode.

  6. 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.

    
                        Console pane outputs 1 when you press W.
  7. 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, enter 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, enter 0.1. This smaller value for the input event throttles the movement speed.

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

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

  8. In the Node Palette, enter create from values in the search box.

  9. Under Math, Vector3, drag Create From Values 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 Create From Values node.

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

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

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

  14. Verify that your player.scriptcanvas graph looks like the following.

    
                        Example Script Canvas graph to move a sphere  across the
                            y-axis.
  15. Save your graph.

  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, Create From Values, 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, enter move_x.

    Example

    Your player.scriptcanvas graph should look like the following.

    
                            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 Create From Values 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 Create From
                                Values nodes in Script Canvas.
  7. Verify that your player.scriptcanvas file graph looks like the following.

    Example

    
                            Example Script Canvas graph to control your sphere
                                movement.
  8. Save your graph.

  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.