Skip to main content

instanceTagUtil

A utility module for working with instance tags.

Functions​

observe​

</>
instanceTagUtil.observe(
tag: string,
tagAddedCallback: (instanceWithTheTag: Instance) → (),
tagRemovedCallback: ((instanceThatHadTheTag: Instance) → ())?
) → Connection

Observes the given CollectionService tag. tagAddedCallback will be automatically called on all instances with the given tag, and tagRemovedCallback (if specified) will be automatically called, being passed the instance that no no longer has the given tag. 

instanceTagUtil.observe("SomeTag", function(instanceWithTheTag)
	
end, function(instanceThatHadTheTag)
	
end)

instanceTagPromise​

</>
instanceTagUtil.instanceTagPromise(
instance: Instance,
tag: string
) → ()

Returns a promise which is resolved when the given instance has the given tag.

NOTE

The returned promise will be cancelled if instance is destroyed.

instanceTagUtil.instanceTagPromise(instance, "SomeTag", function()
	print(instance.Name, "now has the tag 'SomeTag'")
end)

addTagsToInstance​

</>
instanceTagUtil.addTagsToInstance(
instance: Instance,
tags: {string}
) → ()

Adds all tags in tags to the given instance.

instanceTagUtil.addTagsToInstance(workspace.Baseplate, {"Test"})
print(CollectionService:HasTag(workspace.Baseplate, "Test")) --> true

removeTagsFromInstance​

</>
instanceTagUtil.removeTagsFromInstance(
instance: Instance,
tags: {string}
) → ()

Removes all tags in tags from the given instance.

instanceTagUtil.addTagsToInstance(workspace.Baseplate, {"Test"})
print(CollectionService:HasTag(workspace.Baseplate, "Test")) --> true
instanceTagUtil.removeTagsFromInstance(workspace.Baseplate, {"Test"})
print(CollectionService:HasTag(workspace.Baseplate, "Test")) --> false

observeMany​

</>
instanceTagUtil.observeMany(
instance: Instance,
tagsToObserve: {string},
observer: (
newTags: {string},
oldTags: {string}?
) → ()
) → Connection

Works similar to instanceTagUtil.observe, but observes an array of tags instead of a single tag. observer will initially be immediately called being passed an array of all the tags (in tagsToObserve) that the given instance has at that time, and then called again everytime a tag (that exists in tagsToObserve) is added or removed from the given instance.

oldTags will be initially nil the first time observer is called. However whenever the observer is called again, oldTags will be be an array representing the tags the instance had during the time when observer was previously called. 

instanceTagUtil.observeMany(workspace.Part, {"Number1", "Number2"}, function(newTags, oldTags)
	print(`newTags: {newTags}, oldTags: {oldTags}`) 
end)

workspace.Part:AddTag("Number1")
workspace.Part:AddTag("Number2")

-- OUTPUT:
--> {}, nil 
--> {"Number1", "Number2"}, {}
Show raw api
{
    "functions": [
        {
            "name": "observe",
            "desc": "Observes the given [CollectionService](https://create.roblox.com/docs/reference/engine/classes/CollectionService) tag.\n`tagAddedCallback` will be automatically called on all instances with the given `tag`, and `tagRemovedCallback` (if specified)\nwill be automatically called, being passed the instance that no *no longer* has the given `tag`.\n\n```lua\ninstanceTagUtil.observe(\"SomeTag\", function(instanceWithTheTag)\n\t\nend, function(instanceThatHadTheTag)\n\t\nend)\n```",
            "params": [
                {
                    "name": "tag",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "tagAddedCallback",
                    "desc": "",
                    "lua_type": "(instanceWithTheTag: Instance) -> ()"
                },
                {
                    "name": "tagRemovedCallback",
                    "desc": "",
                    "lua_type": "((instanceThatHadTheTag: Instance) -> ())?\n"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Connection"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 29,
                "path": "src/instanceTagUtil/init.luau"
            }
        },
        {
            "name": "instanceTagPromise",
            "desc": "Returns a promise which is resolved when the given instance has the given `tag`.\n\n:::note\nThe returned promise will be cancelled if `instance` is destroyed.\n:::\n\n```lua\ninstanceTagUtil.instanceTagPromise(instance, \"SomeTag\", function()\n\tprint(instance.Name, \"now has the tag 'SomeTag'\")\nend)\n```",
            "params": [
                {
                    "name": "instance",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "tag",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 66,
                "path": "src/instanceTagUtil/init.luau"
            }
        },
        {
            "name": "addTagsToInstance",
            "desc": "Adds all tags in `tags` to the given `instance`.\n\n```lua\ninstanceTagUtil.addTagsToInstance(workspace.Baseplate, {\"Test\"})\nprint(CollectionService:HasTag(workspace.Baseplate, \"Test\")) --> true\n```",
            "params": [
                {
                    "name": "instance",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "tags",
                    "desc": "",
                    "lua_type": "{ string }"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 95,
                "path": "src/instanceTagUtil/init.luau"
            }
        },
        {
            "name": "removeTagsFromInstance",
            "desc": "Removes all tags in `tags` from the given `instance`.\n\n```lua\ninstanceTagUtil.addTagsToInstance(workspace.Baseplate, {\"Test\"})\nprint(CollectionService:HasTag(workspace.Baseplate, \"Test\")) --> true\ninstanceTagUtil.removeTagsFromInstance(workspace.Baseplate, {\"Test\"})\nprint(CollectionService:HasTag(workspace.Baseplate, \"Test\")) --> false\n```",
            "params": [
                {
                    "name": "instance",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "tags",
                    "desc": "",
                    "lua_type": "{ string }"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 112,
                "path": "src/instanceTagUtil/init.luau"
            }
        },
        {
            "name": "observeMany",
            "desc": "Works similar to [instanceTagUtil.observe], but observes an array of tags instead of a single tag. `observer`\nwill initially be immediately called being passed an array of all the tags (in `tagsToObserve`) that the given\n`instance` has at that time, and then called again everytime a tag (that exists in `tagsToObserve`) is added or removed\nfrom the given `instance`.\n\n`oldTags` will be initially `nil` the first time `observer` is called. However whenever the `observer` is called again,\n`oldTags` will be be an array representing the tags the `instance` had during the time when `observer` was *previously*\ncalled.\n\n```lua\ninstanceTagUtil.observeMany(workspace.Part, {\"Number1\", \"Number2\"}, function(newTags, oldTags)\n\tprint(`newTags: {newTags}, oldTags: {oldTags}`) \nend)\n\nworkspace.Part:AddTag(\"Number1\")\nworkspace.Part:AddTag(\"Number2\")\n\n-- OUTPUT:\n--> {}, nil \n--> {\"Number1\", \"Number2\"}, {}\n```",
            "params": [
                {
                    "name": "instance",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "tagsToObserve",
                    "desc": "",
                    "lua_type": "{ string }"
                },
                {
                    "name": "observer",
                    "desc": "",
                    "lua_type": "(newTags: { string }, oldTags: { string }?) -> ()\n"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Connection"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 144,
                "path": "src/instanceTagUtil/init.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "instanceTagUtil",
    "desc": "A utility module for working with instance tags.",
    "source": {
        "line": 6,
        "path": "src/instanceTagUtil/init.luau"
    }
}