Guides
PBR textures in Roblox: SurfaceAppearance maps, sizes and common mistakes
How PBR works in Roblox: SurfaceAppearance maps (color, normal, roughness, metalness, emissive), texture sizes, OpenGL normal maps and common mistakes.
3 min read
Quick answer
How do PBR textures work in Roblox?
Add a SurfaceAppearance object to a MeshPart and point its properties at uploaded images: ColorMap, NormalMap, RoughnessMap, MetalnessMap and an emissive mask. Together they describe colour, surface bumps, shininess and metal, so the mesh responds correctly to Roblox's lighting. They override the MeshPart's single TextureID.
The maps Roblox supports
Roblox's PBR textures guide lists five maps on a SurfaceAppearance:
- Color (albedo): the surface colour, without lighting or shadows painted in. It can carry transparency, controlled by
AlphaMode(Overlay, Transparency, Tint mask, or Opaque in beta). - Normal: fine surface bumps and grooves as lighting information, without extra geometry.
- Roughness: matte versus glossy.
- Metalness: metal or not. It's usually close to all-black or all-white.
- Emissive mask: which areas glow.
Roblox's texture specifications give the image formats: albedo and normal as 24-bit RGB, and roughness, metalness and emissive as single-channel 8-bit greyscale.
For the general idea behind these maps, see PBR materials.
Setting it up
- Import each map as an image. Studio gives each one an asset ID.
- In Explorer, hover the MeshPart, click ⊕ and insert a SurfaceAppearance.
- Paste the IDs into ColorMap, NormalMap, RoughnessMap and MetalnessMap.
If you exported from Blender with the maps wired to a Principled BSDF (Base Color, Metallic, Roughness, and Normal through a Normal Map node), the Importer can bring PBR textures in with an .fbx or .gltf directly.
You generally can't change SurfaceAppearance maps from scripts during a game, because the engine pre-processes them. You can tint them with the Color property, which is cheap and handy for colour variants.
Normal maps: the two common traps
- OpenGL, not DirectX. Roblox expects tangent-space normal maps in OpenGL format. If bumps look like dents, invert the green channel.
- Tangents. Roblox expects imported meshes to include tangents. If a normal map seems to do nothing, re-export the mesh with tangent data (SurfaceAppearance reference).
How big should each map be?
Roblox supports up to 4096×4096, and it streams lower resolutions first on weaker devices. Its own guidance is to size by object: 256 for a 5×5-stud object, 512 for 10×10, 1024 for 20×20. Marketplace accessories are capped at 2048. Each extra map multiplies memory, so give background props a colour map only, or colour plus normal.
Painting the textures
You can bake maps in Blender or Substance Painter, use Studio's Texture Generator (its Quality mode produces a 4K PBR set through a SurfaceAppearance), or start from a generator that outputs PBR maps with the mesh. Generated colour maps sometimes have lighting baked in. Check for painted shadows before you use one (AI-generated textures).
Start with a textured mesh
Vi3W generates PBR textures with the mesh, laid out on its own UVs, and exports them inside a GLB, ready for the Importer. Generate a textured model in Vi3W.
Frequently asked questions
PBR Textures not appearing
PBR textures only show if each map is a real image that's been uploaded and assigned. Blender's shader nodes don't export as PBR maps. UV-unwrap the model, bake colour, normal, roughness and metalness to images, import those images, then add a SurfaceAppearance to the MeshPart and paste each asset ID into the matching slot. A SurfaceAppearance overrides the MeshPart's TextureID.
SurfaceAppearance is Stretched and Broken When Applied to Model
SurfaceAppearance maps are laid out by the mesh's UVs. They don't tile like Roblox's built-in materials. A generic square PBR texture from a texture site won't line up with your mesh's seams. Either texture the mesh for its own UV layout (bake, paint, or use a generator that textures the specific mesh), or use a MaterialVariant for tiling surfaces.
Last reviewed