iMarble

These are screenshots from a version before AdventureBall

These are screenshots from the final version of iMarble.

I have learned a lot bringing AdventureBall to market and I am now going to rewrite it with the intention of optimizing it, as well as cementing my knowledge of how it all works.  I have long wanted to give something back to the community that has helped me along the way, so I am going to publicize the rewriting of AdventureBall.  I have changed the name to iMarble to differentiate between the rewrite and the one that is currently in the app store.  I hope someone finds this of use or interest.  I am using SIO2 1.4.

Page Two

Part One: Rendering Your Scene

Part One Files

This step takes the template that comes with the SIO2 SDK, and adds code relevant for loading and rendering your scene.

Step 1:  Change the Base SDK

I am not sure if Rom has updated the download for iOS 4.0, but I used the template file that I already had downloaded.  If it says Base SDK Missing you need to change it to 4.0 or it wont build.  Under Project/ select Edit Project Settings.  On the Build pane under Architecture, change the value corresponding with Base SDK to iPhone Device 4.0 (or iPhone Simulator 4.0 if you are using that).  You may need to change a similar value in Project/Edit Active Target “iMarble.”

Step 2:  Change the Code Signing Identity

If you tried to build it for the device (but not for the simulator), it would now give an error saying the Code Signing Identity doesn’t match.  In the same menus as Step 1 you will find a section called Code Signing, and one of the values on the right will have Rom’s name in it.  If you have a code signing identity (talk to Apple) then you can replace the one Rom’s with yours.  If you don’t, then you must test in the simulator, and when I get to adding the accelerometers, you will have to find an alternate control scheme, as the simulator (for some reason) does not detect my laptop’s accelerometers.

Hooray, now if you Build&Go it should succeed and load to the device, displaying a black screen.

Step 3:  Renaming the Project

If you just built your project then you may have noticed that the app that was installed on your device is named template.  Under Project/ select Rename.  Now if you Build&Go it should create a new icon on your device named iMarble (or whatever you changed the name to).

Step 4:  Renaming Files

I went another step and renamed template.h and template.mm, to game.h and game.mm, to reflect what I will be using these files for.  After doing this you must change all the references to template in game.h, .mm, and EAGLView.mm.  Press Command – F to bring up the find menu.  Change Find to Find & Replace, then replace all references instances of the word “template” to the word “game” (or whatever you want to name the files) and all is well.

Step 5:  Create and Export Your Scene

In Blender (like in any of the tutorials) export a scene.  For my scene I deleted the default cube and light, but left the camera.  I then added a sphere at the origin (0,0,0) and exported.  Be sure that your whatever object you export has a material.  Then drag and drop the .sio2 file into your xcode project.

Step 6:  Adding the Necessary Code

Add this to game.h:

void gameLoading( void );

Your gameLoading should look like this:

Your gameRender should look like this:

Change line 129 of EAGLView.mm from gameRender, to gameLoading.

That should do it. If you Build&Go now it should load your object, and display it in the centre of the screen. If you vertex paint your object (as shown in most of the tutorials) you can see that it has dimension.

Part Two:  Adding Physics

This section adds physics to the equation, so the ball will roll around.

Part Two Files

Step 1:  Changes in Blender

First I added a plane, and moved it a little below the bottom of the sphere so the sphere would fall to the plane.  I also tilted it a little so the ball would roll off, and vertex painted it.  Next you need to add physics to the sphere and the plane.  Go to the Logic panel:

For the ball (pictured) turn on actor and set it to Rigid body, then turn on Bounds and set it to Sphere.  Do the same for the plane, but leave it set to Static instead of Rigid body, and set the bounds to Triangle Mesh.  Finally export your scene again.

Step 2:  Adding Code

In your code you need to set up gravity, turn it on, and evaluate it in your render loop.

Change your gameLoading to look like this:

Gravity must be set up before you bind your physics objects, and sio2PhysicPlay should come after.  Actually you can put sio2PhysicPlay and sio2PhysicPause wherever you want.  I am putting them here because I want physics to start as soon as I can see something on screen.  Later it will likely get moved for better control.

Next, add one line to gameRender as follows:

And that does it.  If you Build&Go your ball will fall to the plane and roll off the edge.  If you have vertex painted your sphere, you will see your design roll convincingly around it.  If you set your sphere to Dynamic instead of Rigid Body, it will slide across the plane without rolling.

Part Three:  Camera and Controls

I had originally used the sio2PhysicsSetGravity() command in my gameRender loop to adjust the gravity for the entire world and thus causing the only object in the scene to “fall” in whatever direction you tilt the iDevice.  Instead I decided to simulate this for the ball alone.  Then I added camera controls.

Part Three Files

Step 1:  Accelerometer Controls

I wish to use the accelerometer to control the ball.  I set it up so that when you lean the device on the X or Y axis (look at tutorial 5 to figure out which is which) it adds or subtracts from an X and Y variable, which is then set as the Sphere’s linear velocity.  If I controlled the linear velocity directly the ball would instantly change direction.  Controlling it like this causes it to slow as you tilt the device back, before moving in that direction.  I have then set these controls inside a conditional statement based on a collision callback between the sphere and the plane.

In gameLoading you must set up the collision callback:

Then add this before gameRendering:

And finally add this to gameScreenAccelerometer at the bottom:

(don’t forget to declare x and vel (as a vec2) at the top)

Step 2:  Camera Tracking

I have taken the camera from tutorial 9 and removed a couple lines of code so that I have an more of an orthographic like camera, which always stays on one side of the sphere looking down at it.  It still retains the object interaction so that if you roll behind a wall or something, the camera will move in front of it and you can still see.

Put this right after the line where you define SIO2object *_SIO2camera.

Step 3:  Blender

I went back into blender and replaced my tilted plane with a flat plane that is twice the size, so I can better test my controls, then re-exported.

Voila.  If you Build&Go your ball should stay in the middle of the screen as it rolls around the plane.  The controls are tricky, but if you lay your device flat (this must be tested on a device as the simulator doesn’t use accelerometers) the ball will stay still.  Slowly tilt your device in any direction to cause the ball to “fall” in that direction.

Part Three Point Five:  Unloading

I do a three point five because all I need to do now is be able to restart the level, instead of falling forever when you fall off the edge, and we are within reach of a proof of concept.  After this I will start a new page and detail my creation a few game assets we can use to complete a proof of concept.

Part Three Point Five Files

Step 1:  gameUnloading

Put the following above gameRendering.  I actually don’t know if it makes a difference what order all the different sections go in, but this is the way I have it organized, and it isn’t too confusing yet, so this is how I do it.  Don’t forget to declare this in game.h, or an error will tell you to.

Then add code in gameRendering to trigger the unloading:

Now when you fall off the edge, when your linear velocity in the -z direction is higher than 20 (or whatever you set it to) the game will unload then immediately go back to gameLoading, thus restarting your game.

~KeithK

Page Two