Would you like to react to this message? Create an account in a few clicks or log in to continue.

Documenting the Great SIO2

Touch Ski
10 posters

Go down

Documenting the Great SIO2 Empty Documenting the Great SIO2

Post  Touch Ski Fri Apr 10, 2009 4:25 pm

Hey everyone,

I wanted to put together a post discussing my experience with SIO2. I spent the last couple months developing an iPhone app called "Touch Ski 3D" for the company "Naquatic" using SIO2. Prior to creating this game, I had no programming experience whatsoever; I had never used xcode and I had never used Blender. After months of nonstop experimentation and learning, I gained a solid grasp on the workings of Blender and SIO2, and ended up with an extremely fun game. As a result, I feel that I am in a great position to explore and critique SIO2 from the perspective of the average new user. Endless thanks go out to everyone in the SIO2 community, especially to SIO2 himself. I couldn't have done it without you guys! On a side note, I highly recommend that you check out Touch Ski 3D:
App Store Link
Youtube Video Review
It's only $0.99, and I promise you will enjoy it Wink. Okay, shameless plug finished... now to the good stuff.

I downloaded SIO2 and started figuring things out from scratch with the help of the tutorials and the forums. The following is a loosely organized collection of the findings and problems that I experienced with SIO2. It is my attempt to give something back to the community and to SIO2 himself, who has been a big help for me. He has put together a stunning engine, but, understandably, he simply doesn't have the time to assemble the kind of detailed documentation that this engine requires in order to be accessible to new users.

This writeup by no means a comprehensive tutorial, but rather an attempt to record as many individual pitfalls and tips as I can recall from my journey with SIO2, and to get the ball rolling on compiling a truly complete SIO2 documentation. As I mentioned, I had never programmed or done 3D design before. Therefore, some of my points might be right for the wrong reasons, and some of them might be wrong for the right reasons, but hopefully they are at least all functional and helpful. This tutorial is not meant as a substitute for the videos. Watch those before reading this.
If (when) any of you find any problems with this writeup, or have suggestions or additions, please contribute them. Hopefully we will end up with a useful piece of documentation for this wonderful engine.


Unless you are completely familiar with what properties are saved when using the SIO2 exporter's "update" function, you should completely erase your .sio2 file and export a new one from scratch each time you make a change. This way you can be sure that you know your current .sio2 file is completely up to date with your blender project. If something isn't working, erase the .sio2 and its unzipped folder and export the scene again. Consider erasing the .sio2 and re-exporting to be the unwritten first step in each troubleshooting scenario.

Getting objects from blender to the simulator is pretty straightforward. They generally appear in the simulator in the same way they look in Blender. Couple things:
The pivot point of an object is showed in blender by the location of the movement arrows when the object is selected. Hitting "center new" (as discussed in the video tutorial) makes sure the pivot point is centered in the object. It can become skewed when changing the object in edit mode. You also might not want the pivot point to be at the objects center. For example, the bars of the starting gate in Touch Ski 3D pivot on their ends, so it wouldn't make sense to center the pivot point in the middle of the bars.
The way SIO2 handles duplicate objects can be confusing. Any object with ".001" or something similar as a suffix in it's name will be treated as a "duplicate" of the object with the same (suffix-less) name. If you want the object to be different, you have to change the name to something without the ".001." If you want it to be treated as a duplicate, make sure you call sio2ResourceBindAllInstances( sio2->_SIO2resource ); during the binding process, as explained later.

Troubleshooting: Objects don't appear correctly in simulator/device
1. Are all the faces triangles? Go into edit mode, select all the faces, and hit "ctrl t" to convert the faces to triangles
2. Does the object name have a suffix like ".001" ? If so, try changing the name and re-exporting
3. Try deleting the object's material and adding a new one with the default properties
4. Have you been messing with vertex groups? Delete all the vertex groups and re-export.

When I was getting started I had a ton of trouble getting textures to appear. Even after watching the video tutorial I was having no luck. Here is a way to ensure that what you are seeing in Blender is what you will see in the simulator/device:

