Create a HUD

A HUD, or Heads Up Display, is a place where information about the game and the user can be displayed whilst the game is being played. This is usually textually based data and doesn’t need to be rendered in 3D, which means we can take advantage of the fact that the game is a in a webpage and provide the heads up display using html and css.

Gamma provides the gma.hud object, which will create the necessary html for you and insert it into your webpage at runtime. It is then up to the programmer to supply the necessary css such that the HUD appears where desired.

Note

An instance of gma.hud is created for you when you create the manager and can be found on manager.hud

Structure of the HUD

A HUD is broken down into sections which contain parts. Each part can hold one or more items of information.

When the HUD is created, each section will be a div element. Each part within this section will be a dl list and each item of information within this will contain a dt, dd pair.

Specifying the HUD

By default, there is no HUD and it is only after one is specified that any html will be created for the HUD. To specify a hud in your game, you must call gma.hud.setup on manager.hud with a specification of what information you want displayed:

manager.hud.setup(specification);

Specifying Sections

The specification is a Javascript object which contains both keys and values. The keys specify the sections/parts to create and the value holds a javascript object which contains the information you wish to be displayed:

var specification = {
    section1_part1: {},
    section1_part2: {}
};

Each key must has an underscore in it’s name. This is used to split the name into two parts. The first part is the name of the section this part belongs to and the second part is the name of the part itself.

The previous example would generate the following html:

<div id="section1_hud">
    <dl class="part1">
    </dl>

    <dl class="part2">
    </dl>
</div>

As you shown above, each section is assigned an id of the first part of the key with the string “_hud”, and each section contains a class attribute equal to the second part of the key.

Specifiying information

The information is a javascript object which contains a label with either a value or a function:

{
    section1_part1: {
        item1 : 5
        item2 : "hi"
    },
    section1_part2: {
        item1 : function() { return new Date() }
    },

    section2_part1: {
        tHiNg : "blah"
    }
}

If the value is static (i.e. not a function), then it will never be updated once the HUD is created. However if you specify a function, then everytime the HUD is refreshed (which happens as part of the Game Loop), then the HUD will be updated to reflect the result of calling the function again.

The example above information will generate the following html:

<div id="section1_hud">
    <dl class="part1">
        <dt id="hud_item1"><span>item1</span></dt>
        <dd>5</dd>

        <dt id="hud_item2"><span>item2</span></dt>
        <dd>hi</dd>
    </dl>

    <dl class="part2">
        <dt id="hud_item1"><span>item1</span></dt>
        <dd>Wed Oct 13 2010 21:57:41 GMT+0800 (WST)</dd>
    </dl>
</div>

<div id="section2_hud">
    <dl class="part1">
        <dt id="hud_thing"><span>tHiNg</span></dt>
        <dd>blah</dd>
    </dl>
</div>

The dt generated will have an id attribute equal to the name of the item, lowercase, prepended by the string “hud_” holding a span with the label of the information as it’s value. The dd that is created is then given the value of the item.

Styling the HUD

Gamma does not specify how a HUD should appear, instead it only creates some semantic html and lets the game developer create the necessary css to make the HUD appear as desired.

Below is some example css that will look for a top_hud and bottom_hud sections, and turn them into a bar at the top and bottom of the screen respectively. Each of these sections contain parts named left and right, each appearing at their respective sides of the bars.

/* Setup the bars */

#top_hud, #bottom_hud {
  height:2em;
  position:absolute;
  left:0em;
  width:100%;
  background-color:black;
  color: white;
  background-color: rgba(0, 0, 0, 0.7);
}

#top_hud {
  top:0em;
}
#bottom_hud {
  bottom:0em;
}

/* Setup left and right part of each bar */

#bottom_hud dl, #top_hud dl {
  margin: 0.3em;
}

#bottom_hud dl.left, #top_hud dl.left {
  float: left;
}
#bottom_hud dl.right, #top_hud dl.right {
  float: right;
}

/* Setup labels for each itme */

#bottom_hud dt, #top_hud dt,
#bottom_hud dd, #top_hud dd {
  display: inline-block;
  line-height: 1.4em;
  margin: 0;
}

#bottom_hud dt, #top_hud dt {
        padding-right: 0.5em;
}

#bottom_hud dd, #top_hud dd {
  text-align: right;
}
dl.left dd {
  padding-right: 1em;
}
dl.right dt {
  padding-left: 1em;
}

Note

The gma.hud object will hide parts that don’t contain items and sections that don’t contain any parts

We could create a HUD that uses this structure with the following code:

/*global require */
require(['gma/base', 'gma/manager'],

    function(gma) {
        var manager = gma.manager({
            width : 600,
            height : 500
        });

        manager.hud.setup({
            top_left: {
                //manager.getFPS is a function
                //that returns the current fps when called
                time : manager.getFPS
            },

            top_right: {
                score : 1
            },

            bottom_left: {
                test : "hello"
            }
        });
    }
);

Customising the Labels

We can also do some nice tricks with our css to change the apearance of each item’s label. For example, making it hidden, so only the value is visible.

#hud_fps span {
  display:none;
}

Then, once the span is hidden, we can also replace the label with an image. For example, the following rules (assuming you have an fps.png)

#hud_fps span {
  display:none;
}

#hud_fps {
  display: block;
  background: transparent url(fps.png) no-repeat top left scroll;
  height: 18px;
  width: 18px;
  min-width: 18px;
  position: relative;
}

Hiding and Showing the HUD

You can also programmatically hide sections and/or parts of the HUD, and if you are so inclined, show them again with the HUD’s gma.hud.hide and gma.hud.show methods.

Without any arguments, these functions will be applied to the HUD as a whole. Alternatively, you call them with a string that either is the name of the section you want to operate on, or the name of the part prepended by the name of it’s section and an underscore.

For example, say we have a HUD setup in a similar way as shown in Styling the HUD, and we wanted to hide the right part of the top section, then we would call gma.hud.hide with the string “top_right”.

Note

If, after hiding a particular part of a section, there are no more parts in that section, then the entire section will be hidden