Handles user input such as keyboard, mouse and joystick.


This is a global object that can always be accessed.

By “binding” input to functions, it causes the function to be run when the key/button is pressed and again when it is released.

If the same key is bound more than one, more than one function will be called, in the opposite order that they were bound in.


//move the mouse to the center of the screen
GetInputManager:SetMousePos(Vector2(C_SCREEN_X/2, C_SCREEN_Y/2));

Binding Related


nil AddBinding(string inputName, string callbackName, number entityID)

Adding a binding causes the engine to call the specified function every time the key is pressed or released.

How to build the inputName string

This can be a single key, joystick button/dir, or mouse button.

Valid input name examples: a, b, c, 3, 4, f1, control, mouse_middle, mouse_left, space, mouse_wheel_up, tab, escape, subtract, equals, numpad_subtract, numpad_add, left, right, up, down and so forth.

In addition, the following can be appended to the inputName (for non joystick keys

returnThe Enter key, don’t ask me why it’s called return in Clanlib, did they write it on a Commodore 64?
controlThe control key must be held down also.  “control,r” means Ctrl-R must be pressed.
shiftThe shift key must be held down also.  “shift,r” means Shift-R must be pressed.
altThe alt/option key must be held down also.  “shift,r” means Shift-R must be pressed.
alwaysThis means the key will always trigger, even if shift/alt/control is also down.  Without “left,always”, you couldn’t fire with control and press left at the same time.
editor_onlyMeans these keybindings will only trigger when the editor is open.
game_and_editorMeans these keybindings will always trigger.  Default is only while the editor is not open.


//binding with a global callback
GetInputManager:AddBinding("f1,always", "OnHitF1Key", C_ENTITY_NONE);

//Let's also bind something to a specific entity, by providing a valid entityID
GetInputManager:AddBinding("mouse_left", "OnMouseLeft", someEntityID);

Now if you press f1 or click the left mouse button you will see an error about functions not being found.  You need to handle them, add this somewhere to a globally loaded script

function OnHitF1Key(bKeyDown)

if (bKeyDown) then
LogMsg("You pressed F1 down.");
LogMsg("You released F1.");

return true; //keep processing additional callbacks for F1 if applicable

That’s one down.  Now, we need to add a function to the entity’s script (whoever someEntityID came from)

function OnMouseLeft(bKeyDown)

if (bKeyDown) then
LogMsg("You pressed the left mouse button down.");
LogMsg("You released the left mouse button.");

return true; //keep processing additional callbacks for the left mouse button if applicable

About Joystick mapping

Valid joystick name examples: joy_0_left, joy_1_up, joy_0_button_0, joy_any_down

Instead of a # for which joystick, you can use “any” to map to all of them.


inputNameA string defining some forum of input.  Use comma to separate words.  The order doesn’t matter.
callbackNameA string containing the name of a properly setup function that should be called.  (it must accept one parm and return true or false)
entityIDIf not <C_ENTITY_NONE> this means the function is located in this Entity’s namespace.


When an Entity is deleted, any associated bindings to it are also automatically deleted for you.


boolean RemoveBinding(string inputName, string callbackName, int entityID)

This allows you to remove any previously setup binding.  Because there may be many bindings to the same key, you must enter all the information so it knows which binding to remove.


inputNameA string defining the input, the same one used to make the binding.
string callBackNameThe name of the callback function that was used to create the binding we’re after.
entityIDIf the original binding was to an Entity function, you’ll need to enter its ID here.  Otherwise, <C_ENTITY_NONE>.


True if a binding was actually removed.


nil RemoveBindingByEntity(Entity ent)

Allows you to easily remove all bindings from a specified Entity.


When Entity’s are deleted, they automatically call this function.


entThe Entity we need to remove all bindings from.  Note that this wants the Entity, not the ID.

Direct Device Access


Vector2 GetMousePos()


A Vector2 object containing the location of the mouse in screen coordinates.  Use ScreenToWorld to convert to a position on the active Map.


nil SetMousePos(Vector2 vPos)


vPosA Vector2 object containing the new mouse position in screen coordinates.


number GetJoystickCount()


How many joysticks are currently available.


Joystick GetJoystick(number joystickID)

This let’s you get access to additional information about the connected joysticks.  So you can detect say, a 360 controller and properly map to its extra buttons.


You use the normal AddBinding to map to joysticks.


A Joystick object or nil if the joystick doesn’t exist.

The Entity object.
The Vector2 object.
A map is a single area that can be any size and contain any amount of tiles, including Entities and TilePic’s.
By using InputManager::GetJoystick you can access extra information about a specific gamepad or joystick.