# Materials Overview

A Geometry (mesh) is just the shape of the object. jMonkeyEngine cannot render a shape without knowing anything about its surface properties. You need to apply a color or texture to the surface of your Geometries to make them visible. In jMonkeyEngine, colors and textures are represented as Material objects.

All Geometries have Materials: You either use the setters described here to specifiy the Material's properties in your Java code, or you load a custom .j3m file that lists the properties. To improve performance, reuse Materials for similar models, don't create a new Material object for every Geometry. (E.g. use one bark Material for many tree models.)

You can write .j3m files in a text editor, or use the jMonkeyEngine SDK to create .j3m files for you. (Advanced users can also create custom Material Definitions.)

Each Material is based on one of the default material definitions (.j3md files) that are included in the engine. The Materials table shows you the material definitions that jMonkeyEngine supports by default. You want to make the most of your models by setting good looking material parameters: The developers should be in contact with the graphic designer regarding which of the available jMonkeyEngine features (listed here) are intended to be used in individual Models' Materials. You must have an understanding what texture maps are to be able to use textured materials.

## Code Sample

The following samples assume that you loaded a Geometry, e.g. `Spatial myGeometry = assetManager.loadModel("Models/Teapot/Teapot.j3o");`

    Material mat = new Material(assetManager,  // Create new material and
        "Common/MatDefs/Misc/Unshaded.j3md");  //   specify .j3md file path.
    mat.setColor("Color", ColorRGBA.Blue);     // Set one or more parameters.
    myGeometry.setMaterial(mat);               // Use material on Geometry.

or

    myGeometry.setMaterial( (Material)assetManager.loadAsset( "myMaterial.j3m") );

Most Material parameters are not mandatory. For example, it is normal to specify solely the `DiffuseMap` and `NormalMap` when using `Lighting.j3md`, and leave the rest empty. You are only using a subset of the advanced features, but that's acceptable if it results in the material looking the way you want. You can always add more texture maps later.

1) Looks confusing? Start with `Unshaded.j3md`, then look into `Lighting.j3md`.
2) The jMonkeyEngine SDK offers a visual editor where you can set properties and preview the outcome. The SDK Palette contains code snippets to load materials.
3) If you don't know what an obscure parameter means, you're likely not using it.

jMonkeyEngine supports illuminated and unshaded Material Definitions.

- Phong Illuminated materials look more naturalistic.
- Unshaded materials look more abstract.

## Unshaded Coloring and Textures

"Unshaded" materials look somewhat abstract because they ignore lighting and shading. Unshaded Materials work even if the scene does not include a light source. These Materials can be single-colored or textured. For example, they are used for cards and tiles, for the sky, billboards and UI elements, for toon-style games, or for testing.

Basic Material Definition | Usage | Parameter
--- | --- | ---

Common/MatDefs/Misc/Unshaded.j3md

Standard, non-illuminated Materials.
Use this for simple coloring and texturing, glow, and transparency.
See also: Hello Material

Texture Maps
setTexture("ColorMap", assetManager.loadTexture(""));
setBoolean("SeparateTexCoord",true);
setTexture("LightMap", assetManager.loadTexture(""));
Colors
setColor("Color", ColorRGBA.White);
setBoolean("VertexColor",true);
Glow
setTexture("GlowMap", assetManager.loadTexture(""));
setColor("GlowColor", ColorRGBA.White);

Other useful, but less commonly used material definitions:

Special Material Definitions | Usage | Setter, Parameter, Type
--- | --- | ---
Common/MatDefs/Misc/Sky.j3md | A solid skyblue, or use with a custom SkyDome texture. See also: Sky | setTexture("TextureCubeMap", assetManager.loadTexture("")); setBoolean("SphereMap",true); setVector3("NormalScale", new Vector3f(0,0,0));

Common/MatDefs/Terrain/Terrain.j3md

Splat textures for e.g. terrains.
See also: Hello Terrain

setTexture("Texture1", assetManager.loadTexture("")); (red)
setFloat("Texture1Scale",1f);
setTexture("Texture2", assetManager.loadTexture("")); (green)
setFloat("Texture2Scale",1f);
setTexture("Texture3", assetManager.loadTexture("")); (blue)
setFloat("Texture3Scale",1f);
setTexture("Alpha", assetManager.loadTexture(""));

