Tutorial Resources:

To follow along with the tutorial, you can download the starter project and use it as your base to implement the tutorial:

• Lesson4Base.zip (8KB)

The completed lesson files are available at the end of the tutorial.

As covered in Lesson 1, extract the example .zip into a personal project folder, and ensure that it builds in your build environment.

The built .swf of the base starter project should display a blue circle in the center of the screen.

Introduction to the Tutorial

In the last lesson, we saw how to create a simple controller component that moves the character based on a behavioral pattern. Next, we'll add keyboard input, so that the movements are controlled by the player.

To help streamline user input, PBE provides a method to check if a key is down: PBE.isKeyDown().

For more advanced input configurations (such as allowing key remappings or special event notifications for keys), PBE also provides the InputManager and the InputMap. These are more powerful, but often aren't needed for simpler games. We will not discuss them in this tutorial.

Building a Component

Just like in our last lesson, we again set up a basic scene with three basic components: render, spatial, and controller. And again, we will be creating a custom component that inherits from TickedComponent so that it updates itself every frame.

This new component will check if the left or right keys are down, and move the player's object if so.

The various keys that we can poll are referenced through the InputKey class:

   // Input keys can be referenced through static class members:
   InputKey.LEFT
   // Or they can be referenced by a named string lookup:
   InputKey.stringToKey("LEFT")
   

In the base lesson directory, you will find the simple stub class HeroControllerComponent. To make it respond to keyboard events, we will have the onTick() method ask PBE if the keys we are interested in are being pressed. You can do this through the PBE.isKeyDown() method, like so:

   // isKeyDown() returns a boolean -- false means the key is up, and true means that the key is down.
   if (PBE.isKeyDown(InputKey.SPACE))
   {
      // React to the key being depressed:
      Logger.print(this, "Hey, cheer up!");
   }
   

Depending on which keys are down, we will modify our owner's spatial component's position. Just like last time, we will retrieve the spatial position through a PropertyReference, make adjustments according to a set of rules, and then set the position property to the new position value. The only things that are different are the rules by which we change the position.

These are the rules that we will follow this time to move our character back and forth:

• If the right key is being pressed:
  • Move ourselves to the right
• If the left key is being pressed:
  • Move ourselves to the left
• If we are past the right edge:
  • Clamp ourselves to the right edge
• If we are past the left edge:
  • Clamp ourselves to the left edge

Now that we know how we want it to act, let's actually implement it. Modify the HeroControllerComponent to look like the following:

File: /Lesson4Base/Source/HeroControllerComponent.as

       package 
       {
           import com.pblabs.engine.PBE;
           import com.pblabs.engine.components.TickedComponent;
           import com.pblabs.engine.core.InputKey;
           import com.pblabs.engine.entity.PropertyReference;

           import flash.geom.Point;

           // Make a ticked component so that it can update itself every frame with onTick() 
           public class HeroControllerComponent extends TickedComponent
           {
               // Keep a property reference to our entity's position.
               public var positionReference:PropertyReference;

               // onTick() is called every frame
               public override function onTick(tickRate:Number):void
               {
                   // Get references for our spatial position.
                   var position:Point = owner.getProperty(positionReference);

                   // Look at our input keys to see which direction we should move. Left is -x, right is +x.
                   if (PBE.isKeyDown(InputKey.RIGHT))
                   {
                       // Move our hero to the right
                       position.x += 15;
                   }

                   if (PBE.isKeyDown(InputKey.LEFT))
                   {
                       // Move our hero to the left
                       position.x -= 15;
                   }

                   // Finally, add some boundary limits so that we don't go off the edge of the screen.
                   if (position.x > 375)
                   {
                       // Set our position at the wall edge
                       position.x = 375;               
                   } 
                   else if (position.x < -375)
                   {
                       // Set our position at the wall edge
                       position.x = -375;
                   }

                   // Send our manipulated spatial variables back to the spatial manager
                   owner.setProperty(positionReference, position);
               }    
           }
       }
   

And that should do it!

Putting your oar in.

After it's all compiled, you should have an .swf like the following (click to load):

Conclusion

Congratulations! You have finished lesson #4, and given your game the ability to react to user input.

You can download the completed project source files for this project.

• Lesson4Final.zip (8KB)