XML Base Material File Format

A GUID for the base material.

The guid attribute is optional. The GUID for the base material will be generated from its file path in runtime, if the guid attribute isn't specified.

The prefix added to all material parameters when they are passed to the shader.

The attribute that specifies names of definitions that will be passed to the shader.

The attribute indicating that the material should be used as a default material for the bound nodes.

A flag, indicating if all the base material settings can be changed in the Parameters window or via API.

Available values:

• 0 — unchangeable (by default)
• 1 — changeable

You can set the flag to 1 in the following cases:

• When implementing a custom base material: you can adjust it via the Parameters window to achieve the desired result and then transfer the obtained values to the *.basemat file.
• When customizing an existing base material that is used for a specific effect (e.g., a postprocess material): instead of inheriting a user material that stores a couple of changed parameters, you can adjust the base material so one material corresponds to one effect.

A flag, indicating if a material is displayed in the Materials Hierarchy.

Available values:

• 0 — displayed (by default)
• 1 — hidden

A flag, indicating if the Options section is displayed for the material in the Common tab.

Available values:

• 0 — displayed (by default)
• 1 — hidden

A flag, indicating if the material preview is displayed.

Available values:

• 0 — displayed (by default)
• 1 — hidden

The material namespace.

For example, to create the custom base material named custom_base, create a file custom_base.basemat and type:

<base_material parameters_prefix="m" editable="0">
...
</base_material>

A polygon color (source image) and a screen buffer color (destination image) multipliers.

Available values for both attributes:

• none — blending is not used.
• zero — RGBA components of the source/destination image color are multiplied by zero.
• one — RGBA components of the source/destination image color are multiplied by one.
• src_color — RGBA components of the source/destination image color are multiplied by the mR, mG, mB, mA components (per component).
• one_minus_src_color — RGBA components of the source/destination image color are multiplied by the 1 -  mR , 1 -  mG , 1 -  mB , 1 -  mA components (per component).
• src_alpha — RGBA components of the source/destination image color are multiplied by the mA component.
• one_minus_src_alpha — RGBA components of the source/destination image color are multiplied by the 1 -  mA component.
• dest_color — RGBA components of the source/destination image color are multiplied by the bR, bG, bB, bA components (per component).
• one_minus_dest_color — RGBA components of the source/destination image color are multiplied by the 1 -  bR , 1 -  bG , 1 -  bB , 1 -  bA components (per component).
• dest_alpha — RGBA components of the source/destination image color are multiplied by the bA component.
• one_minus_dest_alpha — RGBA components of the source/destination image color are multiplied by the 1 -  bA component.

  Where mR, mG, mB, mA are normalized Red, Blue, Green and Alpha material image channels;
  bR, bG, bB, bA are normalized Red, Blue, Green and Alpha background image channels.

For example, if you want the opaque areas to receive a material color and transparent areas to receive a screen buffer color, type:

<blend src="one" dest="one_minus_src_alpha"/>

In the Parameters window, blending option value can be set in the Transparency section of the Common tab.

Rendering order of the material. Specifies the priority of the material rendering.

Available values:

• -128 — 127. The default value is 0. The higher the rendering order, the lower the rendering priority (the material with the -128 order will be rendered first).

A shadow mask used to control shadows cast by an object lit by light sources.

Available values:

• Integer, representing a mask. The default value is ~0.

A viewport mask.

Available values:

• Integer, representing a mask. The default value is ~0.

A flag indicating whether the material is transparent.

Available values:

• 0 — the material is opaque
• 1 — the Alpha test blending preset.
• 2 — the Alpha blend, Additive, Multiplicative or Custom blending preset.

A flag indicating if writing in the depth buffer is enabled for a material.

Available values:

• 0 — not used
• 1 — used (by default)

A flag indicating if the native depth pre-pass is performed for a material.

Available values:

• 0 — is performed
• 1 — not performed

A flag indicating if an Overlap option is enabled for a material.

Available values:

• 0 — disabled (by default)
• 1 — enabled

A flag indicating if a Two Sided option is enabled for a material.

Available values:

• 0 — disabled (by default)
• 1 — enabled

A flag indicating if a Depth Test option is enabled for a material.

Available values:

• 0 — disabled
• 1 — enabled (by default)

A flag indicating if a Cast Proj and Omni Shadow option is enabled for a material.

Available values:

• 0 — disabled
• 1 — enabled (by default)

A flag indicating if a Cast World shadow option is enabled for a material.

Available values:

• 0 — disabled
• 1 — enabled (by default)

For example, to enable an Alpha test option, type:

<options alpha_test="1"/>

In the Parameters window, a common option value can be set in the Options section of the Common tab.

Name of the group.

For example, some states of the mesh_base material can be grouped as follows:

<base_material name="mesh_base" editable="0" parameters_prefix="m" defines="VERTEX_ATTRIBUTE_GEOMETRY">
	<group name="Default">
		<state name="workflow" items="metalness,specular" defines="items"/>
		<state name="deferred" title="Deferred Buffers" tooltip="Deferred buffers rendering">1</state>
		<state name="multiple_environment_probes" transparent="2" defines="name">0</state>
	</group>
</base_material>

Or the group attribute can be used instead of the corresponding element:

<base_material name="mesh_base" editable="0" parameters_prefix="m" defines="VERTEX_ATTRIBUTE_GEOMETRY">
	<state name="workflow" items="metalness,specular" defines="items" group="Default"/>
	<state name="deferred" title="Deferred Buffers" group="Default">1</state>
	<state name="multiple_environment_probes" transparent="2" defines="name" group="Default">0</state>
</base_material>

Name of the state.

Below are some of the values available:

• terrain_lerp — Replace material's albedo texture by the projected albedo texture of the ObjectTerrainGlobal to ensure smooth blending with the terrain. Used in the mesh_base material.
• use_taa — Enable Temporal Anti-Aliasing for the post material. Enabling this state has an impact on performance, as TAA in this case is applied twice (stage of the rendering sequence plus for the post material).

A flag indicating whether the state is hidden in the Materials Hierarchy

A type of the the state value.

Available values:

• toggle — a switch that enables/disables the state
• switch — a multiple values switch
• int — an integer value

A set of available items for a multiple values switch.

A flag indicating that this state is a switch enabling or disabling a group.

<state name="additional_mask" switch_group="Additional mask"/>

The attribute that specifies names of definitions that will be passed to the shader:

<state name="vertex_color" defines="name"/>

<state name="workflow" items="metalness,specular" defines="items"/>

<state name="opacity_map" transparent="1,2" items="main,normal" defines="name_items"/>

The attribute that specifies passes to which the definitions will be passed.

A state title that will be displayed in the editor.

A tooltip for a state. The tooltip will be displayed in the editor when the state is pointed with the mouse.

A group which a state belongs to. The attribute can be used instead the group element.

A type of the widget reqiured to set a state value.

A flag indicating if the state is internal (i.e. cannot be changed via UnigineEditor but used by internal logic). The child materials don't inherit internal states, so callbacks on these states aren't fired for them.

Available values:

• 0 — not internal (by default)
• 1 — internal

A state can have a condition specified as an attribute. For example, the following state will be displayed when the transparent option is set to Opaque or Alpha test and the Parallax state is enabled:

<state name="parallax_depth_cutout" parallax="1" transparent="0,1"/>

For example, if you want to specify the deferred pass, enabled by default, type:

<state name="deferred" type="switch" items="none,default">1</state>

Texture name.

A pass during which a texture will be rendered.

Available values:

• wireframe — the wireframe pass
• visualizer_solid — the visualizer solid pass
• deferred — the deferred pass
• auxiliary — the auxiliary pass
• emission — the emission pass
• refraction — the refraction pass
• reflection — the reflection pass
• transparent_blur — the transparent blur pass
• ambient — the ambient pass
• light_environment_probe — the environment probe pass
• light_omni — the omni-directional light pass
• light_proj — the projected light pass
• light_world — the world light pass
• light_all — the environment probe, omni-directional light, projected light, world light passes
• depth_pre_pass — the native depth pre-pass
• shadow — the shadows pass
• post — the post-process pass
• forward — the environment probe, omni-directional light, projected light, world light and ambient passes
• transparent — the forward, refraction, transparent blur passes

A type of the texture.

Available values:

• image — a standard texture image (by default).
• gbuffer_albedo — a texture that uses the G-buffer to store albedo values.
• gbuffer_shading — a texture that uses the G-buffer to store shading data.
• gbuffer_normal — a texture that uses the G-buffer to store normal values.
• gbuffer_velocity — a texture that uses the G-buffer to store velocity values.
• gbuffer_material_mask — a texture that uses the G-buffer to store material mask data.
• gbuffer_lightmap — a texture that uses the G-buffer to store lightmap values.
• gbuffer_geodetic_flat_position — a texture that uses the G-buffer to store flat plane coordinates.
• auxiliary — an auxiliary texture that is used for different post effects (an auxiliary pass).
• refraction — a texture that stores refraction data.
• transparent_blur — a 1-channel R16F mask that stores intensity of blurring for transparent materials. The mask specifies where to blur the material.
• lights — a 2D array texture of the RG11B10F format that stores diffuse light in the first layer (RGB) and specular light in the second layer (RGB).
• environment_probes — a 2D array texture of the RGBA16F format that stores reflections in the first layer (RGBA) and ambient lights in the second layer (RGBA).
• bent_normal — an RG11B10F texture that stores bent normals (RGB) used for smooth ambient lighting.
• ssao — a texture that stores SSAO (Screen Space Ambient Occlusion) data.
• ssgi — a texture that stores SSGI (Screen Space Global Illumination) data.
• ssr — a texture that stores SSR (Screen Space Reflections) data.
• ssr_depth — a texture that stores SSR (Screen Space Reflections) depth data.
• dof_mask — a texture that stores a DoF (Depth of Field) mask.
• auto_exposure — an RG16F texture that stores intensity of the exposure (R) and luminance (G).
• screen_color — a texture that stores screen color data and can be used for post effects.
• screen_color_old — a texture that stores Color Old (previous frame) data.
• screen_color_old_reprojection — a texture that stores Color Old (previous frame) Reprojection data.
• normal_unpack — a texture that stores unpacked normals. Available for the following post-effects: SSR, SSGI, SSRTGI, Shadows screen space.
• current_depth — a texture that stores current depth data for all geometry on the scene.
• opacity_depth — a texture that stores depth data for opacity geometry and can be used for soft particles and volumetrics.
• linear_depth — a texture that stores linear depth data.
• opacity_screen — a texture that stores the deferred composite and emission data.
• light_image — a texture storing the light values provided by projected light sources.
• light_shadow_depth — a texture storing depth values (used to render shadows).
• light_shadow_color — a texture used to render translucent shadows: G-channel stores depth values, R-channel - transparency values.
• transparent_environment_probes — a texture that stores environment probes rendered on transparent objects. Available only when Multiple environment probes are enabled.
• reflection_2d — a texture storing reflection values (used to render 2D reflections).
• reflection_cube — a texture storing reflection values (used to render cube-mapped reflections).
• scattering_sky_lut — a texture that stores sky scattering LUT data.
• scattering_ground_lut — a texture that stores ground scattering LUT data.
• wbuffer_constant_id — a constant texture, R32U. A texture of this type stores the ID value of the water mesh which is used to load the corresponding textures and parameters for it.
• wbuffer_diffuse — a diffuse texture. The diffuse color of the water is black, and diffuse texture is necessary for decals, that will be displayed over the water surface
• wbuffer_normal — a normal texture stores normal data for lighting, and alpha channel stores mesh transparency values (it can be used for soft intersections with water geometry)
• wbuffer_water — a water texture, RG8. It is used to create the procedural foam mask. The mask shows where the foam will be depicted
• wbuffer_wu_mask — an underwater mask texture, RGB8. The underwater mask is used only for Global water, since water mesh doesn't have an underwater mode
• wbuffer_ss_environment — an RGBA16 underwater fog texture that stores water bottom coloring values (RGB) and fog transparency (A).
• clouds_screen — an RGBA16F texture into which clouds are rendered.
• clouds_static_coverage — a texture that stores clouds static coverage data.
• clouds_dynamic_coverage — a texture that stores clouds dynamic coverage data.
• field_height_array — a heightmap texture that is used to create an additional height displacement for water surface.
• field_shoreline_array — a field shoreline texture.
• decal_depth — a texture that stores depth data for decals.
• decal_albedo — a texture that stores albedo color data for decals.
• decal_normal — a texture that stores normal data for decals.
• decal_shading -a texture that stores shading data for decals.
• procedural — a procedurally generated texture.
• filter — a filtering texture.

A number of the Texture Mapping Unit (slot) to be used for the texture. The unit specifies a slot of a shader, to which the texture will be passed. The maximum available number of units is 32, the first 16 units supports filtering. If the unit is greater or equal 16, no filtering will be used for the texture.

A texture format.

Available values:

• srgb — a standard RGB color space format.
• signed — a signed normalized format.
• integer — an integer normalized format.

A texture wrapping methods.

Available values:

• clamp — a texture is clamped along all axes
• clamp_x — a texture is clamped along X-axis
• clamp_y — a texture is clamped along Y-axis
• clamp_z — a texture is clamped along Z-axis
• border — a texture is bordered along all axes
• border_x — a texture is bordered along X-axis
• border_y — a texture is bordered along Y-axis
• border_z — a texture is bordered along Z-axis
• repeat — no wrap, a texture is tiled along all axes.

A flag, indicating if the anisotropy for the texture is enabled.

Available values:

• 0  -  disabled (by default)
• 1  -  enabled

A type of the texture filtering.

Available values:

• point   — point filtering (when enablled, disables anisotropy filtering)  
• linear   — linear filtering  
• bilinear   — bilinear filtering  

A texture title that will be displayed in the editor.

A group which a texture belongs to. The attribute is optional: you can use the group element instead.