The image that is exported to the .sio2 is the image that you have assigned in the object's texture slot in the Blender texture panel. However, the positioning and scaling of the image must be set separately. Select an object in object mode, press TAB, and go into edit mode. With the desired faces selected, press "u" and then choose "unwrap," "project from view," or whichever is your desired means of unwrapping. In the UV editor window, you can tweak your unwrapping and apply a UV image, BUT note that the image chosen here is separate from the one that is exported to the .sio2 (as mentioned before). This UV image is merely the one that is shown on the object in blender. If this image is the same as the one you have attached to the object's texture slot, then when you choose the "textured" shading/viewing mode in blender the object should appear exactly as it will in the simulator, provided that you follow SIO2's image format guidelines.

Troubleshooting: Textures don't appear correctly in simulator/device
1. Make sure the object has the desired appearance when you view it in blender's "textured" view mode
2. Go into the unzipped sio2 folder and check whether the image has been exported
3. Make sure the image follows SIO2's image format guidelines (DIMENSIONS MUST BE MULTIPLE OF 2, less that 1024 x 1024, etc)

In blender, in the "map to" tab under the "materials" panel, make sure the "alpha" button is selected. Change the blend mode from the default "mix" to "value." In the "shaders" tab also under "materials" panel, set the "Tralu" slider to something other than 0.00. The video talks more about this slider.

If objects are falling through each other, there are a couple things to check.
1. Have you set the objects as actors? This is an obvious one, but sometimes the most obvious points are the easiest to forget
2. Hit "ctrl a" with the object selected and choose "Scale and Rotation to obData." When you transform an object in blender, it changes it's x, y, and z "Scale" from 1.000 to a new value. "ctrl a" will set the scale back to 1.000. Sometimes having this scale at a value other than 1.000 when you export can cause physics issues.
3. Are the objects extremely small? This can cause inaccuracies in the collision detection. Try scaling them up, but don't forget to do "ctrl a" after youre done.
4. Are all the faces triangles? Go into edit mode, select all the faces, and choose "convert to triangles."
5. Try clicking "center new." Sometimes you can run into physics problems with uncentered objects.
6. Take a look at the Step Simulation code below

I'm going to do my best with this, but since I know nothing about coding outside of the sio2 template files, some of my tips might be blatantly wrong. Once again, this is not a substitute for the tutorials. It's merely my notes on a couple things that I feel were not covered in a way that is maximally helpful for unexperienced users. Experienced programmers should feel free to reorganize these notes into a more usable and standardized form.

A standard SIO2 template is comprised of these parts:
templateRender - the rendering function used as the game runs
templateShutdown - the function called when you stop running the template
templateScreenTap - called once any time a new tap is registered on the templateScreenTouchMove - called any time one of those touches is held and moved
templateScreenAccelerometer - used to get accelerometer data



//I'm not sure what every single one of these things do, but this code you can use to properly load your .sio2. After it has finished loading, you must begin calling the templateRender function. See any of the tutorials for how to do that

sio2ResourceCreateDictionary( sio2->_SIO2resource );
sio2ResourceOpen( sio2->_SIO2resource, "NAMEOFYOURSIO2FILE.sio2", 1 );
i = 0;
while( i != sio2->_SIO2resource->gi.number_entry )
      sio2ResourceExtract( sio2->_SIO2resource );
sio2ResourceClose( sio2->_SIO2resource );

//Next you have to bind the specific things that you use in your project

sio2ResourceBindAllImages( sio2->_SIO2resource );
sio2ResourceBindAllInstances( sio2->_SIO2resource );
sio2ResourceBindAllMaterials( sio2->_SIO2resource );
sio2ResourceBindAllMatrix( sio2->_SIO2resource );
sio2ResourceBindAllPhysicObjects( sio2->_SIO2resource, sio2->_SIO2physic );

