As we saw with the parent coordinate system, it is possible to add 3D objects to a parent container other than the scene. Adding 3D objects to parent containers in this way is referred to as nesting. Nesting is used to transform a group of 3D objects simultaneously. A parent container can be moved, scaled, or rotated, which in turn will transform its children 3D objects.

Let's see a practical example of nesting in action. Imagine you were creating a shoot 'em up style of game where each space ship can be matched with a variety of guns, with each gun represented by a distinct 3D object. While this could be achieved by providing a separate model for combination of ship and gun, such an approach would quickly become unworkable as the number of combinations increased. If you had five ships, and each ship should be matched with six guns, you would need to supply 30 individual models.

A better solution would be to model each of the ships and the guns separately, and combine them at runtime to form the necessary combinations.

Here is a screenshot of the gun:

Here is a screenshot of the ship:

And here is a screenshot of the ship and the guns combined:

The following NestingDemo class demonstrates how the ship and gun 3D objects shown in the screenshots can be added to a container so they can be transformed as a single group.

package
{
  import away3d.containers.ObjectContainer3D;
  import away3d.core.base.Mesh;

The Cast class provides a convenient way to cast objects between types. In this example, it is used in conjunction with the BitmapMaterial class, which will be used to apply a material the 3D objects that we will be adding to the scene. Materials are covered in more detail in Chapter 5, Materials.

  import away3d.core.utils.Cast;
  import away3d.materials.BitmapMaterial;
  
  import flash.events.Event;
  
  public class NestingDemo extends Away3DTemplate
  {

The texture.jpg file has been embedded, and can be accessed via the Texture class.

    [Embed(source="texture.jpg")]
    protected var Texture:Class;

The container property will reference the parent container that the ship and gun models will be added to.

    protected var container:ObjectContainer3D;
        
    public function NestingDemo()
    {
      super();
    }
    
    protected override function initScene():void
    {
      super.initScene();

In the initScene() function, we create a new BitmapMaterial object. This will then be applied to the ship and gun 3D objects.

      var material:BitmapMaterial = 
        new BitmapMaterial(Cast.bitmap(Texture));

The Fighter class is a complex 3D object that has been exported to an ActionScript class. This is similar to the SeaTurtle class that was covered in Chapter 2, Creating and Displaying Primitives. It will be referenced by the fighter variable, and is used to represent the space ship. Exporting models to ActionScript classes is covered in Chapter 6, Models and Animations.

      var fighter:Mesh = new Fighter();

The material is then applied to the 3D object.

      fighter.material = material;

The gun 3D objects are created in much the same way as the ship. We create a new instance of the Gun class, and apply the material to it.

      var gun1:Mesh = new Gun();
      gun1.material = material;

In this case, the tool used to export the Gun class created it in such a way that the init object is not passed to the base Mesh class. This means the position of the 3D object cannot be set using an init object, so the position is instead set via the x, y, and z properties after the object has been created.

      gun1.x = -150;
      gun1.y = 75;
      gun1.z = -115;

The ship has two guns, so we create a second instance of the Gun class. This second gun is positioned on the opposite side of the X axis.

      var gun2:Mesh = new Gun();
      gun2.material = material;
      gun2.x = 150;
      gun2.y = 75;
      gun2.z = -115;

At this point, we have three 3D objects: one ship and two guns. We want to be able to work with these three 3D objects as if they were a single item. This is where nesting is useful. First we create a new container, and add the separate 3D objects as children by supplying them as the first three parameters of the ObjectContainer3D constructor.

      container = new ObjectContainer3D(
        fighter, gun1, gun2,

The final parameter is an init object, which will set the position of the container 2,000 units along the positive end of the Z axis.

        {
          z: 2000
        }
      );
      
      scene.addChild(container);
    }
    
    protected override function onEnterFrame(event:Event):void
    {
      super.onEnterFrame(event);

By nesting the ship and gun 3D objects in a container, they can now be transformed as a single group. In fact, we have already moved the 3D objects as a group by specifying the initial position of the container when it was constructed. The onEnterFrame() function also transforms the 3D objects as a group by modifying the rotation of the container.

      ++container.rotationX;
      ++container.rotationZ;
    }
  }
}

When you run the application, you will see that the ship and gun 3D models maintain their position relative to each other within the parent container while the parent container is moved and rotated.