Building a 3D Flash game with Flare3D and Stage3D

Flare3D is a powerful engine that facilitates management of 3D content in Flash. It was designed to provide a seamless development workflow, so that you can do more with less effort.

This tutorial focuses on the ActionScript code required to build a 3D game in Flash; the process of creating and exporting the game's asset files is not described for this sample project.

After completing this tutorial, you'll know the basic concepts required to develop a complete 3D game in Flash. For this example, you'll work with the files used to build a game called Yellow Planet using Stage3D and Flare3D (see Figure 1).

You can download and play the demo at: http://www.flare3d.com/demos/yellowplanet/

The tutorial is divided into ten steps that describe the basic 3D concepts used to make and control a more sophisticated and complex system. Download the sample files provided in the Requirements section and save the uncompressed archive folder to your desktop. As you follow along with each step, you can refer to the corresponding folder in the sample files to review the class described in each tutorial section. The steps involved to develop the game build upon the previous topics in succession, so you'll learn in a progressive way.

At the time of writing, Flash Builder (and others editors) are not currently configured to publish SWF content for Flash Player 11. To accomplish this, you'll need to use a specific version of the Flex SDK and adjust some settings to output files for Flash Player 11. The files you need are listed in the requirements section. After downloading the files, follow the instructions below to setup Flash Builder to publish Stage3D and Flare3D content.

Importing the project in Flash Builder

After downloading and uncompressing the sample files folder, open the flare3D folder and locate the source code named yellowplanet.

1. Copy the yellowplanet folder and save it to the desired location on your hard drive.
2. Launch Flash Builder and choose File > Import Flash Builder project to import the project. While the Project folder option is selected, click the Browse button and navigate to select the Project folder. After setting the project folder, click Finish (see Figure 2).

Setting up Stage3D and the Flare3D library

To compile SWF files that play back in Flash Player 11, you'll need to update the following project properties:

• Specify the correct Flex SDK version
• Add the Flare3D library
• Add the most recent version of the playerglobal.swc library.

To make these changes, you'll access the project's properties and update the settings.

3. Choose Project > Properties. In the left panel, select the ActionScript Build Path option. Use the provided interface to set the project to use the correct version of the Flex SDK (4.5.1 build 21328).
4. If you haven't previously worked with the Flare3D component, you can add it now. Click the Add SWC... button and browse to select the most recent version of the Flare3D component that you downloaded from the Requirements section. The SWC file is located in the lib folder inside the Flare3D distribution file. After making these changes, your project's properties will look like the settings in Figure 3.

Adding the compiler arguments

In order to publish files for Flash Player 11, you need to set the SWF publish setting to version 13. You also need to configure the project to use the Flex SDK version 4.5.1.

1. In the left pane of the project properties, click the ActionScript Compiler option.

   At the time of this writing, the version 13 option for SWF files is not an available setting in the ActionScript Compiler, so you'll add it manually.
   

2. In the Additional compiler arguments field, enter the following line as shown in Figure 4:

   -swf-version 13

3. At the top of the ActionScript Compiler screen, configure the Flex SDK to use version 4.5.1. as shown above.

Updating HTML settings for Stage3D compatibility

When files are published for Flash Player 11, the wmode parameter must be set as direct. You must add this parameter to the HTML file that will host the application. Flash Builder automatically creates an HTML file using a template file called index.template.html.

1. In the project folder, locate the html-template file and add the following line in every place where the player is configured, like this:

Here's an example of the updated code:

Project resources

This project includes some project files that are located inside the assets folder. If desired, you can open these files and review the different parts used to build the game application:

• 3D Max files: All of models used in this game were modeled using 3D Max. You can edit these files and modify the models as desired. The model files have descriptive names to make it easy to match up the game assets.
• Textures: If you explore the assets folder, you can examine the textures used in the models for the game.
• Assets.fla: This Flash Professional file contains all of the 2D elements for the game's user interface. The file named Assets.swc is a component generated from this file.
• Flare3D files: The files astronaut.f3d, planet.f3d, and shadow.f3d were imported directly from 3D Max using the Flare3D plug-in. These files are located in the bin folder.

After you are familiar with the asset files and you've finished configuring Flash Builder, you're ready to move onto the next section and begin exploring how the game is developed.

YellowPlanet_01.as contains the code described in this section.

