How to use attributes in Roblox

What attributes are

Every instance already has built-in properties such as Size and Color. Attributes sit next to them, under their own heading in the Properties window, and are saved with the place. They are the easiest way to give a script a setting without editing its code, and to share a small piece of state between scripts.

Names may use letters and digits, plus periods, hyphens, slashes and underscores, up to 100 characters, and must not start with RBX, which Roblox keeps for itself. Spaces and symbols such as @ or ! are not allowed. Max Speed with a space is not allowed; use MaxSpeed.

Step 1: Read and write attributes

Insert a Part, add a number attribute Damage set to 20 in the Properties window, then put this Script inside it. It reads the setting, uses a default when the attribute is missing or the wrong type, and writes a second attribute from code.

-- Script inside a Part with a number attribute "Damage".
local part = script.Parent :: BasePart

-- A number attribute, with a default when it is missing or not a number
local function numberAttribute(instance: Instance, name: string, default: number): number
	local value = instance:GetAttribute(name)
	return if typeof(value) == "number" then value else default
end

local damage = numberAttribute(part, "Damage", 10)
print("This part deals", damage, "damage")

-- Set an attribute from code (it appears in the Properties window during Play)
part:SetAttribute("TimesTouched", 0)

part.Touched:Connect(function(hit: BasePart)
	local humanoid = hit.Parent and hit.Parent:FindFirstChildOfClass("Humanoid")
	if humanoid then
		humanoid:TakeDamage(damage)
		part:SetAttribute("TimesTouched", numberAttribute(part, "TimesTouched", 0) + 1)
	end
end)

-- All attributes at once, as a table
for name, value in part:GetAttributes() do
	print(name, "=", value)
end

Setting an attribute to nil removes it. Reading one that was never set gives nil, which is why the helper checks the type: a typo in the Properties window then falls back to the default instead of breaking the script with attempt to perform arithmetic on nil.

Step 2: React when an attribute changes

GetAttributeChangedSignal(name) fires when that one attribute changes; AttributeChanged fires for any attribute and passes its name. This is how a LocalScript can update a label whenever the server changes a player's level, with no RemoteEvent at all.

-- Script in ServerScriptService named Levels.
-- Keeps a Level attribute on each player; the client shows it.
local Players = game:GetService("Players")

Players.PlayerAdded:Connect(function(player: Player)
	player:SetAttribute("Level", 1)
	-- for this example: level up every 30 seconds
	while player.Parent do
		task.wait(30)
		local level = player:GetAttribute("Level")
		if typeof(level) == "number" then
			player:SetAttribute("Level", level + 1)
		end
	end
end)

-- LocalScript in StarterPlayerScripts named LevelWatcher.
local Players = game:GetService("Players")

local player = Players.LocalPlayer

local function show()
	print("You are level", player:GetAttribute("Level"))
end

player:GetAttributeChangedSignal("Level"):Connect(show)
show() -- also show the value it already has

Call the function once yourself after connecting, as show() does: the signal only fires on changes, so a value set before your script started would otherwise never be shown.

Step 3: What replicates, and what to trust

This makes attributes a safe way to show server state on clients, and an unsafe way to receive anything from them. A cheater can set any attribute they like on their own device, but the server keeps its own value, so as long as the server reads its own attributes, a client-side change does nothing. When the client needs to ask for a change, use a RemoteEvent and let the server decide, as the RemoteEvents guide explains.

Attributes or Value objects?

Before attributes existed, the same job was done with child objects such as IntValue, StringValue and BoolValue. Both still work.

Common errors and fixes

Open the Output window (Window menu, then Output) before you press Play.

Build it with RoCode

If you would rather not set this up by hand, RoCode can build it in the place you have open. RoCode is an independent AI agent for Roblox Studio, not made by Roblox: you describe the change in a web chat, and its Studio plugin creates the scripts and instances in your Explorer, so there is no code to paste.

With plugin 3.9 or newer RoCode can run a short playtest and read the errors, but it checks only what it chose to test, so try the changed objects yourself. How RoCode connects to Studio.

Questions

Sources and further reading

• Roblox Creator Docs: Attributes. types, naming rules and replication
• Roblox Creator Docs: Instance:SetAttribute
• Roblox Creator Docs: Instance:GetAttributeChangedSignal
• Roblox Creator Docs: Properties window. adding attributes in Studio

How the code was checked: every script on this page passes Luau's strict type checker against Roblox's API definitions (luau-lsp, 5 November 2026). A type check catches misspelt APIs and wrong types, not game logic, so playtest in Studio before you publish.