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

Windows Application Development

Step 1. Installation of SDK

1.1. Prepare Development Environment

Unigine SDK is not a full development environment and you need to install the required software before starting up:

  1. Install Microsoft Visual C++ 2008/2010 Express Edition (can be downloaded for free).
  2. Install Microsoft Windows SDK 6.1 (for WindowsXP), 7.1 (for Windows 7) to build a 64-bit application (can be downloaded for free).
  3. Install DirectX redistributive June 2010 (can be downloaded for free).
  4. Install Python 2.7 (can be downloaded for free).
  5. Install SCons 2.0+ (can be downloaded for free).

1.2. Install Unigine SDK

There are two ways to install SDK:

  • If you downloaded a Unigine SDK installer, simply run it and choose the components you want to install.
  • If you downloaded a Unigine ZIP archive:
    1. Unpack the Unigine archive into a target directory, for example C:\UnigineSDK.
    2. Run console as administrator (Start -> Search -> type cmd -> RMB on the icon -> Run as administrator)
    3. Go to the directory and run install.py script to set development environment. (If installation was successful, the uninstall.py script will appear).
      Shell commands
      C:\Windows\system32>c:
      
      C:\Windows\system32>cd c:\UnigineSDK
      
      c:\UnigineSDK>install.py
      
      [ Unigine SDK installation script ]
      
      Do you really want to proceed with install? [Y/N]: y
      
      Notice
      In fact, this script only sets environment variables, which are:
      • %UNIGINE_DIR% variable pointing to Unigine SDK location.
      • %WINSDK71_DIR% variable pointing to Windows SDK location.
      • %PYTHON_DIR% variable pointing to Python location.
      • Locations of the following directories are added to the %PATH% variable: %UNIGINE_DIR%\externs\bin; %UNIGINE_DIR%\lib; %UNIGINE_DIR%\bin and location of Python binaries (in the mentioned order).
    4. Reboot.

After installation you will get access to the Unigine SDK contents.

Step 2. (Optional) Rebuilding Unigine Engine or Its Components

Customization Options

Apart from developing your project with UnigineScript, you can also customize the Unigine application C++ code. What exactly is available for customization depends on the version of Unigine SDK:

  • With the limited binary/evaluation version you can only modify the following components:
    1. C++ plugins for the engine.
    2. The source code of Unigine-based sample applications.

    You can also modify the source code of Unigine Editor and high-level scripts (just like all other scripts, they do not require recompilation).

  • If you have the full source version, you can modify the entire Unigine codebase:
    1. The C++ source code of the engine itself.
    2. All Unigine standalone tools.
    3. C++ plugins for the engine.
    4. Plugins for 3D editors.
    5. The source code of Unigine-based sample applications.

After customizing the code, recompilation of Unigine application or its libraries is required.

Notice
It is strongly not recommended to modify the engine source code directly, because you will need to merge your modifications each SDK update. Instead, it is better to use C++ API (including C++ plugin system) designed specifically for extending basic Unigine functionality.

2.1. Rebuild the Unigine-Powered Application

To recompile both the Unigine engine (i.e. the dynamic library Unigine_*.dll) and application on its base (i.e. the binary executable main_*.exe), you can use one of the following options. For Windows, 32-bit or 64-bit, debug or release, single or double coordinates precision versions can be compiled.

  • For semi-automated compilation via the Build script (recommended):
    1. Open a Windows command-line console (Start -> Run -> cmd) or any console file manager (e.g. FAR).
    2. Go to %UNIGINE_DIR%\utils\ folder.
    3. Run the build.py.
      Shell commands
      C:\Windows\system32>c:
      C:\Windows\system32>cd c:\UnigineSDK\utils\
      C:\UnigineSDK\utils>build.py
      By default, a Unigine library, a binary executable and a network plugin (release single-precision versions) will be built for the native platform.
      You can change building options, if required. For example, to build the 32-bit double-precision version of the engine and all standalone tools, run the script with the following options:
      Shell commands
      C:\UnigineSDK\utils>build.py --component=all --type=debug --bits=32 --precision=double
  • For manual compilation via SCons (see the details):
    1. Open a Windows command-line console.
    2. Go to %UNIGINE_DIR%\source\app\main directory.
    3. Type scons (or scons with the cross=x64 option for a 64-bit build) and press ENTER.
      Shell commands
      C:\Windows\system32>c:
      C:\Windows\system32>cd C:\UnigineSDK\source\app\main
      C:\UnigineSDK\source\app\main>scons
      By default, the debug, single-precision version of Unigine library and the binary executable will be built for the native platform.
      Notice
      After compiling for the first time, SCons automatically checks whether any modifications were made to the source engine code and recompiles the library only if necessary.
  • For compilation via MS Visual Studio:
    1. To rebuild the engine libraries, open the project file for Visual Studio %UNIGINE_DIR%\source\engine\unigine_vc2008.vcproj or %UNIGINE_DIR%\source\engine\unigine_vc2010.vcxproj (depending on your Visual Studio version).
    2. Choose Debug -> Build Solution in the menu.
    3. To rebuild the binary executable, open %UNIGINE_DIR%\source\app\main\main_vc2008.vcproj or %UNIGINE_DIR%\source\app\main\main_vc2010.vcxproj (depending on your Visual Studio version).
    4. Choose Debug -> Build Solution in the menu.

