NoesisGUI

First steps with NoesisGUI and Unity

unity.jpg

First contact with the integration of NoesisGUI within Unity is described in this tutorial. The plugin is deeply integrated with Unity, XAMLs appears as native resources that directly use assets imported by Unity like Textures, Fonts and AudioClips. It is recommended that you read the rest of tutorials to familiarize yourself with the basic concepts of XAML and Noesis architecture.

spacer.png

Installation

UPDATE NOTE

Although not strictly necessary we recommend closing Unity and removing the folders '/Assets/NoesisGUI/Plugins and '/Assets/NoesisGUI/Samples' before installing a new version of NoesisGUI.

The first thing is installing the downloaded NoesisGUI-X.X.X.XXXX.unitypackage into your Unity project. You can do this by clicking on the Unity menu option:

Assets -> Import Package -> Custom Package...

and selecting the file NoesisGUI-X.X.X.XXXX.unitypackage that you have downloaded from our web page. A faster alternative is just dragging the unitypackage into the project window.

Unity3DTutorialImg1.png

Once the installation finishes a welcome window should appear giving you information about the new installed version of NoesisGUI. Please take your time to read the changelog for the new version you just installed.

NOTE

Due to a restriction in Unity regarding native plugins you may get a warning requesting a restart of Unity.

Unity3DTutorialImg1_.png

Configuring NoesisGUI

Clicking on Unity menu option Tools -> NoesisGUI -> Settings will open an inspector window that displays global options for NoesisGUI. This same window is also available in Project Settings under the NoesisGUI category. If you want more detail about a specific option just hover the mouse over it to get a useful tooltip description.

Unity3DTutorialImg2.png

Assets

XAML assets

When you drag and drop a XAML file into Unity Asset folder it will automatically create a NoesisXaml asset. If the asset already exists it will update it. As Unity does not currently support importing custom file extensions you will end up having two files inside your project, the .xaml and the .asset. The .xaml file is the one you edit externally and the .asset if the resource that Unity understands. If you don't need to edit the .xaml you can remove it from your project because it is not necessary for the runtime. Although this is not strictly needed because .xaml files are not included in the final build produced by Unity.

NOTE

We recommend placing the Blend project (.csproj) next to your /Assets folder and edit .xamls directly from there. Each time you make changes, Unity will update corresponding resources.

NoesisXaml resources provide useful thumbnails and previews you can use to distinguish from the original .xaml in your project.

Unity3DTutorialImg20.png

The import process will automatically inject dependencies to used resources like Resource Dictionaries, Textures, AudioClips, Fonts and UserControls. To get a list of the dependencies for a given XAML you only need to click on it to open its editor that will show that information.

Unity3DTutorialImg21_.png

Just in case you need to add extra dependencies to your XAML, for example resources used by code in a ViewModel we provided an extension property, Xaml.Dependencies, for that purpose.

<UserControl
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  xmlns:noesis="clr-namespace:NoesisGUIExtensions"
  x:Class="Localization.MainWindow"
  FontFamily="./#Oxygen, ./#FontopoNIHONGO"
  Foreground="#FF488EB5">

  <noesis:Xaml.Dependencies>
    <noesis:Dependency Source="Language-en.xaml"/>
    <noesis:Dependency Source="Language-fr.xaml"/>
    <noesis:Dependency Source="Language-jp.xaml"/>
  </noesis:Xaml.Dependencies>

</UserControl>

Texture assets

Images used inside XAML generate a dependency to the corresponding Unity texture asset. The asset imported by Unity is directly used by Noesis. This means that all settings used under Import Settings are taken into account. If your images have alpha just make sure to set the Alpha Source to Input Texture Alpha and uncheck Alpha is Transparency. Also make sure to add the label 'Noesis' to the texture to have automatic conversion to the premultiplied-alpha format needed by Noesis.

NOTE

Find more information about premultiplied alpha at our forums.

Unity3DTutorialImg22.png

AudioClip assets

AudioClips are natively supported by NoesisGUI using the Behaviors architecture. Clips used in PlaySoundAction are automatically added as XAML dependencies.

Fonts assets

Similar to XAMLs, each time you drop a .ttf, .otf or .ttc file into your project it is imported to the corresponding .asset file that stores the needed information about the font for rendering at runtime. An editor window is implemented for fonts displaying attributes like its Family, Weight, Style and Stretch along with a render preview.

Unity3DTutorialImg220.png

Gamepad

NoesisGUI understands the following Unity Input Manager axes and buttons.

Virtual Name Type Noesis Mapping
Noesis_Horizontal Joystick Axis Key.GamepadUp | Key.GamepadDown
Noesis_Vertical Joystick Axis Key.GamepadLeft | Key.GamepadRight
Noesis_Accept Button Key.GamepadAccept
Noesis_Cancel Button Key.GamepadCancel
Noesis_Menu Button Key.GamepadMenu
Noesis_View Button Key.GamepadView
Noesis_PageUp Button Key.GamepadPageUp
Noesis_PageDown Button Key.GamepadPageDown
Noesis_PageLeft Button Key.GamepadPageLeft
Noesis_PageRight Button Key.GamepadPageRight

