New project

If you want to create a new Unity project ready to work with NoesisGUI we provide a Visual Studio project template available in the Visual Studio Marketplace. To install this template:

• Launch Visual Studio and click Extensions -> Manage Extensions from the Menu Bar.
• In the Extension Manager expand the Online node and search for Noesis. Download the NoesisGUI Project Templates extension and restart Visual Studio.

To create an application from the project template just create a new C# solution using the Unity App (NoesisGUI) template from Visual Studio's Start Page.

Existing project

If you are already working on a Unity project and have decided to add NoesisGUI to implement your game or application user interface, our plugin adds a new entry to the Assets top menu, Open Blend project. The first time you select this option it will create a new Blend project at the root of your Unity project. This project is configured to easily add resources from your 'Asset/' folder.

The project will create a sample XAML at the root of 'Asset/' to start working. Just drag that XAML asset in Unity to the Main Camera of an empty scene and click Play to see your first XAML.

Code-behind

User controls with code-behind need to be adapted to correctly compile in both Blend and Unity. Preprocessor macro directives #define and #if must be used to differentiate NoesisGUI code that is not 100% compatible with WPF. All our samples use preprocessor directives this way.

#if UNITY_5_3_OR_NEWER
   #define NOESIS
   using Noesis;
#else
   using System;
   using System.Windows.Controls;
#endif

namespace DummyGame
{
   /// <summary>
   /// Interaction logic for DummyGameMainView.xaml
   /// </summary>
   public partial class DummyGameMainView : UserControl
   {
      public DummyGameMainView()
      {
         InitializeComponent();
      }

    #if NOESIS
      private void InitializeComponent()
      {
         NoesisUnity.LoadComponent(this);
      }
    #endif
   }
}

XAML assets

When you drag and drop XAML files into your project 'Asset/' folder, Unity will automatically create a NoesisXaml asset with its corresponding thumbnail and preview window.

You can also create a few XAML snippets from the Tools -> NoesisGUI -> Create menu

The import process will automatically inject dependencies to referenced resources like Resource Dictionaries, Textures, AudioClips, VideoClips, Shaders, Fonts, Rives and UserControls. To properly detect dependencies for UserControls and Shaders you must adhere to the following naming conventions:

XAML usage	Dependency Asset
<local:MyUserControl Input="200" />	MyUserControl.xaml
<local:MonochromeBrush Color="White" />	Monochrome.noesisbrush
<local:TintEffect Color="Orange" />	Tint.noesiseffect

To inspect the list of dependencies for a given XAML you only need to click on the asset to open its editor.

Just in case you need to add extra dependencies to your XAML, for example resources used by code in ViewModels, we provided the extension property Xaml.Dependencies. The specified URI should be relative to the XAML where the dependency is defined or you just an absolute URI.

<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>

Theme

A Theme provides default styles for all UI controls, being a good start to create your own game styles. It is configured in the NoesisGUI Settings menu, under the 'Application Resources' entry. By default, our Noesis Theme, located at Packages/com.noesis.noesisgui/Theme, is used.

Note

App.xaml is not used by Unity. Application Resources are set in NoesisGUI Settings instead.

Language Server

A Visual Studio Code extension is available for a rich editing experience when typing XAML. This extension provides capabilities and type information while the Unity Editor is open.

Texture assets

Images used inside XAMLs generate a dependency to the corresponding Unity texture asset. The asset imported by Unity is directly consumed by NoesisGUI. This means that all settings available 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 NoesisGUI.

Sprites

Images packed as sprites inside an atlas can be directly referenced in XAML.

You can also expose Sprite objects in view models, for example:

 [Serializable]
 public class Item
 {
     public string _name;
     public string Name { get => _name; }

     public string _description;
     public string Description { get => _description; }

     public ItemCategory _category;
     public ItemCategory Category { get => _category; }

     public int _life;
     public int Life { get => _life; }

     public int _mana;
     public int Mana { get => _mana; }

     public int _dps;
     public int Dps { get => _dps; }

     public int _armor;
     public int Armor { get => _armor; }

     public UnityEngine.Sprite _icon;
     public UnityEngine.Sprite Icon { get => _icon; }
 }

This Sprite property can be consumed by any ImageSource property in XAML using data-binding:

 <DataTemplate x:Key="InventorySlot">
   <Grid Margin="5" Background="Transparent" ToolTip="{Binding Item.Description}">
     <Border BorderThickness="2" BorderBrush="{StaticResource OrangeBorder}"
       Background="{StaticResource RadialBackground}" CornerRadius="4"/>
     <Image Source="{Binding Item.Icon}"/>
   </Grid>
</DataTemplate>

AudioClip assets

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

<Button Content="START" Command="{Binding StartCommand}">
  <b:Interaction.Triggers>
    <b:EventTrigger EventName="GotFocus">
      <b:PlaySoundAction Source="AudioSlide.mp3" Volume="0.5"/>
    </b:EventTrigger>
    <b:EventTrigger EventName="Click">
      <b:PlaySoundAction Source="AudioClick.mp3" Volume="0.8"/>
    </b:EventTrigger>
  </b:Interaction.Triggers>
</Button>

VideoClip assets

VideoClips can be played using MediaElement. Same as AudioClips, they are automatically detected and added as XAML dependencies.

