UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Программирование
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes

Creating C# Application

A Unigine-based application can be implemented by means of C# only, without using UnigineScript. This article describes how to create a new Unigine-based C# application in Visual Studio on Windows platform.

Implementation by using the C# language is very similar to C++. Read the Creating C++ Application article to get basic principles.

Notice
  • C# (.NET Core) API is cross-platform (recommended).
  • C# (.NET Framework) API is supported on Windows only.

See Also#

  • Examples located in the <UnigineSDK>/source/csharp/samples/Api and <UnigineSDK>/source/csharp/samples/App folders.
  • The article on Setting Up Development Environment to learn more on how to prepare the development environment.

Creating Empty C# Application#

It is very easy to start your own C# project by using UNIGINE SDK Browser:

  1. Open the UNIGINE SDK Browser.
  2. Go to the Projects tab and click CREATE NEW.

  3. Specify the following parameters:

    • Project name — specify the name of your project.
    • Location — specify the path to your project folder.
    • SDK — choose the Unigine SDK.
    • API+IDE — choose either of the two options: C# (.NET Core) or C# (.NET Framework) depending on how you plan to implement your logic.
      Notice
      Choose C# (.NET Core) to start working with the C# API with the Component System available.
    • Architecture — specify the architecture of your target platform.
    • Precision — specify the precision. In this example we will use double precision.
    Notice
    Read more about these parameters in this article.
  4. Click the Create New Project button. The project will appear in the projects list.

You can run your project by clicking the Run button.

Notice
By default, in the world script file a WorldLight and a PlayerSpectator are created. You can leave functions of the world script empty, and create your own lights and players by using C#.

Implementing C# Logic#

C# logic can be implemented using either of the following APIs:

  • C# (.NET Core) APIa recommended approach for C# projects. It allows using C# Component System enabled by default and integrated into the Editor: this way it is easier to implement your application logic in components and assign them to any node to be executed. A component can be reused for as many nodes as you need without changing anything in it. If a node is renamed or disabled, the component assigned to it does not require any changes due to that. When you change anything in your component's logic, the changes are applied to all nodes having this component assigned. The Editor also provides for running an instance of the application to check the result immediately.
  • C# (.NET Framework) API. Code is written using the AppWorldLogic and AppSystemLogic global classes — this approach has some usability limitations. In addition, the Component System is neither enabled, nor integrated with the Editor: working with components is possible only in manual mode via code, using properties.
Notice
When loading a world all NodeReferences it contains are unpacked by default (the hierarchy of NodeReference’s contents is attached to it as a child). This is made to simplify working with node references for beginners in order to make it look like in the UnigineEditor. To disable automatic unpacking simply add the following line to the AppSystemLogic.Init() method: World.UnpackNodeReferences = false;

In this section we will add logic to the empty C# application project and rotate the material ball that is created by default.

C# (.NET Core) Projects#

Let's make the material ball rotate using C# Component System.

Notice
To engage the C# Component System supported by C# (.NET Core) API, follow the instructions in the C# Component System Usage Example.
  1. In UNIGINE SDK Browser, choose your C# project created with the C# (.NET Core) option selected as API+IDE, and click the Open Editor button.

    UnigineEditor will open.
  2. In UnigineEditor, create a new C# component via Asset Browser.

    Let's name it rotator.
  3. By double-clicking a created asset rotator.cs, it will open in the default IDE. Add the following code to this file.
    Source code (C#)
    public class rotator : Component
    {
    	public float angle = 30.0f;
    	
    	void Update()
    	{
    		// write here code to be called before updating each render frame
    		node.Rotate(0, 0, angle * Game.IFps);
    	}
    }
    All saved changes of the component source code make the component update with no compilation required when the Editor window gets focus.
  4. Add this component to the material ball.
  5. Run an instance of the application by clicking the Play button on the toolbar.

The component can be assigned to any node or nodes without changing anything in it.

C# (.NET Framework) projects#

With the approach using only the AppWorldLogic and AppSystemLogic global classes, making the material ball rotate is done as follows.

  1. In the UNIGINE SDK Browser, choose your C# project and click the Open Code IDE button.

    Visual Studio will open.
  2. In Visual Studio, add the following code in your project's AppWorldLogic.cs file.
    Source code (C#)
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Text;
    
    using Unigine;
    
    namespace UnigineApp
    {
    
    	class AppWorldLogic : WorldLogic
    	{
    		// define pointer to node
    		Node node;
    
    		public override bool Init()
    		{
    			// find the material ball node by its name
    			node = World.GetNodeByName("material_ball");
    			return true;
    		}
    
    		public override bool Update()
    		{
    			// set the transformation to the node
    			float angle = 30.0f;
    			node.Rotate(0, 0, angle * Game.IFps);
    			return true;
    		}
    	}
    }
  3. Build your project by clicking Build -> Build Solution in Visual Studio.

  4. Start your project by clicking Debug -> Start in a proper mode in Visual Studio.

Notice
To run your project from SDK Browser, specify the path to the .exe file of your C# project in SDK Browser by customizing Run Project.

This approach has some usability limitations:

  • If a node name has been changed, code wouldn't work.
  • If you run a world that does not contain a node AppWorldLogic refers to, the application will crash.
    Notice
    For each world of the project, one and the same AppWorldLogic is called. It is impossible to link an individual AppWorldLogic to each world.

Using Components in C# (.NET Framework) projects#

Unlike .NET Core, where C# Component System is enabled by default and integrated into the Editor, working with components in .Net Framework requires running the system manually and creating components via properties, which connect code with nodes in UnigineEditor. For example:

Source code (C#)
class AppSystemLogic : SystemLogic
	{
		public override bool Init()
		{
			// initialize C# Component System
			ComponentSystem.Enabled = true;
			
			// generate all property files inside /data folder for all components
			ComponentSystem.SaveProperties();
		
			return true;
		}
	}

If you don't want to use UnigineEditor, you can add components to nodes directly via code without calling SaveProperties():

Source code (C#)
ComponentSystem.AddComponent<MyComponent>(node);
Last update: 10.04.2020