Programming
Fundamentials
Setting Up Development Environment
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Bounds-Related Classes
Containers
Controls-Related Classes
Core Library
Engine-Related Classes
GUI-Related Classes
Node-Related Classes
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes
Utility Classes

Editor Plugin

A Game Framework Editor makes it possible to create a game right in the Unigine Editor.

There are 3 main fields in the Game Framework Editor:

Game Framework Editor
  • New Game - create a new game
  • Open Game - open the game
  • Save Game - save the current game
  • Play Level - play the level
  • Settings - open the settings window

Levels

Represents the list of the levels and operations on them:

  • New Level - create a new level
  • Remove Level - delete the selected level

Entities

Represents the list of the entities and operations on them:

  • New Entity - create a new entity
  • Remove Entity - delete the selected entity
  • Assign Entity - assign an entity to the node reference or to the node
    Notice
    If you asiign an antity to the node, make sure

Info

Displays an information on the selected element.

Game Creation

To create a new game, click the New Game button. The game creation dialog window will be opened:

Game Creation Dialog Window
  • Name - a name of the game. May contain any characters or even be empty. The default value is new_game.
  • File - the name and location (relatively to the data path) of the *.game file, which contains all the information about the game, levels, entities and all of the additional parameters of the game and Editor. The default value is games/new_game/new_game.game.
  • Entity - the name and location (relatively to the data path) of the *.prop file, which contains all the information about the base entity. This file is automatically generated by the Editor. The default value is games/new_game/entity.prop.
  • Property List - the name and location (relatively to the data path) of the *.prop_list file, which contains the list of all the game properties. This file is automatically generated by the Editor. The default value is games/new_game/properties.prop_list.
Notice
If the game name is changed, all the other directories are changed automatically. If any directory is changed manually, this value would not be changed automatically during the game creation.

If you make a mistake filling one of the fields, the warning icon will appear. When you hover the mouse over it, there will be a message with the warning.

If all of the fields are filled correctly, after clicking the Create button the game and all the attached files will be created. The game will be immediately opened in the Editor. All of these settings can be changed afterwards.

Game Editing

Open the game by clicking the Open button to start editing. The directory of the *.game file can be seen in the title bar. The game settings can be changed in the editor settings window (Game framework settings/Game settings/Game):

Game Settings
  • Name - name of the game (optional)
  • Developer - developer of the game (optional)
  • Version - version of the game (optional)
  • Copyright - copyright (optional)
  • Window Title - the title of the window, when the game is loaded (empty by default)
  • Description - game description (optional)
  • Entity Property - the name and location (relatively to the data path) of the *.prop file, which contains all the information about the base Entity. This file is automatically generated by the Editor. The default value is games/new_game/entity.prop.

    If you change the file name or directory, it will be renamed and relocated automatically, but will have the default values.

  • Property List - a *.prop_list file. The name and location (relatively to the data path) of the property list, which contains the list of all the game properties. This file is automatically generated by the Editor. The default value is games/new_game/properties.prop_list.

    If you change the file name or directory, it will be renamed and relocated automatically, but will have the default values.

The settings of the game loading can be changed from the Game launch field (Settings/Game/Game Launch):

  • System script - the name and the path to the system script file, required to launch the game. There is a default framework system script, placed in the data/framework/game/game_system_script.cpp directory.
  • Extern Define - a list of extern defines (for example, if you develop for mobile platforms, use the RENDER_SIMPLE define)
  • Extern Plugin - a list of user C++ plugins

All the game changes should be saved by pressing the Save Game button.

Level Creation

To create a new level, click the New Level button. The level creation dialog window will be opened:

Level Creation Dialog Window

General

  • Name - the level name.
  • % name - the relative level name, which will be automatically set as a name for *.level, *.world and *.h file.
  • Level File - the name and location (relatively to the data path) of the *.level file, containing all of the information about the level.

World

  • File - the name and location (relatively to the data path) of the *.world file for the new level. If the *.world has not been created before, it will be created automatically by using the pattern located in the data/framework/plugin/editor/templates/level/template.world directory.

