= Integrating Nifty GUI: Overlay
:revnumber: 2.0
:revdate: 2020/07/23
:keywords: gui, documentation, nifty, hud


.  xref:gui/nifty_gui.adoc[Nifty GUI Concepts]
.  xref:gui/nifty_gui_best_practices.adoc[Nifty GUI Best Practices]
.  xref:gui/nifty_gui_xml_layout.adoc[Nifty GUI XML Layout] or xref:gui/nifty_gui_java_layout.adoc[Nifty GUI Java Layout]
.  *Nifty +++<abbr title="Graphical User Interface">GUI</abbr>+++ Overlay* or xref:gui/nifty_gui_projection.adoc[Nifty GUI Projection]
.  xref:gui/nifty_gui_java_interaction.adoc[Interact with the GUI from Java]


image::gui/nifty-gui-example.png[nifty-gui-example.png,width="300",height="200",align="left"]


Typically, you define a key (for example escape) that switches the +++<abbr title="Graphical User Interface">GUI</abbr>+++ on and off. The +++<abbr title="Graphical User Interface">GUI</abbr>+++ can be a StartScreen, OptionsScreen, CharacterCreationScreen, etc. While the +++<abbr title="Graphical User Interface">GUI</abbr>+++ is up, you pause the running game, and then overlay the +++<abbr title="Graphical User Interface">GUI</abbr>+++. You also must switch to a different set of user inputs while the game is paused, so the player can use the mouse pointer and keyboard to interact with the +++<abbr title="Graphical User Interface">GUI</abbr>+++.

You can also xref:gui/nifty_gui_projection.adoc[project] the +++<abbr title="Graphical User Interface">GUI</abbr>+++ as a texture onto a mesh texture (but then you cannot click to select).
On this page, we look at the overlay variant, which is more commonly used in games.


== Sample Code


*  link:https://github.com/jMonkeyEngine/jmonkeyengine/blob/master/jme3-examples/src/main/java/jme3test/niftygui/TestNiftyGui.java[TestNiftyGui.java]

[TIP]
====
The jme3-niftygui library is included in jMonkeyEngine. If you installed jMonkeyEngine using one of the <<ROOT:documentation.adoc#install,optional methods>>, it will be added to your projects Library folder as part of the installation. If you're using the jMonkeyEngine SDK, you add it to any project by btn:[RMB] selecting your projects `Library` folder, choosing `menu:Add Library[jme-niftygui]` followed by `Add Library`.
====


== Overlaying the User Interface Over the Screen

This code shows you how to overlay anything on the screen with the +++<abbr title="Graphical User Interface">GUI</abbr>+++. This is the most common usecase.

[source,java]
----

NiftyJmeDisplay niftyDisplay = NiftyJmeDisplay.newNiftyJmeDisplay(
    assetManager, inputManager, audioRenderer, guiViewPort);
/** Create a new NiftyGUI object */
Nifty nifty = niftyDisplay.getNifty();
/** Read your XML and initialize your custom ScreenController */
nifty.fromXml("Interface/tutorial/step2/screen.xml", "start");
// nifty.fromXml("Interface/helloworld.xml", "start", new MySettingsScreen(data));
// attach the Nifty display to the gui view port as a processor
guiViewPort.addProcessor(niftyDisplay);
// disable the fly cam
flyCam.setDragToRotate(true);

----

Currently you do not have a ScreenController – we will create one in the next exercise. As soon  as you have a screen controller, you will use the commented variant of the XML loading method:

[source,java]
----
nifty.fromXml("Interface/helloworld.xml", "start", new MySettingsScreen());
----

The `MySettingsScreen` class is a custom de.lessvoid.nifty.screen.ScreenController in which you will implement your +++<abbr title="Graphical User Interface">GUI</abbr>+++ behaviour.

If you have many screens or you want to keep them organized in separate files there is a method available that will just load an additional XML file. The content of the files are
simply added to whatever XML data has been loaded before.

[source,java]
----
nifty.addXml("Interface/mysecondscreen.xml");
----


== Next Steps

Now that you have layed out and integrated the +++<abbr title="Graphical User Interface">GUI</abbr>+++ in your app, you want to respond to user input and display the current game. Time to create a ScreenController!

*  xref:gui/nifty_gui_java_interaction.adoc[Interact with the GUI from Java]
