UnigineScript
The Language
Core Library
Engine Library
Node-Related Classes
GUI-Related Classes
Plugins Library
High-Level Systems
Samples
C++ API
API Reference
Integration Samples
Usage Examples
C++ Plugins
Content Creation
Materials
Unigine Material Library
Tutorials

Structure

Launcher files are stored in the data/launcher folder, which includes the following:

  • Configuration file launcher.xml
  • Interface files
  • Logic files

The interface and the logic are described by using HTML, CSS and JavaScript.

Launcher Configuration File

The default configuration file stores the following options of the Launcher:

Source code (XML)
				<?xml version="1.0" encoding="utf-8"?> 
<unigine> 
	<window> 
		<width>750</width> 
		<height>498</height> 
		<icon>../data/launcher/icon.png</icon> 
		<title>GeneratTed project: my_project</title> 
		<centered>1</centered> 
		<sizeable>0</sizeable> 
	</window> 
	<arguments> 
		<defines>game</defines> 
		<soundapp>auto</soundapp> 
		<externPlugins></externPlugins> 
		<archs>x86 x64</archs> 
		<version>1.0</version> 
	</arguments> 
	<interface src="../data/launcher/interface.html" /> 
</unigine>
				

window

The window section defines the following window options:

  • width - window width in pixels
  • height - window height in pixels
  • icon - path to the application icon
    Notice
    Path to the icon file is relative to the bin folder
  • title - window title
  • centered - whether the window is center-aligned. Set 1 to make the window center-aligned; otherwise set 0
  • sizeable - whether the window is resizable. Set 1 to make the window resizable; otherwise set 0

arguments

The arguments section stores a list of the Launcher options. The number of the options is not limited.

interface

The interface section specifies a path to the interface file relative to the bin folder.

Launcher Interface

The interface of the Launcher is described by using the interface.html and project.css files.

Notice
It is recommended to use the Latin-1 symbols in the interface file, because the other symbols are shown incorrectly.

Background Layers

There are 2 background layers specified in the interface.html file:

  • Launcher background
    Source code (XML)
    									<div id="launcher-background"></div>
    								
    It is used to specify the background depending on the current language or the other application options.
  • Form background
    Source code (XML)
    								<div id="form-background"></div>
    							
Both backgrounds can be customized.

User Input Form

The form contains a list of elements associated with the application options, such as language, rendering API, window resolution that are set by user.

In the interface file, the form is defined as follows:

Source code (XML)
<form id="form">
	<div id="element_language" class="form-element">
		<label id="label_language"></label>
		<select id="component_language" data-bind="language"></select>
	</div>
	<div id="element_preset" class="form-element">
		<label id="label_preset"></label>
		<select id="component_preset" data-bind="preset"></select>
	</div>
	...
</form>
					
Each element is described inside the div tag:
  • The element name is specified in the label tag by using the translator.
  • The element values are specified in the component associated with this element.

Run Button

The RUN button is used to launch the application with specified options. It is defined as follows:

Source code (XML)
<input id="run_button" type="button" value="RUN" />
					

Launcher Logic

The logic of the Launcher is described by using the JavaScript UIMess library.

System Options

System options, such as an operating system name and version, are mainly used to hide or show the certain elements of the form.

The system options are sent to the application as follows:

Source code
var storageResource = {
	'os_name': '$platform',
	'os_arch': '$arch',
	'system_height': '$height',
	'system_width': '$width',
	'dir': '$directory',
	'home': '$home',
	'app': 'main',
	'project_name': 'GENPROJECT'
};

UIMess.Storage.storage(storageResource);
					

Here:

  • $platform - operating system name. It corresponds to the getPlatform() function.
  • $arch - operating system bit rate. It corresponds to the getArch() function.
  • $height - screen height. It corresponds to the getHeight() function.
  • $width - screen width. It corresponds to the getWidth() function.
  • $directory - current directory. It corresponds to the getDirectory() function.
  • $home - system location of the user directory.
  • $app - name of the main executable file.
  • $project_name - application ID.

Components

Components represent the application options, which are required on application startup. The components are described in the UIMess.js file.

