nifty_gui.md

title
Creating JME3 User Interfaces with Nifty GUI

Creating JME3 User Interfaces with Nifty GUI

You may want your players to press a button to save a game, you want a scrolling text field for highscores, a text label to display the score, drop-downs to select keymap preferences, or checkboxes to specify multi-media options. Usually you solve these tasks by using Swing controls. Although it is possible to embed a jME3 canvas in a Swing GUI, a 3D game typically runs full-screen, or in a window of its own.

This document introduces you to Nifty GUI, a Java library for building interactive graphical user interfaces (GUIs) for games or similar applications. Nifty GUI (the de.lessvoid.nifty package) is well integrated with jME3 through the com.jme3.niftygui package. You define the base GUI layout in XML, and control it dynamically from your Java code. The necessary JAR libraries are included in your jME3 download, you do not need to install anything extra. (Just make sure they are on the classpath.)

• Video demo of Nifty GUI 1.3

Tutorial Overview

Learn to add a Nifty GUI to your jME3 game by going through this multi-part tutorial:

1. Understand the Nifty GUI Concepts described on this page.
2. Browse this short list of Best Practices
3. Lay out your graphical user interface:
   • Lay out the GUI in XML – or –
   • Lay out the GUI in Java
4. Integrate the GUI into the game:
   • Overlay the User Interface Over the Screen – or –
   • Project the User Interface Onto a Texture
5. Interact with the GUI from Java

Must Know: Nifty GUI Concepts

Nifty GUIs are made up of the following elements:

• A Nifty GUI contains one or more screens.
  • Only one screen is visible at a time.
  • Name the first screen start. Name any others whatever you like.
  • Screen are controlled by a Java Controller class.
• A screen contains one or more layers.
  • Layers are containers that impose alignment on their contents (vertical, horizontal, or centered)
  • Layers can overlap (z-order), and cannot be nested.
• A layer contains panels.
  • Panels are containers that impose alignment on their contents (vertical, horizontal, or centered)
  • Panels can be nested, and cannot overlap.
• A panel contains images, text, or controls (buttons, etc).

Resources

• Browse this short list of Best Practices before you start

JME-Nifty Sample Code

• XML examples
  • HelloJme.xml
• Java examples
  • TestNiftyGui.java
  • TestNiftyToMesh.java
• jME3-ready version of the Nifty GUI 1.3 demo (sample code, Java)
  • NiftyGuiDemo.zip
• Find more sample code in the Nifty GUI source repository

External Documentation

Learn more from the NiftyGUI page:

• Nifty GUI - the Manual
• Nifty 1.3 JavaDoc
• Nifty 1.3 Controls JavaDoc
• Forum post: Changing Text in Nifty GUIs programmatically
• Official Nifty GUI Editor
• New Nifty GUI Editor
• Nifty GUI with Groovy

Next Steps

Now that you understand the concepts and know where to find more information, learn how to lay out a simple graphical user interface. Typically, you start doing this in XML.

• Lay out the GUI in XML (recommended)
• Lay out the GUI in Java (optional)
• Lay out the GUI in Editor (experimental)

Nifty Logging (Nifty 1.3.1)

If you want to disable the nifty log lines, add this code after you created nifty:

Logger.getLogger("de.lessvoid.nifty").setLevel(Level.SEVERE); 
Logger.getLogger("NiftyInputEventHandlingLog").setLevel(Level.SEVERE); 

gui, documentation, nifty, hud