Jean-Marc Le Roux Web, RIAs and chocolate spaghettis…

Getting Started With Minko 2

Update: you can read all of Minko's tutorials on our developers Hub
Update: you can also download the developers reference!

Here is a little blog post for anyone who wants to get started using Minko 2 "from scratch". If you want to build Minko from the sources, be able to easily update it whenever necessary and work with the open source samples this tutorial is for you!

But first things first, a little summary of what's available code-wise:

• minko: Minko's core, and that's already a lot of features (old and new). Among them: the scene graph API, the rendering API, ActionScript shaders with the new compiler/API, ray casting...
• minko-collada: the enhanced Collada extension (minko-collada) to load Collada (*.dae) files.
• minko-picking: the extension to add pixel-perfect mouse interactivity.
• minko-examples: a repository full a simple samples targeting one feature at a time.

And now what is about to be released:

• minko-lighting: the lighting engine extension. We've added a lot of cool features and optimizations, such as projected shadows for every light types.
• minko-3ds and minko-obj: extensions to respectively handle the 3DS and OBJ file formats.
• minko-jiglibflash: the extension to plug JigLibFlash into Minko and add 3D physics

A lot of people ask me about tutorials. The tutorials available on the Hub are not for Minko 2 but for the older version. We didn't have enough time to update them, and that's why we provide minko-examples. It's a lot easier to update and to maintain. But of course, the old tutorials will be ported and a lot of new tutorials will be added in June.

Now let's get started...

1. Get the sources

If you really want to start working with Minko 2, I strongly advise to work with the sources. The first reason is that we add a lot of minor fixes and new features every day. You just have to read the commits list to see that we're very very active!

Another reason would be that it's much easier to understand the code if you're able to sneak in and see what it does. Most of the stuff you will use in your very first applications is very high level, and so is the corresponding implementation. It's cool to want to display a rotating cube in just 10 minutes. But it's even better if you can learn "what" the cube is actually "made of" in just one click and a few minutes of head scratching.

a. Get a Git client

The sources of Minko are on GitHub. This is an easy and elegant way for us to share our work. If you'ver worked with Subversion (SVN) before, you can see git has it's little brother. Only better. You can use github for Windows or for Mac if you're into github and social coding.

I also recommend SmartGit which is a really nice Git client for Windows/Mac. SmartGit is very cool because you can merge all your repositories into a single project and perform bulk actions on all of them. That's very useful when you work with Minko and some of its extensions and want to update everything!

b. Clone our repository

"Cloning" our repository means creating a local copy of our code base. To do this, you just need to use the the "clone" feature of your Git client and use the URI provided on the github repository page:

If you're working with GitHub for Windows/Mac, you can clone the repository simply by clicking on the "Clone in Windows" or "Clone in Mac" button on the repository start page:

c. Switch branches

For now, Minko 2 is available in the 2.0b branch of the GitHub repository. If you don't switch to this very branch, the files you'll see in your local copy of the repository will be the files of the master branch. And the master branch is the good old Minko 1 so it's not what we want. To switch branches, you must use your Git client. It's usually a "switch" button:

When you have found the "switch" button, you just have to select the "2.0b" branch. Voilà, you have the latest sources of Minko 2 and you can easily update them from the GitHub repository!

2. Import Minko in you IDE

Now you have the sources, we just need to be able to use them in an ActionScript project. To do this, the best way is to create a library project. Here is how it is done with Flash Builder:

Now you just have to setup the project with the proper settings:

• Project name: minko (obviously...)
• Folder: browse to the folder where you cloned the GitHub repository in step 1
• Flex SDK version: make sure you're using a Flash 11 capable Flex SDK. You can use the Flex 4.6 SDK available here.

And hit "Finish" to get your Minko library project in the package explorer:

3. Compile Minko examples

a. Get the sources

Follow the step 1 to get the sources of minko-examples on GitHub. The examples also rely on "Monitor", a small library featuring a simple customizable properties monitor. You can get the sources of Monitor on GitHub and then you just have to make an ActionScript library project out of it by following steps 1.b and 2 but it's already available as a SWC library.

Minko examples also rely on Minimalcomps to create the 2D UI components. Both Monitor and Minimalcomps are available in the /libs directory. You juste have to add this library to the classpath of your project.

Then create a new ActionScript project and add the minko lirary to it's class path:

b. Import the sources in your IDE

You can edit the class path of any project by opening it's "Properties" panel, going to the "ActionScript Build Path" folder and switching to the "Library path" tab.

Minko examples is setup with a package for each extension. The samples you can build with Minko's core are in the aerys.minko.example.core package, the examples for minko-collada are in the aerys.minko.example.collada package, etc... You'll notice that some packages - such as lighting or effects" - do not have the corresponding extension. That's because we have them internally but they are not good enough to be made public for now. In the near future, we will move those samples in branches in order to make it less ambiguous.

Make sure you've also added the Monitor library to the class path of the project!

b. Compile your first sample

Each sample is a separate ActionScript application file. For example, if you want to compile and run the "red cube" example located in the aerys.minko.example.core.redcube package, you just have to run the RedCubeExample. In some IDEs such as Flash Builder, you'll need to declare it as an application. In order to do this, you can simply right click on the RedCubeExample file in the "Package Explorer" and hit "Set as Default Application" (you can also do it in the properties of the project in the "ActionScript Applications" folder):

If you get a "Context3D not available" error, make sure:

• You're working with a Flash 11 capable Flex SDK for both the minko library and the minko-examples project
• You're using wmode="direct" to embed the SWF in the HTML file
• The minko-examples project is targeting Flash 11 or higher

4. Work with extensions

Extensions are just other livrary projects relying on Minko's core framework. You just have to follow steps 1, 2, and 3 but starting from the GitHub repository of the extension you need! Here are the extensions already available:

• minko-collada: the enhanced Collada extension (minko-collada) to load Collada (*.dae) files.
• minko-picking: the extension to add pixel-perfect mouse interactivity.

Conclusion

Fetching Minko's sources and all its extensions can be a bit annoying. It's not easy to begin with if you don't know Git or GitHub for example. This is why we will provide a ZIP archive with everything you need organized in a user-friendly and comprehensive way. This all-in-one SDK will be available as soon as Minko 2 is out of beta.

In the meantime, if you have issues starting with Minko, please ask in the comments or on Aerys Answers, the official Minko support forum.