Common/MatDefs/Terrain/HeightBasedTerrain.j3md

A multi-layered texture for terrains.
Specify four textures and a Vector3f describing the region in which each texture should appear:
X = start height,
Y = end height,
Z = texture scale.
Texture regions can overlap.
For example: Specify a seafloor texture for the lowest areas,
a sandy texture for the beaches,
a grassy texure for inland areas,
and a rocky texture for mountain tops.

setFloat("terrainSize",512f);
setTexture("region1ColorMap", assetManager.loadTexture(""));
setTexture("region2ColorMap", assetManager.loadTexture(""));
setTexture("region3ColorMap", assetManager.loadTexture(""));
setTexture("region4ColorMap", assetManager.loadTexture(""));
setVector3("region1", new Vector3f(0,0,0));
setVector3("region2", new Vector3f(0,0,0));
setVector3("region3", new Vector3f(0,0,0));
setVector3("region4", new Vector3f(0,0,0));
Settings for steep areas:
setTexture("slopeColorMap", assetManager.loadTexture(""));
setFloat("slopeTileFactor",1f);

Common/MatDefs/Misc/Particle.j3md

Used with texture masks for particle effects, or for point sprites.
The Quadratic value scales the particle for perspective view (
).
Does support an optional colored glow effect.
See also: Hello Effects

setTexture("Texture", assetManager.loadTexture(""));
setTexture("GlowMap", assetManager.loadTexture(""));
setColor("GlowColor", ColorRGBA.White);
setFloat("Quadratic",1f);
setBoolean("PointSprite",true);

## Phong Illuminated

Illuminated materials require a light source added to at least one of their parent nodes! (e.g. rootNode.) Illuminated materials are darker on the sides facing away from light sources. They use Phong illumination model (default), or the Ward isotropic gaussian specular shader (WardIso) which looks more like plastic. They do not cast drop shadows unless you use a FilterPostProcessor.

Illuminated Material Definition | Usage | Setter, Parameter, Type
--- | --- | ---

Common/MatDefs/Light/Lighting.j3md

Commonly used Material with Phong illumination.
Use this material together with DiffuseMap, SpecularMap, BumpMap (NormalMaps, ParalaxMap) textures.
Supports shininess, transparency, and plain material colors (Diffuse, Ambient, Specular colors).
See also: Hello Material

Texture Maps
setTexture("DiffuseMap", assetManager.loadTexture(""));
setBoolean("UseAlpha",true);1)
setTexture("NormalMap", assetManager.loadTexture(""));
setBoolean("LATC",true); 2)
setTexture("SpecularMap", assetManager.loadTexture(""));
setFloat("Shininess",64f);
setTexture("ParallaxMap", assetManager.loadTexture(""));
setTexture("AlphaMap", assetManager.loadTexture(""));
setFloat("AlphaDiscardThreshold",1f);
setTexture("ColorRamp", assetManager.loadTexture(""));
Glow
setTexture("GlowMap", assetManager.loadTexture(""));
setColor("GlowColor", ColorRGBA.White);
Performance and quality
setBoolean("VertexLighting",true);
setBoolean("UseVertexColor",true);
setBoolean("LowQuality",true);
setBoolean("HighQuality",true);
Material Colors
setBoolean("UseMaterialColors",true);
setColor("Diffuse", ColorRGBA.White);
setColor("Ambient", ColorRGBA.White);
setColor("Specular", ColorRGBA.White);
Tangent shading:
setBoolean("VTangent",true);
setBoolean("Minnaert",true);3)
setBoolean("WardIso",true);4)

Special Illuminated Material Definitions | Usage | Setter, Parameter, Type
--- | --- | ---

Common/MatDefs/Terrain/TerrainLighting.j3md

Same kind of multi-layered splat texture as Terrain.j3md, but with illumination and shading.
Typically used for terrains, but works on any mesh.
For every 3 splat textures, you need one alpha map.
You can use a total of 11 texture maps in the terrain's splat texture:
Note that diffuse and normal maps all count against that.
For example, you can use a maximum of 9 diffuse textures, two of which can have normal maps;
or, five textures with both diffuse and normal maps.