//This is the final step for loading
sio2ResourceGenId( sio2->_SIO2resource );
//Get the camera
sio2->_SIO2camera = ( SIO2camera * )sio2ResourceGet( sio2->_SIO2resource, SIO2_CAMERA, "camera/Camera" );
sio2CameraSetPerspective( sio2->_SIO2camera,
                         sio2->_SIO2window );



//Get the handle of the object:
SIO2object * WHATEVERNAMEYOUWANT = ( SIO2object * )sio2ResourceGet( sio2->_SIO2resource, SIO2_OBJECT, "object/SkiL" );

//To translate the object
WHATEVERNAMEYOUWANT->_SIO2transform->loc->x = 124.0f;

//To rotate the object
WHATEVERNAMEYOUWANT->_SIO2transform->rot->x = 100.0f;

//To scale the object
WHATEVERNAMEYOUWANT->_SIO2transform->scl->x = 2.0f;

sio2TransformBindMatrix( WHATEVERNAMEYOUWANT->_SIO2transform );



//Get the handle of the material
SIO2material * WHATEVERNAMEYOUWANT = ( SIO2material * )sio2ResourceGet( sio2->_SIO2resource, SIO2_MATERIAL, "material/NAMEOFYOURMATERIAL" );

//To set the image used by the material
WHATEVERNAMEYOUWANT->_SIO2image[0] = ( SIO2image * )sio2ResourceGet( sio2->_SIO2resource, SIO2_IMAGE, "image/Full.png");

//To set the color of the material
WHATEVERNAMEYOUWANT->diffuse->x = 0.9f;
WHATEVERNAMEYOUWANT->diffuse->y = 0.2f;
WHATEVERNAMEYOUWANT->diffuse->z = 0.5f;

This one line of code has a huge impact on the behavior of your game's physics. It is related to the bullet engine, and someone who knows a lot about it should definitely take the time to explain exactly how it works and what are some good values to use. It determines how often the physics world is updated.

sio2PhysicRender( sio2->_SIO2physic, 1.0f / 15.0f, 1 );


