iOS Application Development

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

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.

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

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.

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

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>
    

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.