Texture Splat Maps
setTexture("DiffuseMap", assetManager.loadTexture(""));
setFloat("DiffuseMap_0_scale",1f);
setTexture("NormalMap", assetManager.loadTexture(""));
setTexture("DiffuseMap_1", assetManager.loadTexture(""));
setFloat("DiffuseMap_1_scale",1f);
setTexture("NormalMap_1", assetManager.loadTexture(""));
setTexture("DiffuseMap_2", assetManager.loadTexture(""));
setFloat("DiffuseMap_2_scale",1f);
setTexture("NormalMap_2", assetManager.loadTexture(""));
setTexture("DiffuseMap_3", assetManager.loadTexture(""));
setFloat("DiffuseMap_3_scale",1f);
setTexture("NormalMap_3", assetManager.loadTexture(""));
etc, up to 11.
Alpha Maps
setTexture("AlphaMap", assetManager.loadTexture(""));
setTexture("AlphaMap_1", assetManager.loadTexture(""));
setTexture("AlphaMap_2", assetManager.loadTexture(""));
Glowing
setTexture("GlowMap", assetManager.loadTexture(""));
setColor("GlowColor", ColorRGBA.White);
Miscellaneous
setColor("Diffuse", ColorRGBA.White);
setColor("Ambient", ColorRGBA.White);
setFloat("Shininess",64f);
setColor("Specular", ColorRGBA.White);
setTexture("SpecularMap", assetManager.loadTexture(""));
setBoolean("WardIso",true);
setBoolean("useTriPlanarMapping",true);
setBoolean("isTerrainGrid",true);

Common/MatDefs/Light/Reflection.j3md | Reflective glass material with environment map (CubeMap/SphereMap). See also: | setTexture("Texture", assetManager.loadTexture("")); setBoolean("SphereMap",true);

## Testing and Debugging

Material Definition | Usage
--- | ---
Common/MatDefs/Misc/ShowNormals.j3md | A color gradient calculated from the model's surface normals. You can use this built-in material to debug the generation of normals in meshes, to preview models that have no material, or as fall-back default material. This built-in material has no parameters.

## Activate Special Features

### NormalMap (Bumpiness)

A NormalMap (alos called BumpMap) describes the fine bumpy details of the Material surface that are not part of the mesh itself. E.g. cracks, pores, creases, notches.

1. Generate normals for the Mesh (not for the Geometry!)

       TangentBinormalGenerator.generate(mesh);

2. Specify the `NormalMap` texture. (
   )

### Specular (Shininess)

To activate Shininess:

1. Specify the `Shininess` intensity.
   A float value between 1 (rough surface with blurry shininess) and 128 (very smooth surface with focused shininess)
2. Specify a Color as `Specular` value.
   The ColorRGBA value of the light source, e.g. often RGBA.White.
3. (Optionally for some Materials) Specify a `SpecularMap` texture.
   This grayscale texture outlines in detail where the DiffuseMap texture should be shiny (white) and were not (black), instead of rendering the whole material evenly shiny.

To deactivate shininess

- Set the `Specular` color to `ColorRGBA.Black`. Do not just set `Shininess` to 0.

### Glow

To activate glow:

1. Add a FilterPostProcessor in your simpleInit() method.
2. Specify a Color as `Glow` value.
   A ColorRGBA value of your choice, e.g. choose a warm or cold color for different effects.
3. (Optionally for some Materials) Specify a `GlowMap` texture.
   This texture outlines in detail where the DiffuseMap texture glows, instead of making the whole material glow everwhere evenly.

To deactivate glow

- Set the `Glow` color to `ColorRGBA.Black`.

### Transparency

Most Material Definitions support an alpha channel for opaqueness and transparency in textures. In an RGBA color, the last float is the alpha channel: 0.0f is transparent and 1.0f is opaque. For example, `mat.setColor("Color", new ColorRGBA(1,0,0,0.5f));` is a half-opaque red.

Additionally, you must specify a blendmode:

Material option | Usage | Example
--- | --- | ---
getAdditionalRenderState().setBlendMode(BlendMode.Off); | Opaque |
getAdditionalRenderState().setBlendMode(BlendMode.Alpha); | Interpolates the background pixel with the current pixel by using the current pixel's alpha. | Use this for normal every-day translucency: Frosted window panes, ice, glass, alpha-blended vegetation textures…
getAdditionalRenderState().setDepthWrite(false); | Disables writing of the pixel's depth value to the depth buffer. | Use this on Materials if you have several transparent/translucent objects obscuring one another, but you want to see through both.
getAdditionalRenderState().setAlphaFallOff(0.5f); getAdditionalRenderState().setAlphaTest(true) | Enables alpha test. Works the same way as "AlphaDiscardThreshold". | Used for textures that have fully opaque pixels next to fully transparent pixels, e.g. foliage, hair, vegetation.

getAdditionalRenderState().setBlendMode(BlendMode.Additive);

Additive alpha blending adds colors in a commutative way, i.e. the result does not depend on the order of transparent layers, since it adds the scene's background pixel color to the current pixel color. This is useful if you have lots of transparent textures overlapping and don't care about the order.
Viewed in front of a white background, Additive textures become fully transparent!

Used for particle effect textures that have a black color background.

getAdditionalRenderState().setBlendMode(BlendMode.AlphaAdditive); | Same as "Additive", except first it multiplies the current pixel color by the pixel alpha. | Used for particle effects that have alpha as background.
getAdditionalRenderState().setBlendMode(BlendMode.Color); | Blends by color. | Generally useless.
getAdditionalRenderState().setBlendMode(BlendMode.Modulate); | Multiplies the background pixel by the current pixel. | ?
getAdditionalRenderState().setBlendMode(BlendMode.ModulateX2); | Same as "Modulate", except the result is doubled. | ?
getAdditionalRenderState().setBlendMode(BlendMode.PremultAlpha); | Pre-multiplied alpha blending. E.g. if the color of the object has already been multiplied by its alpha, this is used instead of "Alpha" blend mode. | For use with Premult Alpha textures.

For partially transparent Materials based on Lighting.j3md, consider setting the `AlphaDiscardThreshold` value. The renderer only renders pixels above your alpha threshold, and does not render pixels below the threshold. This means, that gradients in the AlphaMap are no longer interpreted as soft translucency, but parts of the texture become either fully opaque or fully transparent. You typically activate Alpha Testing for partially transparent objects such as foliage, hair, etc.

### Advanced Options

Material Option | Usage | Example
--- | --- | ---
getAdditionalRenderState().setWireframe(true); | Switch to showing the (textured) Material in wireframe mode. For debugging or "matrix/holodeck" effect. |
getAdditionalRenderState().setFaceCullMode(FaceCullMode.Back); | Activate back-face culling. Mesh faces that are not facing the camera are not rendered, which saves time. Backface culling is activated by default as a major optimization. | The backside of mesh polygons (and the inside of models) is invisible.
getAdditionalRenderState().setFaceCullMode(FaceCullMode.Off); | Nothing is culled. Both mesh faces are rendered, even if they face away from the camera. Slow. | Sometimes used to debug custom meshes if you messed up some of the polygon sides, or for special shadow effects.
getAdditionalRenderState().setFaceCullMode(FaceCullMode.Front); | Activate front-face culling. Mesh faces facing the camera are not rendered. | Typically not used.
getAdditionalRenderState().setFaceCullMode(FaceCullMode.FrontAndBack) | Cull both backfaces and frontfaces. | Use this as an efficient way to make an object temporarily invisible, while keeping all its other in-game properties (node attachment, collision shapes, interactions, etc) active.
getAdditionalRenderState().setColorWrite(false); | Disable writing the color of pixels. | Use this together with setDepthWrite(true) to write pixels only to the depth buffer, for example.
getAdditionalRenderState().setPointSprite(true); | Enables point-sprite mode, e.g. meshes with "Mode.Points" will be rendered as textured sprites. Note that gl_PointCoord must be set in the shader. | Point sprites are used internally for hardware accelerated particle effects.
getAdditionalRenderState().setPolyOffset(); | Enable polygon offset. | Use this when you have meshes that have triangles really close to each over (e.g. ), it will shift the depth values to prevent .

1) UseAlpha specifies whether DiffuseMap uses the alpha channel
2) LATC Specifies whether NormalMap is BC5/ATI2n/LATC/3Dc-compressed
3) Minnaert is a shader type.
4) WardIso is a shader type.

view online version