jMonkeyEngine (jME) is a powerful, open-source 3D game engine for Java developers. At the heart of its rendering and scene management system lies the Scene Graph—a hierarchical tree structure that organizes all objects in your 3D world. Understanding the scene graph is fundamental to creating efficient, well-structured, and high-performance 3D applications.
What is a Scene Graph?
A scene graph is a hierarchical data structure that arranges the logical and spatial representation of a graphical scene. Unlike a simple list of objects, a scene graph establishes parent-child relationships where transformations (position, rotation, scale) and other properties are inherited down the hierarchy.
Think of it as a family tree for your 3D objects:
- Parent nodes affect all their children
- Child nodes inherit transformations from their parents
- Sibling nodes share the same parent's coordinate space
Core jME Scene Graph Architecture
jME's scene graph is built around several key classes that form a clear inheritance hierarchy:
classDiagram
direction TB
class Spatial {
<<abstract>>
+String name
+Transform localTransform
+Spatial parent
+getWorldTransform() Transform
+move() / rotate() / scale()
+getControl() Control
}
class Geometry {
+Mesh mesh
+Material material
+updateModelBound()
}
class Node {
+List~Spatial~ children
+attachChild(Spatial)
+detachChild(Spatial)
+getChild(String) Spatial
}
Spatial <|-- Geometry
Spatial <|-- Node
note for Node "Can contain multiple children\nincluding other Nodes"
note for Geometry "Leaf node - contains\nrenderable content"
Building Your First Scene Graph
1. Basic Setup and Root Node
public class BasicSceneGraph extends SimpleApplication {
@Override
public void simpleInitApp() {
// The 'rootNode' is provided by SimpleApplication
// It's the top-level node of your scene graph
setupCamera();
createSceneHierarchy();
}
private void setupCamera() {
// Position the camera to view our scene
cam.setLocation(new Vector3f(0, 5, 10));
cam.lookAt(Vector3f.ZERO, Vector3f.UNIT_Y);
// Enable fly cam for navigation
flyCam.setMoveSpeed(10f);
}
private void createSceneHierarchy() {
// Create a parent node for our scene
Node sceneNode = new Node("SceneRoot");
// Create ground
Geometry ground = createGround();
sceneNode.attachChild(ground);
// Create a house with hierarchical transformation
Node house = createHouse();
sceneNode.attachChild(house);
// Attach the entire scene to the root node
rootNode.attachChild(sceneNode);
}
private Geometry createGround() {
// Create a flat plane for the ground
Box groundMesh = new Box(10, 0.1f, 10);
Geometry ground = new Geometry("Ground", groundMesh);
// Create a simple material
Material groundMat = new Material(assetManager,
"Common/MatDefs/Misc/Unshaded.j3md");
groundMat.setColor("Color", ColorRGBA.Green);
ground.setMaterial(groundMat);
ground.setLocalTranslation(0, -1, 0);
return ground;
}
}
2. Hierarchical Transformations
This example demonstrates how transformations propagate through the scene graph:
public class HierarchicalTransformations extends SimpleApplication {
@Override
public void simpleInitApp() {
// Create a solar system demonstration
createSolarSystem();
}
private void createSolarSystem() {
// Sun (center of the system)
Geometry sun = createSphere("Sun", 1, ColorRGBA.Yellow);
rootNode.attachChild(sun);
// Earth system node - orbits around sun
Node earthOrbit = new Node("EarthOrbit");
earthOrbit.setLocalTranslation(4, 0, 0); // Orbit radius
rootNode.attachChild(earthOrbit);
// Earth - rotates around its own axis
Geometry earth = createSphere("Earth", 0.3f, ColorRGBA.Blue);
earthOrbit.attachChild(earth);
// Moon system - orbits around earth
Node moonOrbit = new Node("MoonOrbit");
moonOrbit.setLocalTranslation(1, 0, 0); // Orbit around earth
earth.attachChild(moonOrbit);
Geometry moon = createSphere("Moon", 0.1f, ColorRGBA.Gray);
moonOrbit.attachChild(moon);
// Add rotation controls to demonstrate hierarchy
addRotations(sun, earthOrbit, earth, moonOrbit);
}
private Geometry createSphere(String name, float radius, ColorRGBA color) {
Sphere sphere = new Sphere(32, 32, radius);
Geometry geometry = new Geometry(name, sphere);
Material mat = new Material(assetManager,
"Common/MatDefs/Light/Lighting.j3md");
mat.setBoolean("UseMaterialColors", true);
mat.setColor("Ambient", color);
mat.setColor("Diffuse", color);
geometry.setMaterial(mat);
return geometry;
}
private void addRotations(Spatial sun, Node earthOrbit, Spatial earth, Node moonOrbit) {
// Sun rotates slowly
sun.addControl(new RotationControl(0.1f));
// Earth orbits around sun (rotates the orbit node)
earthOrbit.addControl(new RotationControl(0.5f));
// Earth rotates around its axis
earth.addControl(new RotationControl(2f));
// Moon orbits around earth
moonOrbit.addControl(new RotationControl(1f));
}
// Custom control to handle rotation
private class RotationControl extends AbstractControl {
private final float speed;
public RotationControl(float speed) {
this.speed = speed;
}
@Override
protected void controlUpdate(float tpf) {
spatial.rotate(0, tpf * speed, 0);
}
}
}
Advanced Scene Graph Operations
1. Spatial Attachment and Detachment
public class SpatialManagement extends SimpleApplication {
private Node weaponAttachmentPoint;
private Geometry currentWeapon;
private List<Geometry> weaponInventory = new ArrayList<>();
@Override
public void simpleInitApp() {
setupCharacter();
createWeapons();
setupInput();
}
private void setupCharacter() {
// Create a simple character node
Node character = new Node("Character");
character.setLocalTranslation(0, 0, 0);
rootNode.attachChild(character);
// Create attachment point for weapons (e.g., character's hand)
weaponAttachmentPoint = new Node("WeaponAttachment");
weaponAttachmentPoint.setLocalTranslation(0.5f, 1.5f, 0.5f);
character.attachChild(weaponAttachmentPoint);
// Create character body
Geometry body = createBox("Body", 0.3f, 1f, 0.3f, ColorRGBA.Red);
character.attachChild(body);
}
private void createWeapons() {
// Create different weapons
Geometry sword = createSword();
Geometry axe = createAxe();
Geometry bow = createBow();
// Store in inventory (detached from scene graph)
weaponInventory.add(sword);
weaponInventory.add(axe);
weaponInventory.add(bow);
// Equip first weapon
equipWeapon(0);
}
private void equipWeapon(int weaponIndex) {
// Detach current weapon
if (currentWeapon != null) {
weaponAttachmentPoint.detachChild(currentWeapon);
}
// Attach new weapon
if (weaponIndex >= 0 && weaponIndex < weaponInventory.size()) {
currentWeapon = weaponInventory.get(weaponIndex);
weaponAttachmentPoint.attachChild(currentWeapon);
System.out.println("Equipped: " + currentWeapon.getName());
}
}
private Geometry createSword() {
Box blade = new Box(0.05f, 0.5f, 0.05f);
Geometry sword = new Geometry("Sword", blade);
Material mat = new Material(assetManager,
"Common/MatDefs/Misc/Unshaded.j3md");
mat.setColor("Color", ColorRGBA.Gray);
sword.setMaterial(mat);
return sword;
}
private Geometry createAxe() {
// Similar implementation for axe
return createBox("Axe", 0.3f, 0.1f, 0.05f, ColorRGBA.Brown);
}
private Geometry createBow() {
// Similar implementation for bow
return createBox("Bow", 0.01f, 0.4f, 0.4f, ColorRGBA.Yellow);
}
private Geometry createBox(String name, float x, float y, float z, ColorRGBA color) {
Box box = new Box(x, y, z);
Geometry geom = new Geometry(name, box);
Material mat = new Material(assetManager,
"Common/MatDefs/Misc/Unshaded.j3md");
mat.setColor("Color", color);
geom.setMaterial(mat);
return geom;
}
private void setupInput() {
inputManager.addMapping("NextWeapon", new KeyTrigger(KeyInput.KEY_TAB));
inputManager.addListener(new ActionListener() {
@Override
public void onAction(String name, boolean isPressed, float tpf) {
if (name.equals("NextWeapon") && isPressed) {
cycleWeapon();
}
}
}, "NextWeapon");
}
private void cycleWeapon() {
int currentIndex = weaponInventory.indexOf(currentWeapon);
int nextIndex = (currentIndex + 1) % weaponInventory.size();
equipWeapon(nextIndex);
}
}
2. Scene Graph Traversal and Querying
public class SceneGraphTraversal extends SimpleApplication {
@Override
public void simpleInitApp() {
createComplexScene();
demonstrateTraversal();
}
private void createComplexScene() {
// Create a city with buildings, vehicles, and characters
Node city = new Node("City");
// Create districts
Node residentialDistrict = createDistrict("Residential", ColorRGBA.Blue, 5);
Node commercialDistrict = createDistrict("Commercial", ColorRGBA.Red, 5);
Node industrialDistrict = createDistrict("Industrial", ColorRGBA.Green, 5);
residentialDistrict.setLocalTranslation(-10, 0, 0);
commercialDistrict.setLocalTranslation(0, 0, 0);
industrialDistrict.setLocalTranslation(10, 0, 0);
city.attachChild(residentialDistrict);
city.attachChild(commercialDistrict);
city.attachChild(industrialDistrict);
rootNode.attachChild(city);
}
private Node createDistrict(String name, ColorRGBA color, int buildingCount) {
Node district = new Node(name + "District");
for (int i = 0; i < buildingCount; i++) {
Geometry building = createBuilding(name + "Building" + i, color);
building.setLocalTranslation(i * 3 - (buildingCount * 1.5f), 0, 0);
district.attachChild(building);
}
return district;
}
private Geometry createBuilding(String name, ColorRGBA color) {
float height = 1 + FastMath.nextRandomFloat() * 3;
Box buildingMesh = new Box(0.5f, height, 0.5f);
Geometry building = new Geometry(name, buildingMesh);
Material mat = new Material(assetManager,
"Common/MatDefs/Misc/Unshaded.j3md");
mat.setColor("Color", color);
building.setMaterial(mat);
return building;
}
private void demonstrateTraversal() {
System.out.println("=== Scene Graph Analysis ===");
// Find node by exact name
Spatial residential = rootNode.getChild("City/ResidentialDistrict");
if (residential != null) {
System.out.println("Found residential district: " + residential.getName());
}
// Depth-first traversal
System.out.println("\nDepth-first traversal:");
traverseDepthFirst(rootNode, 0);
// Find all geometries with specific characteristics
System.out.println("\nFinding all red buildings:");
List<Geometry> redBuildings = findGeometriesByColor(ColorRGBA.Red);
System.out.println("Found " + redBuildings.size() + " red buildings");
// Count total objects in scene
ObjectCounter counter = new ObjectCounter();
rootNode.depthFirstTraversal(counter);
System.out.println("\nScene statistics:");
System.out.println("Total nodes: " + counter.getNodeCount());
System.out.println("Total geometries: " + counter.getGeometryCount());
}
private void traverseDepthFirst(Spatial spatial, int depth) {
String indent = " ".repeat(depth);
System.out.println(indent + spatial.getName() + " (" + spatial.getClass().getSimpleName() + ")");
if (spatial instanceof Node) {
Node node = (Node) spatial;
for (Spatial child : node.getChildren()) {
traverseDepthFirst(child, depth + 1);
}
}
}
private List<Geometry> findGeometriesByColor(ColorRGBA targetColor) {
List<Geometry> results = new ArrayList<>();
collectGeometriesByColor(rootNode, targetColor, results);
return results;
}
private void collectGeometriesByColor(Spatial spatial, ColorRGBA targetColor, List<Geometry> results) {
if (spatial instanceof Geometry) {
Geometry geom = (Geometry) spatial;
Material mat = geom.getMaterial();
// Check if material has a color parameter (simplified check)
// In real implementation, you'd need more sophisticated material analysis
if (mat.getParam("Color") != null) {
// This is a simplified check - real implementation would extract actual color
results.add(geom);
}
} else if (spatial instanceof Node) {
Node node = (Node) spatial;
for (Spatial child : node.getChildren()) {
collectGeometriesByColor(child, targetColor, results);
}
}
}
// Utility class for counting scene objects
private class ObjectCounter implements SceneGraphVisitor {
private int nodeCount = 0;
private int geometryCount = 0;
@Override
public void visit(Spatial spatial) {
if (spatial instanceof Node) {
nodeCount++;
} else if (spatial instanceof Geometry) {
geometryCount++;
}
}
public int getNodeCount() { return nodeCount; }
public int getGeometryCount() { return geometryCount; }
}
}
Performance Optimization with Scene Graph
1. Spatial Culling and LOD (Level of Detail)
public class OptimizedSceneGraph extends SimpleApplication {
private Node worldNode;
private final int WORLD_SIZE = 100;
@Override
public void simpleInitApp() {
setupFrustumCulling();
createOptimizedWorld();
setupLODDemo();
}
private void setupFrustumCulling() {
// jME automatically performs view frustum culling
// Ensure it's enabled (it is by default)
viewPort.setEnabled(true);
}
private void createOptimizedWorld() {
worldNode = new Node("World");
// Create terrain chunks for efficient culling
for (int x = -WORLD_SIZE/2; x < WORLD_SIZE/2; x += 10) {
for (int z = -WORLD_SIZE/2; z < WORLD_SIZE/2; z += 10) {
Node chunk = createTerrainChunk(x, z);
worldNode.attachChild(chunk);
}
}
rootNode.attachChild(worldNode);
}
private Node createTerrainChunk(int chunkX, int chunkZ) {
Node chunk = new Node("Chunk_" + chunkX + "_" + chunkZ);
chunk.setLocalTranslation(chunkX * 10, 0, chunkZ * 10);
// Create multiple objects in this chunk
for (int i = 0; i < 5; i++) {
for (int j = 0; j < 5; j++) {
Geometry tree = createTree();
tree.setLocalTranslation(i * 2, 0, j * 2);
chunk.attachChild(tree);
}
}
// Set culling hints for optimization
chunk.setCullHint(Spatial.CullHint.Dynamic);
return chunk;
}
private Geometry createTree() {
// Create simple tree geometry
Cylinder trunk = new Cylinder(8, 8, 0.1f, 1f);
Geometry trunkGeom = new Geometry("Trunk", trunk);
Material trunkMat = new Material(assetManager,
"Common/MatDefs/Misc/Unshaded.j3md");
trunkMat.setColor("Color", ColorRGBA.Brown);
trunkGeom.setMaterial(trunkMat);
trunkGeom.setLocalTranslation(0, 0.5f, 0);
Sphere leaves = new Sphere(8, 8, 0.5f);
Geometry leavesGeom = new Geometry("Leaves", leaves);
Material leavesMat = new Material(assetManager,
"Common/MatDefs/Misc/Unshaded.j3md");
leavesMat.setColor("Color", ColorRGBA.Green);
leavesGeom.setMaterial(leavesMat);
leavesGeom.setLocalTranslation(0, 1.5f, 0);
Node tree = new Node("Tree");
tree.attachChild(trunkGeom);
tree.attachChild(leavesGeom);
return tree; // Note: This returns a Node, not Geometry - fixed in usage
}
private void setupLODDemo() {
// Create an object with multiple LOD levels
Node lodObject = new Node("LODObject");
lodObject.setLocalTranslation(0, 0, -20);
// High detail (close)
Geometry highDetail = createDetailedSphere("HighDetail", 1f, ColorRGBA.Red, 32);
highDetail.setCullHint(Spatial.CullHint.Dynamic);
// Medium detail (medium distance)
Geometry mediumDetail = createDetailedSphere("MediumDetail", 1f, ColorRGBA.Green, 16);
mediumDetail.setCullHint(Spatial.CullHint.Always);
// Low detail (far)
Geometry lowDetail = createDetailedSphere("LowDetail", 1f, ColorRGBA.Blue, 8);
lowDetail.setCullHint(Spatial.CullHint.Always);
lodObject.attachChild(highDetail);
lodObject.attachChild(mediumDetail);
lodObject.attachChild(lowDetail);
rootNode.attachChild(lodObject);
// Add LOD control
lodObject.addControl(new LODControl(highDetail, mediumDetail, lowDetail));
}
private Geometry createDetailedSphere(String name, float radius, ColorRGBA color, int samples) {
Sphere sphere = new Sphere(samples, samples, radius);
Geometry geom = new Geometry(name, sphere);
Material mat = new Material(assetManager,
"Common/MatDefs/Misc/Unshaded.j3md");
mat.setColor("Color", color);
geom.setMaterial(mat);
return geom;
}
private class LODControl extends AbstractControl {
private final Geometry highDetail;
private final Geometry mediumDetail;
private final Geometry lowDetail;
public LODControl(Geometry high, Geometry medium, Geometry low) {
this.highDetail = high;
this.mediumDetail = medium;
this.lowDetail = low;
}
@Override
protected void controlUpdate(float tpf) {
if (spatial == null) return;
float distance = spatial.getWorldTranslation().distance(cam.getLocation());
// Update LOD based on distance
if (distance < 10) {
highDetail.setCullHint(Spatial.CullHint.Dynamic);
mediumDetail.setCullHint(Spatial.CullHint.Always);
lowDetail.setCullHint(Spatial.CullHint.Always);
} else if (distance < 20) {
highDetail.setCullHint(Spatial.CullHint.Always);
mediumDetail.setCullHint(Spatial.CullHint.Dynamic);
lowDetail.setCullHint(Spatial.CullHint.Always);
} else {
highDetail.setCullHint(Spatial.CullHint.Always);
mediumDetail.setCullHint(Spatial.CullHint.Always);
lowDetail.setCullHint(Spatial.CullHint.Dynamic);
}
}
}
}
Best Practices and Common Patterns
1. Scene Organization Strategy
public class WellStructuredScene extends SimpleApplication {
@Override
public void simpleInitApp() {
// Organize scene into logical sections
Node staticGeometry = new Node("StaticGeometry");
Node dynamicObjects = new Node("DynamicObjects");
Node lightsAndEffects = new Node("LightsAndEffects");
Node uiElements = new Node("UIElements");
rootNode.attachChild(staticGeometry);
rootNode.attachChild(dynamicObjects);
rootNode.attachChild(lightsAndEffects);
rootNode.attachChild(uiElements);
// Set optimization hints
staticGeometry.setCullHint(Spatial.CullHint.Static);
dynamicObjects.setCullHint(Spatial.CullHint.Dynamic);
populateSceneSections(staticGeometry, dynamicObjects, lightsAndEffects, uiElements);
}
private void populateSceneSections(Node staticGeom, Node dynamicObjs, Node lights, Node ui) {
// Static geometry (terrain, buildings)
staticGeom.attachChild(createTerrain());
staticGeom.attachChild(createBuildings());
// Dynamic objects (characters, vehicles)
dynamicObjs.attachChild(createCharacters());
dynamicObjs.attachChild(createVehicles());
// Lights
lights.attachChild(createSunLight());
lights.attachChild(createPointLights());
}
private Node createTerrain() {
// Implementation for terrain creation
return new Node("Terrain");
}
private Node createBuildings() {
// Implementation for buildings
return new Node("Buildings");
}
private Node createCharacters() {
// Implementation for characters
return new Node("Characters");
}
private Node createVehicles() {
// Implementation for vehicles
return new Node("Vehicles");
}
private Node createSunLight() {
// Implementation for lighting
return new Node("SunLight");
}
private Node createPointLights() {
// Implementation for point lights
return new Node("PointLights");
}
}
Conclusion
The jMonkeyEngine scene graph provides a powerful, hierarchical system for organizing 3D scenes. Key takeaways:
- Hierarchical Transformations: Parent-child relationships enable complex object hierarchies
- Efficient Culling: Automatic frustum culling improves performance
- Flexible Organization: Logical grouping of scene elements
- Dynamic Management: Attach/detach objects at runtime
- Optimization: LOD and culling hints for performance tuning
Mastering the scene graph is essential for creating well-structured, performant 3D applications in jMonkeyEngine. By understanding parent-child relationships, transformation inheritance, and optimization techniques, you can build complex 3D worlds that run efficiently across different hardware configurations.