Menu
Lumberyard
User Guide (Version 1.13)

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:

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

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 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 near your sphere and choose Create entity.

  2. In the Entity Inspector, do the following:

    1. For Name, type Player.

    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.

  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 .

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

  9. In the Asset Browser, navigate to the player.inputbindings file. Right-click the file and choose Open.

  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_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, choose keyboard_key_alphanumeric_A.

    7. For Event value multiplier, type -1.

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

    9. Verify that your settings appear as shown in the following image:

  11. 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. Then, for Input Name, select keyboard_key_alphanumeric_S. For Event value multiplier, type -1.

    8. Verify that your settings appear as shown in the following image:

    9. Choose File, Save.

  12. 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 Using Script Canvas

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

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 new canvas 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 canvas.

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

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

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

  9. Under Utilities, Debug, drag Log from the Node Palette to the canvas. Log 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 (white arrow) to connect it to the In pin of the Log node. This connection tells the Log 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 (yellow circle) to connect it to the Value pin of the Log node. This connection tells the Input Handler node to pass the input event value from the input handler to the first argument on the Log 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:

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 entity that you created in Step 2: Create an Entity and Add Components to Create a Controllable Entity.

  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 Ctrl+G to enter game mode.

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

  8. 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 the script 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 canvas.

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

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

  9. Under Math, Vector3, drag Construct from Values from the Node Palette to the canvas. 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 from Values node.

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

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

  13. From Construct from Values, drag the Result: Vector3 pin to connect it to the Direction pin of the Move Entity node.

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

  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 canvas to select the Input Handler, Multiply, Construct from Values, and Move Entity nodes. An orange outline appears around the selected nodes.

  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.

  6. Find the yellow line that connects the Result pin on the duplicate Multiply node to the Number: Y pin on the duplicate Construct from Values node. Click the connection near the Y pin on the Construct from Values node and move to the Number: X pin.

    Note

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

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

  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.