Previous: Hello SimpleApplication, Next: Hello Assets.

In this tutorial we will have a look at the creation of a 3D scene.

• This tutorial assumes that you know what the Scene Graph is.
• For a visual introduction, check out Scene Graph for Dummies.

When creating a 3D game

1. You create some scene objects like players, buildings, etc.
2. You add the objects to the scene.
3. You move, resize, rotate, color, and animate them.

You will learn that the scene graph represents the 3D world, and why the rootNode is important. You will learn how to create simple objects, how to let them carry custom data (such as health points), and how to "transform" them by moving, scaling, and rotating. You will understand the difference between the two types of "Spatials" in the scene graph: Nodes and Geometries.

package jme3test.helloworld;
 
import com.jme3.app.SimpleApplication;
import com.jme3.material.Material;
import com.jme3.math.Vector3f;
import com.jme3.scene.Geometry;
import com.jme3.scene.shape.Box;
import com.jme3.math.ColorRGBA;
import com.jme3.scene.Node;
 
/** Sample 2 - How to use nodes as handles to manipulate objects in the scene.
 * You can rotate, translate, and scale objects by manipulating their parent nodes.
 * The Root Node is special: Only what is attached to the Root Node appears in the scene. */
public class HelloNode extends SimpleApplication {
 
    public static void main(String[] args){
        HelloNode app = new HelloNode();
        app.start();
    }
 
    @Override
    public void simpleInitApp() {
 
        /** create a blue box at coordinates (1,-1,1) */
        Box box1 = new Box( new Vector3f(1,-1,1), 1,1,1);
        Geometry blue = new Geometry("Box", box1);
        Material mat1 = new Material(assetManager, 
                "Common/MatDefs/Misc/Unshaded.j3md");
        mat1.setColor("Color", ColorRGBA.Blue);
        blue.setMaterial(mat1);
 
        /** create a red box straight above the blue one at (1,3,1) */
        Box box2 = new Box( new Vector3f(1,3,1), 1,1,1);
        Geometry red = new Geometry("Box", box2);
        Material mat2 = new Material(assetManager, 
                "Common/MatDefs/Misc/Unshaded.j3md");
        mat2.setColor("Color", ColorRGBA.Red);
        red.setMaterial(mat2);
 
        /** Create a pivot node at (0,0,0) and attach it to the root node */
        Node pivot = new Node("pivot");
        rootNode.attachChild(pivot); // put this node in the scene
 
        /** Attach the two boxes to the *pivot* node. */
        pivot.attachChild(blue);
        pivot.attachChild(red);
        /** Rotate the pivot node: Note that both boxes have rotated! */
        pivot.rotate(.4f,.4f,0f);
    }
}

Build and run the code sample. You should see two colored boxes tilted at the same angle.

In this tutorial, you learn some new terms:

Every JME3 application has a rootNode: Your game automatically inherits the rootNode object from SimpleApplication. Everything attached to the rootNode is part of the scene graph. The elements of the scene graph are Spatials.

• A Spatial contains the location, rotation, and scale of an object.
• A Spatial can be loaded, transformed, and saved.
• There are two types of Spatials: Nodes and Geometries.

What happens in the code snippet? You use the simpleInitApp() method that was introduced in the first tutorial to initialize the scene.

1. You create the first box Geometry.
   • Create a Box shape with a radius of (1,1,1), that makes the box 2x2x2 world units big.
   • Position the box at (1,-1,1).
   • Wrap the Box shape into a Geometry.
   • Create a blue material.
   • Apply the blue material to the Box Geometry.

         Box box1 = new Box( new Vector3f(1,-1,1), 1,1,1);
         Geometry blue = new Geometry("Box", box1);
         Material mat1 = new Material(assetManager,
           "Common/MatDefs/Misc/Unshaded.j3md");
         mat1.setColor("Color", ColorRGBA.Blue);
         blue.setMaterial(mat1);