In the same way the Stage serves as a container for 2D content, you'll need to create a container to hold 3D objects. This container is called the scene.

The process of creating a new scene is easy because you can type a single line:

In the code above, the container parameter can reference any empty sprite or movie clip instance that has been added to the Stage.

Note: There's a useful version of Scene3D called Viewer3D. This object extends Scene3D by adding scene rotation and the ability to zoom using the mouse to the viewer’s functionality.

In order to load 3D models to the project, you'll use the following code:

A Pivot3D is the most basic object in Flare3D. It is similar to an empty movie clip because you can move, rotate, and translate it, as well as adding other 3D objects to it.

If you compile the project now, you'll see a little astronaut running around.

The addChildFromFile method, as its name implies, adds a new child to the scene from an external resource and returns the object as a Pivot3D container. In this example, the object is called astronaut.

Each file could contain many things, including geometry, cameras, lights, and much more. For that reason, the returned object is not the mesh itself, but a container of the entire file.

The following code sets up the Stage, creates the scene, and loads the Flare3D files that contain the 3D models:

YellowPlanet_02.as contains the code described in this section.

private function setupScene( pivot:Pivot3D ): At this point you've created the scene and loaded the 3D objects. In this section, you'll learn how to find objects inside the scene and apply specific behaviors to them.

Finding a specific object

Once the scene is finished loading, you can access all of the contained objects. You can get any object inside using the method getChildByName("object_name"). This method searches recursively in the hierarchy until it finds the requested object. If nothing was found, the method returns null.

For example, you can get a reference from the sky object by using the folowing line:

If you want to modify all of the children of an specific object, you can use the forEach method. The forEach method calls a function for each child of the specified object.

For example, review the following line:

In the line above, setupScene is a method that receives each child as argument.

Review the code example below:

Updating the scene

You can control when the scene updates by using the Update event. This event is dispatched before the render, so that you can modify the scene each time this method is invoked. The updateEvent function is the main loop in the game.

In this example, updateEvent controls how the fans and the sky are rotated:

1. In the sample files, locate the file named YellowPlanet_02.as. Double-click the file to open it in Flash Professional and test the movie.

As it plays, notice that you can control the rotation of the planet with your mouse movements. As you watch the fans rotate, think about updateEvent function and how the planet’s objects are modified inside it. After you are finished reviewing the sample project, proceed to the next section.

YellowPlanet_03.as contains the code described in this section.

Next, you'll explore how to manipulate a camera with Flare3D. You'll also learn some basic camera manipulation concepts. There are many different strategies you can use to control the position of the camera. This section explains two functions used in the 3D game that simplifies this process.

Reviewing the Astronaut container

If you examine the code in YellowPlanet_03.as, you'll notice that the astronaut is wrapped inside a Pivot3D object.

This step may not seem necessary at the moment. But in the future it facilitates more control of the astronaut when required.

Review the following code to learn how to have greater control over the display of the astronaut:

Setting the camera position using setPositionWithReference

In the sample project game, the astronaut walks around the planet. So the camera must be able to follow him. This camera behavior can be implemented by referencing the astronaut's current position. You can use the setPositionWithReference to accomplish this task. This method is included in the Pivot3DUtils and allows you to position an object in relation to another object used as a reference. This means that you can transform any object relative to another object.

In this game, the camera is always located behind the astronaut. It maintains its position relative to the astronaut. The camera (like any other object into the scene) has an axis that defines both its position and its direction. The direction of the axis is shown in Figure 5.

The +Z points to the astronaut's direction and +Y is pointing up. These vectors are called Up, Dir, and Right (see Figure 6).

Assuming that every object has his own axis, the next line of code sets the camera up (+Y) 80 units and away (-Z) 20 units relative to the astronaut:

As you see, a complex task is resolved using a single line of code by using Flare3D.

Setting the camera's orientation using lookAtWithReference

Now that the camera is in the right position, the lens needs to "look" in the right direction. Using the same strategy as using reference points to set the position of objects, you can also use reference points to look at a specific point in the game.

This method has an additional and optional parameter called 'up' that is required for this game.

Usually, the Up vector is always pointing to the up direction. In many cases, passing a null value is enough to make Flare3D calculate the vector for you (see Figure 7).

However, imagine the folowing example: If you hold your hand with your index finger pointing at an object as though it was a pistol, your thumb automatically points up, which is the desired outcome. Both the Dir and Up vectors are defined.

