How to create presets for the Grass extension and material assistants

While there isn’t a specific button that simply lets you save your current settings to a preset, there is a way to create your own presets and have them auto-loaded in the “Preset” drop downs. It’s simply a matter of editing a file using any text editor. There is a corresponding file for the Grass extension and for each of the material assistants (it would make sense to create presets for the ones with the most settings such as Translucent, Metal, Hair). Moreover, you can also create presets for the Brick procedural which may be quite handy as it contains a total of 31 parameters.

“.XPR” files

You will find the preset files in your Maxwell 3 install folder, in the extensions>presets folder. With the default install, you should have 9 .XPR files there. You can open them in any text editor to see their syntax. On Windows systems I suggest you start your text editor by right-clicking its executable or shortcut from the Windows menu, and choosing “Run as Administrator”. This will give it permissions to save files directly into the Program Files folder, and you will probably make frequent changes to the .XPR files when adding/changing presets. Throughout this tutorial I’ll be using Sublime Text which is an awesome text editor, in case you were looking for one…

Each .XPR file belongs to a certain extension, material assistant, or procedural texture and each file can contain as many presets as you want. When you add a preset and resave the file, you need to restart Maxwell Studio or your main 3D app in order for these presets to show up in their corresponding “Presets” drop down.

Looking at the maxwellgrass.xpr file

Opening this file in your text editor, this is what the beginning of it looks like:

# Preset file MaxwellGrass
Version = ""; 
Extension = "MaxwellGrass"; 
Preset "Wild Grass" 
"Primitive Type" = 1; 
"Density" = 3000; 
"Length" = 7.5; 
"Length Variation" = 60; 
"Root Width" = 6; 
"Tip Width" = 2.5; 
"Initial Angle" = 30; 
"Initial Angle Variation" = 50; 
"Start Bend" = 40; 
"Start Bend Variation" = 25; 
"Bend Radius" = 5; 
"Bend Radius Variation" = 50; 
"Bend Angle" = 80; 
"Bend Angle Variation" = 50; 

Preset "Golf Green" 
"Primitive Type" = 1; 
"Points per Blade" = 4; 
"Density" = 150000; 

Some things to note about this file structure:

  • any line that starts with a “#” sign is ignored and is used only for comments.
  • “Extension = ” specifies for which extension this preset file is for.
  • All presets must be enclosed within the “PresetsList” block which itself starts and finishes with curly braces – {}.
  • Each preset must be named and also be enclosed within curly braces.
  • Don’t forget to put a semicolon (;) at the end of each parameter value.

You will notice that not all available grass extension parameters need to be specified. For unspecified ones, the defaults will be used. So where are the defaults located, and how can you find out the exact name of each parameter you can use?

The “.XUI” files

The UI “specs” of an extension are contained within an “.XUI” file which is found in the Maxwell 3 > extensions folder. As a reminder, an extension can be something like MaxwellGrass, but it can also be a procedural shader, or a material assistant, and, with the release of the Maxwell Extensions API in 3.2 (included for free with Maxwell Render, for both personal and commercial use), in the future an extension can be almost anything – a camera lens, a geometry shader, a geometry modifier etc. These .XUI files can also be opened in a text editor:

# MaxwellGrass extension UI file 
Version = "";
  Parameter Material 
    DisplayName = "Material"; 
    Type = string; 
    UIType = materialPicker; 
    Visible = "yes";

Parameter "Double Sided Material" 
   DisplayName = "Backface Material"; 
   Type = string; 
   UIType = materialPicker; 
   Visible = "yes"; 

Parameter "Density" 
   DisplayName = "Density"; 
   Type = uint; 
   UIType = intSpin; 
   Suffix = "Blades/m2"; 
   Default = 100; 
   MinVal = 0; 

At the top you will see the block “ParameterSet” which will contain the name and attributes of each of the parameters. Some parameters have a default value which you can change here. You can also find out the “true” name of the parameter which you must use in the .XPR file. The true parameter name is specified in the beginning of each parameter block. Take care not to use the “DisplayName” in your .XPR file as sometimes it is different.

Towards the bottom of the .XUI file, you will see a block called “Groups” which specifies how the different parameters are to be organized into groups in the UI. Below the Groups block, you will finally see a “Layout” block which specifies in which order the Groups should end up in the UI. So if you’re a customization freak – here is where you can change in which groups and in which order the parameters should appear in your UI.

Now that we know the true names of the parameters, and what their ranges are, we can start adding them to a preset.

Creating a preset for MaxwellGrass

I will only specify a few parameters in this preset – ones that may not be so straightforward such as specifying a density texture map and the primitive type (flat, curve, cylinder). I’ll start with the primitive type:

Preset "My grass is greener" 
"Primitive Type" = 1; 
"Points per Blade" = 8; 
"Density" = 50000; 
"Length" = 7.5; 
"Length Variation" = 10.0; 
"Root Width" = 2.0; 
"Start Bend Variation" = 30; 
"Bend Radius" = 2.0; 
"Bend Angle" = 90; 
"Bend Angle Variation" = 35.0; 
"Material" = "material"; 
"Double Sided Material" = "material_1"; 
Map_type = "Length Map" 
     file = "E:\MAXWELL\GrassTutDensity.png"; invert = 1; 

If you look in the MaxwellGrass.xui file, the Primitive Type parameter has a default value of 0 and a min/max of 0/2. Its combo items in the drop down are” Curve, Flat, Cylinder. So Curve is type 0, Flat is type 1, Cylinder is type 2. So my preset will use the Flat type since I’ve set its value to 1. Flat is generally preferable because it renders the fastest. Curve type is good for close-ups of grass blades where you always want to see a perfect continuous curve. If this sounds confusing, have a look at the official docs about grass.

Syntax for specifying a texture map in the preset

Adding a map is just slightly more complex, you have to start with Map_type = “Name of the map parameter”. Followed by any parameters in the texture picker you want to customize (if left out, the default value will be used). All enclosed by curly braces. I found out the actual name of the map I wanted, again by looking in the MaxwellGrass.xui file. If you don’t specify an absolute path to the texture map, it will look in the Maxwell 3 > materials database > textures folder.

Specifying materials

The parameters to specify the main grass material and the backface one simply expect the name of any materials already in the scene. Perhaps in the future this can be expanded to work more like the texture map type, ie let you specify a standalone MXM file. But for you now you could simply get into the habit of always making sure you have two MXM References in any scene you intend to use grass, and name these something like “grass” and “grass-back”. In any of your presets, always specify these two material names. Have the MXM references load any referenced MXM file you like.  This way, the preset will work ok for any scene (it will “auto-load” these two materials), and you can always change the referenced MXM without actually changing the names of “grass” and “grass-back” in the scene, which would break the connection.

Leave a Reply