iTGB Cheat Sheet (updated 2-25)

Here's a list of handy things to remember when developing with iTGB
Update(02-11): Added links to code additions at the bottom
Update(02-14): Added important safety tip for multiTouch
Update(02-25): Added important safety tip for PUAP_SCRIPT_CHANGE


Preprocessor commands

PUAP_OPTIMIZE enables the following iPhone optimizations;
t2dSceneObjects now have a setUsesPhysics(bool) function that allows them to use physics or not. All object are false by default, which helps to reduce wasting time processing physics on non-moving objects

also affected:
t2dParticleEffects will stop playing when their world limit is off-screen
t2dSceneObject mCollisionMaxIterations is set to 1 by default


PUAP_SCRIPT_CHANGE activates a few changes to the scripting engine. The big benefit of this is that script execution is much quicker, in particular, variable lookup is faster than without it. When this is defined, iTGB will change the way it reads/compiles scripts, this means that DSOs will be incompatible with previous versions, and old DSOs will be incompatible with iTGB. Because of this, it's best to use scripts that have been compiled with the same binary to ensure compatibility.
Important SafeTy Tip With this flag set, you must initialize your variables or you may get some bogus values. i.e. use this:

function countTo( %input ) {
   %count = "";//or %count == 0;
   while( %count < %input  {
      echo( "current count:" SPC %count );
      %count++;
   }
}

instead of this:

function countTo( %input ) {
   while( %count < %input  {
      echo( "current count:" SPC %count );
      %count++;
   }
}

USE_COMPONENTS adds some functionality to the TGB components system that allow them to receive onUpdate() and onAddToScene() callbacks, like the script behaviors do.

With this undefined, components still work, but will not receive those callbacks, this define is there to improve script->code conversion.





iPhone-specific features

MultiTouch
The first touch is always mapped to the mouse/cursor. If your game does not use multi-touch(example: a port of a PC mouse-driven point 'n click), you wan't have to implement any touch callbacks.
When multiTouch is enabled(using a global variable), touches are handled by script callbacks.

Important Safety Tip: Don't forget to set
$pref::iPhone::enableMultipleTouch = true;
in defaultPrefs.cs


All touches (including the first one) are passed to three functions

oniPhoneTouchUp( %touchCount, %touchX, %touchY )
oniPhoneTouchDown( %touchCount, %touchX, %touchY )
oniPhoneTouchMove( %touchCount, %touchX, %touchY )

The parameters for each function work the same.
%touchCount is the number of touches for this event, %touchX is a list of the touchs X value, %touchy is a list of the touches Y value. Example:

getWord( %touchX, %touchCount );

will give you the X value for the last touch.


Accelerometer
The accelerometer is mapped to joystick0 three axises (xaxis, yaxis and zaxis) and can be mapped as you would a joystick in TGB. Example:

moveMap.bind(joystick0, xaxis, "joystickMoveX" );
      moveMap.bind(joystick0, yaxis, "joystickMoveY" );
      moveMap.bind(joystick0, Zaxis, "joystickMoveZ" );

UPDATE 1-23-09
By default, iTGB will disable all text output to speed things up, to turn that off for debugging, call this function:

enableDebugOutput( true );

This will output all the console text to your XCode GBD output pane. In other words, everything that yo would normally see in the Torsion output and the console.log will be visible through XCode


Images
iTGB supports PVR images. To create a PVR texture from a PNG or another filetype use the

PVR tool. PVRs must be square and power of 2 (e.g. 512x512 pixels). iTGB will look for PVR images first, so, when specifying an image (such as the "bitmap" parameter in a GUI), leave out the extension of the file and iTGB will find the image for you, looking for PVRs first.



$Global Variables

iTGB will force all palleted BMPs to 16 bit if you specify

$pref::iPhone::ForcePalletedBMPsTo16Bit = true

this can save on video memory if you need it.

iTGB will shutdown the network, allowing the game to run faster by not running unused Net code if
$pref::iPhone::UsesNetwork = false in defaultpref.cs


The following need to be set in DefaultPrefs.cs for their changes to load when iTGB does:
$pref::iPhone::StatusBarType ("BlackTransparent"/"BlackOpaque")
$pref::iPhone::StatusBarHidden (true/false)
$pref::iPhone::ScreenOrientation ("Portrait"/"Landscape")
$pref::iPhone::ScreenAutoRotate (true/false)
$pref::iPhone::EnableMultipleTouch (true/false)


General Things To Know
iTGB on Simulator or device will only read DSOs, you don't even need to have the .cs files present on the device. Make sure your scripts are compiled before trying to run.

In order to transfer you game content to you app bundle, you need to include the following in your Xcode project's "Resources" folder;

common folder
game folder
Any other mod folders you are using
main.cs
default.png


Common and game should contain your script DSOs, main.cs is the only file that need not be compiled(main.cs.dso is not loaded, only the cs file)

default.png is the image the iPhone will display while your app(iTGB) is starting up

When you add these items to the XCode project, make sure to select the second option for adding folders(recursively add folders) The icons will be blue in the XCode sideBar if you added them correctly.

XCode will not automatically transfer your changed files if you modfiy them. The best way to make sure that it does is to delete the the .app in your XCode project's build directory, then build. This will not re-compile your project, but it will force XCode to copy all of your resources over.

UPDATE 02-11-09
Code additions from forum members

For those having a problem with iTGB crashing when the home button is pressed: Quit Fix

How to get a Unique identifier for a device in script(Credit to Dave Young) Device ID ConsoleFunction

How to get device real-world location(Credit to Dave Young) Device Location

An implementation of the iPhone keyboard: Keyboard


Updates will come when I think of them. :p