New project

If you want to quickly create a new Unity project set up for NoesisGUI, we offer 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, simply 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 decide to add NoesisGUI to implement your game's or application's 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 preconfigured to easily reference resources from your Assets/ folder, and the solution file will be named {UnityProjectName}-blend.sln.

The project also creates a sample XAML file at the root of Assets/ to help you get started. Simply drag that XAML asset onto the Main Camera in an empty Unity scene and click Play to see your first XAML UI in action.

Code-behind

User controls with code-behind need to be adapted to compile correctly in both Blend and Unity. Preprocessor macro directives such as #define and #if must be used to separate NoesisGUI-specific code that is not 100% compatible with WPF.

All our samples use preprocessor directives in 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 'Assets/' folder, Unity will automatically generate a NoesisXaml asset for each file. These assets come with a thumbnail preview and a dedicated preview window, making it easier to identify and work with your UI files directly within the Unity Editor.

You can also create a few XAML snippets directly 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

It is extremely important that every XAML file declares its dependencies correctly. When building a standalone player in Unity, only the assets explicitly referenced will be included in the final build. If dependencies are not properly linked through your XAML, required resources (such as fonts, textures, or controls) may be excluded, resulting in missing or broken UI elements at runtime.

To inspect the list of dependencies for a given XAML file, simply click on the asset in the Unity Editor to open its inspector panel.

Just in case you need to add extra dependencies to your XAML, such as resources used only from code in ViewModels, we provide the extension property Xaml.Dependencies.

The specified URI can be either relative to the XAML file where the dependency is defined or 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, serving as a solid starting point 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. Instead, Application Resources are set in the NoesisGUI Settings.

Language Server

A Visual Studio Code extension is available to provide a rich editing experience when working with XAML.

This extension enables language server features such as autocompletion, type information, and error highlighting, while the Unity Editor is open.

Texture assets

Images used inside XAMLs generate a dependency to the corresponding Unity texture asset. The texture imported by Unity is directly consumed by NoesisGUI. This means that all settings available under Import Settings are respected.

If your images include alpha, make sure to:

• Set Alpha Source to Input Texture Alpha
• Uncheck Alpha is Transparency
• Add the label Noesis to the texture to enable automatic conversion to the premultiplied-alpha format required by Noesis

Sprites

Sprites in Unity can be used with NoesisGUI just like regular images. If a sprite is part of a sprite atlas, it can still be referenced normally in XAML, as NoesisGUI reads the underlying texture asset.

Additionally, you can expose objects in your view models and bind them directly to Image.Source.

This makes it easy to integrate your existing Unity workflows with Noesis-based UIs.

public class Item
{
    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>

The Inventory sample included in the package demonstrates how to use sprites and atlases effectively to reduce the number of draw calls, helping you build more performance-efficient interfaces.

AudioClip assets

AudioClips are natively supported by NoesisGUI through the Behaviors system.

Any clip used in a PlaySoundAction is automatically added as a dependency of the XAML, ensuring it is properly included in the Unity build.

<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 the MediaElement control.

Just like AudioClips, they are automatically detected and added as XAML dependencies, ensuring they are correctly included in the Unity build.

<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 Unity project, it is automatically imported by NoesisGUI.

An editor window is provided to display key attributes such as Family, Weight, Style, and Stretch, along with a real-time render preview of the font.

Shader assets

As described in the Shaders Tutorial, NoesisGUI can be extended with shaders using Effects and Brushes.

In Unity, shaders for effects are defined in .noesiseffect files, while shaders for brushes are defined in .noesisbrush files. Both formats describe the shader in HLSL.

These assets are automatically added as dependencies to XAMLs based on naming conventions. Specifically, the suffixes Effect and Brush in your class names 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# using the CreateShader function. This function should be called once to initialize the shader. Then, use SetShader on each instance to apply it.

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 starting from version 3.2. These assets are used through the RiveControl, which provides access to state machine input values and triggers directly from XAML or code-behind.

An example is included in the package, fully created with Rive, demonstrating integration and animation control.

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'. Make sure 'Post Processing' is disabled on this camera.
• Create another 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 to define your post-processing effects.
• Attach both cameras to the Stack section of the Main Camera. The 'UI camera' must be the last in the list to ensure it renders after post-processing.

NOTE

In URP, Noesis View also exposes an 'Injection Point' property that controls when the UI pass is rendered. However, changing this property may not work consistently across all platforms, so we recommend using the steps described above for best compatibility.

High Definition Pipeline

In the High Definition Render Pipeline (HDRP), camera post-processing does not affect the UI by default. This behavior can be changed using the 'Injection Point' property exposed by the Noesis View component.

Render to texture

In some scenarios, you may want to render the user interface to a texture instead of directly displaying it on the screen or through a camera. NoesisGUI supports this workflow by allowing you to attach a NoesisView component to any GameObject that is not a camera.

When NoesisView is attached to a non-camera object, its Render Mode automatically switches to Render Texture. This is reflected in the Render Mode property of the component. In this mode, a new property called Target Texture becomes available, allowing you to specify the Render Texture where the UI should be rendered.

To use this feature, create a Render Texture asset and assign it to the Target Texture field in the NoesisView.

The texture must also be used by a material assigned to the object's Mesh Renderer to display the UI on screen. If you want the UI rendered in the texture to be interactive, the GameObject must have a MeshCollider component. This allows NoesisGUI to perform hit testing by projecting mouse or touch events onto the texture's surface.

The Widget3D example included in the package demonstrates how to use Render Texture to display UI controls within 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 method when you want the UI to be occluded by objects in the 3D scene, or when aiming for the highest visual quality in Virtual Reality.

You can place multiple UI elements floating in 3D space, each one attached to a GameObject by using the 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 2023.2+ (Emscripten 3.1.38) is required for using NoesisGUI with WebGL.