rojo/.cursor/rules/roblox/reference/engine/classes/SurfaceAppearance.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: SurfaceAppearance
type: class
memory_category: Instances
summary: |
  An object that allows developers to override the appearance of a MeshPart with
  advanced graphics options.
description: |
  **SurfaceAppearance** objects let you override the appearance of a
  `Class.MeshPart` with advanced graphics options. Most notably, it can apply a
  set of **Physically‑Based Rendering** (PBR) texture images, or maps, on a
  single object. Combining multiple texture maps can more accurately simulate
  color, roughness, and reflectivity in any lighting environment and can enhance
  the visual elements of your assets and environment; see
  [PBR Textures](../../../art/modeling/surface-appearance.md) for more details.

  <figure>
  <img src="/assets/modeling/surface-appearance/SurfaceAppearance-Example-1.jpg" width="405" alt="A realistic leafy bush" />
  <img src="/assets/modeling/surface-appearance/SurfaceAppearance-Example-3.jpg" width="405" alt="A realistic mossy rock" />
  </figure>

  Appearance of this object on a `Class.MeshPart` depends on the user's device
  and graphics quality level. For best results, you may want to preview your
  content with different quality level settings.

  Note that most `Class.SurfaceAppearance` properties cannot be modified by
  scripts, as the necessary pre-processing is usually too expensive during
  runtime.
code_samples: []
inherits:
  - Instance
descendants: []
tags: []
deprecation_message: ''
properties:
  - name: SurfaceAppearance.AlphaMode
    summary: |
      Determines how the alpha channel of the `Class.SurfaceAppearance.ColorMap`
      is used.
    description: |
      This property determines how the alpha channel of the
      `Class.SurfaceAppearance.ColorMap` is used.

      When set to `Enum.AlphaMode|Transparency` and the
      `Class.MeshPart.Transparency` is set to `0`, opaque pixels in the
      `Class.SurfaceAppearance.ColorMap|ColorMap` will render 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.

      See [here](../../../art/modeling/surface-appearance.md#alpha-modes) for
      more information.
    code_samples: []
    type: AlphaMode
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Basic
  - name: SurfaceAppearance.Color
    summary: |
      Applies a tint to your existing colormap. Set directly with color picker
      or programmatically with `Datatype.Color3`.
    description: |
      Applies a tint to your existing colormap. Set directly with color picker
      or programmatically with `Datatype.Color3`.
    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:
      - Basic
  - name: SurfaceAppearance.ColorMap
    summary: |
      Determines the color and opacity of the surface.
    description: |
      This property determines the color and opacity of the surface. This
      texture is sometimes called the **albedo** texture. The alpha channel of
      this texture controls its opacity, which behaves differently based on the
      `Class.SurfaceAppearance.AlphaMode` setting.

      See [here](../../../art/modeling/surface-appearance.md#color-albedo) for
      more information.
    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:
      - Basic
  - name: SurfaceAppearance.ColorMapContent
    summary: ''
    description: ''
    code_samples: []
    type: Content
    tags:
      - Hidden
    deprecation_message: ''
    security:
      read: None
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Basic
  - name: SurfaceAppearance.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.SurfaceAppearance.ColorMap|ColorMap` if
      provided.
    code_samples: []
    type: Content
    tags: []
    deprecation_message: ''
    security:
      read: None
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Basic
  - name: SurfaceAppearance.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.SurfaceAppearance.EmissiveTint|EmissiveTint`,
      `Class.SurfaceAppearance.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:
      - Basic
  - name: SurfaceAppearance.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:
      - Basic
  - name: SurfaceAppearance.MetalnessMap
    summary: |
      Determines which parts of the surface are metal or non-metal.
    description: |
      This property determines which parts of the surface are metal or
      non-metal. The 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 pixels in a metalness map will be
      either pure black or pure white, while values in between can be 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, it's recommended to set
      `Class.Lighting.EnvironmentSpecularScale` and
      `Class.Lighting.EnvironmentDiffuseScale` to 1, as well as
      `Class.Lighting.Ambient` and `Class.Lighting.OutdoorAmbient` to
      `(0, 0, 0)`.

      See [here](../../../art/modeling/surface-appearance.md#metalness) for more
      information.
    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:
      - Basic
  - name: SurfaceAppearance.MetalnessMapContent
    summary: ''
    description: ''
    code_samples: []
    type: Content
    tags:
      - Hidden
    deprecation_message: ''
    security:
      read: None
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Basic
  - name: SurfaceAppearance.NormalMap
    summary: |
      Modifies the lighting of the surface by adding bumps, dents, cracks, and
      curves.
    description: |
      This property modifies the lighting of the surface by adding bumps, dents,
      cracks, and curves, without adding more polygons. The normal map is an RGB
      image that modifies the surface's normal vector used for lighting
      calculations. Its **R**, **G**, and **B** channels 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 referred to as a "tangent space"
      normal map. Note that 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 also 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 the
      modeling software.

      See [here](../../../art/modeling/surface-appearance.md#normal) for more
      information.
    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:
      - Basic
  - name: SurfaceAppearance.NormalMapContent
    summary: ''
    description: ''
    code_samples: []
    type: Content
    tags:
      - Hidden
    deprecation_message: ''
    security:
      read: None
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Basic
  - name: SurfaceAppearance.RoughnessMap
    summary: |
      Determines the apparent roughness across the surface.
    description: |
      This property determines the apparent roughness across the surface. The
      roughness map is a grayscale image where black pixels correspond to a
      maximally smooth surface, and white pixels correspond to a maximally rough
      surface.

      Note that surface roughness works on a very small scale. Reflections on
      smooth surfaces are sharp and concentrated, while reflections on rough
      surfaces are more blurry and dispersed.

      See [here](../../../art/modeling/surface-appearance.md#roughness) for more
      information.
    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:
      - Basic
  - name: SurfaceAppearance.RoughnessMapContent
    summary: ''
    description: ''
    code_samples: []
    type: Content
    tags:
      - Hidden
    deprecation_message: ''
    security:
      read: None
      write: PluginSecurity
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Basic
  - name: SurfaceAppearance.TexturePack
    summary: ''
    description: ''
    code_samples: []
    type: ContentId
    tags: []
    deprecation_message: ''
    security:
      read: RobloxEngineSecurity
      write: RobloxEngineSecurity
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: true
    capabilities:
      - Basic
methods: []
events: []
callbacks: []