Now, while still pointing your index finger at the same object, try to rotate your hand. As it rotates, the Up finger (your thumb) start changing its direction. Notice that even if you always hold your hand to point in the same direction, the Up vector moves as you rotate your hand. In order to program the camera so that it knows which way is up, you'll use the up parameter.

In the sample game, the camera is positioned above in relation to the astronaut. The camera must be set to point down, in order to look at the astronaut. The Up vector of the camera should be pointing to the Dir vector of the astronaut (see Figure 8).

YellowPlanet_04.as contains the code described in this section.

In this section, you'll learn some concepts used to introduce interactivity to the game.

First, explore how the game manages the user's input. Flare3D includes some utilities you can use to quickly manage the keyboard or mouse input as the game is played.

In this class, the Input3D.keyDown() method is used to detect which key is pressed. The method returns a true value while the key is held down.

The utility also includes the Input3D.keyHit() method, which is similar to keyDown but returns the true value only once.

Another interesting concept to explore in the sample project code is the use of rays.

A ray is a virtual and infinite line that starts at some arbitrary point and continues infinitely in some direction.

Rays can test if an object in the game intersects before reaching the infinite. If the test is true, the ray provides additional data about the collision, including the mesh, the exact point of the collision, the normal of the face that was collided, and other data.

Rays are used in this sample project because the astronaut needs to keep running on the spherical floor while remaining aligned to it. Rays are used to achieve both tasks (see Figure 9).

In this case, the stage of the environment is basically an sphere. If desired, you can keep the astronaut aligned to the sphere using other methods, but rays are very helpful because they work with non-uniform surfaces.

Creating a ray using the new RayCollision() method

Use the following line of code to create a new RayCollision:

Adding objects to test against that ray using the ray.addCollisionWith( object ) method

The following code adds the floor of the planet to test collisions with the ray:

The second argument ("false") indicates that the collision is detected only with the floor (discarding floor’s childs).

Testing a ray collision using the ray.test( from, direction ) method

Begin by setting a point where the ray will start. This position should not exactly match the astronaut's position because that is so close to the floor that the ray will not intersect with anything. Instead, set a point higher than that, such as (0,100,0) and use localToGlobal to convert that point into the world coordinates.

After defining the point where the ray starts, the next task is to give it a direction. The direction should be pointing down in the direction of the astronaut. You can get that vector using the getDown() method of Pivot3D.

Use the received collision data

In the previous section, you learned how to test when ray collision returns a value of true. The ray collision data is available and you can use it for the game's logic. The information is  stored in an specific structure. You can use a CollisionInfo object to parse the received data. In the code bellow, notice how you can see obtain the position (info.point.x, info.point.y, info.point.z) and normal orientation (info.normal) information.

YellowPlanet_05.as contains the code described in this section.

The SphereCollision is a utility that works with complex geometry collisions. It is basically a virtual sphere that collides and reacts with one or many mesh objects (see Figure 10).

This sample game uses SphereCollisions to enable the astronaut to collide with the walls and obstacles around the planet. Using SphereCollision, you can wrap the astronaut in virtual sphere to collide with the game environment.

The SphereCollision utility also provides a smooth displacement when the collision ocours, which is called a slider.

The following steps illustrate how to use the SphereCollision class:

1. Create a SphereCollision instance and pass to it a target for the sphere and a radius.
2. Add objects to test against that sphere using the collisions.addCollisionWith( object ) method.
3. Update the collisions by calling the collisions.slider(), collisions.fixed() or collisions.intersect() methods.
4. If a collision occurs, you can access and use the collision data as needed.

Note: RayCollision and SphereCollision are intensive math algorithms, so it's best to use them with low polygonal objects when possible. Since these utilities perform such complex mathematical equations, you'll notice a significant performance difference when running the project in debug or release mode. Additionally, SphereCollision does not work with scaled objects, so always normalize your collision objects before working with them in the game.

Creating sphere collisions using the SphereCollision (source, radius, offset) method

The first step is to declare the collision object, like this:

Later, you can create the SphereCollision using the astronaut as a target with a radius of 3 units. Remember that in Step 3, the astronaut was placed inside a Pivot3D object called "container" (see Figure 11).

