UnigineScript
The Language
Core Library
Engine Library
Node-Related Classes
GUI-Related Classes
Plugins Library
High-Level Systems
Samples
Usage Examples
C++ API
API Reference
Integration Samples
Usage Examples
C++ Plugins
Migration
Migrating to UNIGINE 2.0
C++ API Migration
Migrating from UNIGINE 2.0 to UNIGINE 2.1

Launcher 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, JavaScript and UnigineScript.

Launcher Configuration File

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

Source code (XML)
<unigine>
	<window>
		<width>610</width>
		<height>405</height>
		<centered>1</centered>
		<sizeable>1</sizeable>
		<moveable>0</moveable>
		<frame>1</frame>
		<icon></icon>
		<title>UNIGINE Application Launcher</title>
	</window>
	<arguments>
		<defines/>
	</arguments>
	<interface src="data/launcher/launcher.html"/>
	<script src="data/launcher/launcher.cpp"></script>
</unigine>

window

The window section defines the following window options:

  • width - window width in pixels.
  • height - window height in pixels.
  • 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.
  • moveable - whether the window is movable. Set 1 to make the window movable; otherwise, set 0.
  • frame - whether the window frame is rendered. Set 1 to render the window frame; otherwise, set 0.
  • icon - path to the application icon.
    Notice
    Path to the icon file is relative to the bin folder.
  • title - the window title.

arguments

The arguments section stores a list of the internal launcher options. These options are available via JavaScript and UnigineScript. The number of the options is not limited. For example, here can be specified external definitions, external plugins, a sound application and so on.

The arguments specified in this section can be obtained on the as follows:

Source code (UnigineScript)
string defines = browser.getArgument("defines");

interface

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

script

The script section specifies a path to the UnigineScript .cpp file that contains logic of the launcher. The path is specified relative to the bin folder.

Launcher Interface

The interface of the GUI launcher is described by using the data/launcher/launcher.html and data/launcher/style.css files.

By default, the GUI launcher includes the form with a list of elements associated with the application options, such as rendering API, window resolution that are set by user. Each element is described inside the div tag

The form also contains the Run button that is used to launch the application with specified options.

Launcher Logic

The logic of the GUI launcher is described by using the JavaScript and UnigineScript languages. The source code of the default launcher is available in the following files:

  • launcher.html that contains the JavaScript code placed in the script section.
  • launcher.h that contains implementation of the Launcher class with getter and setter methods for the application options provided via the launcher form.
  • launcher.cpp that describes logic of initialization and shut down of an instance of the Launcher class, provides an interface for calling its setter and getter methods and also runs the application when the Run button is pressed.

The pipeline of interaction of the launcher interface and logic is the following:

  1. The launcher init() function defined on the UnigineScript side is called. The new launcher instance with initial settings is created and the GUI launcher window is opened.
  2. When changing a value of one of the elements via the launcher window, the corresponding JavaScript callback is run. For example, if you change the API element, the required function will be called as follows (passed as value of the onchange attribute):
    Source code (XML)
    <div class="control-group margin-bottom">
    	<label>API:</label>
    	<div class="select-wrapper">
    		<select name="api"  id="api" onchange="setVideoApp(this.options[this.selectedIndex].value)">
    			<option value="auto"		>Auto-detection</option>
    			<option value="direct3d11"	>DirectX 11</option>
    			<option value="opengl"		>OpenGL</option>
    		</select>
    	</div>
    </div>
  3. The JavaScript callback, in turn, calls the required function of the launcher defined on the UnigineScript side.
    Notice
    JavaScript has no direct access to the UnigineScript class instances and its methods: it can call only simple functions via one of the Browser.call() functions.
    For example, when you change the API element, the JavaScript callback calls the UnigineScript function that sets the video application as follows:
    Source code
    function setVideoApp(value) { Browser.call("setVideoApp",value); }
  4. When all the required options are set, the Run button is pressed. It initiates the following process:
    1. On the HTML side, the JavaScript callback is run (passed as value of the onclick attribute):
      Source code (XML)
      <div class="control-group form-buttons">
      	<button class="common" style="float:right; width: 268px; margin-left: 1px;" onclick="run(); return false;">Run</button>
      </div>
    2. On the JavaScript side, the UnigineScript run() function is called:
      Source code
      function run() { Browser.call("run"); }
    3. On the UnigineScript side, the run() function launches the application (see launcher.cpp):
      Source code (UnigineScript)
      void run() {
      	launcher.launch();
      }

Notice
It is also possible to call functions defined on the JavaScript side from UnigineScript by using one of js.call() functions.

System Options

System information, such as an operating system name and version, can be obtained not only via JavaScript and UnigineScript by using the corresponding Browser functions. There are also a set of placeholders available for the HTML part of the launcher. If you add such placeholder to the launcher.html page, it will be replaced with the corresponding value when the launcher is run.

  • $width - the screen width. It corresponds to the getWidth() function.
  • $height - the screen height. It corresponds to the getHeight() function.
  • $data - the path to a directory where persistent application data can be stored. It corresponds to the getData().
  • $home - system location of the user directory. It corresponds to the getHome().
  • $temp - a path to a directory where temporary files are stored. It corresponds to the getTemp().
  • $desktop - a path to the user's desktop directory. It corresponds to the getDesktop().
  • $download - a path to a directory for user's downloaded files. It corresponds to the getDownload().
  • $documents - a path to a directory that contains user document files. It corresponds to the getDocuments().
  • $directory - current directory. It corresponds to the getDirectory() function.
  • $platform - operating system name. It corresponds to the getPlatform() function.
  • $version - the version of the operating system (only for Windows). It corresponds to the getVersion() function.
  • $arch - operating system bit rate. It corresponds to the getArch() function.

These placeholders can be used, for example, to hide or show the elements on the launcher form depending on the operating system or the system architecture.

Setter and Getter Methods

As it was described above, when changing values of the options available via the launcher, the JavaScript functions call the corresponding setter and getter methods defined on the UnigineScript side.

Such methods are implemented in the Launcher class (see launcher.h) on the UnigineScript side. However, JavaScript has no direct access to an instance of this class and its methods: it can call only simple functions. So, the launcher.cpp provides an interface for calling these setter and getter methods from the JavaScript side, which is implemented by using templates.

Notice
These templates are used to generate the simple functions, which, in turn, call setter and getter methods of the launcher.
Source code (UnigineScript)
template launcher_parameter<PARAMETER,TYPE> {
	void set ## PARAMETER(TYPE value) { launcher.set ## PARAMETER(TYPE(value)); }
	TYPE get ## PARAMETER() { return launcher.get ## PARAMETER(); }
}
					
template launcher_parameter_bool<PARAMETER> {
	void set ## PARAMETER(int value) { launcher.set ## PARAMETER(value); }
	int get ## PARAMETER() { return launcher.is ## PARAMETER(); }
}

template launcher_parameter_simple_bool<PARAMETER> {
	void set ## PARAMETER() { launcher.set ## PARAMETER(); }
	int is ## PARAMETER() { return launcher.is ## PARAMETER(); }
}

For example, to generate the setVideoApp() and getVideoApp() functions, the following is specified:

Source code (UnigineScript)
launcher_parameter<VideoApp,string>;
This will generate the following code:
Source code (UnigineScript)
void setVideoApp(string value) { launcher.setVideoApp(string(value)); }
string getVideoApp() { return launcher.getVideoApp(); }
Last update: 2017-07-03