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:

• 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

Entities

Info

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

• 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.

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.

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):

• 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.

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

General

World

Logic

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):

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

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.

When the level is selected, it can be edited in the Level 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.

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.

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):

• 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 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.

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:

The example of the custom logic usage:

#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:

#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_ */

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

General

Logic

Node

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

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

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.

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

• 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.

• 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.

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:

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.

All of the entities are outlined with the blue circles:

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

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:

#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:

#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:

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):