Logic

  • Use Custom Logic - use custom logic. If this parameter is disabled, a standard framework level logic is used; otherwise, Class and File additional fields for specifying the custom logic to be used are activated.
  • Logic Class - the name of the class, which instance will be created while the level loading.
  • Logic File - the name and location (relatively to the data path) of the *.h file, containing the level logic.

    If the file of the specified name does not exist, it will be created automatically based on the standard pattern (data/framework/plugin/editor/templates/level/logic.h), which is inherited from the base level logic class Level.

Notice
The same level logic class can be used for different levels.

If you want to change autofill parameters for the level creation, open the editor settings window (Game framework settings/Game settings/File Path Settings For New Levels):

File Path Settings For New Levels Field

The specified directories will be set automatically for the following files:

  • Level (*.level) - the name and location of the *.level file
  • Logic (*.h) - the name and location of the *.h file with the level logic
  • World (*.world) - the name and location of the *.world file
Notice
All the paths should be specified relatively to the *.game file.

If you make a mistake filling one of the fields, the warning icon will appear. When you hover the mouse over it, there will be a message with the warning.

If all of the fields are filled correctly, after clicking the Create button the level file and all the attached files will be created. The level will be opened in the Editor. All of these settings can be changed afterwards.

Level Editing

When the level is selected, it can be edited in the Level tab:

Level Editing Tab
  • Name - the level name
  • World - the name and location (relatively to the data path) of the *.world file for the new level.
  • Logic - the name and location (relatively to the data path) of the *.h file, containing the level logic. If the file of the specified name does not exist, it will be created automatically based on the standard pattern (data/framework/plugin/editor/templates/level/logic.h), which is inherited from the base level logic class Level.
  • Logic class - the name of the class, which instance will be created while the level loading.
Notice
If you do not want the custom logic to be used, just delete all of the values in Logic and Logic class fields.

All the game changes should be saved by pressing the Save game button.

To load or reload the world just double click the level in the level list, so Editor will regenerate and reload all of the properties and load the required world for your level for you to edit it, change its parameters, add, delete or edit nodes. Loaded level is highlighted with blue.

When the level world is loaded in Editor, the Play level button becomes active in a runtime, in other words the game is launched. Play level button loads one more engine instance for the game to be launched in a runtime.

Notice
Another engine instance will be of the same version as the Editor,

You can change the settings of the level loading from the Editor in the level playing options window (Game framework settings/Editor settings/Play level options):

Play Level Options Field
  • Binary - specify a binary file to be loaded when the level is played
  • Debug - specify if a debug mode is enabled
  • Video API - video API switcher. Available values:
    • OpenGL - OpenGL API (available for Windows, OS and Linux)
    • Direct3D9 - Direct3D9 API (available for Windows)
    • Direct3D11 - Direct3D11 API (available for Windows)
  • Resolution - engine window resolution
  • VSync - vertical synchronization
  • Fullscreen - full screen mode
  • Engine Config - an engine configuration file
  • Engine Log - an engine log file
  • Editor Config - an editor configuration file

Custom Level Logic

Custom logic can be applied to all of the levels in the game. It can be unique for each level or common for all of them.

Notice
The custom logic class and a path to *.h file with logic can be set in the Logic and Logic class fields.

A logic file should be inherited from base framework Level class for the game to work correctly. Its is placed in the data/framework/game/level.h directory.

If the user code is incorrect, the game would not be loaded. The corresponding warning messages will appear in the console and log files.

You can access the logic file quickly by pressing the Edit Logic button near the Logic field. By default, the folder with the specified logic will be opened. You can specify the name of the logic file in the Open Cmd File field of the Editor tab, so the file itself will be opened when clicking the Edit Logic button:

Open Cmd File

The example of the custom logic usage:

Source code(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”);
    }
    
    // this function is called before all entities creation
    void onWarm() {
      // place your warming code here
      log.message(“MyLevel onWarm() called\n”);
    }
    
    // this function is called after all entities creation
    void onInit() {
      // place your init code here
      log.message(“MyLevel onInit() called\n”);
    }
    
    void onShutdown() {
      // place your shutdown code here
      log.message(“MyLevel onSutdown() called\n”);
    }
    
    void onPreUpdate() {
      // calling before entities update
      // place your update code here
    }
    
    void onPostUpdate() {
      // calling after entities update
      // place your update code here
      if(first_update) {
        log.message(“MyLevel onPostUpdate() called\n”);
        first_update = false;
      }
    }
    
    void onRender() {
      // place your render code here
    }
    
    void onFlush() {
      // place your flush code here
    }
};

#endif /* _MYLEVEL_H_ */

The class instance will be automatically created by the game while level loading and all of the functions will be called in the proper order.

You can create your own base class, inherited from the framework Level class, and inherit your other classes from it. For it, just include a header of base class file in you level logic file:

Source code(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_ */
Notice
Make sure that you specified the name of the custom class and the logic file location in the Level tab.

Entity Creation

To create a new entity, click the New Entity button. The entity creation dialog window will be opened:

Entity Creation Dialog Window

General

  • Name - the entity name, which gives a name to the corresponding entity class and property.
  • % name - the relative entity name, which will be automatically set as a name for *.entity, *.h, *.prop and *.node file.
  • File - the name and location (relatively to the data path) of the *.entity file, containing all of the information about the entity.

Logic

  • Parent - the name of the base entity, from which the new entity and its property instance is inherited.
  • File - the name and location (relatively to the data path) of the *.h file, containing the entity logic.

    If the file of the specified name does not exist, it will be created automatically based on the standard pattern (data/framework/plugin/editor/templates/entity/logic.h), which is inherited from the base entity class Entity.

  • Property - the name and location (relatively to the data path) of the *.prop file, containing the property. If the file of the specified name does not exist, it will be created automatically.
Notice
The same logic class cannot be used for different entities.

Node

  • Use Node - specifies if the entity is created with the node assigned. If disabled, a new entity will be created without any node assigned, so when you select it in the nodes hierarchy, it would not have the Node tab. While placing such an entity into the world (by drag&drop operation), a dummy node with this entity assigned will appear. Like other nodes, a dummy node can have a property assigned.

    For nodes without entities assigned there is the same update and shutdown logic (calls of the onInit(), onUpdate(), onFlush(), onRender() and onShutdown() functions), but the logic of the entity initialization is different. If the entity is assigned to the node reference, its class instance is placed into the root node by the Node::setVariable method; but if the entity is assigned to the node, a class instance is not placed anywhere and cannot be obtained from the node. But you can get it manually through the onInit() function. Lets, for example, assign an empty (without a node assigned) entity called MyEntity to the node with complicated hierarchy. We know, that as a child it has a mesh called "my_mesh", which then can be obtained by intersection methods. If it will get an instance of our class as a variable, then we will be able to obtain a class instance of our entity from this node:

    Source code(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);
        }
    };
    Notice
    If you have set an entity or other logic class through the Node::setVariable() method, you need to call a Node::setVariable(NULL) method in the shutdown().
  • Node File - the name and location (relatively to the data path) of the *.node file for the new entity.

    If the *.node has not been created before, it will be created automatically by using the pattern located in the data/framework/plugin/editor/templates/entity/template.node directory.

If you want to change autofill parameters for the entity creation, open the editor settings window (Settings/Game/File Path Settings For New Entities):

File Path Settings For New Entities Field

The specified directories will be set automatically for the following files:

  • Entity (*.entity) - the name and location of the *.entity file
  • Logic (*.h) - the name and location of the *.h file with the entity logic
  • Node (*.node) - the name and location of the *.node file
  • Property (*.property) - the name and location of the *.prop file
Notice
All the paths should be specified relatively to the *.game file.

If you make a mistake filling one of the fields, the warning icon will appear. When you hover the mouse over it, there will be a message with the warning.