To run the built Unigine application, you need to specify compulsory start-up options (see details below).

2.2. Rebuild Engine Plugins

To rebuild engine C++ plugins, perform one of the following:

  • To rebuild a plugin automatically together with the engine, use the Build script. For example, to reduild the Network plugin use the following:
    Shell commands
    C:\UnigineSDK\utils>build.py --component=engine --plugin=Network --type=release --bits=32 
    							
  • To rebuild a plugin manually, use SCons:
    1. Go to the required directory inside <UnigineSDK>\source\plugins\ via the command line.
    2. Type scons (or scons with the cross=x64 option for a 64-bit build) and press ENTER.

    For example, to rebuild the Network plugin manually, perform the following:

    1. Go to <UnigineSDK>\source\plugins\Network directory via the command line.
    2. Type scons and press ENTER to build with SCons (see the details on available Network options).
      Notice
      To be run, the Network plugin requires setting -extern_plugin Network at the start-up (see details below).

2.3. Rebuild Tools

To recompile the Unigine standalone tools (ResourceEditor, ImageDDS, Archiver, XmlTree, etc.), do one of the following:

  • For semi-automatic compilation, use the Build script (recommended).
    Shell commands
    C:\UnigineSDK\utils>build.py --component=tools --type=release --bits=32
  • For manual compilation via SCons (see the details):
    1. Go to one of the directories inside %UNIGINE_DIR%\source\tools\.
    2. Type scons (or scons with the cross=x64 option for a 64-bit build) and press ENTER to build the application (the binary executable).

2.4. Rebuild Plugins for 3D Editors

To rebuild plugins for 3D graphics packages (3ds Max, Maya or Softimage), perform one of the following:

  • To rebuild plugins by using build scripts:
    1. Go to the required directory inside %UNIGINE_DIR%\source\tools\plugins\.
    2. Run one of the build_*.bat file (e.g. run build_x64.bat for a 64-bit build).
  • To rebuild plugins via Nmake:
    1. Go to one of the directories inside %UNIGINE_DIR%\source\tools\plugins\.
    2. Use any of the following compilation options:
      • Nmake (from Visual Studio) using Makefile.win32 file
      • MS Visual Studio using *.sln file (if any)
      • GNU Make using Makefile file (if any)

2.5. Rebuild Task-Specific Applications

Some specific functionality is not supported by the main Unigine application. For that, you need to recompile separate binary executables.

To rebuild the task-specific application, perform the following:

  • Go to the required application directory <UnigineSDK>\source\plugins\app\ via the command line.
  • Type scons (or scons with the cross=x64 option for a 64-bit build) and press ENTER to build the application.
Notice
To be run, the application requires settings at the startup (see details below).

For example, to recompile AppWall application (appwall_*) for several monitors (up to 6):

  1. Go to <UnigineSDK>\source\plugins\app\AppWall directory via the command line.
  2. Type scons (or scons with the cross=x64 option for a 64-bit build) and press ENTER.
Notice
See more details how to launch AppWall application and set up the custom number of windows.

2.6. Rebuild Sample Applications

Into Unigine SDK there are included sample applications that can be modified and used as templates to create your own applications.

  • To rebuild D3D9AppMFC application that creates an MFC-based application and renders Unigine viewport into it in DirectX 9 mode:
    • Go to %UNIGINE_DIR%\source\samples\App\D3D9AppMFC directory.
    • Build with MS Visual Studio using *.sln or *.vcproj file.
  • To rebuild GLAppSDL application that creates an SDL-based application and renders Unigine viewport into it in OpenGL mode:
    • Go to %UNIGINE_DIR%\source\samples\App\GLAppSDL directory.
    • Build with MS Visual Studio using *.sln or *.vcproj file.
  • To rebuild the GLAppQt application that renders Unigine viewport into the Qt window in OpenGL mode, the D3D9AppQt (DirectX 9) application and D3D11AppQt (DirectX 11) application:
    • Go to the required directory inside %UNIGINE_DIR%\source\samples\App\ (GLAppQt, D3D9AppQt or D3D11AppQt).
    • Run qmake tool by typing qmake.
    • Run Nmake tool by typing make_x86 (or make_x64 for a 64-bit build) Makefile.win32.

Step 3. Building Your Application

To build your application you can use the binaries provided in Unigine SDK or recompiled ones. Your Windows application can be of the following types, which will be indicated by a postfix of the used binary executable (and Unigine library as well):

  • 32-bit application (an executable with _x86 postfix)
  • 64-bit application (an executable with _x64 postfix)
  • Development (debug) version (d postfix)
  • Production (release) version (no specific postfix)
  • Single precision coordinates version (default Unigine libraries)
  • Double precision coordinates version

