Mac OS X Application Development

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

1. Install Xcode version 5.0.
2. Install SCons 2.0+ (can be downloaded for free or installed via MacPorts).
3. Install Python 2.7 (can be installed via MacPorts).

To install Unigine SDK, you need to do the following:

1. Unpack the Unigine archive into a target directory, for example ~/UnigineSDK.
2. Run install.py script to set Unigine development environment. (If installation was successful, uninstall.py script will appear).
   Shell commands

   mac-name:~ username$ cd ~/UnigineSDK/
   mac-name:UnigineSDK username$ ./install.py
   
   [ Unigine SDK installation script ]
   
   Do you really want to proceed with install? [Y/N]: y
   

   Notice

   In fact, this script only changes the following environment variables:

   • Adds to $PATH variable locations of the following directories: <UnigineSDK>/externs/bin;<UnigineSDK>/lib;<UnigineSDK>/bin.
   • Adds to $DYLD_LIBRARY_PATH variable locations of the following directories: <UnigineSDK>/externs/bin; <UnigineSDK>/lib.
3. Re-login to make the changes in ~/.profile take effect.
   Notice

   Make sure that your terminal takes environment variables into account.
   From the Terminal main menu, choose Edit > Profile Preferences > Title and Command and check Run command as a login shell box.

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

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

     You can build plugins for 3D editors only on Windows.
  5. The source code of Unigine-based sample applications.

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

To recompile both the Unigine engine (i.e. the dynamic library libUnigine_*.dylib) and application on its base (i.e. the binary executable main), you can use one of the following options. For Mac OS X, 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. To open the command-line Terminal, run Applications -> Utilities -> Terminal application.
  2. Go to the ~/<UnigineSDK>/utils/ folder.
  3. Run the build.py.
     Shell commands

     mac-name:~ username$ cd ~/UnigineSDK/utils
     mac-name:utils username$ ./build.py
     

     By default, a 64-bit release version of 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

     mac-name:utils username$ ./build.py --component=all --type=debug --bits=32 --precision=double

• For manual compilation via SCons (see the details):
  1. Open the command-line Terminal.
  2. Go to <UnigineSDK>/source/app/main directory.
  3. Type scons (or scons with the cross=x86 option for a 32-bit build) and press ENTER.
     Shell commands

     mac-name:~ username$ cd ~/UnigineSDK/source/app/main
     mac-name:main username$ scons

     By default, the debug, single-precision 64-bit version of Unigine library and the binary executable will be built.
     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 Xcode:
  1. Run Xcode (version 5.0).
  2. Open the following projects and build them in turn by choosing Product -> Build in the menu:
     • <UnigineSDK>/source/engine/libUnigine_x64.xcodeproj to build the engine.
     • <UnigineSDK>/source/App/main/main_x64.xcodeproj to build the application.

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

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 use the following:
  Shell commands

  mac-name:~ username$ cd ~/UnigineSDK/utils
  mac-name:utils username$ ./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=x86 option for a 32-bit build) and press ENTER to build with SCons.

  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 (or scons with the cross=x86 option for a 32-bit build) 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).

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

  mac-name:~ username$ cd ~/UnigineSDK/utils
  mac-name:utils username$ ./build.py --component=tools --type=release --bits=32

• For manual compilation via SCons (see the details):
  1. Go to one of the directories inside <UnigineSDK>/source/tools/.
  2. Type scons (or scons with the cross=x86 option for a 32-bit build) and press ENTER to build the application (the binary executable).

Some specific functionality is not supported by the main Unigine application (for example, stereo rendering onto separate output devices, etc.) For that, you need to recompile separate binary executables.

To rebuild task-specific applications, perform one of the following:

• To rebuild, for example, an AppSurround application automatically by using the Build script, perform the following:
  Shell commands

  mac-name:~ username$ cd ~/UnigineSDK/utils
  mac-name:utils username$ ./build.py --component=engine --plugin=AppSurround --type=release --bits=32
  							

