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

Structure

Warning
Game Framework is deprecated and no longer supported. We can't guarantee the stable work of the framework.

There are two base classes to be inherited and extended to implement the game logic in Game Framework:

  • Extensible class Level - to describe the world
  • Extensible class Entity - to describe the node (to be more exact, the node reference)

Class Game is used to manage the game and load the logic for levels and entities.

Information on the level, entity and game itself is stored in the *.level , *.entity and*.game files correspondingly.

All of the entities have assigned properties.

Game Structure

All the project information is stored in the following XML format files:

*.entity

Contains an information about the user entity and the directories of the following files:

  • *.node - node reference file
  • *.prop - property file
  • *.h - entity logic file

Usage Example

Source code (XML)
<?xml version="1.0" encoding="utf-8"?>
<entity name="EntityActor">
    <description/>
    <node>framework/samples/platformer/entities/entity_actor/entity_actor.node</node>
    <logic>framework/samples/platformer/scripts/entities/entity_actor.h</logic>
    <property>framework/samples/platformer/entities/entity_actor/entity_actor.prop</property>
</entity>

*.level

Contains an information about the level and the directories of the following files:

  • *.world - world file
  • *.h - level logic file

Usage Example

Source code (XML)
<level name="level_1">
    <world>framework/samples/platformer/levels/level_1/level_1</world>
    <logic>framework/samples/platformer/scripts/levels/platformer_level.h</logic>
    <logic_class>PlatformerLevel</logic_class>
    <description/>
</level>

*.game

Contains an information about the game and the directories of the following files:

  • the list of all of the used *.entity files
  • the list of all of the used *.level files
  • *.prop - file containing the base property for all entities
  • *.prop_list - file with the list of all the libraries required to load the game
Source code (XML)
<?xml version="1.0" encoding="utf-8"?>
<game version="0">
  <info>
    <name>platformer game</name>
    <developer/>
    <copyright/>
    <version/>
    <description/>
    <window_title/>
    <entity_property>framework/samples/platformer/entity.prop</entity_property>
    <properties>framework/samples/platformer/platformer_properties.prop_list</properties>
    <parameters>
      <parameter name="new_level_path">levels/%name/%name.level</parameter>
      <parameter name="new_level_logic_path">scripts/levels/%name/%name.h</parameter>
      <parameter name="new_level_world_path">levels/%name/%name.world</parameter>
      <parameter name="new_entity_path">entities/%name/%name.entity</parameter>
      <parameter name="new_entity_logic_path">scripts/entities/%name/%name.h</parameter>
      <parameter name="new_entity_node_path">entities/%name/%name.node</parameter>
      <parameter name="new_entity_property_path">entities/%name/%name.prop</parameter>
    </parameters>
  </info>
  <levels>
    <level name="level_1" level="framework/samples/platformer/levels/level_1/level_1.level"/>
    <level name="level_2" level="framework/samples/platformer/levels/level_2/level_2.level"/>
  </levels>
  <entities>
    <entity name="EntityActor" entity="framework/samples/platformer/entities/entity_actor/entity_actor.entity"/>
    <entity name="PlatformerActor" entity="framework/samples/platformer/entities/paltformer_actor/paltformer_actor.entity"/>
    <entity name="Hero" entity="framework/samples/platformer/entities/hero/hero.entity"/>
    <entity name="Monster" entity="framework/samples/platformer/entities/monster/monster.entity"/>
    <entity name="DeadZone" entity="framework/samples/platformer/entities/dead_zone/dead_zone.entity"/>
    <entity name="EndLevel" entity="framework/samples/platformer/entities/end_level/end_level.entity"/>
    <entity name="MonsterBoss" entity="framework/samples/platformer/entities/monster_boss/monster_boss.entity"/>
    <entity name="Bonus" entity="framework/samples/platformer/entities/bonus/bonus.entity"/>
  </entities>
</game>
Notice
All of these files represent a database of the game. You can access them by using the GameData class, which will allow you to get all of the information about the game and a list of the required files, change the data or save it into a file.

