search

austinhallock / html5-virtual-game-controller

An easy-to-implement, customizable virtual game controller for HTML5 games
MIT License
333 stars 63 forks source link

readme

HTML5 Virtual Game Controller

About

Author: Clay.io - Tools for HTML5 game developers

This library is for easy integration of a virtual game controller overlay for HTML5 games. With HTML5, it's easy to get your game to run on touch-screen devices like phones and tablets, but user-input is a whole different story. With just the accelerometer and touch to work with, it makes it hard to have a game's input pair well with the desktop version.

The HTML5 Virtual Game Controller aims to alleviate the problem with a super-simple, yet customizable option for adding a touch-based gamepad to your game when touch is enabled. The controller will only be shown if touch is available on the device.

Watch a demo video here, or try the game out (if you have a touch-capable device). In Chrome, you can enable fake touch events with: ctrl+shift+i, then click the settings icon on the bottom right. Select the "Overrides" tab, and check "Emulate touch events" at the bottom). The demo game isn't the most efficient on mobile devices in it's current state, but iOS Safari should handle it. The game mentions to press the space key, the "B" button has been mapped to that functionality. This was a game that completely didn't work with touch prior to this library.

As of January 20th 2013, tested in Chrome, Firefox, IE10, and Mobile Safari.

Easy Setup

<script type='text/javascript' src='/path/to/gamecontroller.js'></script>
<script type='text/javascript'>
    $( function() { // jQuery *not* required - just be to call onload
        GameController.init();
    } );
</script>

If you are using node.js and something like browserify, you can install with npm install game-controller

If you are still in the process of choosing an HTML5 Game Engine, see this list - complete with reviews and details of popular HTML5 Game Engines.

Advanced Options

The entire customization for this library is done through the options object that is passed as a parameter to the init method. This can be as simple as passing nothing, are as advanced as passing dozens of options.

var options = {};
GameController.init( options );

Below is a list of the possible options, and what each does.

Examples

DPad on left, 2 buttons on right

GameController.init();

GamePad 1

Joystick on left, 1 button on right

GameController.init( {
    left: {
        type: 'joystick'
    },
    right: {
        position: {
            right: '5%'
        },
        type: 'buttons',
        buttons: [
        {
            label: 'jump', fontSize: 13, touchStart: function() {
                // do something
            }
        },
        false, false, false
        ]
    }
} );

GamePad 2

Joysticks on both sides

GameController.init( {
    left: {
        type: 'joystick',
        position: { left: '15%', bottom: '15%' },
        joystick: {
          touchStart: function() {
            console.log('touch starts');
          },
          touchEnd: function() {
            console.log('touch ends');
          },
          touchMove: function( details ) {
            console.log( details.dx );
            console.log( details.dy );
            console.log( details.max );
            console.log( details.normalizedX );
            console.log( details.normalizedY );
          }
        }
    },
    right: {
        type: 'joystick',
        position: { right: '15%', bottom: '15%' } ,
        joystick: {
          touchMove: function( details ) {
             // Do something...
           }
       }
    }
});

GamePad 3

Two large buttons at bottom

GameController.init( {
    left: {
        position: { left: '50%', bottom: '5%' },
        dpad: {
            up: false,
            down: false,
            left: { width: '50%', height: '10%' },
            right: { width: '50%', height: '10%' }
        }
    },
    right: false
} );

GamePad 4

These examples are just the start - the customization allows for quite a bit to be done, and of course, the code can always be edited as well.