This page has been translated automatically.
Programming
Fundamentals
Setting Up Development Environment
UnigineScript
C++
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
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes
注意! 这个版本的文档是过时的,因为它描述了一个较老的SDK版本!请切换到最新SDK版本的文档。
注意! 这个版本的文档描述了一个不再受支持的旧SDK版本!请升级到最新的SDK版本。

Editor(编辑器)插件

Game Framework Editor(游戏框架编辑器)能使您在Unigine Editor中正确创建游戏。

Game Framework Editor中有3个主要区域:

Game Framework Editor
  • New Game(新建游戏) - 创建新游戏
  • Open Game(打开游戏) - 打开游戏
  • Save Game(保存游戏) - 保存当前游戏
  • Play Level(播放关卡) - 播放关卡
  • Settings(设置) - 打开设置窗口

关卡(Levels)

其代表的是罗列的关卡以及对这些关卡所进行的操作:

  • New Level(新建关卡) - 创建新关卡
  • Remove Level(移除关卡) - 删除所选关卡

实体(Entities)

其代表的是罗列的实体以及对这些实体所进行的操作:

  • New Entity(新建实体) - 创建新实体
  • Remove Entity(移除实体) - 删除所选实体
  • Assign Entity(分配实体) - 将实体分配给节点引用或节点

Info

其作用是显示所选元素的信息。

创建游戏(Game)

要想创建新游戏,须点击New Game(新建游戏)按钮。 这时,游戏创建的对话框窗口将被打开:

游戏创建的对话框窗口
  • Name(名称) - 指游戏的名称。 它可以包含任意字符或者干脆为空。 其默认值为new_game
  • File(文件) - 指*.game文件的路径名称(相对于data目录的路径),该文件包含了有关游戏(game),关卡(levels),实体(entities)的所有信息,也包含了游戏和Editor的所有附加参数。 其默认值为games/new_game/new_game.game
  • Entity(实体) - 指*.prop文件的路径名称(相对于data目录的路径),该文件包含了有关基本实体(Entity)的所有信息。 它会由Editor自动生成。 其默认值为games/new_game/entity.prop
  • Property List(属性列表) - 指*.prop_list文件的路径名称(相对于data目录的路径),该文件罗列出了所有的游戏属性。 它会由Editor自动生成。 其默认值为games/new_game/properties.prop_list
注意
如果游戏的名称发生了更改,那其它的所有目录也都会被自动更改。 如果有任何一个目录是被手动更改的,那该值将不能在游戏创建期间被自动更改。

如果您将选项栏中的某一个给填错了,那警告图标就会出现。 当您将鼠标悬停在该图标上时,就会显示警告信息。

如果所有的选项栏都填写正确,在点击完Create(创建)按钮之后,游戏和所有的附加文件就会被创建。 而游戏也将被Editor瞬间打开。 所有这些设置在以后都可以更改。

编辑游戏(Game)

通过点击Open(打开)按钮打开要进行编辑的游戏。 在标题栏上可以看到*.game文件的目录。 Game的设置可以在Editor的Settings窗口(Game framework settings/Game settings/Game)中更改:

Game设置
  • Name(名称) - 指游戏的名称(可选项)
  • Developer(开发者) - 指游戏的开发者(可选项)
  • Version(版本) - 指游戏的版本(可选项)
  • Copyright(版权) - 指版权(可选项)
  • Window Title(窗口标题) - 指游戏被加载时窗口的标题(默认留空)
  • Description(描述) - 指游戏的描述(可选项)
  • Entity Property(实体属性) - 指*.prop文件的路径名称(相对于data目录的路径),该文件包含了有关基本实体(Entity)的所有信息。 它会由Editor自动生成。 其默认值为games/new_game/entity.prop

    如果您更改了该文件的名称或目录,那它就会被重命名以及被自动重新定位,不过它具有默认值。

  • Property List(属性列表) - 一个*.prop_list文件。 指属性列表的路径名称(相对于data目录的路径),该文件罗列出了所有的游戏属性。 它会由Editor自动生成。 其默认值为games/new_game/properties.prop_list

    如果您更改了该文件的名称或目录,那它就会被重命名以及被自动重新定位,不过它具有默认值。

您可从Game launch选项栏更改游戏加载的相关设置(Settings/Game/Game Launch):

  • System script(系统脚本) - 指system(系统)脚本的路径名称,该型脚本是启动游戏所必需的。 引擎为框架提供了默认的system(系统)脚本,它存放在路径下文件data/framework/game/game_system_script.cpp中。
  • Extern Define(外部定义) - 指外部定义的列表(例如,如果您是用作移动平台开发的,就要使用RENDER_SIMPLE来定义)
  • Extern Plugin(外部插件) - 指用户C++插件的列表