All of the components have the following functions:

  • disable(boolean) - disables the ability to set the component value. If no argument is passed, the function returns its current value.
  • lock(boolean) - locks the component. If no argument is passed, the function returns its current value.
    Notice
    You cannot change even the disable properties.
  • value(mixed) - sets the component value. If no argument is passed, the function returns its current value.
  • options(mixed) - adds the component options. If no argument is passed, the function returns its current value.
  • name() - returns the component internal name.

All of the required components are added to UIMess.FormManager as follows (see the project.js file):

Source code
 UIMess.FormManager.addForm([
	UIMess.Language(),
	UIMess.Presets(),
	UIMess.VideoApp(),
	UIMess.Quality(),
	UIMess.FullScreen(),
	UIMess.Stereo(),
	UIMess.MultiMonitor(),
	UIMess.Resolution(),
	UIMess.AntiAliasing(),
	UIMess.Anisotropy(),
	UIMess.PlayMode(),
	UIMess.CommandLine('data_path', '../'),
	UIMess.CommandLine('system_script', '{projectName}/unigine.cpp'),
	UIMess.CommandLine('engine_config', '../data/{projectName}/unigine.cfg'),
	UIMess.CommandLine('engine_log', '../{projectName}_log.htm'),
	UIMess.ConsoleCommand('world_load', '{projectName}/{projectName}')
]);

$(function () {
	UIMess.FormManager.bindForm('form');
	
	UIMess.start();
});
The components are initialized in the UIMess framework, event handlers are set, the component values specified in the previous launch (if any) or the default values are loaded to the current components.

Each component is associated with the corresponding element of the form by using UIMess.FormManager.bindForm(form), where form is a form ID. In interface.html, such an element is marked by using the data-bind attribute. For example:

Source code (XML)
<div id="element_language" class="form-element">
	<label id="label_language"></label>
	<select id="component_language" data-bind="language"></select>
</div>
The language element is associated with the language component. If you change the element value on the form, the component value is also changed.

Events

Component events are based on JS Signals that is analogue of the QT Signal. The signals.Signal object is returned for each event call.

The following events are defined for the component:

  • changeSignal() that is called when the component value is changed.
  • disableSignal() that is called when the component is disabled.

The add() and remove() functions are used to add and delete a callback, respectively.

To get the component from the FormManager, it is required to use the getComponent() function. For example, you can get the language component and add a callback function that fires when the language is changed:

Source code
UIMess.FormManager.getComponent('language').changeSignal().add(function(value) {
	alert('New Language: ' + value);
});
						

Translation

Translation of the interface elements is performed by using the UIMess.Translator module. The default translation rules are defined in the translations.js file.

Each element of the interface has a unique ID attribute that is used to translate the page to another supported language. The translator is initialized as follows:

Source code
UIMess.Translator.setup({
	'en': {
		'name': 'English',
		'keys': {
			'label_language': {'html': 'Language:'},
			...
		}
	},
	'ru': {
		'name': 'Русский',
		'keys': {
			'label_language': {'html': 'Язык:'},
			...
		}
	}
});					
					
In the example, the setup function receives objects that are represented by key-value pairs, where the key indicates the language name (for example, en, ru), and the value contains another object with the following properties:
  • name - full name of the language. It is displayed in the Language element.
  • keys - object represented by the key-value pairs, where the key indicates a class or ID of the interface element, and the value is another object with the following keys:
    • html - interface element value.
    • css - object represented by the key-value pairs, where the key is the CSS property name, and the value is the CSS property value.
    • attribute - object represented by the key-value pairs, where the key is the element attribute name, and the value is the element attribute value.
Notice
If the css property or the attribute are set for one language, and then the language is switched to another one, the properties are not reset.

The UIMess.Translator.translate() function is used to run the translator.

Notice
You can also call the UIMess.start() function right after the UIMess.FormManager.bind() function to initialize the translator.

Application Run

The following construction is used to run the application with the specified options:

Source code
UIMess.EngineLauncher.launch(UIMess.FormManager.getCommandLine());
					
Here:
  • UIMess.FormManager.getCommandLine() returns a string of options that are required to run the application.
  • UIMess.EngineLauncher.launch() forms the name of the executable file by using the system data and then launches it with the given options.

This construction is associated with the RUN button.

Last update: 2017-07-03