If you are new to Unigine, see also Adding scripts to the project tutorial. It covers the very basics how to start coding your scripts in UnigineScript (no compilation required).

3.1. Build App Development Version

While Unigine scripts do not require recompilation, you may want to recompile the startup C++ code for your project that initializes the application runtime:

  1. Go to %UNIGINE_DIR%\source\app\main directory.
  2. Customize main.cpp, if necessary.
  3. Build your application using one of the following options:
    • MS Visual Studio:
      1. Open a project file for Visual Studio: %UNIGINE_DIR%\source\app\main\main_vc2008.vcproj or %UNIGINE_DIR%\source\app\main\main_vc2010.vcxproj (depending on your Visual Studio version).
      2. Choose Debug -> Build Solution in the menu. Select Debug mode for compilation.
    • SCons (see the details). SCons automatically checks whether any modifications were made and recompiles the application together with the engine only if necessary.
      Shell commands
      C:\UnigineSDK\source\app\main>scons

3.2. Build App Production Version

Building the final release version of your application includes several additional steps, if compared to a development version. Here is the typical workflow:

  1. Copy the development version of your project into a separate folder.
  2. Prepare the final content to be used:
    1. To prevent the users from accessing the console, disable it by setting engine.console.setLock(1).
    2. Prepare the release version of configuration file.
    3. Compress all textures using ImageDDS tool.
    4. Delete all uncompressed textures.
    5. Delete VCS files.
    6. Compress XML files into a binary format using XmlTree tool. Binary format is more compact and is parsed faster.
    7. If necessary, pack your resources into ZIP or UNG using Archiver tool.

      Notice
      Archived resources can also be streamed. But it is strongly not recommended to archive terrain files, otherwise it will load with lags.
  3. If necessary, cache the source code written in UnigineScript.
  4. If necessary, rebuild the release version of Unigine engine (the binary executable together with dynamic library). You can skip this step if you did not modify the engine source code. Instead, use pre-compiled engine files included in the SDK. (Find them under %UNIGINE_DIR%\bin and %UNIGINE_DIR%\lib folders).
  5. If necessary, use a launcher for your application. In case your project was created via the project generator in the SDK browser (New Project tab), you can use the generated launcher. Otherwise you can create your own launcher on basis of our realization. If there is no launcher, all application data is simply stored in the configuration file. In this case, you can specify the following information in the application startup script (e.g. batch file):
    • The binary executable to be used
    • Configuration file (with application screen resolution and other project settings) to be used
    • Path to the custom system script unigine.cpp (see the details)
    • Project to be loaded (name of the world)
    • Path to the Unigine default data (with all required shaders, default materials, properties, Unigine Editor scripts, etc.)
  6. If necessary, make an installer that will install your application together with all dependencies.

Step 4. Deploying Your Application

After building and assembling your application, it is ready to run.

  • If it is a development version, you need to create a launcher for you application.
    1. Before running <UnigineSDK>\bin\main binary executable, you need to specify start-up settings: what rendering and sound API to use, size of the window created for the Unigine-based application, etc.
    2. After that, you can test it on your local development machine, edit the project code and see results on-the-fly, modify any resources, and continue testing. Debugging on other Windows machine is a matter of simple "copy and run" process: just copy the compiled binary code and the folder with resources to a new location.
  • If it is the release version, then you are all set to release your application into production.

Launching App with Specific Functionality

If you are going to launch applications with extended functionality (i.e. use engine plugins or launch task-specific Unigine app), you will need to specify additional command-line options on engine start-up.

How to Use C++ Plugins

To use C++ plugins after building them, you need to specify extern_plugin command line argument on the start-up. (The path is specified relative to the binary executable).

Shell commands
-extern_plugin plugin_name
For example, for the Network plugin it can be -extern_plugin ..\source\plugins\Network that is relative to the bin folder.
If you copy Network_x86.dll into the bin folder, you can simply type -extern_plugin Network.

How to Run Stereo Apps

To use stereo applications after building them (separate_* or 3dvision_*) that cannot be rebuilt due to proprietary libraries distribution limitations), you need to specify the stereo mode to be rendered via setting extern_define command line argument on the start-up. See the list of available stereo options.

Step 5. (Optional) Uninstallation of Unigine SDK

If you want to uninstall Unigine SDK, do one the following:

  • If you used a Unigine SDK installer, uninstall it as a regular application via Control Panel -> Programs and Features or simply run <UnigineSDK>/unins000.exe
  • If you unpacked Unigine from a ZIP file:
    1. Run the %UNIGINE_DIR%\uninstall.py script from command shell with Administrator permissions (see above).
    2. Delete the Unigine working directory.
    3. Reboot.
Last update: 2017-07-03