BoxQuest: To Run, Or Not To Run

Game Development

Input mechanisms are a common issue being addressed by HTML5 developers. In my previous post, we dove into our latest Github sample – BoxQuest – and in this post I want to dive into more detail regarding Freewill.js, the virtual controls framework being used in BoxQuest.

There were a number of goals in mind for Freewill.js:

  • Avoid reliance on any external frameworks.
  • Make usage as simple as possible.
  • Allow room for customization.
  • Multiple Joysticks and Buttons; true multi-touch support.

The result is a virtual controls framework that can be easily included in any HTML5 application, giving the developer the ability to implement the control system to match the project.

Including Freewill.js

First off, the Freewill.js framework can be obtained from the BoxQuest repository and is included into an application the same way as any <script> element.

In Cocos2d-HTML5, this means including it as a part of our jsloader.js script configuration; however, it can be included more generically as follows.

<script type="text/javascript" src="Freewill.js"></script>

Once we’ve added the script to our application, the next step is to define our base variable.

/* Load freewill. */
this.freewill = new Freewill({
container: document.querySelector('#freewill')
});

In our case, #freewill is a <div> overlaying the contents of index.html, yet these controls could be added to any element that supports touch event listeners on the DOM. The default behavior of each control is handled by the framework, while allowing each to be customized through various parameters and touch listener overrides.

Adding a Button

To add a Freewill.js button to our application, we leverage the addButton function:

/* Add a Button to control jumping. */
this.freewill.jump = this.freewill.addButton({
image: './images/freewill/buttonblue.png',
pos: [0.0, 0.0]
});

The variable itself is represented by this.freewill.jump; note that we are defining a variable because we need a reference to our in order to override the onTouchStart, onTouchMove, and onTouchEnd functions of our button.

There are two required parameters that we need to provide values for:

  • image: A path to the image that will be displayed for this control.
  • pos: The [X,Y] screen coordinates to position this control.

Even though BoxQuest utilizes invisible controls, the image and pos parameters are still required. In addition, there are a handful of optional parameters that can be set:

  • trigger: The [X,Y,Width,Height] area that will trigger touch events when interacted with.
  • opacLow: Value between 0.0 and 1.0 indicating the opacity of the control when it is not being interacted with.
  • opacHigh: Value between 0.0 and 1.0 indicating the opacity of the control when it is being interacted with.

By default, the trigger is set to the position and dimensions of the control based on pos and image; however, this area can be overridden. In BoxQuest, we defined trigger to be anywhere on the right-side of the screen:

trigger: [window.innerWidth / 2.0, 0.0, window.innerWidth / 2.0, window.innerHeight]

…and opacLow and opacHigh to both be 0.0, meaning the user will never actually see the control. Instead, they have an invisible area to interact with.

The final step is to initiate some action when the button is actually clicked, and for this we override the onTouchStart function.

/* When the user touches the screen, we initiate a jump (vertical impulse.) */
this.freewill.jump.onTouchStart = function () {
/* Perform some action here. */
};

Adding a Joystick

To add a Freewill.js joystick, the process is very similar to that of the button, but instead we use the addJoystick function:

/* Add a Joystick to control movement. */
this.freewill.move = this.freewill.addJoystick({
imageBase: './images/freewill/buttonblue.png',
imagePad: './images/freewill/buttonblue.png',
fixed: true
});

This time, we create the variable this.freewill.move so that we can later add functionality to control our Hero. In this case, there are three required parameters:

  • imageBase: A path to the image that will be displayed as the base of this control; remains stationary.
  • imagePad: A path to the image that will be displayed as the pad of this control; follows the user’s finger as they move it around the base.
  • fixed: A boolean variable that determines whether the entire control will remain stationary (i.e. locked to a specific coordinate) or will reposition itself to the point where the user initiates a touch.

As with the button, we have a number of optional parameters:

  • pos: The [X,Y] screen coordinate to position this control.
  • trigger: The [X,Y,Width,Height] area that will trigger touch events when interacted with.
  • opacLow: Value between 0.0 and 1.0 indicating the opacity of the control when it is not being interacted with.
  • opacHigh: Value between 0.0 and 1.0 indicating the opacity of the control when it is being interacted with.

In BoxQuest, we’ve defined an invisible (opacLow and opacHigh are both 0.0), non-moving (fixed is true) Joystick that controls the movement of our Hero when the left-side of the screen is interacted with (custom trigger) parameter.

To apply forces that move our Hero through the world, we’ve overridden the onTouchMove and onTouchEnd functions of the this.freewill.move variable. The framework automatically invokes these functions if they are defined.

Other Examples

You may notice that the functionality of Freewill.js is very similar to the control mechanism being used in PeaksAndValleys for its dual-joystick controls. This is because our BoxQuest implementation was based on the foundation created for PeaksAndValleys.

Prior to Freewill.js, Jerome Etienne’s virtualjoystick.js was leveraged in the PeaksAndValleys sample. However, there were a few requirements as the project expanded which were not inherently addressed, and so Freewill.js was created.

While Freewill.js is intended to support a large number of use cases, if you find yourself in need of customization, by all means build on the source code. If you have any questions about the source, please leave a comment here or reach out to me directly via Twitter® (@WaterlooErik). I’m always happy to hear about projects you’re working on, so don’t hesitate to drop me a line!

About Erik O.

HTML5 Application Development Consultant at BlackBerry.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus