Skip to main content

Attributor

Wraps an Instance so its attributes read and write like plain table fields. attributor.Key calls instance:GetAttribute("Key"), attributor.Key = value calls instance:SetAttribute("Key", value), and calling the object (attributor()) returns a dictionary snapshot of every attribute. Nothing is cached; every access goes straight to the instance, so values are always current and writes replicate exactly like normal attributes. 

local Attributor = require(path.to.Attributor)

local stats = Attributor(workspace.Dummy)

stats.Health = 100        -- workspace.Dummy:SetAttribute("Health", 100)
stats.Health -= 25        -- reads, then writes 75
print(stats.Health)       -- 75
print(stats.MissingKey)   -- nil, the attribute does not exist

for name, value in stats() do
	print(name, value)    -- every attribute on the instance
end

stats:Destroy()           -- optional; also happens when the instance is destroyed

Instance and Destroy are real fields on the object, so attributes with those two names cannot be reached through the proxy. Writes are subject to the usual SetAttribute rules (attribute names must be valid and values must be attribute-compatible types) and will error otherwise.

Credits: written by KashTheKing. No third-party dependencies.

Installation and guide: Attributor package page.

Properties​

Instance​

This item is read only and cannot be modified. Read Only
</>
Attributor.Instance: Instance

The wrapped instance. Becomes nil once the Attributor is destroyed.

Functions​

new​

</>
Attributor.new(
instance: Instance--

The instance whose attributes the proxy reads and writes.

) → Attributor--

A proxy where proxy.Name gets and proxy.Name = value sets the attribute Name.

Creates an attribute proxy for instance. The module itself is this function, so call it as Attributor(instance). The proxy connects to instance.Destroying and cleans itself up when the instance is destroyed, so calling Attributor:Destroy yourself is only needed when you want to drop the wrapper earlier than that.

Destroy​

</>
Attributor:Destroy() → ()

Detaches the proxy from its instance: clears Attributor.Instance so the instance can be garbage collected and removes the metatable, so later reads return nil and later writes only touch the now-plain table. Does not destroy or modify the instance. Safe to call more than once; also runs automatically when the instance is destroyed.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Creates an attribute proxy for `instance`. The module itself is this function, so call it as\n`Attributor(instance)`. The proxy connects to `instance.Destroying` and cleans itself up when the\ninstance is destroyed, so calling [Attributor:Destroy](#Destroy) yourself is only needed when you\nwant to drop the wrapper earlier than that.",
            "params": [
                {
                    "name": "instance",
                    "desc": "The instance whose attributes the proxy reads and writes.",
                    "lua_type": "Instance"
                }
            ],
            "returns": [
                {
                    "desc": "A proxy where `proxy.Name` gets and `proxy.Name = value` sets the attribute `Name`.",
                    "lua_type": "Attributor"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 91,
                "path": "packages/src/Attributor/init.luau"
            }
        },
        {
            "name": "Destroy",
            "desc": "Detaches the proxy from its instance: clears [Attributor.Instance](#Instance) so the\ninstance can be garbage collected and removes the metatable, so later reads return `nil`\nand later writes only touch the now-plain table. Does not destroy or modify the instance.\nSafe to call more than once; also runs automatically when the instance is destroyed.\n\n\t",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 109,
                "path": "packages/src/Attributor/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "Instance",
            "desc": "The wrapped instance. Becomes `nil` once the Attributor is destroyed.",
            "lua_type": "Instance",
            "readonly": true,
            "source": {
                "line": 44,
                "path": "packages/src/Attributor/init.luau"
            }
        }
    ],
    "types": [],
    "name": "Attributor",
    "desc": "Wraps an `Instance` so its attributes read and write like plain table fields. `attributor.Key`\ncalls `instance:GetAttribute(\"Key\")`, `attributor.Key = value` calls\n`instance:SetAttribute(\"Key\", value)`, and calling the object (`attributor()`) returns a\ndictionary snapshot of every attribute. Nothing is cached; every access goes straight to the\ninstance, so values are always current and writes replicate exactly like normal attributes.\n\n```lua\nlocal Attributor = require(path.to.Attributor)\n\nlocal stats = Attributor(workspace.Dummy)\n\nstats.Health = 100        -- workspace.Dummy:SetAttribute(\"Health\", 100)\nstats.Health -= 25        -- reads, then writes 75\nprint(stats.Health)       -- 75\nprint(stats.MissingKey)   -- nil, the attribute does not exist\n\nfor name, value in stats() do\n\tprint(name, value)    -- every attribute on the instance\nend\n\nstats:Destroy()           -- optional; also happens when the instance is destroyed\n```\n\n`Instance` and `Destroy` are real fields on the object, so attributes with those two names cannot\nbe reached through the proxy. Writes are subject to the usual `SetAttribute` rules (attribute\nnames must be valid and values must be attribute-compatible types) and will error otherwise.\n\n**Credits:** written by KashTheKing. No third-party dependencies.\n\nInstallation and guide: [Attributor package page](/docs/packages/attributor).",
    "source": {
        "line": 36,
        "path": "packages/src/Attributor/init.luau"
    }
}