Attributes

The attribute system allows you to access custom data attached to any Instance.

---

The core functions return an Attribute Table, which is a standard Lua table with the following structure:

• .Name (string): The name of the attribute.

• .TypeName (string): The data type of the attribute (e.g., "string", "CoordinateFrame", "Rect2D").

• .Value: The attribute's value. The format of this value depends on its TypeName.

---

:GetAttributes()

Retrieves a table containing all attributes attached to the Instance. This is the most efficient way to inspect every attribute on an object at once.

The function returns an array-like table where each element is another table representing a single attribute. Each attribute table contains three key-value pairs:

• .Name (string): The name of the attribute.

• .TypeName (string): The type of the attribute (e.g., "string", "Color3", "number").

• .Value: The actual value of the attribute, with a data type matching its TypeName.

Returns

• (table) An array of attribute tables.

Example: Inspecting All Attributes

This example iterates through all attributes on a Part named "TestPart" and prints their details.

local testPart = game.Workspace.TestPart
local allAttributes = testPart:GetAttributes()

print("Attributes for: " .. testPart.Name)

for _, attr in ipairs(allAttributes) do
    -- attr is a table like { Name = "TestName", TypeName = "string", Value = "TestValue" }
    print(string.format(" -> Name: %s, Type: %s", attr.Name, attr.TypeName))
end

Expected Output:

Attributes for: TestPart
 -> Name: MyString, Type: string
 -> Name: MyColor, Type: Color3
 -> Name: IsActive, Type: boolean

:GetAttribute(string: name)

Finds and returns a single attribute by its exact name. This is the simplest way to get the value of a specific, known attribute.

Parameters

• name (string): The case-sensitive name of the attribute to find.

Returns

• (table) An attribute table with .Name, .TypeName, and .Value fields if found.

• nil if no attribute with the specified name exists on the Instance.

Example: Retrieving a Specific Attribute

This example looks for an attribute named "SpecialID" and prints its value.

local testPart = game.Workspace.TestPart
local idAttribute = testPart:GetAttribute("SpecialID")

if idAttribute then
    -- The attribute was found, we can safely access its value
    print("Found attribute 'SpecialID'.")
    print("  - Type: " .. idAttribute.TypeName)
    print("  - Value: " .. tostring(idAttribute.Value))
else
    print("Attribute 'SpecialID' was not found on the part.")
end

---

:GetFirstAttributeOfType(string: TypeName)

Finds and returns the first attribute that matches the given type name. This is useful when you need to find data of a certain kind but don't care about its specific name.

Parameters

• typeName (string): The case-sensitive type of the attribute to find (e.g., "Color3", "Vector3", "string").

Returns

• (table) The first attribute table found that matches the type.

• nil if no attributes of the specified type exist on the Instance.

Example: Finding a Color Attribute

This example finds the first Color3 attribute on a part, regardless of its name, and applies that color to the part itself.

local testPart = game.Workspace.TestPart
local colorAttribute = testPart:GetFirstAttributeOfType("Color3")

if colorAttribute then
    print(string.format("Found a Color3 attribute named '%s'.", colorAttribute.Name))
    
    -- The value is a Color3 object, which can be assigned directly
    testPart.Color = colorAttribute.Value
    print("Applied the attribute's color to the part.")
else
    print("No Color3 attributes were found on this part.")
end

---

Attribute Data Types

The .Value field of a returned Attribute Table can be one of several types. Here’s how to access the data for each TypeName.

Primitive Types

These are returned as standard Lua types.

TypeName	Lua Type	Description
string	string	A standard string of text.
double	number	A floating-point number. Also used for Number.
bool	boolean	A true or false value.
BrickColor	integer	The numerical ID of a BrickColor.

Example

local strAttr = part:GetAttribute("MyString")
print(strAttr.Value) -- prints the string directly

local numAttr = part:GetAttribute("MyNumber")
print(numAttr.Value * 2) -- Can be used in math

Object Types

These are returned as custom userdata objects or tables.

• Color3

  The .Value is a Color3 object. You can access its components with .R, .G, and .B.

  local colorAttr = part:GetFirstAttributeOfType("Color3")
  if colorAttr then
      -- The value is a Color3 object
      local r, g, b = colorAttr.Value.R, colorAttr.Value.G, colorAttr.Value.B
      print(string.format("Color: R=%.2f, G=%.2f, B=%.2f", r, g, b))
  end

• Vector3

  The .Value is a Vector3 object with .X, .Y, and .Z components.

  local vectorAttr = part:GetAttribute("MyVector")
  if vectorAttr then
      local pos = vectorAttr.Value
      print("Position: " .. pos.X .. ", " .. pos.Y .. ", " .. pos.Z)
  end

• Vector2

  The .Value is a Lua table with .X and .Y number fields.

  local vector2Attr = part:GetAttribute("MyVector2")
  if vector2Attr then
      print(string.format("Vector2 Value: X=%d, Y=%d", vector2Attr.Value.X, vector2Attr.Value.Y))
  end

• CoordinateFrame

  The .Value is a Lua table containing the CFrame's components, each being a Vector3 object.

  local cfAttr = part:GetFirstAttributeOfType("CoordinateFrame")
  if cfAttr then
      local cfValue = cfAttr.Value
      print("CFrame Position: " .. tostring(cfValue.Position))
      print("CFrame LookVector: " .. tostring(cfValue.LookVector))
  end

• Rect2D

  The .Value is a Lua table containing .Min and .Max fields, both of which are tables representing a 2D vector ({X, Y}).

  local rectAttr = part:GetFirstAttributeOfType("Rect2D")
  if rectAttr then
      local rect = rectAttr.Value
      print(string.format("Rect: Min(%d, %d), Max(%d, %d)", 
          rect.Min.X, rect.Min.Y, rect.Max.X, rect.Max.Y))
  end

• UDim

  The .Value is a Lua table with a .Scale (number) and .Offset (integer) field.

  local udimAttr = part:GetFirstAttributeOfType("UDim")
  if udimAttr then
      local udim = udimAttr.Value
      print(string.format("UDim: Scale=%.2f, Offset=%d", udim.Scale, udim.Offset))
  end