2. You create a second box Geometry.
   • Create a second Box shape with the same size.
   • Position the second box at (1,3,1). This is straight above the first box, with a gap of 2 world units inbetween.
   • Wrap the Box shape into a Geometry.
   • Create a red material.
   • Apply the red material to the Box Geometry.

         Box box2 = new Box( new Vector3f(1,3,1), 1,1,1);
         Geometry red = new Geometry("Box", box2);
         Material mat2 = new Material(assetManager,
           "Common/MatDefs/Misc/Unshaded.j3md");
         mat2.setColor("Color", ColorRGBA.Red);
         red.setMaterial(mat2);

3. You create a pivot Node.
   • Name the Node "pivot".
   • By default the Node is positioned at (0,0,0).
   • Attach the Node to the rootNode.
   • The Node has no visible appearance in the scene.

         Node pivot = new Node("pivot");
         rootNode.attachChild(pivot);

     If you run the application with only the code up to here, the scene appears empty. This is because a Node is invisible, and you have not yet attached any visible Geometries to the rootNode.

4. Attach the two boxes to the pivot node.

           pivot.attachChild(blue);
           pivot.attachChild(red);

   If you run the app with only the code up to here, you see two cubes: A red cube straight above a blue cube.

5. Rotate the pivot node.

           pivot.rotate( 0.4f , 0.4f , 0.0f );

   If you run the app now, you see two boxes on top of each other – both tilted at the same angle.

You can transform (e.g. rotate) Geometries around their own center, or around a user defined center point. A user defined center point for one or more Geometries is called pivot.

• In this example, you have grouped two Geometries by attaching them to one pivot Node. You use the pivot Node as a handle to rotate the two Geometries together around one common center. Rotating the pivot Node rotates all attached Geometries, in one step. The pivot node is the center of the rotation. Before attaching the other Geometries, make certain that the pivot node is at (0,0,0). Transforming a parent Node to transform all attached child Spatials is a common task. You will use this method a lot in your games when you move Spatials around.
  Examples: A vehicle and its driver move together; a planet with its moon orbits the sun.
• Contrast this case with the other option: If you don't create an extra pivot node and transform a Geometry, then every transformation is done relative to the Geometry's origin (typically the center).
  Examples: If you rotate each cube directly (using red.rotate(0.1f , 0.2f , 0.3f); and blue.rotate(0.5f , 0.0f , 0.25f);), then each cube is rotated individually around its center. This is similar to a planet rotating around its own center.

There are three types of 3D transformation: Translation, Scaling, and Rotation.

thing.setLocalTranslation( new Vector3f( 0.0f, 40.2f, -2.0f ) );

thing.move( 0.0f, 40.2f, -2.0f );

thing.scale( 10.0f, 0.1f, 1.0f );

thing.rotate( 0f , 0f , 180*FastMath.DEG_TO_RAD );

thing.setLocalRotation( 
  new Quaternion().fromAngleAxis(180*FastMath.DEG_TO_RAD, new Vector3f(1,0,0)));

If you get unexpected results, check whether you made the following common mistakes:

Many Spatials represent game characters or other entities that the player can interact with. The above code that rotates the two boxes around a common center (pivot) could be used for a spacecraft docked to a orbiting space station, for example.

Depending on your game, game entities do not only change their position, rotation, or scale (the transformations that you just learned about). Game entities also have custom properties, such as health, inventory carried, equipment worn for a character, or hull strength and fuel left for a spacecraft. In Java, you represent entity data as class variables, e.g. floats, Strings, or Arrays.

You can add custom data directly to any Node or Geometry. You do not need to extend the Node class to include variables! For example, to add a custom id number to a node, you would use:

pivot.setUserData( "pivot id", 42 );

To read this Node's id number elsewhere, you would use:

int id = pivot.getUserData( "pivot id" ); 

By using different Strings keys (here the key is pivot id), you can get and set several values for whatever data the Spatial needs to carry. When you start writing your game, you might add a fuel value to a car node, speed value to an airplane node, or number of gold coins to a player node, and much more.

You have learned that your 3D scene is a scene graph made up of Spatials: Visible Geometries and invisible Nodes. You can transform Spatials, or attach them to nodes and transform the nodes. You know the easiest way how to add custom entity properties (such as player health or vehicle speed) to Spatials.

Since standard shapes like spheres and boxes get old fast, continue with the next chapter where you learn to load assets such as 3-D models.