Bringing your WME Lite game to iPhone [WME Resource Center]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Bringing your WME Lite game to iPhone ======

The iOS (iPhone, iPad, iPod Touch) development is under rather tight control of Apple, so the entering point is a little bit higher than what you might be used to from the PC world.



===== Prerequisites =====

To develop for iOS you need:

  * a computer running Mac OS X Snow Leopard
  * XCode development environment (WME Lite is tested with XCode version 3, there is a new version 4 available, but it's untested) [[http://developer.apple.com/devcenter/download.action?path=/Developer_Tools/xcode_3.2.6_and_ios_sdk_4.3__final/xcode_3.2.6_and_ios_sdk_4.3.dmg|download]]
  * iOS SDK (part of the XCode installation)
 
With the above items you will be able to build iOS application and run them inside the iOS Simulator. However, to be able to upload the application to the actual device and to distribute the application (i.e. to upload to AppStore or to use ad hoc distribution) you will need to join the [[http://developer.apple.com/programs/ios/|iOS Developer Program]] ($99/year).

Once you joined the iOS Developer Program, you will be able to add your testing device as a development device and to distribute your game. You will find all the necessary information in [[http://developer.apple.com/devcenter/ios/index.action|iOS Developer Center]]. Essentially, by joining the developer program, you will be provided with a certificate, which allows you to digitally sign the application. Only signed applications can be uploaded to devices and redistributed.


===== Compiling the game =====

I wish there was an easier way, but currently the process isn't automated. Basically you need to:

  * obtain WME Lite sources
  * add your game package(s)
  * compile the game in XCode

The third step will take care of digitally signing the game and uploading it to the device or to the iPhone simulator.
The process is described in the following article: [[building]]


===== iOS notes =====

==== Multitasking and auto-save ====

Since version 4, iOS supports multitasking and applications can choose whether they want or don't want to support it. WME Lite deliberately doesn't support multitasking. The reason is, that the underlaying SDL graphics library currently doesn't cope well with returning to a running application. It means, that when the user presses the Home button, the WME Lite game is terminated. However, before being terminated, it's possible to instruct WME Lite to save the current game. That way the player can resume playing when they start the game again.

The iOS version of WME Lite provides two scripting properties that control this behavior:

**Game.AutoSaveOnExit** - specifies whether the game should auto-save when the user presses the Home button. It's enabled by default.
**Game.AutoSaveSlot** - specifies the saved game slot used for auto-save. The default value is 999.

Using these properties you can instruct WME Lite to auto-save on exist to a specified slot. Then you can allow the player to resume a quick-saved game. For example, in your main menu check whether the slot 999 is used, and if it is, display a button called "Resume game", which will simply load the game from slot 999.

Please note that the game is NOT auto-saved if there is a system-exclusive window displayed.


==== Touch input ====

If you are porting an existing game to iOS, you will most likely need to modify the user interface for touch input. Basically it means your game will only receive the LeftClick, LeftRelease and LeftDoubleClick events. There's no right-click, no mouse wheel, no keyboard input, so plan your interface accordingly. Make sure all hotspots in the game are large enough to be "touchable".

Since the mouse pointer does not make sense for most touch-controlled games, WME Lite provides a new scripting property called **Game.HiddenCursor**, which will automatically hide the mouse pointer when set to **true**.


==== TrueType fonts ====

As noted in the [[fonts]] chapter, if your game uses TrueType fonts, you must distribute all the fonts with the game. WME Lite is not able to use preinstalled system fonts in iOS.


==== Resolution ====

WME Lite always uses the largest resolution of a given device and scales all graphics. If the aspect ratio differs, the image is letterboxed. The game runs always in landscape mode and screen rotating currently isn't supported.
The original iOS devices use resolution 480x320. The new "retina" displays used in iPhone 4 and iPod Touch 4 use double resolution, 960x640. iPad and iPad 2 use resolution 1024x768.


==== Performance considerations ====

The iOS devices have limited memory. There is no "virtual memory" like in desktop operating systems. If your game depletes all available memory, it will be terminated by iOS. For that reason avoid huge animations with many frames. If your sprites contain empty space, cut the image to the necessary minimum. If you temporarily load some game objects (actors, entities, windows), unload them when they are no longer needed.
Keep in mind the disk access is very slow. Try to spread loading of the initial data. For example, when the game starts, you can first load and display some simple loading screen, then start loading larger data (such as the actor).

There are many different iOS devices by now, and their performance differs considerably. There is a huge gap between the original iPhone and the latest iPad2. Also note that the iPhone simulator doesn't represent the performance of a real device at all. Always test your game on real devices.


==== Limits ====

The maximum texture size is 1024x1024 pixels. If you use large images, you will need to cut them.

----

{{http://dead-code.org/misc/5ma_ipod.png}}