By default, the virtual sphere will be positioned at the center of the pivot. In this example, the pivot of the astronaut is at his feet, so you need to apply an offset for the virtual sphere, which is the third Vector3D parameter at (0,3,0) as shown in Figure 11.

If you remember section 3 "Reviewing the astronaut container" the astronaut character was wraped into a container. Now it’s time to explain that. The astronaut has the ability to jump. Then, in some cases, the character can jump over a fan to avoid a sure death. But, the astronaut must not jump obstacles like buildings. At this moment, you can detect a collision between the astronaut and the obstacles. If astronaut jumps the obstacles, the collision is never dispatched. For this reason the SphereCollision is added to the container instead of the astronaut. Then, when the astronaut jumps, the sphere remains in the bottom and the collision is detected (See Figure 12).

Adding collisions with obstacles

Once the collision is created, you must specify the objects that must be checked. In the sample game, these objects (Pivot3D objects) are each called "obstacle" so you need to add a collision for each of them.

Once you move the astronaut, all of the collisions are tested. The updateEvent() function contains the following line:

If the astronaut collides with an obstacle, this method generates a displacement to fix the intersection and relocate the astronaut to the right place in the scene. This avoids issues that may cause the astronaut to become stuck in a single location and appear to be frozen in the scene.

YellowPlanet_06.as contains the code described in this section.

Now it's time to add some nice looking special effects (see Figure 13).

Particles enable you to quickly draw a large set of data simultaneously. When you create effects, you can group all of the particles and draw them together in one draw call, to avoid drawing each particle separately. As you can imagine, this strategy increases the drawing speed, because particles works a bit differently than other 3D objects and they are usually facing the camera.

Follow these steps to use particles in a 3D Flash game:

1. Create a particle class that extends the Particle3D class to use as a particle template.
2. Override the methods init, update and clone from the Particle3D class to add the desired behavior to the particles.
3. Create a ParticleMaterial3D class to set textures, colors or any other filter compatible with particles.
4. Create a ParticleEmiter3D class using the material and particle template.
5. Configure the emitter using the emitParticlesPerFrame, particlesLife and decrementPerFrame properties.

In this example, the new emitters were created in separate classes that extend from the ParticleEmiter3D class to keep the code simple and easier to update.

Setting up the particle elements

First, set the variables used for particles. Notice that both smoke and fire are Texture3D objects.

Next, load the textures as external files.

Working with the FireEmiter

You create the fire emiter and add it to the astronaut. The FireEmiter class extends ParticleEmiter3D, and you can find this class in the sample files folder in the following directory: src\objects

Set the parent of the FireEmiter to the astronaut. This ensures that the particles will be emited from the astronaut model.

Working with the SmokeEmiter

You can use SmokeEmiter the same way you work with FireEmiter. In this sample game, SmokeEmiter is associated with each fan located on the planet.

Note that the SmokeEmiter class uses the fan direction for each emiter:

YellowPlanet_07.as contains the code described in this section.

The concepts described in this section are similar to those used when developing any other Flash game. In this step, the goal is to make the astronaut jump over the Y axis.

