classy

[!IMPORTANT] Classy is actively being worked on and features are constantly being added!

✨ What Is Classy?

Classy is a lifecycle manager built on top of CollectionService that makes both composition and OOP architecture more appealing in Luau.

It is the cleaner, strictly-typed, smarter iteration of the original package, Wrapper, which is now archived. If you're using Wrapper, switch to Classy.

🚀 Why Use Classy?

👀 A Taste

Isn't this great? A quick shorthand:

-- All parts with the "KillPart" tag will now kill anything with a humanoid!
Classy.new("KillPart", function(instance: BasePart, janitor: Classy.Janitor)
	janitor:Add(instance.Touched:Connect(function(hit: BasePart)
		local humanoid = hit.Parent and hit.Parent:FindFirstChildWhichIsA("Humanoid")
		if not humanoid then
			return
		end

		humanoid.Health = 0
	end))
end, {
	ClassNames = { "BasePart" },
	Ancestors = { workspace },
}):Init()

📦 Quick Start

Install

[dependencies]
Classy = "jaeymo/classy@2.2.0"

wally install

Dependencies

🧪 Examples

Classy's best feature is that you can use function-based or class-based construction, and both build the same underlying system. Here's the class used in the examples below:

--!strict

local Classy = require(path.to.classy)

local KillPartClass = {}
KillPartClass.__index = KillPartClass

export type KillPart = typeof(setmetatable({} :: {
	Part: BasePart,
	Janitor: Classy.Janitor,
}, KillPartClass))

function KillPartClass.new(part: Instance, janitor: Classy.Janitor): KillPart
	return setmetatable({
		Part = part :: BasePart,
		Janitor = janitor,
	}, KillPartClass)
end

function KillPartClass.Init(self: KillPart)
	self.Janitor:Add(self.Part.Touched:Connect(function(hit: BasePart)
		local humanoid = hit.Parent and hit.Parent:FindFirstChildWhichIsA("Humanoid")

		if not humanoid then
			return
		end

		humanoid.Health = 0
	end))
end

function KillPartClass.DoSomething(self: KillPart)
	print(self)
end

function KillPartClass.Destroy(self: KillPart)
	print("This object has been destroyed!")
end

🏛️ Class-based construction

local KillPartClassy = Classy.newClass("KillPart", KillPartClass, {
	ClassNames = { "BasePart" },
	Ancestors = { workspace },
	Logging = true,
})

🧩 Function-based construction

local AnotherExample = Classy.new("KillPart", function(instance: Instance, janitor: Classy.Janitor)
	return KillPartClass.new(instance, janitor)
end, {
	ClassNames = { "BasePart" },
	Ancestors = { workspace },
	Logging = true,
})

▶️ Initialize

KillPartClassy:Init()
AnotherExample:Init()

🔌 Interact with applied objects

Once initialized, you can interact with applied objects directly. ObserveApplied covers both instances that are already applied and ones added later:

KillPartClassy:ObserveApplied(function(instance, applied)
	applied:GetData():DoSomething()
end)

Prefer a raw signal? KillPartClassy.InstanceAdded fires only for instances applied from now on, and InstanceRevoked fires when they are removed.

[!TIP] Building something simple that doesn't need a class? Use the shorthand from A Taste. It's the same system with less boilerplate.

⚙️ Settings

Both Classy.new and Classy.newClass accept an optional Config table (ClassyConfig) as their last argument. Every option is optional:

Classy.newClass("Door", DoorClass, {
	ClassNames = { "Model" },
	Ancestors = { workspace.Doors },
	Predicate = function(instance)
		return instance:GetAttribute("Enabled") ~= false
	end,
	NamingConvention = { Init = "Start", Destroy = "Cleanup" },
	WaitForMetadata = true,
	Logging = true,
}):Init()

[!NOTE] Lifecycle methods are automatic. After your object is constructed and registered, Classy calls its Init method (if it has one), and calls Destroy when the instance is revoked. Rename them with NamingConvention. Because the object is registered first, Init can find its own object with getComponent or GetApplied. See Lifecycle for the full order and what happens on failure.

[!NOTE] When checks run. ClassNames, Ancestors, and Predicate are checked when an instance gets the tag (or joins the game with it) and again whenever an applied instance's ancestry changes. An instance that stops passing is revoked, and it is not re-applied automatically if it passes again later. Re-tag it or call :Apply yourself.

🔄 Lifecycle

Applying an instance (from its tag, :Apply, or applyComponents) runs these steps in order:

1. Construct: your function, or your class's new, runs.
2. Register: the object becomes available through GetApplied, GetAll, and getComponent.
3. Init: your Init method runs (skipped if AutoInit = false or the method doesn't exist).
4. Initialized: Initialized becomes true and InstanceAdded fires.

Your constructor and Init are allowed to yield. Classy handles the cases that creates:

ObserveApplied only hands you initialized objects. Ones still in Init arrive through InstanceAdded when they finish.

[!NOTE] If the instance is revoked while Init is running and Init then errors, the error is not rethrown and :Apply returns nil. The error is only logged as a warning when Logging is on.

[!TIP] Since Destroy also runs after a failed Init, write it so it tolerates a half-built object.

📚 API

Constructors

Your function (or your class's new) is called with the same four arguments:

Classy.new("Door", function(instance, janitor, context, metadata)
	-- ...
end)

function DoorClass.new(instance, janitor, context, metadata)
	-- ...
end

Working with components

Every applied object is registered on its instance, so you can fetch and drive an instance's components from anywhere.

-- Grab a specific component and use it
local killPart = Classy.getComponent(workspace.Lava, "KillPart")
if killPart then
	killPart:GetData():DoSomething()
end

-- Call a method on every component the instance has
Classy.callOnAllComponents(workspace.Lava, "DoSomething")

-- Attach components at runtime, with per-component metadata.
-- The tag must be registered globally first!
Classy.registerGlobal("KillPart", KillPartClassy)

Classy.applyComponents(workspace.Lava, {
	KillPart = { Damage = 25 },
})

-- Fire a trigger
Classy.emit(workspace.Lava, "Activated", { Source = "Lever" })

[!NOTE] getComponent and GetApplied can return an object whose Init is still running. Check .Initialized if you need it finished.

Triggers

A component can declare triggers in its metadata under Triggers, mapping a trigger name to one of its methods. Classy.emit then calls that method with the context you pass:

Classy.registerGlobal("Door", DoorClassy)

Classy.applyComponents(door, {
	Door = {
		Triggers = { Activated = "Open" },
	},
})

-- Calls door's Door component: Data:Open({ Source = "Lever" })
Classy.emit(door, "Activated", { Source = "Lever" })

Component aliases

Metadata can include UseComponent (or useComponent) naming another globally registered component. Classy builds a copy of that component's Classy for the new tag, so one constructor can power many differently-configured components:

Classy.registerGlobal("Inventory", InventoryClassy)
Classy.registerGlobal("Resource", ResourceClassy)

Classy.applyComponents(player, {
	Inventory = { MaxItemAmount = 20 },

	-- Built from the Resource component instead of an "Ammo" Classy
	Ammo = {
		UseComponent = "Resource",
		StartingAmount = 0,
		MaxCount = 0,
	},
})

The alias reuses the base's constructor and config (ClassNames, AutoInit, Ancestors, Predicate, NamingConvention, Logging, RemoveTagOnCleanup, Nuke, WaitForMetadata) and gets its own tag. Its Context is a copy of the base's with tag set to the alias tag. If the base isn't registered, Classy warns and skips the component.

Metadata

Metadata passed to Apply or applyComponents is handed to your constructor as its fourth argument and saved on the instance as a JSON attribute named _<lowercase tag>_metadata (for example _door_metadata), so it must only contain JSON-serializable values (no functions or Instances). With WaitForMetadata = true, Classy waits up to 7 seconds for that attribute to exist before applying, which lets you tag an instance first and set its metadata attribute (as a JSON string) afterwards.

Global registry

Classy objects

What Classy.new and Classy.newClass return.

local applied = KillPartClassy:Apply(workspace.Lava)
if applied then
	applied:GetData():DoSomething()
end

local connection = KillPartClassy:ObserveApplied(function(instance, applied)
	applied:GetData():DoSomething()
end)

-- Later
connection:Disconnect()

[!WARNING] Revoking clears the Applied wrapper, and Classy:Destroy() clears the Classy, so don't use either afterwards. With Nuke = true (the default), revoking also clears your object's table and removes its metatable. Set Nuke = false if you need your object to stay intact after it's revoked. Don't call Classy:Destroy() while an instance is still inside its constructor.

Applied objects

The wrapper Classy keeps for each instance.

🤝 Contributing

Contributions, issues, and feature requests are welcome!

1. Fork the repo
2. Create your branch: git checkout -b feature/cool-thing
3. Commit your changes: git commit -m "Add cool thing"
4. Push and open a Pull Request

Check the issues page for things to work on.

📄 License

Released under the MIT License.