<Grid x:Name="LayoutRoot">
  <Border>
    <Border.Effect>
      <noesis:TintEffect/>
    </Border.Effect>
    <MediaElement Source="Particles.mp4" Stretch="UniformToFill" LoadedBehavior="Manual">
      <b:Interaction.Triggers>
        <b:EventTrigger EventName="Loaded">
          <noesis:PlayMediaAction/>
        </b:EventTrigger>
        <b:EventTrigger EventName="MediaEnded">
          <noesis:StopMediaAction/>
          <noesis:PlayMediaAction/>
        </b:EventTrigger>
      </b:Interaction.Triggers>
    </MediaElement>
  </Border>
</Grid>

Fonts assets

Similar to XAMLs, each time you drop a .ttf, .otf or .ttc file into your project it is imported automatically. An editor window is implemented for displaying attributes like Family, Weight, Style and Stretch along with a render preview.

Shader assets

As described in the Shaders Tutorial, NoesisGUI can be extended with shaders using Effects and Brushes. In Unity, shaders for effects are implemented in .noesiseffect files. For brushes, you must use .noesisbrush files. Both assets describe the shader in HLSL language.

These assets are automatically added as dependencies to XAMLs based on the name of the class that implements the effect. The suffixes Effect and Brush are replaced by .noesiseffect and .noesisbrush respectively. For example:

• The node <local:TintEffect Color="Orange"/> generates a dependency to the asset 'Tint.noesiseffect'
• The node <local:NoiseBrush scale="2"/> generates a dependency to the asset 'Noise.noesisbrush'

Shaders are loaded in C# by using the function CreateShader. This function must be invoked only once for all instances. Once the shader is created, it can be set on each instance by using SetShader.

public class NoiseBrush : BrushShader
{
    private static NoesisShader Shader;

    public NoiseBrush()
    {
        if (Shader == null) Shader = CreateShader();

        SetShader(Shader);
        SetConstantBuffer(_constants);
    }
}

The examples VideoEffect and BrushShaders can be used as guides to implement your own shaders.

Rive assets

Rive assets (.riv) are supported by NoesisGUI since 3.2. These assets are consumed by our RiveControl which offers state machine input values and triggers. There is an example included in the package fully created with Rive.

Post-processing

Universal Pipeline

In the Universal Render Pipeline (URP) camera post processing effects are applied to the UI. If you want to render the UI after post processing you need to use Camera Stacking. We recommend the following steps:

• Create a new camera only for the UI and attach a Noesis View component to it. Set 'Render Type' to 'Overlay' and 'Culling Mask' to 'Nothing'.
• Create a new camera for post processing. Set 'Render Type' to 'Overlay' and 'Culling Mask' to 'Nothing'. Enable the 'Post Processing' checkbox.
• Create an empty GameObject with a Volume component for the post processing effects.
• Attach both cameras to the Stack section of the Main Camera. 'UI Camera' must be first in the list.

NOTE

Camera Stacking can be very inefficient on mobile devices. For better performance, NoesisGUI 3.1.6+ exposes a new property in the View, 'Injection Point' to give control about when the UI render pass executes.

High Definition Pipeline

In the High Definition Render Pipeline (HDRP) camera post processing effects are applied before the UI. If you want the UI to be affected by the post processing you need to use a Custom Pass:

• Attach a 'Custom Pass Volume' component the main camera.
• Set 'Mode' to 'Camera'.
• Set 'Target Camera' to the main camera.
• Select 'Injection Point' (only 'Before Post Process' or 'After Post Process' makes sense).
• Add a 'Custom Pass' of type 'NoesisCustomPass'.
• Set 'Clear Flags' to 'Stencil'.

Render to texture

Sometimes you don't want the user interface to be directly rendered to the screen or camera. NoesisGUI supports rendering XAML to textures. 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.

This texture must also be used by one of the materials assigned to the Mesh Renderer. 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.

Widget3D example shows how to use RenderTexture to draw UI controls inside 3D scenes.

public class Redraw : MonoBehaviour
{
   void Update()
   {
      NoesisView view = gameObject.GetComponent<NoesisView>();
      view.ExternalUpdate();

      if (view.NeedsRendering)
      {
            Camera camera = gameObject.GetComponent<Camera>();
            camera.Render();
      }
   }
}

World-Space UI

The user interface can also be rendered directly in 3D, without using render to texture. This is the recommended way if you want the UI to be occluded by objects in the 3D scene, or if you want the best quality in Virtual Reality.

You can have several UIs floating in the space. Each one attached to a GameObject by using the new Noesis World UI component.

The following properties are exposed in this component:

• View: The Noesis View used to render the specified XAML.
• XAML: The UI placed in the GameObject position.
• Container: The Name of the Panel container (in the View) where the specified XAML will be inserted.
• Scale: Allows scaling UI pixels to scene units.
• Offset: Adjust UI position relative to the GameObject.
• Center: If enabled centers the UI in the GameObject position.

The Main View must contain a XAML with a container where child UIs are added. The name of the container is specified in the Noesis World UI component. It can be located anywhere in the XAML. For example:

<Grid xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
  <Canvas x:Name="Root"/>
</Grid>

iOS

For now, Bitcode is not supported, it must be disabled. We recommend disabling it at project level to affect all targets in Xcode.

WebGL

Unity 2022.2+ (Emscripten 3.1.8) is required for using NoesisGUI with WebGL.