• To rebuild a task-specific application manually, use the following:
  1. Go to the required directory inside <UnigineSDK>/source/app/ via the command line.
  2. Type scons (or scons with the cross=x86 option for a 32-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 AppSurround application, perform the following:
  1. Go to <UnigineSDK>/source/app/AppSurround directory via the command line.
  2. Type scons (or scons with the cross=x86 option for a 32-bit build) and press ENTER to build the application.
  Notice

  See more details how to compile AppSurround with a custom number of monitors and set them up.

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

• To rebuild GLAppQt application that renders Unigine viewport into the Qt window in OpenGL mode:
  • Go to %UNIGINE_DIR%/source/samples/App/GLAppQt directory.
  • Run qmake tool by typing qmake.
  • Run make tool by typing make.

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 <UnigineSDK>/source/app/main directory.
2. Customize main.cpp, if necessary.
3. Compile the application via 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

   mac-name:~ username$ cd ~/UnigineSDK/source/app/main
   mac-name:main username$ scons

Also you can recompile the application via Xcode as follows:

1. Run Xcode (version 5.0).
2. Open the <UnigineSDK>/source/App/main/main_x64.xcodeproj project, cusomize it (if necessary) and build by choosing Product -> Build in the menu.

Building the final release version of your application includes several additional steps, if compared to a development version. It includes compressing resources and packaging your project into a bundle. You can use sample Mac OS applications (found in ~/<UnigineSDK>/builds folder) as a template to create your own application. Here is the typical workflow:

1. Prepare the final content to be used:
   1. Compress all textures using ImageDDS tool.
   2. To prevent the users from accessing the console, disable it by setting engine.console.setLock(1).
   3. Prepare the release version of configuration file.
2. Copy a sample application (for example, <UnigineSDK>/builds/Crypt) with scripts and macos folder inside. To create your own Mac OS application, you need to modify this template.
   For a start, rename the copied folder, for example, to <UnigineSDK>/builds/MyApp.
3. Customize data.sh script: modify the path (relative to the script directory) to the project resources (see item 2.2). Other paths can be left unchanged.
   Shell commands

   #!/bin/sh
   
   # Step 1. Pack Unigine core data (shaders, default textures, etc.) into core.ung archive:
   # 1.1. Path to core.sh script that will be executed
   # 1.2. Path to the Unigine core data
   # 1.3. Target folder inside your project directory to store packed core resources
   ../core.sh ../../data/core data
   
   # Step 2. Compress and pack your project data into my_project.zip archive:
   # 2.1. Path to data.sh script that will be executed
   # 2.2. Path to the project resources. The resulting ZIP file will be named after this directory.
   # 2.3. Target folder inside your project directory to store packed project resources
   if [ "$1" != "-c" ]; then
   	../data.sh ../../data/my_project data
   fi
   

4. Run data.sh script:
   Shell commands

   mac-name:~ username$ cd ~/UnigineSDK/builds/MyApp/
   mac-name:MyApp username$ data.sh
   

   This script performs the following:
   1. Copies Unigine core data into the specified folder, and packs it into core.ung archive.
   2. Copies and compresses all project resources:
      • Compresses XML files (world file, as well as materials, properties, nodes and UI files) into binary format that is more compact and is parsed faster.
      • Creates ZIP archive named after the project resources directory.
   If any, svn directories (used by the version control system) and uncompressed directories are automatically excluded by this script.

   Set the following flag when running data.sh script if you not want to compress your project resources (do not forget to compress them manually in this case!):

   Shell commands

   mac-name:MyApp username$ data.sh -c
   

   Notice

   Archived resources can also be streamed. But it is strongly not recommended to archive terrain files, otherwise it will load with lags.
5. Add an icon (*.icns) for your bundle application into MyApp/macos folder.
6. Customize a configuration file stored in the MyApp/macos folder.
7. Customize an information property list file macos/Info.plist. You need to modify the following key values (see the keys description in the official Mac OS guide).
   Source code (XML)

   <plist version="1.0">
   	<dict>
   		<!--Application bundle name displayed underneath the application icon.-->
   		<key>CFBundleName</key>
   		<string>MyApp</string>
   		<!--Application bundle identifier string that identifies your application to the system
   		It is specified in in reverse-DNS format.-->
   		<key>CFBundleIdentifier</key>
   		<string>com.Company.MyApp</string>
   		<!--Application bundle version.-->
   		<key>CFBundleVersion</key>
   		<string>0.01</string>
   		<!--Images used as application icons.-->
   		<key>CFBundleIconFile</key>
   		<string>app_icon.icns</string>
   		<!--The name of the Unigine main executable file. Leave this value unchanged.-->
   		<key>CFBundleExecutable</key>
   		<string>main</string>
   		</dict>
   </plist>
   

8. Customize macos.sh script.
   Shell commands

   #!/bin/sh
   
   # Source folder where main binary, information property list file, icon and configuration file
   # are stored by default
   SOURCE=./macos
   # Step 1. Modify the application bundle name:
   TARGET=./MyApp.app
   
   # Step 2 (Optional). If you have customized main.cpp and rebuilt Unigine engine, you can use
   # the recompiled binary to create your bundle. The path to the recompiled binary and library to use:
   if [ "$1" = "-b" ]; then
   	cp ../../../bin/main $SOURCE
   	cp ../../../lib/libUnigine_x64.dylib $SOURCE
   fi
   
   ...
   
   # Resources that are used to create a bundle and stored in the source folder:
   cp $SOURCE/Info.plist $TARGET/Contents/
   cp $SOURCE/main $TARGET/Contents/MacOS/
   cp $SOURCE/libUnigine_x64.dylib $TARGET/Contents/MacOS/
   cp $SOURCE/unigine.cfg $TARGET/Contents/MacOS/
   # Step 3. Modify icon name (take notice that the same icon should be specified in Info.plist):
   cp $SOURCE/app_icon.icns $TARGET/Contents/Resources/
   ...
   

9. Run macos.sh script.
   Shell commands

   mac-name:MyApp username$ macos.sh
   

   If you have customized the engine source code or main.cpp and rebuilt the Unigine engine, you can use the recompiled binary when creating your bundle. In this case you also need to specify -b flag:
   Shell commands

   mac-name:MyApp username$ macos.sh -b
   

   This script creates a bundled application that contains all resources required to run your application. By default, it is stored in MyApp/macos folder.

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

-extern_plugin plugin_name