Tuesday, December 24, 2013

Vibration (Game Programming)

A few posts ago, I lamented the loss of the classic BEEP command (ASCII 07), and now it turns out that Firefox OS has the equivalent for phones. It's called Vibrate!



It's not music, but sometimes you want to alert the user and the music and sound is turned off. Or sometimes you might want to add a vibration as an extra cue that an explosion is taking place. Or sometimes you want to give the user a clue that they actually touched the screen in the right place by giving them a little buzz.

Regular web browsers don't do this and today's code won't work in desktop Firefox. But it works in Firefox OS!

Here's a little stand-alone code sample that shows exactly how to add vibrate to your games.

<!DOCTYPE HTML>
<html>  
  <head>
  <title>Vibration</title>
  <meta charset="UTF-8">
 
  <style>  
    
    #myButton1
    {
      position:absolute;
      top: 70px;
      left: 50px;
    }

    #myButton2
    {
      position:absolute;
      top: 70px;
      left: 120px;
    }
   
    #myButton3
    {
      position:absolute;
      top: 70px;
      left: 230px;
    } 
     
  </style>

    <script type="text/javascript">
       
      // Add load event listener to run first function.
      window.addEventListener("load", runFirst, false);
                  
      // This function runs when the document loads.
      function runFirst() {
        
        myButton1.addEventListener(
          "mousedown", myClick1,false);

        myButton2.addEventListener(
          "mousedown", myClick2,false);

        myButton3.addEventListener(
          "mousedown", myClick3,false);
       
        // Initial message.
        myPara.innerHTML = "Tap on a button.";
       
        // Background color
        document.body.style.backgroundColor = "GreenYellow";
      }
             
      function myClick1() {    
        window.navigator.vibrate(200);
      }
     
      function myClick2() {    
        window.navigator.vibrate([200,100,200]);
      } 

      function myClick3() {    
        window.navigator.vibrate(500);
      }  
 
    </script>
  </head>
   
  <body>  


    <p id="myPara">Text goes here.</p>

    <button id="myButton1">Short</button>
    <button id="myButton2">Short Short</button>
    <button id="myButton3">Long</button>

</body>

</html>


You can read about the Vibrate API on MDN here: https://developer.mozilla.org/en-US/docs/Web/Guide/API/Vibration. It's simple. It vibrates!

The vibrate method takes one parameter. It can be either a single number, or an array of numbers. For example, if you add window.navigator.vibrate(200) to your code, your phone will buzz for 200 milliseconds (or 2/10 of a second).

If you use an array of numbers, the first number will set the length of vibration, the second number will set the length of silence (non-vibration), and the third will vibrate again. For example,

        window.navigator.vibrate([200,100,200]);

will vibrate for 200 milliseconds, then pause for 100 milliseconds, and then vibrate for another 20 milliseconds. Beep! Beep! You can have as many elements in the array as you want, just alternate between vibration and non-vibration. I could see a Morse code training device here, if anyone uses Morse code any longer.

The rest of the sample just sets up three buttons, positions them absolutely with CSS, and attaches events to each button with event listeners. By the way, you don't want to use the onclick or onmousedown  inline event triggers you may be used to. Firefox OS doesn't allow them in certain situations and you don't need them. And the mousedown event is faster than click as well, because click is waiting for you to let go. And remember, there's no mice here, this is just translated on the phone to touch events.

One other thing to note is that I decided that this sample should have a background color since the white buttons might not show up well on a white screen. Since I like to do as much as I can in JavaScript, I set the background color here:

        document.body.style.backgroundColor = "GreenYellow";

You may be used to using background-color in CSS, but when you do the JavaScript thing, a lot of CSS properties change their name slightly when they move to the JavaScript country. And bgcolor has been deprecated a long time. Here's a nice list of CSS to JavaScript translations: http://noobflash.com/set-style-dynamically-with-javascript/

Here's what the screen looks like, in all its GreenYellow color. And here's the place to find these weird color names https://developer.mozilla.org/en-US/docs/Web/CSS/color_value. Upper and lower case don't matter so you can also type greenyellow. And the exact red/green/blue values are rgb(173,255,47).




All this was tested and run on my trusty ZTE Open Firefox OS phone.

Add some vibration to your game today!