Pointer Lock Plugin

• Version: 0.1.0
• Type: Input
• Author: Benjamin D. Richards for Kiwi.js Team
• Website: www.kiwijs.org
• Kiwi.js Version Last Tested: 1.1.1

Versions

TODO

• Detect and report whether the browser supports pointer lock

0.1.0

• Plugin created

Files/Folders

• README.md - This readme file.
• gruntfile.js - A build file that populates the 'dist' and 'docs' folders with the appropriate content.
• package.json - Node packages required for the grunt build along with information for the gruntfile to use when building.
• docs/ - Documentation generated by yuidocs.
• examples/ - Examples of the plugin in action.
• src/ - The source files for the plugin.

Description

The Pointer Lock plugin grants you quick and easy access to pointer lock functionality in your KiwiJS games.

Pointer lock is a useful browser function. It freezes the position of the mouse, hides the cursor, and reports all mouse movement. In this way you can move the mouse any distance in any direction, without bumping into the edge of the screen.

NOTE: Pointer lock is currently only available in Chrome and Firefox. Other browsers do not support this functionality. Future versions of this plugin should detect and report this incompatibility.

How to use

Acquiring the Plugin

Download the plugin from [GitHub](release link here). Use either src/pointer-lock.js or src/pointer-lock.min.js. We suggest you place these files within a plugins folder in your project along with any other plugins you might use, just to keep things tidy.

Including the Plugin

Directly after you have loaded the main KiwiJS library, link the plugin file.

<script src="js/lib/kiwi.min.js"></script>
<script src="js/plugins/pointer-lock.js"></script>

Activating the Plugin

Create a Kiwi.Plugins.PointerLock.PointerLock object. That's it - you're done!

myGame.pointerLock = new Kiwi.Plugins.PointerLock.PointerLock( myGame );

Now, when you load your game, you can click anywhere on the game area to activate pointer lock. You may need to click "Accept" on a prompt at first. Press ESC to deactivate pointer lock.

We recommend you create this object in the create method of a state. The PointerLock relies on certain game subsystems being online, and this is guaranteed to be the case by the time states are initialising.

We also recommend that you attach the PointerLock object to your game, rather than the state, as is conventional for KiwiJS assets. This simply ensures that you retain access to the object after state transitions. Neither state nor game needs to know about the object.

Customising the Plugin

You may optionally create your PointerLock object using a params object. You may specify any or all of the parameters. Note that you must always specify game.

// Default params
myGame.pointerLock = new Kiwi.Plugins.PointerLock.PointerLock( {
	game: myGame,
	lockOnClick: true,
	trackWhileUnlocked: true,
	runOnLock: function() {},
	runOnUnlock: function() {},
	runOnLockError: function() {}
	runOnMouseMove: function() {}
} );

game is the game object. You must always specify this. You may pass a single game object in place of the params object.

lockOnClick is a helper which you may wish to override. When lockOnClick is true, any time an unlocked pointer clicks on the game, it is locked. If you would rather have finer control over this behaviour, you may use the clickGameToLock() method (called automatically on creation and whenever pointer lock is ended); or if you want even finer control, use enablePointerLock(). Note that pointer lock must be initiated by a user gesture; you cannot simply call it on page load.

trackWhileUnlocked allows you to differentiate between locked and unlocked mouse movements. If it is false, the plugin will not call runOnMouseMove() when the pointer is unlocked. If it is true, the plugin will always call the method.

runOnLock is called once whenever the pointer is locked. By default this and all following functions are an empty function. Override them any way you please.

runOnUnlock is called once whenever the pointer is unlocked, for example by pressing the ESC key or by calling the disablePointerLock() method. Note that, if you have set lockOnClick to false, this is a great place to set up a new listener to reenable pointer lock.

runOnLockError is called when the API encounters an error when attempting to initialise pointer lock. This will most likely occur if you are attempting to engage pointer lock outside a proper user gesture. The plugin will automatically print a warning to the console indicating that there was an error before running this method.

runOnMouseMove is called when the mouse moves. This can happen many, many times per second. Every update, the plugin updates its movementX and movementY values. As this is part of a user gesture, it is the best time to trigger events with full permissions.

All of these parameters exist as properties of the PointerLock object itself, and may be set at runtime. For example:

pointerLock.trackWhileUnlocked = false;

Thank You

We hope you find this plugin useful.