14 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

Decal

Inherits from: FaceInstance → Instance → Object

The Decal object applies an image texture to a face of a parent BasePart. The affected face is dependent on the Face property, and the size of the decal is dependent on the size of the face.

The applied image texture is determined by its ColorMapContent property. For details on how to upload images, see asset management.

For more information, review textures and decals. See also:

Texture for repeating surface images.
MeshPart.TextureContent to apply an image texture to a MeshPart.
SurfaceGui to apply an ImageLabel or ImageButton to an in-experience 3D object.

Inherits from: FaceInstance

Descendants: Texture

Memory category: GraphicsTexture

Code samples: View on Creator Hub (Changing-Decal-Texture, Fading-Decal).

Properties

Name	Type / Returns	Description
Decal.AutoLocalize	boolean	When set to `true`, the decal's image asset is eligible for automatic localization capture.
Decal.Color3	Color3	The `Color3` tint of the `Decal`.
Decal.ColorMap	ContentId	Content ID that determines the color and opacity of the surface.
Decal.ColorMapContent	Content	`Content` object that determines the color and opacity of the surface.
Decal.LocalTransparencyModifier	float	Acts as a multiplier for the decal's `Transparency` property. The effects are only visible to the local player.
Decal.MetalnessMap	ContentId	Content ID that determines the metalness map of the surface.
Decal.MetalnessMapContent	Content	`Content` object that determines the metalness map of the surface.
Decal.NormalMap	ContentId	Content ID that determines the normal map of the surface.
Decal.NormalMapContent	Content	`Content` object that determines the normal map of the surface.
Decal.Rotation	float	Rotates the decal texture.
Decal.RoughnessMap	ContentId	Content ID that determines the roughness map of the surface.
Decal.RoughnessMapContent	Content	`Content` object that determines the roughness map of the surface.
Decal.Shiny	float	Deprecated property that previously set the shininess of the decal.
Decal.Specular	float	Deprecated property that previously set the specularity of the decal.
Decal.Texture	ContentId	The content ID of the image to be applied by the `Decal`.
Decal.TextureContent	Content	The texture content displayed by the `Decal`.
Decal.TexturePackContent	Content	Engine-managed `Content` that stores the compressed runtime texture-pack data for PBR decals.
Decal.Transparency	float	Determines the transparency of the `Decal`.
Decal.UVOffset	Vector2	Shifts the UV coordinates by adding an offset before texture mapping.
Decal.UVScale	Vector2	Stretches or compresses the UV coordinates by multiplying a scale factor.
Decal.ZIndex	int	Determines the rendering order when multiple decals are assigned the same face.

Inherited from FaceInstance

Name	Type / Returns	Description
FaceInstance.Face	NormalId	Sets which face of the parent `BasePart` the object appears on.

Inherited from Instance

Name	Type / Returns	Description
Instance.Archivable	boolean	Determines if an `Instance` and its descendants can be cloned using `Instance:Clone()`, and can be saved/published.
Instance.archivable	boolean
Instance.Capabilities	SecurityCapabilities	The set of capabilities allowed to be used for scripts inside this container.
Instance.IsInSandbox	boolean	Indicates whether the instance is inside a sandboxed container.
Instance.Name	string	A non-unique identifier of the `Instance`.
Instance.Parent	Instance	Determines the hierarchical parent of the `Instance`.
Instance.PredictionMode	PredictionMode	Reflects the client-side prediction mode applied to the instance under server-authoritative physics.
Instance.RobloxLocked	boolean	A deprecated property that used to protect `CoreGui` objects.
Instance.Sandboxed	boolean	When enabled, the instance can only access abilities in its `Capabilities` list.
Instance.UniqueId	UniqueId	A unique identifier for the instance.

Inherited from Object

Name	Type / Returns	Description
Object.ClassName	string	A read-only string representing the class this `Object` belongs to.
Object.className	string

Decal.AutoLocalize

