Observers

A collection of observer utility functions.

Functions

observeLocalCharacter

This item only works when running on the client. Client

</>

Observers.observeLocalCharacter(callback: Callback) → () → ()

Creates an observer that captures the local character in the game. This can only be called from client-side code.

-- In a LocalScript or Client-context script
observeLocalCharacter(function(character)
	print("Local character spawned")

	return function()
		-- Cleanup
		print("Local character removed")
	end
end)

observeTag

</>

Observers.observeTag(

tag: string,

callback: Callback<T>,

ancestors: {Instance}?

) → () → ()

Creates an observer around a CollectionService tag. The given callback will fire for each instance that has the given tag.

The callback should return a function, which will be called when the given instance's tag is either destroyed, loses the given tag, or (if the ancestors table is provided) goes outside of the allowed ancestors.

The function itself returns a function that can be called to stop the observer. This will also call any cleanup functions of currently-observed instances.

local stopObserver = Observers.observeTag("MyTag", function(instance: Instance)
	print("Observing", instance)

	-- The "cleanup" function:
	return function()
		print("Stopped observing", instance)
	end
end)

-- Optionally, the `stopObserver` function can be called to completely stop the observer:
task.wait(10)
stopObserver()

Ancestor Inclusion List

By default, the observeTag function will observe a tagged instance anywhere in the Roblox game hierarchy. The ancestors table can optionally be used, which will restrict the observer to only observe tagged instances that are descendants of instances within the ancestors table.

For instance, if a tagged instance should only be observed when it is in the Workspace, the Workspace can be added to the ancestors list. This might be useful if a tagged model prefab exist somewhere such as ServerStorage, but shouldn't be observed until placed into the Workspace.

local allowedAncestors = { workspace }

Observers.observeTag(
	"MyTag",
	function(instance: Instance)
		...
	end,
	allowedAncestors
)

observePlayer

</>

Observers.observePlayer(callback: Callback) → () → ()

Creates an observer that captures each player in the game.

observePlayer(function(player)
	print("Player entered game", player.Name)

	return function(exitReason)
		-- Cleanup
		print("Player left game", player.Name, "reason", exitReason.Name)
	end
end)

observeAttribute

</>

Observers.observeAttribute(

instance: Instance,

name: string,

callback: Callback,

guard: ((value: AttributeValue) → boolean)?

) → () → ()

Creates an observer around an attribute of a given instance. The callback will fire for any non-nil attribute value.

observeAttribute(workspace.Model, "MyAttribute", function(value)
	print("MyAttribute is now:", value)

	return function()
		-- Cleanup
		print("MyAttribute is no longer:", value)
	end
end)

An optional guard predicate function can be supplied to further narrow which values trigger the observer. For instance, if only strings are wanted:

observeAttribute(
	workspace.Model,
	"MyAttribute",
	function(value) print("value is a string", value) end,
	function(value) return typeof(value) == "string" end
)

The observer also returns a function that can be called to clean up the observer:

local stopObserving = observeAttribute(workspace.Model, "MyAttribute", function(value) ... end)

task.wait(10)
stopObserving()

observeProperty

</>

Observers.observeProperty(

instance: Instance,

property: string,

callback: Callback<unknown>

) → () → ()

Creates an observer around a property of a given instance.

observeProperty(workspace.Model, "Name", function(newName: string)
	print("New name:", name)

	return function()
		-- Cleanup
		print("Model's name is no longer:", name)
	end
end)

observeCharacter

</>

Observers.observeCharacter(

callback: Callback,

allowedPlayers: {Player}?

) → () → ()

Creates an observer that captures each character in the game.

observeCharacter(function(player, character)
	print("Character spawned for " .. player.Name)

	return function()
		-- Cleanup
		print("Character removed for " .. player.Name)
	end
end)

An optional allowedPlayers array can be provided. Only characters belonging to players in the array are observed.

observeCharacter(function(player, character)
	-- ...
end, { somePlayer, anotherPlayer })