//This goes in your templateRender function and controls the camera rendering process
sio2CameraRender( sio2->_SIO2camera );
            sio2CameraUpdateFrustum( sio2->_SIO2camera );

            sio2ResourceCull( sio2->_SIO2resource,
                         sio2->_SIO2camera );
            //Render mist if you have it
            sio2MistRender( MIST );

            //Renders the necessary objects
            sio2ResourceRender( sio2->_SIO2resource,

Important: be sure that you have added sio2InitWidget(); in EAGLView after sio2InitAL();

In your loading function:

      NAMEOFYOURSTREAM = sio2StreamOpen( "NAMEOFIMAGEFILE.tga", 1 );
         NAMEOFYOURIMAGE = sio2ImageInit( "HUD.tga" );
            sio2ImageGenId( NAMEOFYOURIMAGE, NULL, 0.0f );
         NAMEOFYOURMATERIAL = sio2MaterialInit( "HUD" );
         NAMEOFYOURWIDGET = sio2WidgetInit( "HUD" );
         NAMEOFYOURWIDGET->_SIO2transform->scl->x = 512.0f;
         NAMEOFYOURWIDGET->_SIO2transform->scl->y = 32.0f;
         NAMEOFYOURWIDGET->_SIO2transform->loc->x  = -15.0f;
         NAMEOFYOURWIDGET->_SIO2transform->loc->y  = 283.0f;
         sio2EnableState( & NAMEOFYOURWIDGET->flags,

In your render function:

sio2WindowEnter2D( sio2->_SIO2window, 0.0f, 1.0f );
         sio2WindowEnterLandscape2D( sio2->_SIO2window );

            sio2TransformBindMatrix( ANYWIDGETNAME->_SIO2transform );
            // Render our widget
            sio2WidgetRender( ANYWIDGETNAME, sio2->_SIO2window, 1 );
            // Reset the rendering states set by SIO2widget.
         sio2WindowLeaveLandscape2D( sio2->_SIO2window );

In conclusion, here are some steps that i believe should be taken in order to better document the engine. SIO2 himself is extremely busy, so if we want this engine to continue to flourish users are going to have to step up and make these things happen.
1. Tie the video tutorials in with the tutorials' code. I understand that the videos are designed to depict the blender-related components of the tutorials, but there is a huuuuge disconnect between the videos and the code itself which is a giant hurdle for new users.
2. In the tutorial files, instead of using names like _SIO2object for object handles and _SIO2material for material handles, use names like YOUROBJECT and YOURMATERIAL in order to clearly differentiate between titles that are part of the SIO2 syntax and names that are set up by the user.
3. Better explain how to manipulate the camera. How exactly do sio2Vec3Diff and sio2Normalize work with respect to the camera? In what ways does rotation work differently for the camera than for other objects? How exactly do the parameters for sio2Rotate3D do?
4. Add more detailed comments in the tutorial code. I know people mention this a lot, but we really need someone to go through and improve the comments. I'm nowhere near experienced enough to do this.

I will add more things in as I remember them. It's not pretty, but it's a start. Let's get some serious documentation going!

Touch Ski

Posts : 7
Join date : 2009-04-10

Back to top Go down

Documenting the Great SIO2 Empty Re: Documenting the Great SIO2

Post  sio2interactive Fri Apr 10, 2009 4:57 pm

Thank you so much for writing this, Im sure its going to help alot of people (and also avoid me repeating the same thing over and over again through emails Wink but that's another story hehehe...). I totally agree with you that right now what SIO2 needs is a solid documentation, I start writing ideas of my own and well... honestly it'll take a book to cover everything (and still)... but someone have to start somewhere...

I would really like if someone (like you said) can stand up and give me a hand on the documentation or start creating a decent wiki similar as the one on the blender website, explaining the bridge between the 3D editor and the game code. I personally found this format to be awesome:


Also we really need to have other exporter created for other 3D package (specially Maya at this time since it runs on Mac). I thought that by publishing the full SIO2 file format spec. it'll encourage someone to write one but... nobody did... I do not have a Maya license (and obviously don't want to work with pirated software). If someone can make a donation and provide me a Maya license, I would be pleased to write an SIO2 exporter in MEL.

In addition honestly I think that SIO2 start to become really too big for 1 person to maintain... I got more than enough on my plate already between creating my own game, working on the new engine features, taking care of the certificate, replying users, maintaining the website etc...

For the last month and a half Im working on SIO2 full time... and the certificate are my only source of revenue at the moment (and yet not enough to pay the bills). I would definitely appreciate if dedicated users can start giving me help with some of the stuff mentioned earlier... Also it would be great to expand the variety of the SIO2 product and have a little store to sponsor the project such as blender e-shop:

I do not think that closing the sources and start packaging SIO2 with only a static lib and some scrips or other "closed" way is a way to go... and for that SIO2 needs helps from his community... every one can benefit of the success.

That was my 2 cents...


ps: and tks again the the tips and trick above...

Posts : 1526
Join date : 2008-08-26
Age : 45
Location : Shanghai

Back to top Go down

Documenting the Great SIO2 Empty Re: Documenting the Great SIO2

Post  uprise78 Fri Apr 10, 2009 11:20 pm

If there is anything I can do to help I'd be more than happy to lend a hand. I finally finished up my last project for now and have turned down all others for a bit so that I can start to make a game. I will basically be starting from only a limited background with Blender, OpenGL and SIO2 but plenty of experience with programming in general. I've been slowing going through some Blender tutorials and reading the red book so I should be ready to roll with an actual game. Let me know if there is anything I can do to lend a hand...


Posts : 228
Join date : 2008-10-31

Back to top Go down

Documenting the Great SIO2 Empty Re: Documenting the Great SIO2

Post  Francescu Sat Apr 11, 2009 12:20 am

Agreed. A wiki would probably work best.

I'd like to see a section on how to handle various scenes/screens in a game and how you can achieve that by having separate render functions for each various path in the game, etc.

A section on how ways to create menus with Sio2Widgets and Sio2Fonts, etc...and how you can combine SIO2 with iPhone SDK Cocoa touch widgets, etc...

As I'm working on my current project, I'm making notes of all the hurdles I had to go through in order to document these for the community. It would also be good to have an FAQ of the most asked questions in general...

Cheers cheers



Posts : 136
Join date : 2009-03-18

Back to top Go down

Documenting the Great SIO2 Empty Re: Documenting the Great SIO2

Post  calebcohoon Sun Jul 26, 2009 1:20 pm

Great stuff! Thanks


Posts : 15
Join date : 2009-07-25

Back to top Go down

Documenting the Great SIO2 Empty Re: Documenting the Great SIO2

Post  mordenkaim Thu Jul 30, 2009 9:36 am

I second (third, fourth?) the wiki idea. They are very nice since the entire community could contribute to the articles, and the forums are going to get cumbersome quick with the way that posts are ramping up. I'd be glad to author some articles on the answers to some of my noob questions and some of the pitfalls from the perspective of someone with a lot of programming experience but little experience with xcode or iphone programming.


Posts : 21
Join date : 2009-05-19

Back to top Go down

Documenting the Great SIO2 Empty Re: Documenting the Great SIO2

Post  sio2interactive Thu Jul 30, 2009 2:02 pm


Posts : 1526
Join date : 2008-08-26
Age : 45
Location : Shanghai

Back to top Go down

Documenting the Great SIO2 Empty Re: Documenting the Great SIO2

Post  bboyandru Thu Sep 03, 2009 1:57 am

Hy, and thanks for your tutorial, but I don't manage to get the widgets working. Please give me an example with displaying a widget, with an image on the background, the simplest one.
I am new to SIO2 and to 3d programming and xcode, and I have to make a game, and with the widgets i want to make the menu.
Thank you,


Posts : 11
Join date : 2009-09-02

Back to top Go down

Documenting the Great SIO2 Empty Re: Documenting the Great SIO2

Post  IanLinart Thu Sep 03, 2009 7:25 am

bboyandru wrote:Hy, and thanks for your tutorial, but I don't manage to get the widgets working. Please give me an example with displaying a widget, with an image on the background, the simplest one.
I am new to SIO2 and to 3d programming and xcode, and I have to make a game, and with the widgets i want to make the menu.
Thank you,

it'S pretty simple, init your two widgets (for me, my back is a widget too) (look tutorial 7 or 17) and render it, but be carefull of the order of rendering, render you background FIRST and your widget that you want to be on top of it after.

Posts : 26
Join date : 2009-08-12
Age : 35
Location : Montréal

Back to top Go down

Documenting the Great SIO2 Empty Re: Documenting the Great SIO2

Post  william Thu Sep 24, 2009 8:00 am

I think this post should be sticked.


Posts : 15
Join date : 2009-09-09

Back to top Go down

Documenting the Great SIO2 Empty Re: Documenting the Great SIO2

Post  innovation Tue Sep 29, 2009 8:15 am

First the SIO2 engine is a really powerful engine. I just discovered it and will be using it to develop a game.
I just started trying out the engine and i found it this post very useful in solving some physics problems. While most of the stuff here is covered in the tutorials, some of those can be easy to miss, like i did and that can cause a lot of frustration.

My scene was a ball in a box. Initially i didnt have the box set as an actor (my bad) , so the ball just kept falling through the base of the box.
Once i got that sorted out, the sides of he box had been scaled and rotated, which caused them not to react correctly in the physics world.
Hitting CTRL-A and selecting "Scale and Rotation to ObData" like the post said fixed that problem.

Great post.


Posts : 3
Join date : 2009-09-22
Location : Toronto

Back to top Go down

Documenting the Great SIO2 Empty Re: Documenting the Great SIO2

Post  Sponsored content

Sponsored content

Back to top Go down

Back to top

- Similar topics

Permissions in this forum:
You cannot reply to topics in this forum