Away3D supports the Mouse3DEvent.ROLL_OVER / Mouse3DEvent.ROLL_OUT and Mouse3DEvent.MOUSE_OVER / Mouse3DEvent.MOUSE_OUT pair of events. While both pairs of events are triggered when the mouse is moved over an object and then back off, there is a subtle difference between when they are dispatched.

Take the following application. It creates two overlapping spheres, with each added to a container, and uses the trace() function to notify us when the Mouse3DEvent.ROLL_OVER, Mouse3DEvent.ROLL_OUT, Mouse3DEvent.MOUSE_OVER and Mouse3DEvent.MOUSE_OUT events are dispatched by the container.

package
{
  import away3d.containers.ObjectContainer3D;
  import away3d.events.MouseEvent3D;
  import away3d.materials.WireColorMaterial;
  import away3d.materials.WireframeMaterial;
  import away3d.primitives.Sphere;

  public class MouseRollMoveEventDemo extends Away3DTemplate
  {
    public function MouseRollMoveEventDemo()
    {
      super();
    }

In the initScene() function we create two spheres that are separated by 100 units along the X-axis. Since these spheres have a default radius of 100 units they will overlap.

    protected override function initScene():void
    {
      super.initScene();
      var sphere1:Sphere = new Sphere (
        {
          x: 50,
          y: 0,
          z: 500
        }
      );

      var sphere2:Sphere = new Sphere (
        {
          x: -50,
          y: 0,
          z: 500
        }
      );

The two sphere 3D objects are added as children of a ObjectContainer3D object, which in turn is added as a child of the scene.

      var container:ObjectContainer3D = 
new ObjectContainer3D(sphere1, sphere2);
      scene.addChild(container);

We setup event listeners for three events: MouseEvent3D.MOUSE_OVER, MouseEvent3D.MOUSE_OUT, and MouseEvent3D.ROLL_OVER. Three anonymous functions will be called in response to these events, each using the trace() function to display a line of text.

      container.addEventListener(
        MouseEvent3D.MOUSE_OVER, 
        function(event:MouseEvent3D):void
        {
          trace("Container Mouse Over");
        }
      );
      container.addEventListener(
        MouseEvent3D.MOUSE_OUT, 
        function(event:MouseEvent3D):void
        {
          trace("Container Mouse Out");
        }
      );
      container.addEventListener(
        MouseEvent3D.ROLL_OVER, 
        function(event:MouseEvent3D):void
        {
          trace("Container Roll Over");
        }
      );
      container.addEventListener(
        MouseEvent3D.ROLL_OUT, 
        function(event:MouseEvent3D):void
        {
          trace("Container Roll Out");
        }
      );
    }
  }
}

With the application running, the mouse is moved from the empty space surrounding the two spheres onto the one on the left, like in the following image:

This produces the following output:

Since both the Mouse3DEvent.ROLL_OVER and Mouse3DEvent.MOUSE_OVER events are triggered when the cursor is moved over a 3D object, you would expect to see this output.

Now the mouse cursor is moved from the left sphere to the right sphere.

This second movement produces the following output:

When the mouse is moved off the left sphere the Mouse3DEvent.MOUSE_OUT event was dispatched. This event then bubbled up to the parent container. Because the two spheres are overlapping, when the mouse cursor moved out of the left sphere, it immediately moved over onto the right sphere. This dispatched the Mouse3DEvent.MOUSE_OVER event, which again bubbled up to the parent container.

During this movement the cursor may have moved from one of the containers' child 3D object to the next, but it never passed over empty space in between. In other words, the mouse never moved out of the container. Herein lies the big difference between the two pairs of events. While the Mouse3DEvent.MOUSE_OVER and Mouse3DEvent.MOUSE_OUT events have bubbled up from the children of the container as the mouse moves over them individually, the Mouse3DEvent.ROLL_OVER and Mouse3DEvent.ROLL_OUT even ver and out of all of the children.

Finally, the mouse moves off the right sphere and back over empty space.

This final movement produces the following output:

Container Mouse Out

Container Roll Out

The Mouse3DEvent.MOUSE_OUT event is triggered because the mouse has moved out of the right sphere. The Mouse3DEvent.ROLL_OUT event is also triggered because the mouse has moved out of all the children contained in the container.

So the Mouse3DEvent.ROLL_OVER event will be dispatched when the mouse moves over any of a container's children, and then the Mouse3DEvent.ROLL_OUT event will be dispatched when the mouse moves off all of the children. On the other hand, the Mouse3DEvent.MOUSE_OVER and Mouse3DEvent.MOUSE_OUT events will be triggered when the mouse moves over and out of each of the individual children.