所有的游戏更改都应通过点击Save Game(保存游戏)按钮来保存。

创建关卡(Level)

要想创建新关卡,须点击New Level(新建关卡)按钮。 这时,关卡创建的对话框窗口将被打开:

关卡创建的对话框窗口

General(一般)

  • Name - 指关卡的名称。
  • %name - 指相对的关卡名称,其会被自动设置为*.level文件,*.world文件和*.h文件的名称。
  • Level File - 指*.level文件的路径名称(相对于data目录的路径),该文件包含了有关关卡的所有信息。

World(世界)

  • File - 指新关卡的*.world文件的路径名称(相对于data目录的路径)。 如果*.world文件之前还未被创建,那它就将通过路径下文件data/framework/plugin/editor/templates/level/template.world中存放的模型来进行自动创建。

Logic(逻辑)

  • Use Custom Logic - 指要使用自定义逻辑。 如果禁用了该参数,就会使用标准的框架关卡逻辑;否则,用来指定自定义逻辑的附加选项栏Logic ClassLogic File将被激活。
  • Logic Class - 指类的名称,在关卡加载时该类的实例将被创建。
  • Logic File - 指*.h文件的路径名称(相对于data目录的路径),该文件包含了关卡逻辑。

    如果具有指定名称的该文件不存在,那它就将基于标准模型(存放在路径下文件data/framework/plugin/editor/templates/level/logic.h中)来进行自动创建,该模型是从基本的关卡逻辑类Level继承而来。

注意
同一关卡逻辑类可用于不同的关卡。

如果您想要更改关卡创建的自动填写参数,须打开Editor的Settings窗口(Game framework settings/Game settings/File Path Settings For New Levels):

File Path Settings For New Levels Field(新关卡选项栏的文件路径设置)

引擎会为如下文件自动设置指定目录:

  • Level (*.level) - 指*.level文件的路径名称
  • Logic (*.h) - 指带有关卡逻辑的*.h文件的路径名称
  • World (*.world) - 指*.world文件的路径名称
注意
所有的路径都应相对于*.game文件来指定。

如果您将选项栏中的某一个给填错了,那警告图标就会出现。 当您将鼠标悬停在该图标上时,就会显示警告信息。

如果所有的选项栏都填写正确,在点击完Create(创建)按钮之后,关卡文件和所有的附加文件就会被创建。 而关卡也将Editor打开。 所有这些设置在以后都可以更改。

编辑关卡(Level)

当关卡被选中之后,就可以在Level(关卡)标签页内对它进行编辑:

关卡编辑的标签页
  • Name - 指关卡的名称
  • World - 指新关卡的*.world文件的路径名称(相对于data目录的路径)。
  • Logic - 指*.h文件的路径名称(相对于data目录的路径),该文件包含了关卡逻辑。 如果具有指定名称的该文件不存在,那它就将基于标准模型(存放在路径下文件data/framework/plugin/editor/templates/level/logic.h中)来进行自动创建,该模型是从基本的关卡逻辑类Level继承而来。
  • Logic class - 指类的名称,在关卡加载时该类的实例将被创建。
注意
如果您不想使用自定义逻辑,只需删除Logic选项栏和Logic class选项栏中所有的值即可。

>所有的游戏更改都应通过点击Save Game(保存游戏)按钮来保存。

要想加载或重新加载某个虚拟世界,只需双击关卡列表中的关卡即可,这样,Editor就会生成并重新加载所有的属性,也会为您的关卡加载所需的虚拟世界,如此一来您就能对它进行编辑,参数更改,添加,删除或编辑节点的操作了。 已加载的关卡会以蓝色来高亮显示。

当适用某个关卡的虚拟世界在Editor中被加载了之后,Play level(播放关卡)按钮会在运行时(rumtime)中变为可用,换句话说,游戏被启动了。 Play level(播放关卡)按钮会为要启动的游戏在运行时(runtime)中加载不止一个引擎的实例。

注意
其它的引擎实例的版本将与Editor所具有的版本相同。

您可从Editor的关卡播放选项窗口更改关卡加载的相关设置(Game framework settings/Editor settings/Play level options):

