/
SurfaceAppearance.yaml
237 lines (222 loc) · 9.05 KB
/
SurfaceAppearance.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
name: SurfaceAppearance
type: class
category:
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
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.BasePart.Transparency|MeshPart.Transparency` is set to 0, opaque
pixels in the `Class.SurfaceAppearance.ColorMap` will render as completely
opaque in the 3D scene. This solves various problems for textures with
different transparent and opaque areas, such as foliage. When parts of the
surface are fully opaque, the Roblox engine can render them with proper
depth-based occlusion. Opaque surfaces also generally work better with
depth-based effects like `Class.DepthOfFieldEffect`, glass and water
refraction, and water reflection.
See [here](../../../art/modeling/surface-appearance.md#alpha-modes) for
more information.
code_samples:
type: AlphaMode
tags: []
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Appearance
serialization:
can_load: true
can_save: true
- name: SurfaceAppearance.Color
summary: ''
description: ''
code_samples: []
type: Color3
tags: []
deprecation_message: ''
security:
read: None
write: None
thread_safety: ReadSafe
category: Appearance
serialization:
can_load: true
can_save: true
- 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: Content
tags: []
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Appearance
serialization:
can_load: true
can_save: true
- 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: Content
tags: []
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Appearance
serialization:
can_load: true
can_save: true
- 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: Content
tags: []
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Appearance
serialization:
can_load: true
can_save: true
- 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: Content
tags: []
deprecation_message: ''
security:
read: PluginSecurity
write: PluginSecurity
thread_safety: ReadSafe
category: Appearance
serialization:
can_load: true
can_save: true
- name: SurfaceAppearance.TexturePack
summary: ''
description: ''
code_samples: []
type: Content
tags: []
deprecation_message: ''
security:
read: RobloxSecurity
write: RobloxSecurity
thread_safety: ReadSafe
category: Appearance
serialization:
can_load: true
can_save: true
methods: []
events: []
callbacks: []