Input

From OrbEdit Wiki

Jump to: navigation, search

Contents

Input Handling Basics

Image:ESDF.png

Orb's input system is based on a stack of InputContexts. An InputContext is a Lua class that has a method for each key press and release you are interested in. Whenever that key is pressed or released, the corresponding method of the Context at the top of the stack is called. Input only ever goes to the Context at the top of the stack, but the stack can be shuffled around at any time.

The term InputContext might be a little confusing at first. Game input can be broken down into different situations or contexts. Depending on the context in which a player presses a key, you will want to do something different. For example, if the context is "gameplay", pressing the A Button should make the player jump. However, if the context is "menu", pressing the A Button will select a menu item. When the menu is dismissed, that InputContext is popped from the stack, revealing the gameplay InputContext underneath, switching back to a "gameplay" context.


Getting Input

Orb recognizes ONLY key press and key release events. Key repeating has been disabled, that is, pressing and holding a key will only result in a single key press event. If you wish to check for a key being held down you will need to accomplish that through coroutines. Each time you press or release a key, that key's keycode is sent to Orb, telling it which key was pressed or released. Orb keeps several mappings that allow keycodes to be translated into a method to be called in your InputContexts.

Before these mappings can work, however, there are a few thing you have to do:

  1. Define what buttons you want your game to support. Think of a button as something like OK, Cancel, or Up, that represents some functionality in your game.
  2. Define a mapping between keys and buttons. For example, you might want the W key to map to Up. Thus, when the player presses W, it will perform the Up command.

Input.xml

These definitions both exist in the Input.xml file in your Project's root directory. Some defaults are provided, but you should modify this file to suit your game. This file is fairly well-commented and its format is very straight-forward. When your game starts, this file is processed and the appropriate mappings are created in order to dispatch keyboard input to your InputContexts.

Gamepad Input

Image:DPad.png

Gamepad input is no different than keyboard input. There are tons of ways to hook a gamepad up to your PC; you can use a USB adapter and a Playstation controller, hook up a 360 controller directly, or even use an actual gamepad made for the PC. In all cases, pressing a button on your gamepad will act identically to pressing a button on your keyboard; a keycode is sent to Orb, which then uses your Input.xml mapping to dispatch to the correct method in the active InputContext.

Orb uses a library named [SDL] for detecting gamepads. When Orb starts, you should see a message on the console telling you how many gamepads were detected. At this time, multiple input devices are not supported, but will be soon!


The InputContext Class

Let's look at a snippet from an InputContext class to see how it works: 

-- class: NewInputContext
NewInputContext= InputContext:new({name = "NewInputContext"});  -- Constructor, inherits from InputContext
 
-- Called when this InputContext is opened
function NewInputContext:open(...)
  print("open");
end
.
.
.
-- Called whenever the OK button is pressed
function NewInputContext:OKPressed()
  print("OK Pressed");
end
 
-- Called whenever the OK button is released
function NewInputContext:OKReleased()
  print("OK Released");
end
.
.
.
-- InputContext scripts must ALWAYS return an instance of the InputContext they define
return NewInputContext:new();

Keypress Methods

The naming convention for keypress methods is always the same: ButtonPressed() and ButtonReleased(), where Button is the name defined in Input.xml. Even though your game may define a large set of buttons, your InputContexts only need to have methods for the buttons they are interested in. For example, a MenuContext probably wouldn't care about the Jump button, so would not define a JumpPressed() or JumpReleased() method.

Control Methods

In addition to methods to handle input, InputContexts have 4 additional methods known as Control Methods. These are as follows:

  • InputContext:open(...): Called when the InputContext is initially opened, via InputManager:open()
  • InputContext:close(...): Called when the InputContext is closed, via InputManager:close()
  • InputContext:focus(...): Called when the InputContext becomes the active InputContext
  • InputContext:blur(...): Called when the InputContext loses its active state to another InputContext

Control methods are very important for being able to chain Contexts together. For example, the open() method for a MenuContext might make a menu Sprite visible, in effect "opening" the menu, and its close() method might make that same Sprite invisible, "closing" the menu.

All of this is much easier to understand by looking at actual code, now is a good time to check out the InputContext Tutorial!


OrbEdit makes it easy to add new InputContext classes, simply right-click on a directory in the Project Explorer View and select New->Input Context. This will automatically import a new InputContext class, populated with the appropriate methods based on your Input.xml file.

Retrieved from "http://chalicegames.com/orb/wiki/index.php/Input"