This page has been translated automatically.
视频教程
界面
要领
高级
实用建议
UnigineEditor
界面概述
资产工作流程
设置和首选项
项目开发
调整节点参数
Setting Up Materials
Setting Up Properties
照明
Landscape Tool
Sandworm (Experimental)
使用编辑器工具执行特定任务
Extending Editor Functionality
嵌入式节点类型
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Objects
Sound Objects
Pathfinding Objects
Players
编程
基本原理
搭建开发环境
Usage Examples
UnigineScript
C++
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine Tools
GUI
双精度坐标
应用程序接口
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
注意! 这个版本的文档是过时的,因为它描述了一个较老的SDK版本!请切换到最新SDK版本的文档。
注意! 这个版本的文档描述了一个不再受支持的旧SDK版本!请升级到最新的SDK版本。

创建C#应用程序

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 on Windows platform.基于Unigine的应用程序只能通过C#来实现,而无需使用UnigineScript。本文介绍如何在Windows平台上创建一个新的基于Unigine的C#应用​​程序。

Implementation by using the C# language is very similar to C++. Read the Creating C++ Application article to get basic principles.使用C#语言的实现与C ++非常相似。阅读创建C ++应用程序文章以获取基本原理。

注意
  • C# (.NET Core) API is cross-platform (recommended).C# (.NET Core) API是跨平台(推荐)
  • C# (.NET Framework) API is supported on Windows only.仅Windows支持C# (.NET Framework) API。

See Also也可以看看#

  • Examples located in the <UnigineSDK>/source/csharp/samples/Api and <UnigineSDK>/source/csharp/samples/App folders.示例位于<UnigineSDK>/source/csharp/samples/Api<UnigineSDK>/source/csharp/samples/App文件夹中。
  • The article on Setting Up Development Environment to learn more on how to prepare the development environment.设置开发环境上的文章,以了解有关如何准备开发环境的更多信息。

Creating Empty C# Application创建空的C#应用​​程序#

It is very easy to start your own C# project by using UNIGINE SDK Browser:使用UNIGINE SDK浏览器来启动自己的C#项目非常容易:

  1. Open the UNIGINE SDK Browser.打开UNIGINE SDK浏览器。
  2. Go to the Projects tab and click CREATE NEW.
    转到Projects选项卡,然后单击CREATE NEW
  3. Specify the following parameters:
    • Project name — specify the name of your project.Project name — specify the name of your project.
    • Location — specify the path to your project folder.Location — specify the path to your project folder.
    • SDK — choose the Unigine SDK.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.
      注意
      Choose C# (.NET Core) to start working with the C# API with the Component System available.Choose C# (.NET Core) to start working with the C# API with the Component System available.
      Choose C# (.NET Core) to start working with the C# API with the Component System available.
      API+IDE — choose either of the two options: C# (.NET Core) or C# (.NET Framework) depending on how you plan to implement your logic.
      注意
      Choose C# (.NET Core) to start working with the C# API with the Component System available.Choose C# (.NET Core) to start working with the C# API with the Component System available.
    • Architecture — specify the architecture of your target platform.Architecture — specify the architecture of your target platform.
    • Precision — specify the precision. In this example we will use double precision.Precision — specify the precision. In this example we will use double precision.
    注意
    Read more about these parameters in this article.Read more about these parameters in this article.
    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.
    注意
    Choose C# (.NET Core) to start working with the C# API with the Component System available.Choose C# (.NET Core) to start working with the C# API with the Component System available.
    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.Read more about these parameters in this article.
    指定以下参数:
    • Project name — specify the name of your project.Project name-指定项目的名称。
    • Location — specify the path to your project folder.Location-指定项目文件夹的路径。
    • SDK — choose the Unigine SDK.SDK —选择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.
      注意
      Choose C# (.NET Core) to start working with the C# API with the Component System available.Choose C# (.NET Core) to start working with the C# API with the Component System available.
      Choose C# (.NET Core) to start working with the C# API with the Component System available.
      API+IDE —根据计划实现逻辑的方式选择两个选项之一:C#(.NET Core)或C#(.NET Framework)。
      注意
      Choose C# (.NET Core) to start working with the C# API with the Component System available.选择C# (.NET Core)以在组件系统可用的情况下开始使用C#API。
    • Architecture — specify the architecture of your target platform.Architecture —指定目标平台的体系结构。
    • Precision — specify the precision. In this example we will use double precision.Precision-指定精度。在此示例中,我们将使用双精度
    注意
    Read more about these parameters in this article.本文中阅读有关这些参数的更多信息。
  4. Click the Create New Project button. The project will appear in the projects list.
    单击Create New Project按钮。该项目将出现在项目列表中。

You can run your project by clicking the Run button.您可以通过单击Run按钮来运行项目。

注意
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#.默认情况下,在世界脚本文件中创建WorldLight和PlayerSpectator。您可以将世界脚本的功能留空,并使用C#创建自己的灯光和播放器。

Implementing C# Logic实施C#逻辑#

