WebWorks Gamepad API thanks to our friend Peardox

I’m very pleased to announce the release of a Gamepad API for WebWorks applications. Not only is this a cool API that will open up new capabilities for WebWorks apps and games, but it was done in collaboration with one of our open source community members. Before I talk too much about the API, I want to take some time to thank Simon, better known as Peardox, for his many contributions. Peardox contributed the base code for several of the more advanced plugins that have been done by the community, including:

  • Mongoose – the embedded webserver
  • ScreenDisplay – screen hardware information
  • UPnP – gathers information from Universal Plug n Play devices

Peardox also provided some great additional contributions to the DeviceInfo plugin, which provides a bunch of lower level information from the device.

Besides the plugins that have been created, Peardox’s work has also greatly contributed to what it’s possible to do in a WebWorks plugin, and the new Gamepad plugin is no exception. So, thanks very much for all your contributions, Simon, on behalf of the whole BlackBerry community.

Our gamepad test app running on a Q5 – Image created in Mockit!

Our gamepad test app running on a Q5 – Image created in Mockit!

Peardox came to me with an initial proof-of-concept for the Gamepad API. He had a working version and sample based on the Native Gamepad code, but other work was making him busy and he didn’t have the time to finish it off. I completed the minor remaining tasks, but I also wanted to make using this API really seamless for Web developers. So, I spent some extra time making it implement the current HTML5 Gamepad spec. I also tested it with the Gamepad Tester loaded into a WebWorks app just to be sure.

Implementing the spec means that you use this API in a slightly different way than most WebWorks plugins. The plugin will check to see if navigator.getGamepads exists, and if not will map it to its own function for that call. That will happen when the “webworksready” or “deviceready” event has fired. This method returns the list of available gamepads in an array:


The Gamepad API recommendation is to check this array on the Animation Frame updates so that graphical and controller input is synchronized. For example, this is the method from the sample app:


There are events fired as well for when a gamepad is connected or disconnected, and in the sample this is used to update the list of attached controllers to display input from:


You’ll see from the sample app that the buttons go in a certain order – that’s the HTML5 Gamepad API’s “standard” mapping. As long as the controller is one that this plugin has an ID for then it knows how to map it to the “standard” order. Otherwise it will send it in the raw order that it gets, and the mapping attribute will be the empty string. That’s also according to the spec.

It’s really as simple as that. With a few lines, you can connect gamepads to your application or game controls and provide great new capabilities for your users. Consider adding gamepad support to multimedia apps, like a remote control, or to presentation and data visualisation applications.

The Gamepad API is available as a WebWorks 1.0 extension and a WebWorks 2.0 / Cordova plugin.

If you’re interested in contributing or working on open source, checkout the public BlackBerry repositories on GitHub. We’d appreciate your input. Contact me to get started: @timothywindsor on twitter, on GitHub.

About timwin1