Play Level Options(播放关卡选项)选项栏
  • Binary - 用来指定播放关卡时要加载的二进制文件
  • Debug - 用来指定是否启用debug模式
  • Video API - 指视频API切换器。 可设置的值有:
    • OpenGL - OpenGL API(适用Windows,OS和Linux系统)
    • Direct3D9 - Direct3D9 API(适用Windows系统)
    • Direct3D11 - Direct3D11 API(适用Windows系统)
  • Resolution - 指引擎窗口的分辨率
  • VSync - 指垂直同步
  • Fullscreen - 指全屏模式
  • Engine Config - 指引擎的配置文件
  • Engine Log - 指引擎的日志文件
  • Editor Config - 指Editor的配置文件

自定义关卡逻辑

自定义逻辑可被应用给游戏中的所有关卡。 它可以是每个关卡独有的,又或是所有关卡都通用的。

注意
自定义逻辑类和带有逻辑的*.h文件的路径名称可以在Logic class选项栏和Logic选项栏中进行设置。

要想游戏能正确运行,逻辑文件就应该从基本的框架关卡类继承。 该类存放在路径下文件data/framework/game/level.h中。

如果用户代码不正确,游戏就不能被加载。 而相应的警告消息也会出现在控制台和日志文件中。

您可通过点击Logic选项栏旁边的Edit Logic(编辑逻辑)按钮来快速访问逻辑文件。 默认情况下,带有指定逻辑的文件夹将被打开。 您可在Editor标签页内的Open Cmd File(打开Cmd文件)选项栏中指定逻辑文件的名称,这样,文件自身就会在点击Edit Logic(编辑逻辑)按钮时被打开:

Open Cmd File选项栏

自定义逻辑的用法举例:

源代码 (UnigineScript)
#ifndef _MYLEVEL_H_
#define _MYLEVEL_H_

/******************************************************************************\
 *
 * class MyLevel
 *
\******************************************************************************/

class MyLevel : Level {
    
  private:
     int first_update = true;
   public:
  
     MyLevel() {
       log.message(“MyLevel constructor called\n”);
     }
 
    ~MyLevel() {
      log.message(“MyLevel desstructor called\n”);
    }
    
    // 在所有实体(entities)创建之前调用该函数
    void onWarm() {
      // 在此放置您的警告代码
      log.message(“MyLevel onWarm() called\n”);
    }
    
    // 在所有实体(entities)创建之后调用该函数
    void onInit() {
      // 在此放置您的init代码
      log.message(“MyLevel onInit() called\n”);
    }
    
    void onShutdown() {
      // 在此放置您的shutdown代码
      log.message(“MyLevel onSutdown() called\n”);
    }
    
    void onPreUpdate() {
      // 实体(entities)更新之前调用
      // 在此放置您的update代码
    }
    
    void onPostUpdate() {
      // 实体(entities)更新之后调用
      // 在此放置您的update代码
      if(first_update) {
        log.message(“MyLevel onPostUpdate() called\n”);
        first_update = false;
      }
    }
    
    void onRender() {
      // 在此放置您的render代码
    }
    
    void onFlush() {
      // 在此放置您的flush代码
    }
};

#endif /* _MYLEVEL_H_ */

类的实例将会在关卡加载时由游戏自动创建,所有的函数也都会以适当的顺序被调用。

您可创建属于您自己的基类,该基类被从框架关卡类继承,而后从它继承您的其它类。 为此,只需在您的关卡逻辑文件中包含基类文件的文件头即可:

源代码 (UnigineScript)
#ifndef _MYLEVEL_0_H_
#define _MYLEVEL_0_H_

#include <data/....my_project_path.../scripts/my_level.h>

/******************************************************************************\
 *
 * class MyLevel_0
 *
\******************************************************************************/

class MyLevel_0 : MyLevel {
    
  private:
  
   public:

    onInit() {
      super.onInit();
      log.message(“my custom logic init\n”);
    }

};

#endif /* _MYLEVEL_0_H_ */
注意
请您确保已在Level(关卡)标签页内指定了自定义类的名称和逻辑文件的路径名称。

创建实体(Entity)

要想创建新实体,须点击New Entity(新建实体)按钮。 这时,实体创建的对话框窗口将被打开:

实体创建的对话框窗口

General(一般)

  • Name - 指实体名称,其会将名称赋予给对应的实体类和属性。
  • %name - 指相对的实体名称,其会被自动设置为*.entity文件,*.h文件,*.prop文件和*.node文件的名称。
  • File - 指*.entity文件的路径名称(相对于data目录的路径),该文件包含了有关实体的所有信息。

