Head-Up Display (HUD)

A HUD (Head-Up Display) is part of a game's visual user interface. It's an overlay that displays additional information as (typically) 2-dimensional text or icons on the screen, on top of the 3D scene. Not all games have, or need a HUD. To avoid breaking the immersion and cluttering the screen, only use a HUD if it is the only way to convey certain information.

HUDs are used to supply players with essential information about the game state.

You have two options how to create HUDs.

OptionProsCons
Attach elements to default guiNode:Easy to learn. jMonkeyEngine built-in API for attaching images and bitmap text.Only basic features.
You will have to write custom controls / buttons / effects if you need them.
Use advanced Nifty GUI integration:Full-featured interactive user interface.
Includes buttons, effects, controls.
Supports XML and Java layouts.
Steeper learning curve.

Simple HUD: GUI Node

Using the GUI Node is the default approach in jme3 to create simple HUDs. If you just quickly want to display a line of text, or a simple icon on the screen, use this no-frills method.

Next to the rootNode for the 3-dimensional scene graph, jME3 also offers a 2-dimension (orthogonal) node, the guiNode.

This is how you use the guiNode for HUDs:

The BitmapTexts and Pictures appear as 2 dimensional element on the screen.

Note: The size unit for the guiNode is pixels, not world units.

By default, the guiNode has some scene graph statistics attached in SimpleApplication. To clear the guiNode and attach your own GUI elements, you detach all children.

guiNode.detachAllChildren();

Displaying Pictures in the HUD

A simple image can be displayed using com.jme3.ui.Picture.

Picture pic = new Picture("HUD Picture");
pic.setImage(assetManager, "Textures/ColoredTex/Monkey.png", true);
pic.setWidth(settings.getWidth()/2);
pic.setHeight(settings.getHeight()/2);
pic.setPosition(settings.getWidth()/4, settings.getHeight()/4);
guiNode.attachChild(pic);

When you set the last boolean in setImage() to true, the alpha channel of your image is rendered transparent/translucent.

Displaying Text in the HUD

You use com.jme3.font.BitmapText to display text on the screen.

BitmapText hudText = new BitmapText(guiFont, false);          
hudText.setSize(guiFont.getCharSet().getRenderedSize());      // font size
hudText.setColor(ColorRGBA.Blue);                             // font color
hudText.setText("You can write any string here");             // the text
hudText.setLocalTranslation(300, hudText.getLineHeight(), 0); // position
guiNode.attachChild(hudText);

The BitmapFont object guiFont is a default font provided by SimpleApplication. Copy you own fonts as .fnt plus .png files into the assets/Interface/Fonts directory and load them like this:

BitmapFont myFont = assetManager.loadFont("Interface/Fonts/Console.fnt");
hudText = new BitmapText(myFont, false);

Displaying Geometries in the HUD

It is technically possible to attach Quads and 3D Geometries to the HUD. They show up as flat, static GUI elements. Note that if you use a lit Material, you must add a light to the guiNode. Also remember that size units are pixels in the HUD (a 2-wu cube is displayed tiny 2 pixels wide!).

Positioning HUD Elements

Keeping the HUD Up-To-Date

Use the update loop to keep the content up-to-date.

public void simpleUpdate(float tpf) {
  ...
  hudText.setText("Score: " + score);
  ...
  picture.setImage(assetManager, "Interface/statechange.png", true);
  ...
}

Advanced HUD: Nifty GUI

The recommended approach to create HUDs is using Nifty GUI.

  1. Lay out the GUI in one or several Nifty XML or Java files.
  2. Write the controller classes in Java.
  3. Load the XML file with the controller object in your game's simpleInit() method.

The advantage of Nifty GUI is that it is well integrated into jME and the jMonkeyPlatform, and that it offers all the features that you expect from a professional modern user interface.

For HUDs, you basically follow the same instructions as for creating a normal Nifty GUI, you just don't pause the game while the HUD is up.

gui, display, documentation, hud

view online version