Because the astronaut is located inside the container object, it doesn`t matter how the orientation of the container changes. The astronaut will always move up and down over its own Y axis.

After completing this step, you'll update the logic of the game. In order to manage the flow of the game play, it's important to add some state variables. Additionally, you'll add the function gameLogics to update all of the game states as the game is played.

Managing states and game variables

Add the code shown below to implement some game logics. To control the astronaut character's behavior, you'll need to store the character's state. And to control the astronaut's moment, you'll add a new variable called jumpValue.

Working with the gameLogics method

The gamesLogic method is called on each Update iteration. The gamesLogic method checks the astronaut’s state. If desired, you can modify the game behavior to change how it works. For example, if the user presses the Space key, it activates the FireEmiter and updates the character's animation. Here's an example:

YellowPlanet_08.as contains the code described in this section.

The game is really shaping up nicely now. You've come to the point where the fun parts are added to make the game more exciting. In this section, you'll add the code that enables the astronaut character to kill enemies, die, and fly!

These are the hazards and pitfalls that bring the game to the life. You'll continue working with the game logic, to continue incorporating new features into the game.

At this point, it's also time to move the behaviors that control the fans and mines to a new function called gameObjects.

Managing states and game variables

Create a new game variable in the game logic variables named shakeFactor:

You'll use the shakeFactor variable to shake the camera and create a special effect whenever the astronaut dies.

Understanding gameObjects

The gameObjects behave similarly to gameLogics because the gameObjects method is called on each Update iteration. This function gets the astronaut's current position and updates the game state by comparing the distance between the astronaut character and the other elements in the scene.

Working with fan collision

If the distance between the astronaut and a fan is less than fan’s radius, then the game's state is changed to "fan" and the astronaut is launched into the sky the next time the gameLogics method is called (see Figure 14).

Working with mine collision

If the distance between the astronaut and a mine is less than 10 units, the game logic uses the value of the state variable to set one of two possible outcomes:

• State = "jump" – Results in the astronaut jumping over the mine and the mine is destroyed.

• State = "run" – Results in the astronaut colliding with the mine and astronaut dies (see Figure 15).

Re-activating killed mines

Every time a mine is destroyed, it is repositioned to the other side of the planet. Then it must be re activated.

To detect if the mine is in the other side of the planet, you can compare the Up vector of each mine with the current Up vector of the astronaut. If you multiply the two vectors using dotProduct, and both vectors are pointing in the same direction, the result is a positive numeric value, which means that the astronaut and the mine are located on the same side of the planet. If the comparison determines that the vectors are pointing in different directions, the result is a negative number because the mine is located far away from the astronaut's location (see Figure 16).

YellowPlanet_09.as contains the code described  in this section.

In this section, you'll use Flash Professional to integrate sounds and 2D content in the 3D Flash game.

The addition of sound and 2D objects add an exciting new facet to the game and make it much more enjoyable to play.

There are many different ways you can bring Flash content into the game. In this example, you can keep things simple by exporting your game assets as a component (SWC file).

Follow these next steps to export the contents of an FLA file as a component:

1. Open a Flash file and use the Property inspector to set the linkage names to the objects and movie clips you want to export.
2. Right-click on the desired elements in the Library panel. In the context menu that appears, select the option: Export SWC File.

After exporting a SWC file, you can add the resulting library to your project and use the included assets to create new instances of them.

This part of the process is very similar to working with basic movie clip symbols and sounds.

Setting up the 2D interface

The 2D interface for the sample game is included in the assets.swc file. You can create an instance of this object using the following lines of code:

Interacting with graphic user interface elements

As a user plays the game, three different scores are tracked. The user's individual game points, the number of energy objects collected and the overall highest score ever are all calculated and tracked, in order to be displayed in the game's interface. The score data is updated in gameGUI() function. This function modifys the text characters in the 2D UI elements to display the current game information (see Figure 17).

Pop, crash, bang!

The game includes messages that are displayed whenever the astronaut dies or destroys a mine. These messages are comprised of 2D graphic elements too (see Figure 18).

Review the following lines of code to see how messages are placed in the correct location within the scene, using the astronaut's position as reference.

The method getScreenCoords() converts the 3D container’s coordinates to 2D coordinates (to return a Point object).

YellowPlanet_10.as contains the code described in this section.

The objective of the game is to collect energy items that the astronaut finds while walking around the planet. When the user collects three energy items, they are promoted to the next level in the game and the astronaut's speed is increased (see Figure 19).

The energy items are an external 3D model stored in the energy.f3d file. To add the energy items to the game, you load the F3D file and add it to the scene, just like you added the other Flare3D elements.

Positioning energy items

Every time the astronaut finds an energy item, a brand new energy item is generated and placed at a random location on the planet. The new energy item's position is randomly calculated, like this:

More energy = more speed

Every time the astronaut finds a new energy item, his speed is increased: 

When the astronaut takes the 3° consecutive energy item, he is temporarily unable to move for a little while and the "Next Level" alert is displayed. After this occurs, the game's state returns to "run." This type of extra detail adds more excitement to the game and results in a more enjoyable user experience.

The 3D Flash game called Yellow Planet is included with the official Flare3D release as a tutorial. You can use the sample project assets to explore how Flare3D works. In this tutorial, you've learned about the primary tasks associated with developing the game.

Hopefully this quick introduction has inspired you to develop your own Flash games using the Flare3D technology and leverage the new features in Flash Player 11.

To learn more about working with Flare3D, visit the Flare3D website.

Also be sure to check out the Stage 3D Developer Center to find helpful articles, tutorials and sample projects to get you up to speed quickly.