Using the given axes names you can configure any gamepad or joystick to work with NoesisGUI. More information about the meaning of each Noesis Mapping can be found in the C++ Integration Tutorial.

Unity3DTutorialImg21.png

Rendering

The MonoBehaviour in charge of rendering XAMLs is NoesisView. You need to attach that component to your GameObject. If you attach to a Camera object then the user interface will be rendered as a layer on top of the camera.

You can easily setup a user interface rendering to camera by doing drag and drop of a XAML asset into the Scene View. You can also drag and drop XAMLs into the Hierarchy Window.

Unity3DTutorialImg4.png

To display and interact with the user interface you must enter Play mode. Note that at Play mode the NoesisView preview window will display performance stats useful to optimize your interfaces.

Unity3DTutorialImg3.png

NOTE

By default camera post processing effects will affect the GUI. In case you don't want this to happen. You need to create a new camera to render NoesisGUI. This camera must have a larger Depth value and must set Clear Flags to Don't Clear. You must also make sure the Culling Mask is set to None to avoid rendering 3D elements in this camera.

Sometimes you don't want the user interface to be directly rendered to the screen or camera. NoesisGUI supports rendering XAML to textures that can be later mapped to objects. Just attaching a NoesisView to any GameObject that is not a camera will activate the Render Texture mode. In this mode a new property, Target Texture is available. Just create a Render Texture asset in Unity and assign it to that property.

Unity3DTutorialImg61.png

Note

For masking, NoesisGUI needs a stencil buffer. This can be activated in Unity by selecting a 24-bits Depth Buffer.

This texture must also be used by one of the materials assigned to the Mesh Renderer, a Plane in this example.

Unity3DTutorialImg62.png

NOTE

By default, in 'Render Texture' mode the property 'Continuous Rendering' is disabled to render only when changes happen.

Unity3DTutorialImg63.png

If you want to interact with the GUI rendered in the texture, your GameObject must have a MeshCollider component so texture coordinates can be obtained when doing the hit testing projection.

Hit Testing

In some situations it is necessary to check if mouse is over or was clicked over any element of the UI. This can be done with the HitTest method available through the VisualTreeHelper class.

Here is an example where a Collider mouse event was received and we want to find out if we should discard it because any UI element could have been clicked before:

using UnityEngine;
using Noesis;

public class HitTestSample : MonoBehaviour
{
    Visual _root;

    void Start()
    {
        var gui = GetComponent<NoesisView>();
        _root = (Visual)gui.Content;
    }

    void OnMouseDown()
    {
        UnityEngine.Vector3 mousePos = Input.mousePosition;
        Point point = new Point(mousePos.x, Screen.height - mousePos.y);
        HitTestResult hit = VisualTreeHelper.HitTest(this._root, point);
        if (hit.VisualHit == null)
        {
            // No UI element was hit

            // ...your code here
        }
    }
}

Standalone Players

Building on iOS

For now, Bitcode is not supported. It must be disabled in the project settings.

Unity3DTutorialImg102.png

Building on Android

The process of building for Android is very simple, only a few settings should be taken into account. The steps to follow are:

  1. Select File -> Build Settings...
Unity3DTutorialImg11.png
  1. Select the Scenes to be deployed
  2. Select platform Android
  3. Adjust the desired Player Settings (Resolution, Icons, Splash Image...). Make sure that Minimum API Level is at least Android 2.3.3 'Gingerbread'. NoesisGUI is not compatible with previous Android versions.
  4. Click the Build button
  5. Select the location where you want to save the .apk file
  6. Install the .apk into your Android device and Run it

You can also generate an Eclipse project to extend your application. In that case the steps are the following:

  1. Select File -> Build Settings...
  2. Select the Scenes to be deployed
  3. Select platform Android
  4. Adjust the desired Player Settings (Resolution, Icons, Splash Image...). Make sure that Minimum API Level is at least Android 2.3.3 'Gingerbread'. NoesisGUI is not compatible with previous Android versions.
  5. Click the Export button
  6. Select the location where you want to store the Eclipse project
  7. Optimize deployed data
  8. Build project with Eclipse to generate the .apk file
  9. Install the .apk into your Android device and Run it

Note

If your application needs to use .OBB extension files you should probably have checked the option Split Application Binary. Then it is convenient to set Player Settings option Write Access to External (SDCard). We found several clients having problems running the application just after being installed, because Unity can't access the extension file and XAML resources won't be found.

Unity3DTutorialImg12.png

Building on Universal Windows Platform

Only Universal Windows Platform for Windows 10 is supported.

  1. Make sure the SDK is set to "Universal 10".
Unity3DTutorialImg200.png
  1. Press "Build" button.
  2. Open the generated Visual Studio project.
  3. Build the solution for the desired platform, ARM, x86 or x86_64.
  4. Deploy and Execute.

Building on WebGL

The option 'Development Build' is reported to give problems. Avoid it if possible and also make sure the 'Enable Exceptions' setting is set to 'Explicitly Thrown Exceptions Only'. Rest of options are also reported to cause issues.

Unity3DTutorialImg201.png
© 2017 Noesis Technologies