Logic(逻辑)

  • Parent - 指基本实体的名称,新实体及其属性的实例都是从该基本实体继承而来。
  • File - 指*.h文件的路径名称(相对于data目录的路径),该文件包含了实体逻辑。

    如果具有指定名称的该文件不存在,那它就将基于标准模型(存放在路径下文件data/framework/plugin/editor/templates/entity/logic.h中)来进行自动创建,该模型是从基本的实体类Entity继承而来。

  • Property - 指*.prop文件的路径名称(相对于data目录的路径),该文件包含了属性信息。 如果具有指定名称的该文件不存在,那它就会被自动创建。
注意
同一逻辑类不能用于不同的实体。

Node(节点)

  • Use Node - 用来指定是否使用已分配的节点来创建实体。 如果禁用了该参数,那新实体就会在不使用任何已分配节点的情况下被创建,这样,当您在节点层级中选中它时,它就没有Node(节点)标签页。 在将这样的一个实体放进虚拟世界中(通过拖拽操作)时,分配有该实体的伪节点就会出现。 与其它类型的节点一样,伪节点也能被分配属性。

    对于未分配实体的节点而言,它们拥有相同的update逻辑和shutdown逻辑(指onInit()onUpdate()onFlush()onRender()onShutdown()这几个函数的调用),不过,它们实体初始化的逻辑是不同的。 如果实体被分配给了节点引用,那该实体的类的实例就会由Node::setVariable方法放进根节点中;但是如果实体是被分配给节点的,那类的实例将不会被放在任何地方,它也不能从节点获得。 不过,您却可以通过onInit()函数来手动获取它。 让我们举个例子来说明:假设将被称为MyEntity的一个空(未分配节点)实体分配给了带有复杂层级的节点。 我们知道,作为子节点,它会拥有一个被称为"my_mesh"的mesh(网格),而该mesh则可由相交(intersection)方法获得。 如果作为变量的指定类的实例会由此mesh获取,那我们就能从该节点获得指定实体的类的实例:

    源代码 (UnigineScript)
    class MyEntity : Entity {
        
      private:
        ObjectMesh my_mesh;
      public:
        
        void onInit() {
          my_mesh = getNode(“my_mesh”);
          my_mesh.setVariable(this);
        }
        
        void onShutdown() {
          my_mesh.setVariable(NULL);
        }
    };
    注意
    如果您通过Node::setVariable()方法设置了实体或其它逻辑类,那您就需要在shutdown()阶段调用Node::setVariable(NULL)方法。
  • Node File - 指新实体的*.node文件的路径名称(相对于data目录的路径)。

    如果*.node文件之前还未被创建,那它就将通过路径下文件data/framework/plugin/editor/templates/entity/template.node中存放的模型来进行自动创建。

如果您想要更改实体创建的自动填写参数,须打开Editor的Settings窗口(Settings/Game/File Path Settings For New Entities):

File Path Settings For New Entities Field(新实体选项栏的文件路径设置)

引擎会为如下文件自动设置指定目录:

  • Entity (*.entity) - 指*.entity文件的路径名称
  • Logic (*.h) - 指带有实体逻辑的*.h文件的路径名称
  • Node (*.node) - 指*.node文件的路径名称
  • Property (*.property) - 指*.prop文件的路径名称
注意
所有的路径都应相对于*.game文件来指定。

如果您将选项栏中的某一个给填错了,那警告图标就会出现。 当您将鼠标悬停在该图标上时,就会显示警告信息。

如果所有的选项栏都填写正确,在点击完Create(创建)按钮之后,实体文件和所有的附加文件就会被创建。 所有这些设置在以后都可以更改。

编辑实体(Entity)

当实体被选中之后,就可以在Entity(实体)标签页和Fields(字段)标签页内对它进行编辑:

实体编辑的标签页
  • Name - 指实体的名称。
  • Parent - 指基本实体的名称,新实体及其属性的实例都是从该基本实体继承而来。
  • Node - 指*.node文件的路径名称。
  • Logic - 指*.h文件的路径名称(相对于data目录的路径),该文件包含了实体逻辑。

    如果具有指定名称的该文件不存在,那它就将基于标准模型(存放在路径下文件data/framework/plugin/editor/templates/entity/logic.h中)来进行自动创建,该模型是从基本的实体类Entity继承而来。

  • Property - 指*.prop文件的路径名称(相对于data目录的路径),该文件包含了属性信息。

    如果具有指定名称的该文件不存在,如果具有指定名称的该文件不存在,那它就会被自动创建。

  • 描述 - 指实体的自定义描述。

