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

iOS Application Development

With Unigine you can take advantage of native iOS functionality out of the box. Unigine offers multi-touch screen support, as well as automatic switching between portrait and landscape orientations that will give your application the native look and feel. (See details how to enable support of mobile controls for your application). Besides it, Unigine also supports ARM NEON instruction set that allows powerful hardware acceleration and impressive performance gains (2-10x performance boost) for iOS applications.

Notice
To run Unigine sample applications, a bundle application that is signed with your development certificate (*.ipa) should be created first.
Go to the directory with sample application (<UnigineSDK>/builds/*/*.app) and run iospack from the terminal.

Requirements

  • You must have an Intel-based Mac running Mac OS X to develop iOS applications for iPad, iPad 2, iPhone 3GS and iPhone 4. The target device should support OpenGL ES 2.0.
  • In order to get development tools, you need to sign up for the iOS Developer program by visiting http://developer.apple.com/programs/ios.
  • To test and deploy iOS application on the real device, it should be signed with a development certificate. (See the official iOS development guide for more details).
    Notice
    As a registered iOS developer you will be able to develop and run applications in the Simulator only. To build applications that can be run on a actual device you need to enroll in the iOS Developer program.

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 Xcode 5.0.
  2. Install SCons 2.0 (can be downloaded for free or installed via MacPorts).
  3. Install Python 2.7 (can be downloaded for free).

1.2. Install Unigine SDK

Unigine SDK for iOS requires a full SDK version to be already installed since it contains only iOS-specific files without the engine itself. You need to unpack the Unigine archive and add all files (preserving folder structure) to the full SDK.
After that, you will have all files required to build Unigine engine for iOS platform. Additionally, there are included sample applications that can be used as a template to create your own bundle application.

Step 2. (Optional) Rebuilding Unigine Engine

If you need to add some extended functionality to be used in your project, or to change the engine start-up window, you will need to rebuild the Unigine-based application together with the engine itself.

2.1. Rebuild Unigine-Powered Application

If you have the full source code version of Unigine SDK, you can recompile the Unigine engine (i.e. static libraries for iOS) and application on its base (i.e. the binary executable main) using SCons.

  1. To open the command-line terminal, run Applications -> Utilities -> Terminal application.
  2. Go to the ~/<UnigineSDK>/source/app/iOS folder.
  3. Type scons_ios and press ENTER. By default, the ARM-based development build for iOS devices will be created. (To create the release version, type scons_ios debug=0. See the details on available SCons compilations options).
Shell commands
mac-name:~ username$ cd ~/UnigineSDK/source/app/iOS/
mac-name:iOS username$ scons_ios

By compilation main binary executable file is created with libraries already statically linked into it.

2.2. Rebuild Unigine-Powered Application for Simulator

To create a build that can be run in iOS Simulator, type scons platform=ios cross=x86.

Notice
Using a simulator is not recommended, as the rendering rate in it is extremely low and does not reflect the actual performance on the real Apple hardware. It can be used only to develop and test native iOS GUI.

Step 3. Building Your Application

To build your application you can use the binaries provided in Unigine SDK or recompiled ones. Your iOS application can be of the following types, which is indicated by a postfix of the binary executable:

  • Arm-based version of application
  • 32-bit application for iOS Simulator
  • Development (debug) version (_d postfix)
  • Production (release) version (no specific postfix)

If you are new to Unigine-based mobile application development, see guidelines how to set up and optimize your project for a mobile device. Create and set up your project for rendering on mobile devices on your desktop development machine (see details):

Another useful feature of Unigine applications (development versions only) is connecting to the device via Telnet protocol. The TCP port is 8888. You can remotely control the application running on a target device by passing console commands, for example, using PuTTY or any other Telnet client. To close the session, use logout command.

3.1. Build App Development Version

You can use sample iOS applications (found in ~/<UnigineSDK>/builds folder) as a template to create your own application.

  1. (Optional) If you have customized the engine startup code (<UnigineSDK>/source/app/main.mm), rebuild the Unigine-based application as described above.
  2. Copy a sample application (for example, <UnigineSDK>/builds/Crypt) with scripts and ios folder inside. To create your own iOS application, you need to modify this template.
    For a start, rename the copied folder, for example, to <UnigineSDK>/builds/MyApp.
  3. Go to the created folder and customize data_ios.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_ios.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_ios.sh ../../data/core data
    
    # Step 2. Compress and pack your project data into my_project.zip archive:
    # 2.1. Path to data_ios.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_ios.sh ../../data/my_project data
    fi
    
  4. Run data_ios.sh script:
    Shell commands
    mac-name:~ username$ cd ~/UnigineSDK/builds/MyApp/
    mac-name:MyApp username$ data_ios.sh
    
    This script performs the following:
    1. Copies Unigine core data (only such data which is necessary for mobile version) 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.
      • Images stored in uncompressed folder are compressed into PVR4 format.
      • Creates ZIP archive named after the project resources directory.
    If any, svn directories (used by the version control system) are automatically excluded by this script.

    Set the following flag when running data_ios.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_ios.sh -c
    
  5. (Optional step). If you you are building your app on a remote development machine (via SSH), run ioslogin script in order for your pack to be properly signed. If not, skip this step.
    Shell commands
    mac-name:MyApp username$ ioslogin
    
  6. Add an icon for your bundle application into MyApp/ios folder.
  7. Copy a configuration file that will be used by your application into MyApp/ios folder.
  8. Customize an information property list file ios/Info.plist. You need to modify the following key values (see the keys description in the official iOS guide). Other values can be left unchanged unless otherwise required.
    Source code (XML)
    <plist version="1.0">
    	<dict>
    		<!--Application bundle name displayed underneath the application icon.-->
    		<key>CFBundleDisplayName</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>CFBundleIconFiles</key>
    		<array>
    			<string>app_icon.png</string>
    		</array>
    		<!--The name of the Unigine main executable file. Leave this value unchanged.-->
    		<key>CFBundleExecutable</key>
    		<string>main</string>
    		...
    		</dict>
    </plist>
    
  9. Customize the ios.sh script.
    Shell commands
    #!/bin/sh
    
    # Source folder where main binary, information property list file, icon and configuration file
    # are stored by default.
    SOURCE=./ios
    # Step 1. Modify the application bundle name:
    TARGET=./MyApp.app
    
    # Step 2 (Optional). If you have customized main.mm and rebuilt Unigine engine, you can use
    # the recompiled binary to create your bundle. The path to the recompiled binary:
    if [ "$1" = "-b" ]; then
    	cp ../../source/app/iOS/main $SOURCE
    fi
    
    ...
    
    # Resources that are used to create a bundle and stored in the source folder:
    cp $SOURCE/Info.plist $TARGET
    cp $SOURCE/main $TARGET
    cp $SOURCE/unigine.cfg $TARGET
    # Step 3. Modify icon name (take notice that the same icon should be specified in Info.plist):
    cp $SOURCE/app_icon.png $TARGET
    cp -r ./data $TARGET
    
    ...
    
  10. Run ios.sh script.
    Shell commands
    mac-name:MyApp username$ ios.sh
    
    • If you have customized main.mm or the engine source code and rebuilt the Unigine engine, you can use the recompiled binary when creating your bundle. In this case you need to specify -b flag:
      Shell commands
      mac-name:MyApp username$ ios.sh -b
      
      This script does the following:
      1. Signs both Unigine executable and the application bundle MyApp.app with your developer certificate.
      2. Archives the bundle into MyApp.ipa file.
      The archived bundle that contains all resources required to run your application is stored in MyApp/ios folder.
    • In order to skip archiving a bundle into .ipa, specify -np flag:
      Shell commands
      mac-name:MyApp username$ ios.sh -np
      
    Notice
    If you want to use analyzing tools from iOS SDK, you need to export App Identifier as environment variable before running ios.sh.
    Shell commands
    mac-name:~ username$ export IDENTIFIER=<app_identifier>
    

3.2. Build App Production Version

Building the release version of iOS application bundle is basically the same as building the development version.
Perform all steps as described above, but build the release version of the Unigine main binary.

Step 4. Deploying Your Application on a Mobile Device

After building and signing your application, it is ready to be deployed on a mobile device.

  • Plug in your device. The device should be provisioned for development (see the official iOS guide for more details).
  • Open Xcode Organizer -> Devices -> <YourDevice> -> Applications.
  • Drag and drop your application MyApp.ipa and wait until it is copied onto the Apple device.
  • Run your application directly on the mobile device.
Last update: 2017-07-03