If all of the fields are filled correctly, after clicking the Create button the entity file and all the attached files will be created. All of these settings can be changed afterwards.

Entity Editing

When the entity is selected, it can be edited in the Entity and Fields tabs:

Entity Editing Tab
  • Name - the entity name.
  • Parent - the name of the base entity, from which the new entity and its property instance is inherited.
  • Node - the name and location of the *.node file.
  • Logic - the name and location (relatively to the data path) of the *.h file, containing the entity logic.

    If the file of the specified name does not exist, it will be created automatically based on the standard pattern (data/framework/plugin/editor/templates/entity/logic.h), which is inherited from the base entity class Entity.

  • Property - the name and location (relatively to the data path) of the *.prop file, containing the property.

    If the file of the specified name does not exist, it will be created automatically.

  • Description - a custom description of the entity.

Fields Editing Tab
  • Init order - defines an order of entities initialization. Work only for level initialization and for entities placed in the world. It has no influence on entities created dynamically.
  • Enabled - indicates if the entity and its node reference are enabled.
  • Rendereable - indicates if the onRender() method is called for this entity.
  • Flushable - indicates if the onFlush() method is called for this entity.
  • Updateable - indicates if the onUpdate() method is called for this entity.
  • Update order - defines an order for the onRender(), onFlush() and onUpdate() methods to be called.
Notice
All of this parameters can be changed dynamically in the code.

Every time the game or the level is loaded, the entity list is generated automatically in accordance with the class hierarchy in the user class. For the editor to correctly load the game and generate the entity list, the user code must be compiled. If it has not been compiled, the game would not be loaded and the corresponding warning messages will appear in the console and log files.

To place the entity instance in the level, just drag it from the list and drop into the loaded level. The node reference with the assigned property will be added to the editor automatically:

Entity Adding

There is also another way of adding the entity into the level:

  • Choose the node reference in the Unigine Editor.
  • Choose the entity in the Game Framework Editor and click the Assign Entity button.

So, the entity property will be assigned to the node reference, so it will become an entity.

Notice
If the entity has been assigned to the node reference before, the entity will be reassigned and all the property parameters will have their default values.

All of the entities are outlined with the blue circles:

Entities Outline
Notice
If an entity is a part of the node reference, you need to specify the entity_traversal property to it. Otherwise, the entity would not be initialized.

Custom Entity Logic

The entity hierarchy build and the property generation is based on the dynamically compiled user code.

Notice
For an entity to work correctly, there must be the logic, property and node files.

As mentioned before, Fields represent properties or custom settings for the entity. They are automatically generated based on the user code attributes and are grouped in accordance with the entity hierarchy.

The example of the custom entity:

Source code(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() {
      // place your init code here
    }
    
    void onShutdown() {
      // place your shutdown code here
    }
    
    void onUpdate() {
      // place your update code here
      // just rotate node
      angle += rotate_speed * game.getGameIFps();
      setRotation(quat(0.0f,0.0f,1.0f,angle));
    }
    
    void onRender() {
      // place your render code here
    }
    
    void onFlush() {
      // place your flush code here
    }
};

#endif /* _MYENTITY_H_ */

The example above shows the algorithm of the node rotation with the speed equal to the rotate_speed value. To change this speed right in the framework editor, you can use Fields. Just add setter and getter methods with the special attributes for the parameter to be displayed in the editor:

Source code(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() {
      // place your init code here
    }
    
    void onShutdown() {
      // place your shutdown code here
    }
    
    void onUpdate() {
      // place your update code here
    }
    
    void onRender() {
      // place your render code here
    }
    
    void onFlush() {
      // place your flush code here
    }

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

#endif /* _NEWENTITY_H_ */

After the level restart, in the Fields tab there will be a new float Rotation Speed field:

Custom Field

When the entity instance is added to the world, its properties can be also adjusted in the Nodes panel. They can be found in the Fields tab of the selected entity (node reference):

Custom Field in Editor
Last update: 2017-07-03