字段编辑的标签页
  • Init order - 用来定义实体(entities)初始化的顺序。 该字段仅适用关卡初始化和被放进虚拟世界的实体。 它对动态创建的实体无影响。
  • Enabled - 用来指明是否启用实体及其节点引用。
  • Rendereable - 用来指明onRender()方法是否供该实体调用。
  • Flushable - 用来指明onFlush()方法是否供该实体调用。
  • Updateable - 用来指明onUpdate()方法是否供该实体调用。
  • Update order - 用来定义调用onRender()onFlush()onUpdate()这几种方法的顺序。
注意
所有这些参数都可以在代码中动态更改。

每次游戏被加载或关卡被加载时,实体列表都会被依照用户类中类的层级自动生成 。 为使Editor能正确加载游戏并生成实体列表,就必须编译用户代码。 如果用户代码还未被编译,那游戏将不能被加载,而相应的警告消息也会出现在控制台和日志文件中。

要想将实体的实例放进关卡,只需将其从列表拖出并将其拽进已加载的关卡即可。 分配有属性的节点引用会被自动添加给Editor:

实体的添加

还有另一种将实体添加进关卡的方法:

  • 在Unigine Editor中选择节点引用。
  • 在Game Framework Editor(游戏框架编辑器)中选中实体并点击Assign Entity(分配实体)按钮。

这样,实体的属性就被分配给了节点引用,而该节点引用也就变成了实体。

注意
如果实体之前已被分配给了节点引用,那实体就将被重新分配,所有的属性参数也都将拥有属于它们的默认值。

所有的实体都用蓝色框框出了:

实体框
注意
如果某个实体是节点引用的一部分,那您就需要为其设置entity_traversal属性。 否则,该实体将不能被初始化。

自定义实体逻辑

实体的层级构建以及属性的生成都基于动态编译的用户代码。

注意
要想实体能正确运作,就必须要有逻辑文件,属性文件和节点文件。

如前所述,Fields(字段)代表着实体的属性或自定义设置。 它们都是基于用户代码的属性特征(attributes)被自动生成的,并且这些字段也会依照实体的层级进行分组。

自定义实体的例子:

源代码 (UnigineScript)
#ifndef _MYENTITY_H_
#define _MYENTITY_H_

/******************************************************************************\
 *
 * class MyEntity
 *
\******************************************************************************/

class MyEntity : Entity {
    
  private:
    float rotate_speed = 15.0f;
    float angle = 0.0f;
  public:
    
    MyEntity() {
      
    }
    
    ~MyEntity() {
      
    }
    
    void onInit() {
      // 在此放置您的init代码
    }
    
    void onShutdown() {
      // 在此放置您的shutdown代码
    }
    
    void onUpdate() {
      // 在此放置您的update代码
      // 只是旋转节点
      angle += rotate_speed * game.getGameIFps();
      setRotation(quat(0.0f,0.0f,1.0f,angle));
    }
    
    void onRender() {
      // 在此放置您的render代码
    }
    
    void onFlush() {
      // 在此放置您的flush代码
    }
};

#endif /* _MYENTITY_H_ */

上例向您展示了速度等于rotate_speed值的节点旋转的算法。 要想在框架编辑器中正确更改该速度,您就可以使用Fields(字段)。 只需为Editor中显示的参数添加具有特殊的属性特征(attributes)的setter方法和getter方法即可:

源代码 (UnigineScript)
#ifndef _NEWENTITY_H_
#define _NEWENTITY_H_

/******************************************************************************\
 *
 * class NewEntity
 *
\******************************************************************************/

class NewEntity : Entity {
    
  private: 
    
    float rotate_speed = 15.0f;
    float angle = 0.0f;
    
  public:
    
    NewEntity() {
      
    }
    
    ~NewEntity() {
      
    }
    
    void onInit() {
      // 在此放置您的init代码
    }
    
    void onShutdown() {
      // 在此放置您的shutdown代码
    }
    
    void onUpdate() {
      // 在此放置您的update代码
    }
    
    void onRender() {
      // 在此放置您的render代码
    }
    
    void onFlush() {
      // 在此放置您的flush代码
    }

    [get_float:Rotation Speed]
    float getRotateSpeed() {
      return rotate_speed;
    }
    
    [set_float:Rotation Speed]
    void setRotateSpeed(float value) {
      rotate_speed = value;
    }
};

#endif /* _NEWENTITY_H_ */

待关卡重启完之后,在Fields(字段)标签页内就会出现一个新的float型字段Rotation Speed(旋转速度)

自定义字段(Field)

待实体(entity)的实例被添加给虚拟世界之后,其属性也将能在Nodes(节点)面板中进行调节。 这些属性位于所选实体(节点引用)的Fields(字段)标签页内:

Editor中的自定义字段(Field)
最新更新: 2017-07-03
Build: ()