Component

Bind components to Roblox instances using the Component class and CollectionService tags.

NOTE

The Component class is made by sleitnick, this is just a modified variant of it which includes case changes (from PascalCase to camelCase), bug & edgecase fixes and performance improvements.

To avoid confusion of terms:

• Component refers to this module.
• Component Class (e.g. MyComponent through this documentation) refers to a class created via Component.new
• Component Instance refers to an instance of a component class.
• Roblox Instance refers to the Roblox instance to which the component instance is bound.

Methods and properties are tagged with the above terms to help clarify the level at which they are used.

Types

ExtensionFn

</>

type ExtensionFn = (component) → ()

ExtensionShouldFn

</>

type ExtensionShouldFn = (component) → boolean

Extension

</>

interface Extension {

shouldExtend: ExtensionShouldFn?

shouldConstruct: ExtensionShouldFn?

constructing: ExtensionFn?

constructed: ExtensionFn?

starting: ExtensionFn?

started: ExtensionFn?

stopping: ExtensionFn?

stopped: ExtensionFn?

}

An extension allows the ability to extend the behavior of components. This is useful for adding injection systems or extending the behavior of components by wrapping around component lifecycle methods.

The shouldConstruct function can be used to indicate if the component should actually be created. This must return true or false. A component with multiple shouldConstruct extension functions must have them all return true in order for the component to be constructed. The shouldConstruct function runs before all other extension functions and component lifecycle methods.

The shouldExtend function can be used to indicate if the extension itself should be used. This can be used in order to toggle an extension on/off depending on whatever logic is appropriate. If no shouldExtend function is provided, the extension will always be used if provided as an extension to the component.

As an example, an extension could be created to simply log when the various lifecycle stages run on the component:

local Logger = {}
function Logger.constructing(component, componentClass) print("constructing", component) end
function Logger.constructed(component, componentClass) print("constructed", component) end
function Logger.starting(component, componentClass) print("starting", component) end
function Logger.started(component, componentClass) print("started", component) end
function Logger.stopping(component, componentClass) print("stopping", component) end
function Logger.stopped(component, componentClass) print("stopped", component) end

local MyComponent = Component.new({tag = "MyComponent", extensions = {Logger}})

Sometimes it is useful for an extension to control whether or not a component should be constructed. For instance, if a component on the client should only be instantiated for the local player, an extension might look like this, assuming the instance has an attribute linking it to the player's UserId:

local player = game:GetService("Players").LocalPlayer

local OnlyLocalPlayer = {}
function OnlyLocalPlayer.shouldConstruct(component)
	local ownerId = component.instance:GetAttribute("OwnerId")
	return ownerId == player.UserId
end

local MyComponent = Component.new({tag = "MyComponent", extensions = {OnlyLocalPlayer}})

It can also be useful for an extension itself to turn on/off depending on various contexts. For example, let's take the Logger from the first example, and only use that extension if the bound instance has a Log attribute set to true:

function Logger.shouldExtend(component)
	return component.instance:GetAttribute("Log") == true
end

ComponentConfig

</>

interface ComponentConfig {

tag: string--

CollectionService tag to use

ancestors: {Instance}?--

Optional array of ancestors in which components will be started

extensions: {Extension}?--

Optional array of extension objects

}

Component configuration passed to Component.new.

• If no ancestors option is included, it defaults to {workspace, game.Players}.
• If no extensions option is included, it defaults to a blank table {}.

Properties

started

EventComponent Class

</>

Component.started: Signal

Fired when a new instance of a component is started.

local MyComponent = Component.new({tag = "MyComponent"})

MyComponent.started:Connect(function(component) end)

stopped

EventComponent Class

</>

Component.stopped: Signal

Fired when an instance of a component is stopped.

local MyComponent = Component.new({tag = "MyComponent"})

MyComponent.stopped:Connect(function(component) end)

instance

Component Instance

</>

Component.instance: Instance

A reference back to the Roblox instance from within a component instance. When a component instance is created, it is bound to a specific Roblox instance, which will always be present through the Instance property.

MyComponent.started:Connect(function(component)
	local robloxInstance: Instance = component.instance
	print("Component is bound to " .. robloxInstance:GetFullName())
end)

Functions

new

Component

</>

Component.new(config: ComponentConfig) → ComponentClass

Create a new custom Component class.

local MyComponent = Component.new({tag = "MyComponent"})

A full example might look like this:

local MyComponent = Component.new({
	tag = "MyComponent",
	ancestors = {workspace},
	extensions = {Logger}, -- See Logger example within the example for the Extension type
})

local AnotherComponent = require(somewhere.AnotherComponent)

-- Optional if UpdateRenderStepped should use BindToRenderStep:
MyComponent.renderPriority = Enum.renderPriority.Camera.Value

function MyComponent:construct()
	self.MyData = "Hello"
end

function MyComponent:start()
	local another = self:component(AnotherComponent)
	another:DoSomething()
end

function MyComponent:stop()
	self.MyData = "Goodbye"
end

function MyComponent:heartbeatUpdate(dt)
end

function MyComponent:steppedUpdate(time, dt)
end

function MyComponent:renderSteppedUpdate(dt)
end

fromTag

Component

</>

Component.fromTag(tag: string) → ComponentClass?

Returns the component class bound to the given tag, if found.

fromTagPromise

Component

</>

Component.fromTagPromise(tag: string) → Promise

Promisified version of Component.fromTag.

heartbeatUpdate

Component Class

</>

Component.heartbeatUpdate(dt: number) → ()