Game Framework Editor can also be used to create and edit these files.

*.prop and *.prop_list files are automatically generated by the Game Framework Editor plugin.

Property

Working with the property is handy for both programmers and designers. Due to the usage of the most property capabilities in Game Framework, the property can identify the user entity, adjust all the user parameters (including the entity inheritance), pass the parameter into the user class script and much more.

For the entity to be recognized as a Node Reference wrapper, it must have the assigned property. Therefore, when the game is launched, the corresponding user class will be created automatically.

All of the properties need to be inherited from the entity_base property, located in the data/framework/game/properties/entity_base.prop directory. The entity_base property contains the only one class parameter, defining the name of the class. All the properties, inherited from the entity_base, share this parameter; it cannot be edited and is redefined automatically.

Property inheritance hierarchy is the same as for entity.

Warning
All of the entity properties are generated automatically in accordance with the user code. Do not manually add or delete states or parameters.

Fields

Engine analyzes all the classes inherited from the Entity class and based on the user class function attributes generate the parameter for the property. Such functions are called "Fields" and require bothset() and get() methods to be specified.

Every time the user Entity class instance is created, the Fieldset() methods are called automatically to pass the relevant parameter from the property with the user set value.

Notice
Some fields can be identified automatically.

The types of the Fields are listed below.

int

A parameter of the integer type.

Attributes:

  • [get_int:field_name] - getter
  • [set_int:field_name] - setter

Usage Example

Source code (UnigineScript)
[get_int:my int parameter]
int getMyParameter() {
  return 0;
}

[set_int:my int parameter]
void setMyParameter(int v) {
  // do something
}

float

A parameter of the float type.

Attributes:

  • [get_float:field_name] - getter
  • [set_float:field_name] - setter

Usage Example

Source code (UnigineScript)
[get_float:my float parameter]
float getMyParameter() {
  return 0.0f;
}

[set_float:my float parameter]
void setMyParameter(float v) {
  // do something
}

double

A parameter of the double type.

Attributes:

  • [get_double:field_name] - getter
  • [set_double:field_name] - setter

Usage Example

Source code (UnigineScript)
[get_double:my double parameter]
double getMyParameter() {
  return 0.0;
}

[set_double:my double parameter]
void setMyParameter(double v) {
  // do something
}

vec3

A parameter of the vec3 type.

Attributes:

  • [get_vec3:field_name] - getter
  • [set_vec3:field_name] - setter

Usage Example

Source code (UnigineScript)
[get_vec3:my vec3 parameter]
vec3 getMyParameter() {
  return vec3(0.0f,0.0f,0.0f);
}

[set_vec3:my vec3 parameter]
void setMyParameter(vec3 v) {
  // do something
}

vec4

A parameter of the vec4 type.

Attributes:

  • [get_vec4:field_name] - getter
  • [set_vec4:field_name] - setter

Usage Example

Source code (UnigineScript)
[get_vec4:my vec4 parameter]
vec4 getMyParameter() {
  return vec4(0.0f,0.0f,0.0f,0.0f);
}

[set_vec4:my vec4 parameter]
void setMyParameter(vec4 v) {
  // do something
}

string

A parameter of the string type.

Attributes:

  • [get_string:field_name] - getter
  • [set_string:field_name] - setter

Usage Example

Source code (UnigineScript)
[get_string:my string parameter]
string getMyParameter() {
  return “my_string”;
}

[set_string:my string parameter]
void setMyParameter(string v) {
  // do something
}

color

A parameter of the color type.

Attributes:

  • [get_color:field_name] - getter
  • [set_color:field_name] - setter

Usage Example

Source code (UnigineScript)
[get_color:my color parameter]
vec4 getMyParameter() {
  return vec4(1.0f,1.0f,1.0f,1.0f);
}

[set_color:my color parameter]
void setMyParameter(vec4 v) {
  // do something
}

toggle

A parameter of the toggle type.

Attributes:

  • [get_toggle:field_name] - getter
  • [set_toggle:field_name] - setter

