Tutorial: your first mobile 3D application with Minko

As you already know I’m sure, you can build Android and iOS devices with the Flash platform. And Stage3D is also available on those devices! As a matter of fact, Stage3D was especially designed to work on mobiles. And so was Minko! We put a lot of efforts in building a robust and fast engine that will work on most mobile devices. This tutorial will start where the “Your first Minko application” tutorial stopped and explain what needs to be done to get it working on mobile.

Create your mobile project

The first thing to do is – of course – create a mobile project. With Flash Builder it is very simple: you just have to go into File > New > ActionScript Mobile Project. If you need a little reminder of how to bootstrap your project/development environment, you can read the “Getting started with Minko” tutorial. The only difference compared to creating a desktop/wepp application is to uncheck “BlackBerry Table OS” in the Mobile Settings panel: Stage3D is not yet available on BlackBerry devices. There is an issue opened on the BlackBerry tracker if you want to vote for it!

Configure the application

Now our project has been created we just have to make sure it can use the Stage3D API. It implies two little changes in the app.xml file (this file is named after your main class, most of the time it’s Main-app.xml):

1. renderMode has to be set to “direct”
2. depthAndStencil has to be set to “true”

Here is a basic example of a properly setup app.xml file for AIR 3.2:

	Main
	Main
	Minko Mobile Example
	0.0.0
	
		[This value will be overwritten by Flash Builder in the output app.xml]

	        
       		direct
        	true
	        

	true
        false
        true
    
    
        UIDeviceFamily
			
				1
				2
			
		]]>
        high
    
    
        
		    
		    
		    
		    
		    
					
	]]>
    

Bootstrap the Main class

That’s the beauty of the Flash platform, Stage3D and Minko: the project boostrap aside, the code of the application is exactly the same whether you are working on a desktop, web or mobile application! Therefore, you can bootstrap your Main class by following the “Your first Minko application” tutorial! Basically, you just have to copy/paste the MinkoApplication sample class…

public class MinkoApplication extends Sprite
{
  private var _viewport : Viewport;
  private var _scene : Scene;
 
  protected function get scene() : Scene
  {
    return _scene;
  }
 
  protected function get viewport() : Viewport
  {
    return _viewport;
  }
 
  public function MinkoApplication()
  {
    super();
 
    // make sure the stage is available
    if (stage)
      initialize();
    else
      addEventListener(Event.ADDED_TO_STAGE, initialize);
  }
 
  private function initialize(event : Event = null) : void
  {
    removeEventListener(Event.ADDED_TO_STAGE, initialize);
 
    // create the viewport
    _viewport = new Viewport();
    // add the viewport to the stage
    stage.addChild(_viewport);
 
    initializeScene();
 
    addEventListener(Event.ENTER_FRAME, enterFrameHandler);
  }
 
  protected function initializeScene() : void
  {
    // create an empty scene
    _scene = new Scene();    
  }
 
  protected function enterFrameHandler(event : Event) : void
  {
    // render a frame
    _scene.render(_viewport);
  }
}

… and make your Main class extend it:

public class Main extends MinkoApplication
{
  public function Main()
  {
    super();
  }
}

Run your mobile application for the first time

If you use Flash Builder, it will display the Debug Configurations panel when you will try to run/debug your mobile application for the first time. This panel does not have anything special regarding Stage3D or Minko, but it’s still a good thing to see the basics! There are two important fields on the panel:

1. The “Target platform” field will specify what device you want to target for this debug session.
2. The “Launch method” field will specify whether you want to run the application in the desktop device emulator or directly on the device. Of course, the “On device” method is better if you want to have a preview of the actual performances.

Display your first 3D object

Now that our project is setup and that we can launch it on the device or in the emulator, we will display our first 3D object. You just have to follow the “Display your first 3D object” tutorial for your mobile project. Here is what you’ll get if you choose to run it on the desktop emulating the iPhone4 device: You can also directly download the sources for this project! If you have questions/suggestions regarding this tutorial, please post in the comments or on Aerys Answers, Minko’s official support forum.