rojo/.cursor/rules/roblox/reference/engine/classes/MaterialVariant.yaml

# This file is automatically generated. Please don't edit it manually.
# To submit a bug report on the content, see
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72

name: MaterialVariant
type: class
memory_category: Instances
summary: |
  Represent a variant of a Material.
description: |
  Using MaterialVariant objects can expand the variety of materials in an
  experience. MaterialVariant has properties that can define the appearance of a
  material. Its name can be set in MaterialService to globally override a
  built-in material, or set in the `Class.BasePart.MaterialVariant` property to
  change certain Parts. MaterialVariant objects only work as descendants of
  MaterialService.
code_samples: []
inherits:
  - Instance
descendants: []
tags: []
deprecation_message: ''
properties:
  - name: MaterialVariant.AlphaMode
    summary: |
      Determines how the alpha channel of the `Class.MaterialVariant.ColorMap`
      is used.
    description: |
      This property determines how the alpha channel of the
      `Class.MaterialVariant.ColorMap` is used.

      When set to `Enum.AlphaMode|Transparency` and the
      `Class.MeshPart.Transparency` is set to `0`, opaque pixels in the
      `Class.MaterialVariant.ColorMap|ColorMap` renders as completely opaque in
      the 3D scene. This combination works better with depth-based effects and
      occlusion.

      When set to `Enum.AlphaMode|Transparency` and the
      `Class.MeshPart.Transparency` is set to at least `0.02`, a different
      blending method is used that can better represent smooth transparency
      gradients and soft edges. This combination does not support all effects
      and occlusion may not be perfect.

      For more information, see
      [Alpha modes](../../../art/modeling/surface-appearance.md#alpha-modes).
    code_samples: []
    type: AlphaMode
    tags:
      - NotBrowsable
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities: []
  - name: MaterialVariant.BaseMaterial
    summary: |
      Category Material this variant belongs to.
    description: |
      Category Material this variant belongs to.
    code_samples: []
    type: Material
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities: []
  - name: MaterialVariant.ColorMap
    summary: |
      Determines the color of the surface.
    description: |
      This property determines the color of the surface. This texture is
      sometimes called the albedo texture. The alpha channel is not used.
    code_samples: []
    type: ContentId
    tags: []
    deprecation_message: ''
    security:
      read: PluginSecurity
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities: []
  - name: MaterialVariant.ColorMapContent
    summary: |
      Determines the color of the surface. Only supports asset URIs as textures.
    description: |
      This property determines the color of the surface. This texture is
      sometimes called the albedo texture. The alpha channel is not used.
    code_samples: []
    type: Content
    tags: []
    deprecation_message: ''
    security:
      read: PluginSecurity
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities: []
  - name: MaterialVariant.CustomPhysicalProperties
    summary: ''
    description: ''
    code_samples: []
    type: PhysicalProperties
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Material
    serialization:
      can_load: true
      can_save: true
    capabilities: []
  - name: MaterialVariant.EmissiveMaskContent
    summary: |
      Determines the emissivity across the surface.
    description: |
      This property determines the apparent emissivity across the surface. An
      emissive mask is a grayscale image where black pixels correspond to no
      emissivity, and white pixels correspond to full emissivity.

      The emissive contribution gets added to total lighting contribution across
      the surface, and the sum gets multiplied by the albedo texture, which
      would be sampled from `Class.MaterialVariant.ColorMap|ColorMap` if
      provided.
    code_samples: []
    type: Content
    tags: []
    deprecation_message: ''
    security:
      read: PluginSecurity
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities: []
  - name: MaterialVariant.EmissiveStrength
    summary: |
      Determines the strength of emissive contribution.
    description: |
      This value is a multiplier to control how strong the emissive contribution
      is across the surface. If the final contribution of emissives goes beyond
      supported dynamic range, it will get clamped; this could result in
      emissive contribution appearing all white when using large emissive
      strength values. Since this value is a multiplier, the maximum value to
      prevent clamping depends on all of the other contributing values,
      including `Class.MaterialVariant.EmissiveTint|EmissiveTint`,
      `Class.MaterialVariant.ColorMap|ColorMap` and combined lighting
      contribution.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities: []
  - name: MaterialVariant.EmissiveTint
    summary: |
      Determines the tinting color for emissive contribution.
    description: |
      This value is an RGB color for tinting emissive contribution.
    code_samples: []
    type: Color3
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities: []
  - name: MaterialVariant.MaterialPattern
    summary: |
      Determines texture tiling method.
    description: |
      Determines texture tiling method.
    code_samples: []
    type: MaterialPattern
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities: []
  - name: MaterialVariant.MetalnessMap
    summary: |
      Determines which parts of the surface are metal and are non-metal.
    description: |
      This property determines which parts of the surface are metal and are
      non-metal. A metalness map is a grayscale image where black pixels
      correspond to non-metals and white pixels correspond to metals.

      Metals only reflect light the same color as the metal, and they reflect
      much more light than non-metals. Most materials in the real world can be
      categorized either metals or non-metals. For this reason, most pixels in a
      metalness map will be either pure black or pure white. Values in between
      are typically used to simulate dirt or grunge on top of an underlying
      metal area.

      When `Class.Lighting.EnvironmentSpecularScale` is 0, metalness has no
      effect. For the most realistic reflections, setting
      EnvironmentSpecularScale and `Class.Lighting.EnvironmentDiffuseScale` to
      1, and `Class.Lighting.Ambient` and `Class.Lighting.OutdoorAmbient` to
      (0,0,0) is recommended.
    code_samples: []
    type: ContentId
    tags: []
    deprecation_message: ''
    security:
      read: PluginSecurity
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities: []
  - name: MaterialVariant.MetalnessMapContent
    summary: |
      Determines which parts of the surface are metal and are non-metal. Only
      supports asset URIs as textures.
    description: |
      This property determines which parts of the surface are metal and are
      non-metal. A metalness map is a grayscale image where black pixels
      correspond to non-metals and white pixels correspond to metals.

      Metals only reflect light the same color as the metal, and they reflect
      much more light than non-metals. Most materials in the real world can be
      categorized either metals or non-metals. For this reason, most pixels in a
      metalness map will be either pure black or pure white. Values in between
      are typically used to simulate dirt or grunge on top of an underlying
      metal area.

      When `Class.Lighting.EnvironmentSpecularScale` is 0, metalness has no
      effect. For the most realistic reflections, setting
      EnvironmentSpecularScale and `Class.Lighting.EnvironmentDiffuseScale` to
      1, and `Class.Lighting.Ambient` and `Class.Lighting.OutdoorAmbient` to
      (0,0,0) is recommended.
    code_samples: []
    type: Content
    tags: []
    deprecation_message: ''
    security:
      read: PluginSecurity
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities: []
  - name: MaterialVariant.NormalMap
    summary: |
      Modifies the lighting of the surface by adding bumps, dents, cracks, and
      curves without adding more polygons.
    description: |
      This property modifies the lighting of the surface by adding bumps, dents,
      cracks, and curves without adding more polygons.

      Normal maps are RGB images that modify the surface's normal vector used
      for lighting calculations. The R, G, and B channels of the NormalMap
      correspond to the X, Y, and Z components of the local surface vector
      respectively, and byte values of 0 and 255 for each channel correspond
      linearly to normal vector components of -1 and 1.016 respectively. This
      range is stretched slightly from -1 to 1 so that a byte value of 127 maps
      to exactly 0. The normal vector's Z axis is always defined as the
      direction of the underlying mesh's normal. A uniform (127,127,255) image
      translates to a completely flat normal map where the normal is everywhere
      perpendicular to the mesh surface. This format is called "tangent space"
      normal maps. Roblox does not support world space or object space normal
      maps.

      Incorrectly flipped normal components can make bumps appear like indents.
      If you import a normal map and notice the lighting looks off, you may need
      to invert the G channel of the image. The X and Y axes of the tangent
      space frame correspond to the X and Y directions in the image after it's
      transformed by the mesh UVs. If you view your normal map in an image
      editor as if it were displayed on a surface, normals pointing towards the
      right side of the screen should appear more red, and normals pointing
      towards the top side of your screen should appear more green.

      The terms "DirectX format" and "OpenGL format" are sometimes used to
      describe whether the G channel of the normal map is inverted or not.
      Roblox expects the OpenGL format.

      Roblox expects imported meshes to include tangents. Modeling software may
      also refer to this as "tangent space" information. If you apply a normal
      map and it does not seem to make any visual difference, you may need to
      re-export your mesh along with its tangent information from modeling
      software.
    code_samples: []
    type: ContentId
    tags: []
    deprecation_message: ''
    security:
      read: PluginSecurity
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities: []
  - name: MaterialVariant.NormalMapContent
    summary: |
      Modifies the lighting of the surface by adding bumps, dents, cracks, and
      curves without adding more polygons. Only supports asset URIs as textures.
    description: |
      This property modifies the lighting of the surface by adding bumps, dents,
      cracks, and curves without adding more polygons.

      Normal maps are RGB images that modify the surface's normal vector used
      for lighting calculations. The R, G, and B channels of the NormalMap
      correspond to the X, Y, and Z components of the local surface vector
      respectively, and byte values of 0 and 255 for each channel correspond
      linearly to normal vector components of -1 and 1.016 respectively. This
      range is stretched slightly from -1 to 1 so that a byte value of 127 maps
      to exactly 0. The normal vector's Z axis is always defined as the
      direction of the underlying mesh's normal. A uniform (127,127,255) image
      translates to a completely flat normal map where the normal is everywhere
      perpendicular to the mesh surface. This format is called "tangent space"
      normal maps. Roblox does not support world space or object space normal
      maps.

      Incorrectly flipped normal components can make bumps appear like indents.
      If you import a normal map and notice the lighting looks off, you may need
      to invert the G channel of the image. The X and Y axes of the tangent
      space frame correspond to the X and Y directions in the image after it's
      transformed by the mesh UVs. If you view your normal map in an image
      editor as if it were displayed on a surface, normals pointing towards the
      right side of the screen should appear more red, and normals pointing
      towards the top side of your screen should appear more green.

      The terms "DirectX format" and "OpenGL format" are sometimes used to
      describe whether the G channel of the normal map is inverted or not.
      Roblox expects the OpenGL format.

      Roblox expects imported meshes to include tangents. Modeling software may
      also refer to this as "tangent space" information. If you apply a normal
      map and it does not seem to make any visual difference, you may need to
      re-export your mesh along with its tangent information from modeling
      software.
    code_samples: []
    type: Content
    tags: []
    deprecation_message: ''
    security:
      read: PluginSecurity
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities: []
  - name: MaterialVariant.RoughnessMap
    summary: |
      Determines the apparent roughness across the surface.
    description: |
      This property determines the apparent roughness across the surface. A
      roughness map is a grayscale image where black pixels correspond to a
      maximally smooth surface, and white pixels correspond to a maximally rough
      surface.

      Roughness refers to how much variation the surface has on a very small
      scale. Reflections on smooth surfaces are sharp and concentrated.
      Reflections on rough surfaces are more blurry and dispersed.
    code_samples: []
    type: ContentId
    tags: []
    deprecation_message: ''
    security:
      read: PluginSecurity
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities: []
  - name: MaterialVariant.RoughnessMapContent
    summary: |
      Determines the apparent roughness across the surface. Only supports asset
      URIs as textures.
    description: |
      This property determines the apparent roughness across the surface. A
      roughness map is a grayscale image where black pixels correspond to a
      maximally smooth surface, and white pixels correspond to a maximally rough
      surface.

      Roughness refers to how much variation the surface has on a very small
      scale. Reflections on smooth surfaces are sharp and concentrated.
      Reflections on rough surfaces are more blurry and dispersed.
    code_samples: []
    type: Content
    tags: []
    deprecation_message: ''
    security:
      read: PluginSecurity
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities: []
  - name: MaterialVariant.StudsPerTile
    summary: |
      Determines the scale of textures.
    description: |
      Determines the scale of textures. Larger values for this property will
      lead to the textures appearing larger, and repeating less frequently.
    code_samples: []
    type: float
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities: []
methods: []
events: []
callbacks: []