C# logic can be implemented using either of the following APIs:可以使用以下任一API来实现C#逻辑:

  • 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 Core) API C#项目的推荐方法。它允许使用默认启用并集成到编辑器中的 C#组件系统:这样可以更轻松地在组件中实现应用程序逻辑并将它们分配给要执行的任何节点。组件可以根据需要在任意数量的节点上重复使用,而无需更改组件中的任何内容。如果节点被重命名或禁用,则为其分配的组件不需要任何更改。当您更改组件逻辑中的任何内容时,更改将应用​​于分配了该组件的所有节点。编辑器还提供了运行应用程序实例以立即检查结果的功能。
  • 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. C# (.NET Framework) API。代码是使用AppWorldLogic和AppSystemLogic全局类编写的-这种方法具有一些可用性限制。此外,既未启用组件系统,也未将其与编辑器集成:只能使用 properties 通过代码以手动模式使用组件。
注意
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, to make it the same as in the UnigineEditor. To disable automatic unpacking simply add the following line to the AppSystemLogic.Init() method: World.UnpackNodeReferences = false;加载世界时,默认情况下将解压缩其中包含的所有NodeReferences(NodeReference内容的层次结构作为子级附加到该世界)。这样做是为了简化节点引用对于初学者的工作,以使其看起来像在UnigineEditor中。 要禁用自动拆包,只需将以下行添加到AppSystemLogic.Init()方法中: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#应用​​程序项目中添加逻辑,并旋转默认情况下创建的物料球。

C# (.NET Core) ProjectsC#(.NET Core)项目#

Let's make the material ball rotate using C# Component System.让我们使用C#组件系统使物料球旋转。

注意
To engage the C# Component System supported by C# (.NET Core) API, follow the instructions in the C# Component System Usage Example.要使用C# (.NET Core) API支持的C#组件系统,请按照 C#组件系统使用示例中的说明进行操作。
  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.
    在UNIGINE SDK浏览器中,选择使用C# (.NET Core)选项作为API + IDE选择创建的C#项目,然后单击打开编辑器按钮。

    UnigineEditor将打开。
  2. In UnigineEditor, create a new C# component via Asset Browser.

    Let's name it rotator.
    在UnigineEditor中,通过Asset Browser创建一个新的C#组件。

    我们将其命名为rotator
  3. By double-clicking a created asset rotator.cs, it will open in the default IDE. Add the following code to this file.
    源代码 (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.
    双击创建的资产rotator.cs,它将在默认IDE中打开。将以下代码添加到该文件。
    源代码 (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);
    	}
    }
    编辑器窗口获得焦点时,所有已保存的组件源代码更改都将使组件更新,而无需编译。
  4. Add this component to the material ball.将此组件添加到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) projectsC#(.NET Framework)项目#

With the approach using only the AppWorldLogic and AppSystemLogic global classes, making the material ball rotate is done as follows.使用仅使用AppWorldLogic和AppSystemLogic全局类的方法,使material ball旋转如下。

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

    Visual Studio will open.
    在UNIGINE SDK浏览器中,选择您的C#项目,然后单击Open Code IDE按钮。

    Visual Studio将打开。
  2. In Visual Studio, add the following code in your project's AppWorldLogic.cs file.
    源代码 (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;
    		}
    	}
    }
    Visual Studio,将以下代码添加到项目的AppWorldLogic.cs文件中。
    源代码 (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.
    通过在Visual Studio中单击Build -> Build Solution来构建项目。
  4. Start your project by clicking Debug -> Start in a proper mode in Visual Studio.
    通过在Visual Studio中单击Debug -> Start以适当的模式启动项目。
注意
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.要从SDK Browser运行项目,请通过自定义.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.
    注意
    For each world of the project, one and the same AppWorldLogic is called. It is impossible to link an individual AppWorldLogic to each world.For each world of the project, one and the same AppWorldLogic is called. It is impossible to link an individual AppWorldLogic to each world.
    For each world of the project, one and the same AppWorldLogic is called. It is impossible to link an individual AppWorldLogic to each world.
    如果您运行的世界不包含AppWorldLogic引用的节点,则应用程序将崩溃。
    注意
    For each world of the project, one and the same AppWorldLogic is called. It is impossible to link an individual AppWorldLogic to each world.对于项目的每个世界,都调用一个相同的AppWorldLogic。不可能将单个AppWorldLogic链接到每个世界。

Using Components in C# (.NET Framework) projects在C#(.NET Framework)项目中使用组件#

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:

源代码 (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;
		}
	}
不像.NET Core,其中默认情况下启用了C#组件系统并将其集成到编辑器中,并与.Net Framework需要手动运行系统并通过属性创建组件,这些组件将代码与UnigineEditor中的节点连接。例如:

源代码 (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():

源代码 (C#)
ComponentSystem.AddComponent<MyComponent>(node);
如果您不想使用UnigineEditor,则可以直接通过代码将组件添加到节点,而无需调用SaveProperties():

源代码 (C#)
ComponentSystem.AddComponent<MyComponent>(node);
最新更新: 2020-11-24
Build: ()