If this method is present on a component, then it will be automatically connected to RunService.Heartbeat.

TIP

Component will only ever hook up 1 heartbeat connection for every single component instance. As of writing, in sleitnick's variant, a heartbeat connection is hooked up for each component instance, which is not scalable for large scale operations.

Method

This is a method, not a function. This is a limitation of the documentation tool which should be fixed soon.

local MyComponent = Component.new({tag = "MyComponent"})

function MyComponent:heartbeatUpdate(dt)
end

steppedUpdate

Component Class

</>

Component.steppedUpdate(

time: number,

dt: number

) → ()

If this method is present on a component, then it will be automatically connected to RunService.Stepped.

TIP

Component will only ever hook up 1 stepped connection for every single component instance. As of writing, in sleitnick's variant, a stepped connection is hooked up for each component instance, which is not scalable for large scale operations.

Method

This is a method, not a function. This is a limitation of the documentation tool which should be fixed soon.

local MyComponent = Component.new({tag = "MyComponent"})

function MyComponent:steppedUpdate(time, dt)
end

renderSteppedUpdate

This item only works when running on the client. ClientComponent Class

</>

Component.renderSteppedUpdate(dt: number) → ()

If this method is present on a component, then it will be automatically connected to RunService.RenderStepped. If the [Component].renderPriority field is found, then the component will instead use RunService:BindToRenderStep() to bind the function.

TIP

Component will only ever hook up 1 render stepped connection for every single component instance. As of writing, in sleitnick's variant, a render stepped connection is hooked up for each component instance , which is not scalable for large scale operations.

However, if renderPriority is specified, then a new render stepped connection will be hooked up for the component instance.

Method

This is a method, not a function. This is a limitation of the documentation tool which should be fixed soon.

-- Example that uses `RunService.RenderStepped` automatically:

local MyComponent = Component.new({tag = "MyComponent"})

function MyComponent:renderSteppedUpdate(dt)
end

-- Example that uses `RunService:BindToRenderStep` automatically:

local MyComponent = Component.new({tag = "MyComponent"})

-- Defining a renderPriority will force the component to use BindToRenderStep instead
MyComponent.renderPriority = Enum.renderPriority.Camera.Value

function MyComponent:renderSteppedUpdate(dt)
end

all

Component Class

</>

Component:all() → {Component}

Gets a copy table array of all existing component objects. For example, if there was a component class linked to the "MyComponent" tag, and three Roblox instances in your game had that same tag, then calling all would return the three component instances.

local MyComponent = Component.new({tag = "MyComponent"})

-- ...

local components = MyComponent:all()
for _,component in components do
	component:DoSomethingHere()
end

fromInstance

Component Class

</>

Component:fromInstance(instance: Instance) → Component?

Gets an instance of a component class from the given Roblox instance. Returns nil if not found.

local MyComponent = require(somewhere.MyComponent)

local myComponentInstance = MyComponent:fromInstance(workspace.SomeInstance)

fromInstancePromise

Component Class

</>

Component:fromInstancePromise(

instance: Instance,

timeout: number?

) → Promise<ComponentInstance>

Resolves a promise once the component instance is present on a given Roblox instance.

An optional timeout can be provided to reject the promi se if it takes more than timeout seconds to resolve. If no timeout is supplied, timeout defaults to 60 seconds.

local MyComponent = require(somewhere.MyComponent)

MyComponent:fromInstancePromise(workspace.SomeInstance):andThen(function(myComponentInstance)
	-- Do something with the component class
end)

construct

Component Class

</>

Component:construct() → ()

construct is called before the component is started, and should be used to construct the component instance.

WARNING

You should handle any potential data loading (or any code that needs to yield) in the construct method, as the component will not be started unless all other components bound to the same instance have been constructed. This addresses Issue 127.

A warn will be outputted in the console after about 10 seconds if there are still other pending components not yet fully constructed, while this component is awaiting to be started. You should ensure all your components construct within reasonable amount of time!

Cancellation

If this method has not yet finished when the component instance is stopped, then it will be forcefully stopped.

local MyComponent = Component.new({tag = "MyComponent"})

function MyComponent:construct()
	self.SomeData = 32
	self.OtherStuff = "HelloWorld"
end

start

Component Class

</>

Component:start() → ()

start is called when the component is started, and all other component instances of the instance bound to the component are ready. At this point in time, it is safe to grab other components also bound to the same instance.

Cancellation

If this method has not yet finished when the component instance is stopped, then it will be forcefully stopped.

local MyComponent = Component.new({tag = "MyComponent"})
local AnotherComponent = require(somewhere.AnotherComponent)

function MyComponent:start()
	-- e.g., grab another component:
	local another = self:component(AnotherComponent)
end

stop

Component Class

</>

Component:stop() → ()

stop is called when the component is stopped. This occurs either when the bound instance is removed from one of the whitelisted ancestors or when the matching tag is removed from the instance. This also means that the instance might be destroyed, and thus it is not safe to continue using the bound instance (e.g. self.instance) any longer.

This should be used to clean up the component.

local MyComponent = Component.new({tag = "MyComponent"})

function MyComponent:stop()
	self.SomeStuff:destroy()
end

component

Component Instance

</>

Component:component(componentClass: ComponentClass) → Component?

Retrieves another component instance bound to the same Roblox instance.

local MyComponent = Component.new({tag = "MyComponent"})
local AnotherComponent = require(somewhere.AnotherComponent)

function MyComponent:start()
	local another = self:component(AnotherComponent)
end