Material Type File Specification

Material type files (*.materialtype) are in written JSON format and contain the following elements.


  • groups: A list of property groups that appear in the Inspector window of the Material Editor. Each group contains the following:
    • id: An identifier for this group that is unique to this material type. The value must be formatted in C-style.
    • displayName: The given name of this group that will appear in the Material Editor.
    • description: The given description of this group that will appear as tooltips in the Material Editor.
The general group is built-in and always available, even if there is no general group defined in the groups section. This group is typically used to contain any basic properties of this material type.
  • properties: Defines the groups of properties that can be configured in a material file. Each group is defined as a key/value pair, where key is the group id, and value is an array of property definitions.

    Material properties support the following data types:

    • Bool
    • Int
    • UInt
    • Float
    • Vector2
    • Vector3
    • Vector4
    • Color
    • Image
    • Enum


An array of references to shader files (.shader). Each reference contains the following values.

  • file: The path to the shader file. The path must be relative to the asset root or to the material type file.
  • tag: A unique name for this shader item that can be used to reference the shader from other places in the material type definition. It must be a C-Style identifier.

In this example, we reference the ShadowMap and DepthPass shaders.

"shaders": [
        "file": "../ShadowMap.shader",
        "tag": "shadowmap"
        "file": "../DepthPass.shader",
        "tag": "depth"


An array of material functors. Each one reads material property values, performs some logic or calculations, and sets shader inputs accordingly. These can be defined in Lua or C++. Each functor data contains the following:

  • type: The name of the functor type. This will be “Lua” for custom Lua script functors, or the name of specialized functor type (defined in C++).

  • args: An object containing key/value pairs of all the arguments to send to this functor. The attributes vary depending on functor type. For ‘Lua’ functors, there is a single ‘file’ argument that references the Lua file.

To do:

Need a list of available functor types and their expected arguments.

A GitHub issue has not been been created for this task. Create an issue here.

uvNameMap (optional)

This array lists default identifiers for mesh UV streams.

To do:

Need a document about UV streams.

A GitHub issue has not been been created for this task. Create an issue here.

Copyright © 2022 Open 3D Engine Contributors

Documentation Distributed under CC BY 4.0.
For our trademark, privacy and antitrust policies, code of conduct, and terms of use, please click the applicable link below or see

The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Policy page.