UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
FAQ
Программирование
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
CIGI Client Plugin
Rendering-Related Classes

Custom Materials

If for some reason you cannot find the appropriate base material or you need a special post-process, there is a way of creating a brand new material. This way is not recommended, as even slight changes in the engine source code can influence your material and it would not work correctly.

A custom material is a manual material implemented using XML according to the base or user material file format. Both the base and the user material can be the custom one.

Custom Base Material#

The custom base material is the same as the default one: it is read-only, non-hierarchical, referred by the name and so on.

So, the algorithm of custom base material creation is the following:

  1. Create a *.basemat material file in the target directory (all of the Unigine base materials are located in the data/core/materials/default directory).
  2. Implement the base material according to the base material file format in the created *.basemat file.
    Notice
    As any manual material, the base material doesn't need the GUID. It will be generated in run-time by its name.
    When implementing the custom base material, you can set the editable flag to 1: it will allow you to adjust the material via the Materials Editor to get the desired visual effect.
    Notice
    Despite the fact that the base material can become editable, you cannot save changes made to it via the Materials Editor, so you should manually transfer the obtained values to the *.basemat file.
  3. Specify a set of shaders - either combine existing shaders or write your own ones.
  4. Depending on the set of shaders, add required textures, parameters, and states to the base material.
  5. Check, if the new material is loaded and rendered correctly.

As an example, check the base mesh_base material (data/core/materials/default/mesh/mesh_base.basemat). It has two workflows: specular and metalness, contains a huge set of features.

  1. Declare the XML file and the base material.
    Source code (XML)
    <?xml version="1.0" encoding="utf-8"?>
    <base_material version="2.0" name="mesh_base" editable="0" parameters_prefix="m" defines="VERTEX_ATTRIBUTE_GEOMETRY">
    ...
    </base_material>

    Check the base_material element for the details.

  2. Specify shaders.
    Source code (XML)
    <shader pass="deferred" node="object_mesh_static"
    	deferred="1"
    	defines="BASE_DEFERRED"
    	two_sided_defines=",TWO_SIDED"
    	transparent_defines=",ALPHA_TEST,TRANSPARENT_BLEND"
    	vertex="core/shaders/mesh/opacity/deferred.shader"
    	fragment="core/shaders/mesh/opacity/deferred.shader"/>
    		
    <shader pass="depth_pre_pass" node="object_mesh_static"
    	deferred="1"
    	two_sided_defines=",TWO_SIDED"
    	defines="BASE_ALPHA_TEST"
    	transparent_defines=",ALPHA_TEST,TRANSPARENT_BLEND"
    	vertex="core/shaders/mesh/depth_pre_pass.shader"
    	fragment="core/shaders/mesh/depth_pre_pass.shader"/>s
     ...

    Check the shader element for the details.

  3. Specify material states.
    Source code (XML)
    <state name="ambient_light" hidden="1">1</state>
    <state name="alpha_fade"	defines="name"	hidden="1"/>
    <state name="skinned" defines="name"	hidden="1"/>
    <state name="spline" defines="name"	hidden="1"/>
    <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>
     ...

    Check the state element for the details.

  4. Set parameters.
    Source code (XML)
    <group name="Default">
    	<parameter name="material_mask" deferred="1"	shared="0" type="expression" widget="mask24">0xffffffff</parameter>
    </group>
    
    <group name="Base">
    	<parameter name="albedo_color" workflow="0" shared="0" type="color" title="Albedo"			tooltip="Albedo multiplier">1.0 1.0 1.0 1.0</parameter>
    	<parameter name="metalness" workflow="0"	shared="0" type="slider" tooltip="Metalness multiplier">0.0</parameter>
    	<parameter name="roughness" workflow="0" shared="0" type="slider" tooltip="Roughness multiplier">1.0</parameter>
    	<parameter name="specular" workflow="0" shared="0" type="slider"	title="Specular" tooltip="Specular multiplier">0.5</parameter>
    	...
    	<parameter name="triplanar_blend" base_mapping="2" type="slider" title="Triplanar blend" tooltip="Triplanar">0.5</parameter>
    </group>
     ...

    Check the parameter element for the details.

  5. Source code (XML)
    <texture unit="0" name="diffuse"	workflow="1" anisotropy="1" group="Base" tooltip="Diffuse texture, alpha channel is detail texturing modulation">core/textures/common/white.dds</texture>
    <texture unit="0" name="albedo" workflow="0" anisotropy="1" group="Base"	tooltip="Albedo texture">core/textures/common/white.dds</texture>
     ...

    Check the texture element for the details.

  6. Set bindings.
    Source code (XML)
    <bind node="object_mesh_cluster" to="object_mesh_static" defines="USE_CLUTTER_CLUSTER_PARAMETERS"/>
    <bind node="object_mesh_clutter" to="object_mesh_static" defines="USE_CLUTTER_CLUSTER_PARAMETERS"/>
    <bind node="object_mesh_dynamic" to="object_mesh_static"/>
    <bind node="object_mesh_skinned" to="object_mesh_static"/>
    ...

    Check the bind element for the details.

When the base material is ready, you can use it as any default base material.

Custom User Material#

A custom user material is similar to the custom base material except that such material is hierarchical: it has a parent material and refers to the base material. As any manual material, the custom user material cannot be renamed and its parent cannot be changed. Also changes made to parameters of such material via Materials Editor won't be saved (even if the editable flag is set).

The custom user material is implemented by programmers when it is necessary to create a material without using Materials Editor.

In *.mat file, a name of the custom user material is stored. However, its child materials can store name-based or GUID-based reference to it. A GUID for such material will be generated in run time by using its name.

The algorithm of custom user material creation is the following:

  1. Create a *.mat material file in the target directory.
  2. Implement the user material according to the material file format in the created *.mat file. As any manual material, the custom material doesn't need a GUID.
    Notice
    Specify the manual attribute for the custom material. Otherwise, the material won't be loaded as it will be treated as the run-time user material without the GUID.

In the example below, the user material is inherited from the mesh_base material and overrides its parameters:

Source code (XML)
<?xml version="1.0" encoding="utf-8"?>
<material version="2.5.0.2" name="mesh_base_1" base_material="mesh_base" manual="1">
	<parameter name="albedo_color">0 0 0 0</parameter>
	<parameter name="metalness">1</parameter>
	<parameter name="roughness">0</parameter>
</material>
Last update: 27.12.2018