When set to true, the decal's image asset is eligible for automatic localization through the Automatic Asset Capture system. The LocalizationService uses this property to determine whether the decal's ColorMapContent should be captured and potentially replaced with a localized version.

This property only applies to non-PBR decals. If any PBR maps (NormalMapContent, RoughnessMapContent, or MetalnessMapContent) are set, automatic localization capture is suppressed to avoid inconsistent rendering.

Field	Value
type	boolean
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Localization
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Decal.Color3

The Color3 tint of the Decal. Note that this property only sets the tint of the decal rather than the color; unless the image associated with the Decal was originally pure white, then the color cannot be freely changed using this property.

Field	Value
type	Color3
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Code samples: View on Creator Hub (Decal-Color3).

Decal.ColorMap

This property takes a content ID to determine the color and opacity of the surface. This texture is sometimes called the albedo texture.

Field	Value
type	ContentId
tags	["NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":false,"can_save":false}
capabilities	["Basic"]

Decal.ColorMapContent

This property takes a Content object to determine the color and opacity of the surface. This texture is sometimes called the albedo texture.

Field	Value
type	Content
tags	["NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":false,"can_save":false}
capabilities	["Basic"]

Decal.LocalTransparencyModifier

Acts as a multiplier for the decal's Transparency property. The effect is only visible to the LocalPlayer and will not replicate to the server.

When this property is set to 1, the Decal will be completely invisible regardless of its original transparency. When it is set to 0, the decal's rendered transparency will match the Transparency value.

Field	Value
type	float
tags	["Hidden","NotReplicated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":false,"can_save":false}
capabilities	["Basic"]

Decal.MetalnessMap

This property takes a content ID that determines the metalness map applied to the surface. A metalness map controls how metallic the surface appears at each point, blending between a dielectric (non-metal) and a metallic response to light. It defaults to an empty content, in which case no metalness map is applied.

Assigning a normal, roughness, or metalness map makes the Decal a physically based rendering (PBR) surface. To assign this map from a Content object, use MetalnessMapContent.

