Making and touch games for the iPad, iPhone or Android devices can sometimes get tricky when dealing with input. Due to only having one state of input, a touch point (rather than a few mouse buttons and a large number of keyboard keys), it can get confusing as to how to specify different tasks in your game. How do you separate a moving command from a shooting command? Now, with the new TouchButton plugin you can add exciting, multitouch capable, customizable touch buttons to your game.

Below is an example demoing the plugin. You can move the character around the screen using the dpad at the bottom left and shoot the crates using the ‘a’ button on the right. This works for both touch input as well as mouse, however touch does support multi touch so you can shoot and run at the same time.

The source code for this example is located in the plugin’s example folder.

Downloading and Adding the Plugin

Download the TouchButton plugin from here. One you have it installed, unzip the folder to the location of your game. We recommend containing all your plugins within a plugin folder. Inside the folder you will find two js files, a readme.txt and an example folder. Read through the readme.txt file to get an overview of the plugin. We will be using the touchButton-1.0.0.js file for our game as it contains the plugin. There is also a minified version of the plugin if you prefer.

To add the plugin to our game we need to add it as a script to our html file.

We also need to add the plugin to our game’s options variable. Here we specify that we are using one plugin which is called ‘TouchButton’, which corresponds to the unique name located inside the plugin. This will boot the plugin and add it to our game so we can access it easily.

Now that we have added our plugin let’s look at how to use it.

What are Touch Buttons?

Touch Buttons, simply put, are sprite objects with an up and down state.

Creating Touch Buttons

Creating a touch button is just as simple as creating a Sprite object. Pass through the state, texture and location for the button.

Getting Input from Touch Buttons

To check whether a Touch Button is currently down, which means it is being pressed, we can use the isDown boolean variable. Each frame the Touch Button plugin automatically checks each touch button against all inputs and sets the isDown/isUp variables accordingly.

Sprite Sheets for Touch Buttons

Creating spritesheets for the Touch Button plugin is relatively simple. By default each spritesheet should have two cells, an up state and a down state. The up state image should exist in the first cell of the sprite sheet and the down state image should be in the second cell.

Animating Touch Buttons

Because Touch Buttons are extended Sprite objects with animations we are able to have nice animated buttons as well as static ones. Each Touch Button has two animations already attached to it, an up and a down animation. These, as explained earlier, are set to the first and second frame of the sprite sheet by default.

However, if we provide a larger sprite, because we want to animate our button, we will need to replace the animations. To do this we have to re-add the animation to the animation manager with our new frames.

This will replace the existing animations and cause the new, specified, animations to play instead. We need to pass through an additional true boolean at the end to ensure the animation to cause the changes to switch and apply correctly.

Note that you need to change the down animation before the up animation as we want to switch to the up animation last so it is the active animation when the game starts.

Custom Touch Button Hitboxes

When playing games on your iPad or iPhone it can be irritating to try and specifically touch the small buttons on the screen. Therefore we need a way to increase the size of the area of the button without making the button huge, taking up valuable screen space. To do this we can replace the default hitbox of the Touch Button with a new Kiwi.Rectangle set to our desired size. This way, the button will have a larger area of collision but the image will stay the same size.

Disabling and Hiding Touch Buttons

Sometimes we are going to want to disable our buttons from working without completely deleting the button. We can simply use the disable and enable function to restrict or allow input to be taken from the button.

What about if we want to hide our button from the screen but still allow input to occur on it? In that case we can use the hide/show functions of the Touch Button. This is useful for creating invisible buttons for your games.