iPhone

This documentation explains how to build for iPhone target with the ShiVa Authoring Tool.

Note that the iPhone build is only available on Mac OSX Snow Leopard.

Prerequisites

There is few things to do before being able to compile and upload your application for iPhone:

• Install XCode
• Install iOS SDK

Please refer to ShiVa Authoring Tool Installation (in section “Required Third Party Tools for iPhone/iPad”) for more details.

Step 1 : Content

Application pack

A game in ShiVa Editor is made of various files : 2d media, 3d media, audio and scripts.

You must export all these files into a unique .stk file. For that, in the Game Editor Module in ShiVa Editor, select option to export the game as a run-time package. ShiVa Editor will produce a single .stk file. Select this file in the Application Pack field.

Restriction : file name must contain only alphanumeric characters (dot, column, dash or weird characters are not allowed).

Icon

This icon will appear in the Home screen and launcher (as a direct link to your game).

Format : the icon must be a png file 114x114px.
Guidelines : you must follow the iPhone Icon design guidelines described here : http://developer.apple.com/iphone/library/documentation/UserExperience/Conceptual/MobileHIG/IconsImages/IconsImages.html

Startup splash-screen

The splashscreen is the first image displayed on the device, before the 3d content.

Format : the image must be a png file 640x960px, even for a landscape image.

Startup movie

This movie is played right after the splashscreen with all the common UI.

Format : the best way to create a compatible video is to import the original one in iTunes, select it, go to Advanced>Create iPod or iPhone version, then drag’n’drop it from iTunes to the desktop.

Preview

This is the preview area for the splash-screen and icon.

Native Code

ShiVa Editor 1.9 allows you to code some parts of your application in C++ or convert all your lua code into readable C++.
To use this feature, when exporting the game in Shiva Editor, check option “Runtime package ( stk and cpp source )” as shown in picture below.

Shiva Editor will generate a .stk package (that does not contain any lua code) and a folder containing your lua code converted into C++. You must add these C++ files manually in the Content panel so that the Authoring Tool builds them as part of your application.

Using native code feature gives you a chance to modify the generated C++ files before adding them in the panel. This has two main purposes:

• Modify the generated C++ files to improve the performances.
• Modify the generated C++ files to make them invoke some APIs located in external C++ files. For that, you need to add your external C++ files in the panel together with the modified generated C++ files. This may be usefull to call a complex C++ algorithm that requires performances or to invoke a system library. Please note that the only way to invoke external C++ APIs is to invoke them from the generated C++ files (because Shiva Engine is not aware of their existance).

Note: every time you export the game from Shiva Editor, the C++ files are generated again. That may overwrite the changes you made to these files.

Additional files

Additional application data files (for instance a xml data file, or a movie file).
Use the application.getPackDirectory function to get the absolute path of the files and load them while application is running.

Step 2 : Authoring

Warning: as step 2 and step 3 are optional, Authoring tool does not display the 'Next' button to reach them. Instead, to reach 'Step 2' and 'Step 3' panels please click the panel name on top of Authoring Tool window.

Authoring type

Authoring type is the type of the generated application as follows:

• Application : generates an application to push directly on the AppStore. Generates a single .app file that you can upload on the Store or push on your iPhone. For more details pleaser go to https://itunesconnect.apple.com/WebObjects/iTunesConnect.woa.
• Project : generates a complete Xcode project, ready to be compiled. With such project, you can extend the engine functionalities or embed the engine in your application.
  Important : The simulator mode is not yet supported when building an Xcode project, so be sure to build a development or distribution solution in the Authoring Tool, and to be in device mode not simulator mode in Xcode.
  Note that this option replaces the old SDK.
  You may want to take a look at the tutorial : Implementing the mail client for iPhone
  

Signing

Provision profile
Select the right profile in the dropdown list, the profiles can be managed on the Apple developer website : http://developer.apple.com/iphone/manage/provisioningprofiles/ and must be saved in the “Library/MobileDevice/Provisionning Profiles” folder.

Bundle identifier
Auto-filled when choosing a profile, this is a unique identifier used to generate the project, usually com.yourname.yourapplicationame.

Signing identity
Your organization name available in your Keychain when a certificate is installed.

Versioning

Version
Application version : of the form x.x.x. This is the version shown to end users.

Icon highlight

Enable the gloss mask on your icon

Without

With

Step 3 : Build

Warning: as step 2 and step 3 are optional, Authoring tool does not display the 'Next' button to reach them. Instead, to reach 'Step 2' and 'Step 3' panels please click the panel name on top of Authoring Tool window.

Build type

One of the following options:

• Simulator : generates an application to load on the iPhone simulator.
• Development : generates an application with a development provisioning profile ready to load on your development devices.
  Do not build as development if you intend to publish on the appStore.
• Distribution : generates an application using a distribution provisioning profile ready to upload on the appStore.
  To upload an application on the appStore go here : https://itunesconnect.apple.com/WebObjects/iTunesConnect.woa.

View Options

Content scale factor
Between 1.0 and 2.0. Controls the resolution.
The maximum resolution is limited to the resolution of the target device.

Exemple: on an iPhone4, if set to 2.0, the resolution will be 960x640, 2.0*(320x480).

Antialiasing samples
Enable anti-aliasing, value can be 0, 2 or 4 samples. 4 requires higher performances.
This function is available since the iPhone 3GS running at least iOS 4.

Use OpenGLES 1.1
Force the engine to be in OpenGLES 1.1. This ensures good performances but less quality as it disables all the “nextgen” effects like normal maps, bloom...

Force exit on suspend
Since the OS4, the application is no longer killed when the home button is pressed, this to enable the multitask. Check this option to force exit.

Display status bar
If checked, the status bar is displayed while your application is loaded.
Note that the status bar is displayed as an overlay under the engine.

Status bar style
Desired style for the status bar : Gray Opaque, Black Opaque, Black transparent as follows:


Movie Player supported orientations
Restrict possible movie player orientation to be portrait/landscape only.

Output folder

Folder where to save generated application.

Custom post build script

To execute some commands right after the build, create a .bat file with the commands and copy it in the script folder “Stonetrip\ShiVa Authoring Tool\Data\YourOS\iPhone\Scripts”. This file will be available in the dropdown list once Authoring Tool has been restarted.