Field	Value
type	ContentId
tags	["Hidden"]
security	{"read":"PluginSecurity","write":"PluginSecurity"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Decal.MetalnessMapContent

This property takes a Content object that determines the metalness map applied to the surface. A metalness map controls how metallic the surface appears at each point, blending between a dielectric (non-metal) and a metallic response to light. It defaults to an empty content, in which case no metalness map is applied.

Assigning a normal, roughness, or metalness map makes the Decal a physically based rendering (PBR) surface.

Field	Value
type	Content
security	{"read":"None","write":"PluginSecurity"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Decal.NormalMap

This property takes a content ID that determines the normal map applied to the surface. A normal map perturbs the surface normals used in lighting calculations, adding the appearance of fine detail such as bumps and grooves without changing the underlying geometry. It defaults to an empty content, in which case no normal map is applied.

Assigning a normal, roughness, or metalness map makes the Decal a physically based rendering (PBR) surface. To assign this map from a Content object, use NormalMapContent.

Field	Value
type	ContentId
tags	["Hidden"]
security	{"read":"PluginSecurity","write":"PluginSecurity"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Decal.NormalMapContent

This property takes a Content object that determines the normal map applied to the surface. A normal map perturbs the surface normals used in lighting calculations, adding the appearance of fine detail such as bumps and grooves without changing the underlying geometry. It defaults to an empty content, in which case no normal map is applied.

Assigning a normal, roughness, or metalness map makes the Decal a physically based rendering (PBR) surface.

Field	Value
type	Content
security	{"read":"None","write":"PluginSecurity"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Decal.Rotation

This property controls the rotation angle of the decal texture in degrees. Rotation is applied to the UV coordinates in the clockwise direction.

Field	Value
type	float
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Decal.RoughnessMap

This property takes a content ID that determines the roughness map applied to the surface. A roughness map controls how rough or smooth the surface appears at each point, which in turn determines how sharp or blurry its reflections are. It defaults to an empty content, in which case no roughness map is applied.

Assigning a normal, roughness, or metalness map makes the Decal a physically based rendering (PBR) surface. To assign this map from a Content object, use RoughnessMapContent.

Field	Value
type	ContentId
tags	["Hidden"]
security	{"read":"PluginSecurity","write":"PluginSecurity"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Decal.RoughnessMapContent

This property takes a Content object that determines the roughness map applied to the surface. A roughness map controls how rough or smooth the surface appears at each point, which in turn determines how sharp or blurry its reflections are. It defaults to an empty content, in which case no roughness map is applied.

Assigning a normal, roughness, or metalness map makes the Decal a physically based rendering (PBR) surface.

Field	Value
type	Content
security	{"read":"None","write":"PluginSecurity"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Decal.Shiny

Deprecated. This non-functional property is deprecated and should not be used in new work.

This property dictates how shiny the decal is. It takes a value between 0 and 1, where 1 is "fully shiny."

Field	Value
type	float
tags	["NotReplicated","Deprecated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":false}
capabilities	["Basic"]

Decal.Specular

Deprecated. This property no longer functions correctly and is deprecated. It should not be used in new work.

Sets the specularity, which is how the surface responds to light being shined on it.

Field	Value
type	float
tags	["NotReplicated","Deprecated"]
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":false}
capabilities	["Basic"]

Decal.Texture

Deprecated. This property has been deprecated. Use ColorMapContent for future work.

The content ID of the image to be applied by the Decal.

Field	Value
type	ContentId
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Decal.TextureContent

Deprecated. This property has been deprecated. Use ColorMapContent for future work.

The texture content displayed by the Decal. Supports asset URIs and EditableImage objects.

Field	Value
type	Content
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Decal.TexturePackContent

Managed by the engine and not accessible from scripts. A Content that holds the decal's compressed runtime texture data. When the Decal is a physically based rendering (PBR) surface, the engine packs its color, normal, roughness, and metalness maps into a single texture-pack asset and references it here. Defaults to an empty content.

Field	Value
type	Content
security	{"read":"RobloxEngineSecurity","write":"RobloxEngineSecurity"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Decal.Transparency

Determines the transparency of the Decal with 0 being completely opaque and 1 completely transparent.

Note that LocalTransparencyModifier acts as a multiplier for this transparency level and should be used when the transparency of the decal is likely to be changed by another script.

Field	Value
type	float
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Decal.UVOffset

This property controls the UV coordinate translation. The X value (U offset) and Y value (V offset) are added to every corresponding UV coordinate during texture mapping.

Field	Value
type	Vector2
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Decal.UVScale

This property controls the scale applied to the horizontal and vertical coordinates. The X value (U scale) and Y value (V scale) are multiplied by every corresponding UV coordinate during texture mapping.

Field	Value
type	Vector2
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Decal.ZIndex

This property determines the order in which decals on the same Face of a BasePart are rendered. Lower values are rendered first, so a decal with a higher ZIndex renders on top of those with a lower ZIndex.

If you're unsure whether you'll need to layer a decal between two already-existing decals in the future, use larger separations between ZIndex values such as 10 or 100 to ensure space for future decals between.

Field	Value
type	int
security	{"read":"None","write":"None"}
thread safety	ReadSafe
category	Appearance
serialization	{"can_load":true,"can_save":true}
capabilities	["Basic"]

Methods

Inherited from Instance

Name	Type / Returns	Description
Instance:AddTag	()	Applies a tag to the instance.
Instance:children	Instances	Returns an array of the object's children.
Instance:ClearAllChildren	()	This method destroys all of an instance's children.
Instance:Clone	Instance	Create a copy of an instance and all its descendants, ignoring instances that are not `Archivable`.
Instance:clone	Instance
Instance:Destroy	()	Sets the `Instance.Parent` property to `nil`, locks the `Instance.Parent` property, disconnects all connections, and calls `Destroy()` on all children.
Instance:destroy	()
Instance:FindFirstAncestor	Instance?	Returns the first ancestor of the `Instance` whose `Instance.Name` is equal to the given name.
Instance:FindFirstAncestorOfClass	Instance?	Returns the first ancestor of the `Instance` whose `Object.ClassName` is equal to the given className.
Instance:FindFirstAncestorWhichIsA	Instance?	Returns the first ancestor of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstChild	Instance?	Returns the first child of the `Instance` found with the given name.
Instance:findFirstChild	Instance
Instance:FindFirstChildOfClass	Instance?	Returns the first child of the `Instance` whose `ClassName` is equal to the given class name.
Instance:FindFirstChildWhichIsA	Instance?	Returns the first child of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstDescendant	Instance?	Returns the first descendant found with the given `Instance.Name`.
Instance:GetActor	Actor?	Returns the `Actor` associated with the Instance, if any.
Instance:GetAttribute	Variant	Returns the value which has been assigned to the given attribute name.
Instance:GetAttributeChangedSignal	RBXScriptSignal	Returns an event that fires when the given attribute changes.
Instance:GetAttributes	Dictionary	Returns a dictionary of the instance's attributes.
Instance:GetChildren	Instances	Returns an array containing all of the instance's children.
Instance:getChildren	Instances
Instance:GetDebugId	string	Returns a coded string of the debug ID used internally by Roblox.
Instance:GetDescendants	Instances	Returns an array containing all of the descendants of the instance.
Instance:GetFullName	string	Returns a string describing the instance's ancestry.
Instance:GetStyled	Variant	Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified.
Instance:GetStyledPropertyChangedSignal	RBXScriptSignal	Returns an event that fires when the given style property changes on the instance.
Instance:GetTags	Array	Gets an array of all tags applied to the instance.
Instance:HasTag	boolean	Check whether the instance has a given tag.
Instance:IsAncestorOf	boolean	Returns true if an `Instance` is an ancestor of the given descendant.
Instance:IsDescendantOf	boolean	Returns `true` if an `Instance` is a descendant of the given ancestor.
Instance:isDescendantOf	boolean
Instance:IsPropertyModified	boolean	Returns `true` if the value stored in the specified property is not equal to the code-instantiated default.
Instance:QueryDescendants	Instances	Returns an array containing all descendants of the instance that match the `selector` string.
Instance:Remove	()	Sets the object's `Parent` to `nil`, and does the same for all its descendants.
Instance:remove	()
Instance:RemoveTag	()	Removes a tag from the instance.
Instance:ResetPropertyToDefault	()	Resets a property to its default value.
Instance:SetAttribute	()	Sets the attribute with the given name to the given value.
Instance:WaitForChild	Instance	Returns the child of the `Instance` with the given name. If the child does not exist, it will yield the current thread until it does.

Inherited from Object

Name	Type / Returns	Description
Object:GetPropertyChangedSignal	RBXScriptSignal	Get an event that fires when a given property of the object changes.
Object:IsA	boolean	Returns true if an object's class matches or inherits from a given class.
Object:isA	boolean

Events

Inherited from Instance

Name	Type / Returns	Description
Instance.AncestryChanged		Fires when the `Instance.Parent` property of this object or one of its ancestors is changed.
Instance.AttributeChanged		Fires whenever an attribute is changed on the `Instance`.
Instance.ChildAdded		Fires after an object is parented to this `Instance`.
Instance.childAdded
Instance.ChildRemoved		Fires after a child is removed from this `Instance`.
Instance.DescendantAdded		Fires after a descendant is added to the `Instance`.
Instance.DescendantRemoving		Fires immediately before a descendant of the `Instance` is removed.
Instance.Destroying		Fires immediately before (or is deferred until after) the instance is destroyed via `Instance:Destroy()`.
Instance.StyledPropertiesChanged		Fires whenever any style property is changed on the instance, including when a property is set to `nil`.

Inherited from Object

Name	Type / Returns	Description
Object.Changed		Fires immediately after a property of the object changes, with some limitations.