Usage Example

Source code (UnigineScript)
[get_toggle:my toggle parameter]
int getMyParameter() {
  return 0;
}

[set_toggle:my toggle parameter]
void setMyParameter(int v) {
  // do something
}

switch

A parameter of the switch type.

Attributes:

  • [get_switch:field_name] - getter
  • [set_switch:field_name] - setter

Usage Example

Source code (UnigineScript)
[get_switch:my switch:”one,two,three”]
int getMyParameter() {
  return 0;
}

[set_switch:my switch]
void setMyParameter(int v) {
  // do something
}

file

A parameter of the file type. Identical to the parameter of the string type, but having an icon to open a file selection window.

Attributes:

  • [get_file:field_name] - getter
  • [set_file:field_name] - setter

Usage Example

Source code (UnigineScript)
[get_file:my file:”one,two,three”]
int getMyParameter() {
  return 0;
}

[set_file:my file]
void setMyParameter(int v) {
  // do something
}

mask

A parameter of the mask type. To modify this kind of the parameter in Editor you need to double click to it. In the opened dialog window you can define the mask.

Attributes:

  • [get_mask:field_name] - getter
  • [set_mask:field_name] - setter

Usage Example

Source code (UnigineScript)
[get_mask:"Mask field"]
int getMaskField() {
  return mask_field;
}


[set_mask:"Mask field"]
void setMaskField(int value) {
  mask_field = value;
}
Notice
In case if any Field does not contain setter or getter method, the parameter would not be created. The notifying message will appear in logs.

Field Type Auto Identification

int, float, double, string, vec3, vec4 field types can be identified automatically. Instead of direct specification (e.g.[get_int] or [set_int]), you can specify just an attribute name (e.g. [get:”field_name”]). Editor will automatically identify the type of the parameter (for "get" functions), or a type of argument (for "set" functions).

For example, we need to create a field of the integer type:

Source code (UnigineScript)
[set:"Damage"] 
void setDamage(int value) {
  damage = value;
}

[get:"Damage"] 
int getDamage() {
  return damage;
}
Notice
toggle, switch, color andfile fields need to be specified manually.

Extensible Class Level

A Level class is a base class to define the level logic. This class implements the work of all of the entities in the following ways:

  • Dynamically add and delete the user entity.
  • Delete the entity or relocate it into the pool.
  • Control the periodic function call dispatcher.
  • Provide the event system.
  • Operate with the pool of relocated entities.

The virtual methods of the Level class, such asonWarm(), onInit(), onShutdown(), onPreUpdate(), onPostUpdate(), onFlush() andonRender(), can be redefined to implement the user logic of the level.

Notice
You should not redefine other Level class methods.

Extensible Class Entity

An Entity class is a base class to define the game object logic and provide the quick access to the node.

The virtual methods of the Entity class, such asonInit(), onShutdown(), onUpdate(), onFlush() andonRender(), can be redefined to implement the user logic of the level. Besides, you can disableonUpdate(), onFlush() andonRender() functions call for every user entity, if you don't need them to be called for this node.

You can dynamically enable or disable these functions calls with the Entity::setUpdateable(int mode), Entity::setFlushable(int mode) andEntity::setRenderable(int mode) methods (which are alsoToggle Fields and are passed to the base property for all the user Entities).

Every entity refers to the Level class instance, to which it belongs to.

Class Game

A Game class is responsible for the entire user code work. It operates levels and load them dynamically by names or indices.

The framework logic is implemented in the world script and is reloaded every time the new world is loaded. The Game class executes the following operations:

  1. Generates an Expression at the level initialization.
  2. Places the user code in the Expression along with the implementation of all of the user entities and levels.
  3. After the Expression compilation generates the corresponding Level class instance.
  4. Place all the user entities in the world are reconstruct them.
  5. While compiling, analyzes the user code and passes property parameters into Entity class instances.
Notice
Every level or entity refer to the Game class instance, to which they belong to.
Last update: 2017-07-03