This is an introduction to the concept of Spatials, the elements of the 3D scene graph. The scene graph is a data structure that manages all objects in your 3D world. For example, the scene graph keeps track of the 3D models that you load and position. When you extend a Java class from com.jme3.app.SimpleApplication, you automatically inherit the scene graph and its rootNode.

The rootNode is the central element of the scene graph. Even if the scene graph is empty, it always contains at least the rootNode. We attach Spatials to the rootNode. Attached Spatials are always in a parent-child relationship. Every time you attach a Spatial to something, it is implicitly detached from its previous parent. A Spatial can have only one parent. A Spatial can have several children.

If you think you need to understand the scene graph concept better, please read Scenegraph for dummies first.

In your Java code, a Spatial is either a com.jme3.scene.Node or a com.jme3.scene.Geometry. You use the two for different purposes:

The polygon Mesh inside a Geometry can be one of three things:

• Shapes: The simplest type of Meshes are jME's default Shapes such as cubes and spheres. You can use several Shapes to build complex Geometries. Shapes are built-in and can be created without using the AssetManager.
• 3D Models: 3D models and scenes are also made up of meshes, but are more complex than Shapes. You create Models and Scenes in external 3D Mesh Editors and export them as Ogre XML or Wavefront OBJ. Use the Asset Manager to load models into a your jME3 game.
• Custom Meshes: Advanced users can create Custom Meshes programmatically.

You can include custom user data –that is, custom Java objects and methods– in Nodes and Geometries. This is very useful for maintaining information about a game element, such as health, budget, ammunition, inventory, equipment, etc for players, or landmark locations for terrains, and much more.

The following example adds an integer field named health to the Spatil player_node, and initializes it to 100.

player_node.setUserData("health", 100);

To be able to add accessors to the player, you create a custom PlayerControl class and add it to the Spatial.

player_node.addControl(PlayerControl.class);

In PlayerControl you define methods that set and get your users data in the spatial object.

public int getHealth() {
  return (Integer)spatial.getUserData("health");
}
public void setHealth(int h) {
  spatial.setUserData("health",h);
}

Elsewhere in your code, you can access this data wherever you have access to the Spatial player_node.

health = player_node.getControl(PlayerControl.class).getHealth();
...
player_node.getControl(PlayerControl.class).setHealth(99);

• You can add as many data objects (including Strings, Integers, Floats, Arrays,) to a Spatial as you want. Just make sure to label them with unique Strings (health, inventory, equipment, etc).
• The saved data can be custom Java objects if you make the custom Java class implement the Savable interface.
• When you save a Spatial as a .j3o file, the custom data is saved, too, and it will be restored the next time you load the .j3o!

This is how you list all data keys that are already defined for one Spatial:

for(String key : spatial.getUserDataKeys()){
    System.out.println(spatial.getName()+"'s keys: "+key);
}

Often after you load a scene or model, you need to access a part of it as an individual Geometry in the scene graph. Maybe you want to swap a character's weapon, or you want to play a door-opening animation. First you need to know the unique name of the sub-mesh.

1. Open the model in a 3D mesh editor, or in the jMonkeyEngine SDK's Scene Composer.
2. Find out the existing names of sub-meshes in the model.
3. Assign unique names to sub-meshes in the model if neccessary.

In the following example, the Node house is the loaded model. The sub-meshes in the Node are called its children. The String, here door 12, is the name of the mesh that you are searching.

Geometry submesh = (Geometry) houseScene.getChild("door 12");