# Saving and Loading Materials with .j3m Files

In the Material Definitions article you learned how to configure Materials programmatically in Java code. If you have certain commonly used Materials that never change, you can clean up the amount of Java code that clutters your init method, by moving material settings into .j3m files. Then later in your code, you only need to call one setter instead of several to apply the material.

## Writing the .j3m File

1. For every Material, create a file and give it a name that describes it: e.g. `SimpleBump.j3m`
2. Place the file in your project's `assets/Materials/` directory, e.g. `MyGame/src/assets/Materials/SimpleBump.j3m`
3. Edit the file and add content using the following Syntax, e.g.:

       Material shiny bumpy rock : Common/MatDefs/Light/Lighting.j3md {
            MaterialParameters {
                Shininess: 8.0
                NormalMap: Textures/bump_rock_normal.png
                UseMaterialColors : true
                Ambient  : 0.0 0.0 0.0 1.0
                Diffuse  : 1.0 1.0 1.0 1.0
                Specular : 0.0 0.0 0.0 1.0
            }
       }

How to this file is structured:

1. Header
   1. `Material` is a fixed keyword, keep it.
   2. `shiny bumpy rock` is a descriptive string that you can make up. Choose a name to help you remember for what you intend to use this material.
   3. After the colon, specify on which Material definition you base this Material.
2. Now look up the choosen Material Definition's parameters and their parameter types from the Material table. Add one line for each parameter.
   - For example: The series of four numbers in the example above represent RGBA color values.
3. Check the detailed syntax reference below if you are unsure.

Tip: In the jMonkeyPlatform, use File>New File>Material>Empty Material File to create .j3m files.

## How to Use .j3m Materials

This is how you use the prepared .j3m Material on a Spatial. Since you have saved the .j3m file to your project's Assets directory, the .j3m path is relative to `MyGame/src/assets/…`.

    myGeometry.setMaterial(assetManager.loadAsset("Materials/SimpleBump.j3m"));

Tip: In the jMonkeyPlatform, open Windows>Palette and drag the `JME Material: Set J3M` snippet into your code.

## Syntax Reference for .j3m Files

### Paths

Make sure to get the paths to the textures (.png, .jpg) and material definitions (.j3md) right.

- The paths to the built-in .j3md files are relative to jME3's Core Data directory. Just copy the path stated in the Material table.
  `Common/MatDefs/Misc/Unshaded.j3md` is resolved to `jme3/src/src/core-data/Common/MatDefs/Misc/Unshaded.j3md`.
- The paths to your textures are relative to your project's assets directory.
  `Textures/bump_rock_normal.png` is resolved to `MyGame/src/assets/Textures/bump_rock_normal.png`

### Data Types

All data types (except Color) are specified in com.jme3.shader.VarType. “Color” is specified as Vector4 in J3MLoader.java.

Name | jME Java class | .j3m file syntax
--- | --- | ---
Float |  | a float (e.g. 0.72) , no comma or parentheses
Vector2 | `com.jme3.math.Vector2f` | Two floats, no comma or parentheses
Vector3 | `com.jme3.math.Vector3f` | Three floats, no comma or parentheses
Texture2D | `com.jme3.texture.Texture` | Path to texture in `assets` directory, no quotation marks
Boolean | (basic Java type) | `true` or `false`
Int | (basic Java type) | Integer number, no comma or parentheses
Color | `com.jme3.math.ColorRGBA` | Four floats, no comma or parentheses
Vector4 |  |
FloatArray |  |
Vector2Array |  |
Vector3Array |  |
Vector4Array |  |
Matrix3 |  |
Matrix4 |  |
Matrix3Array |  |
Matrix4Array |  |
TextureBuffer |  |
Texture3D |  |
TextureArray |  |
TextureCubeMap |  |

### Flip and Repeat Syntax

- A texture can be flipped using the following syntax `NormalMap: Flip Textures/bump_rock_normal.png`
- A texture can be set to repeat using the following syntax `NormalMap: Repeat Textures/bump_rock_normal.png`
- If a texture is set to both being flipped and repeated, Flip must come before Repeat

### Syntax for Additional Render States

- A Boolean can be “On” or “Off”
- Float is “123.0” etc
- Enum - values depend on the enum

Name | Type | Purpose
--- | --- | ---
Wireframe | (Boolean) |
FaceCull | (Enum: FaceCullMode) |
DepthWrite | (Boolean) |
DepthTest | (Boolean) |
Blend | (Enum: BlendMode) |
AlphaTestFalloff | (Float) |
PolyOffset | (Float, Float) |
ColorWrite | (Boolean)
PointSprite | (Boolean) |

## Examples

### Example 1: Shiny

    Spatial signpost = (Spatial) assetManager.loadAsset(
        new OgreMeshKey("Models/Sign Post/Sign Post.mesh.xml", null));
    signpost.setMaterial( (Material) assetManager.loadAsset(
        new AssetKey("Models/Sign Post/Sign Post.j3m")));
    TangentBinormalGenerator.generate(signpost);
    rootNode.attachChild(signpost);

The file `assets/Models/Sign Post/Sign Post.j3m` contains:

    Material Signpost : Common/MatDefs/Light/Lighting.j3md {
        MaterialParameters {
             Shininess: 4.0
             DiffuseMap:  Models/Sign Post/Sign Post.jpg
             NormalMap:   Models/Sign Post/Sign Post_normal.jpg
             SpecularMap: Models/Sign Post/Sign Post_specular.jpg
             UseMaterialColors : true
             Ambient  : 0.5 0.5 0.5 1.0
             Diffuse  : 1.0 1.0 1.0 1.0
             Specular : 1.0 1.0 1.0 1.0
        }
    }

The JPG files are in the same directory, `assets/Models/Sign Post/…`.

### Example 2: Repeating Texture

    Material mat = assetManager.loadMaterial(
        "Textures/Terrain/Pond/Pond.j3m");
    mat.setColor("Ambient", ColorRGBA.DarkGray);
    mat.setColor("Diffuse", ColorRGBA.White);
    mat.setBoolean("UseMaterialColors", true);

The file `assets/Textures/Terrain/Pond/Pond.j3m` contains:

    Material Pong Rock : Common/MatDefs/Light/Lighting.j3md {
         MaterialParameters {
             Shininess: 8.0
             DiffuseMap: Repeat Textures/Terrain/Pond/Pond.png
             NormalMap:  Repeat Textures/Terrain/Pond/Pond_normal.png
         }
    }

The PNG files are in the same directory, `assets/Textures/Terrain/Pond/`

### Example 3: Transparent

The file `assets/Models/Tree/Leaves.j3m` contains:

    Material Leaves : Common/MatDefs/Light/Lighting.j3md {

        Transparent On

        MaterialParameters {
            DiffuseMap : Models/Tree/Leaves.png
            UseAlpha : true
            AlphaDiscardThreshold : 0.5
            UseMaterialColors : true
            Ambient : .5 .5 .5 .5
            Diffuse : 0.7 0.7 0.7 1
            Specular : 0 0 0 1
            Shininess : 16
        }
        AdditionalRenderState {
            Blend Alpha
            AlphaTestFalloff 0.50
            FaceCull Off
        }
    }

The PNG file is in the same directory, `assets/Models/Tree/…`

view online version