@rbxts/planck 0.3.0-alpha.2 → 0.3.0-rc.1

package/src/Scheduler.luau

@@ -1,48 +1,86 @@
---!nonstrict
 local DependencyGraph = require(script.Parent.DependencyGraph)
 local Pipeline = require(script.Parent.Pipeline)
 local Phase = require(script.Parent.Phase)
 
+type DependencyGraph<T> = DependencyGraph.DependencyGraph<T>
+type Pipeline = Pipeline.Pipeline
+type Phase = Phase.Phase
+
 local utils = require(script.Parent.utils)
-local hooks = require(script.Parent.hooks)
 local conditions = require(script.Parent.conditions)
 
 local getSystem = utils.getSystem
 local getSystemName = utils.getSystemName
+local getEventIdentifier = utils.getEventIdentifier
 
+local isSystem = utils.isSystem
 local isPhase = utils.isPhase
 local isPipeline = utils.isPipeline
-
 local isValidEvent = utils.isValidEvent
-local getEventIdentifier = utils.getEventIdentifier
+
+type GenericTable = utils.GenericTable
+type SignalLike<U...> = utils.SignalLike<U...>
+type ConnectionLike = utils.ConnectionLike
+type ConnectFn<T, U...> = utils.ConnectFn<T, U...>
+type Callback<U...> = utils.Callback<U...>
+
+export type SystemFn<U...> = utils.SystemFn<U...>
+export type InitializerSystemFn<U...> = utils.InitializerSystemFn<U...>
+export type InitializerResult<U...> = utils.InitializerResult<U...>
+
+type InternalSystem<U...> = utils.InternalSystem<U...>
+export type System<U...> = utils.System<U...>
+export type SystemTable<U...> = utils.SystemTable<U...>
+
+type Condition<U...> = conditions.Condition<U...>
+
+type Vec<T> = { T }
+type Map<K, V> = { [K]: V }
+
+type BasePlugin<T> = {
+	build: (self: T, scheduler: Scheduler<...unknown>) -> (),
+	new: (...any) -> T,
+}
+
+type PluginImpl = {
+	__index: PluginImpl,
+	build: (self: Plugin, scheduler: Scheduler<...unknown>) -> (),
+	cleanup: ((self: Plugin) -> ())?,
+	new: (...any) -> Plugin,
+}
+
+type Plugin = setmetatable<{}, PluginImpl>
+
+type SystemLog<E> = {
+	-- An Error object or message
+	e: E,
+	-- The string that will be printed
+	log: string,
+	-- The traceback as reported by the Scheduler
+	trace: string,
+}
+
+export type SystemInfo<U...> = {
+	system: InternalSystem<U...>,
+	run: InternalSystem<U...>,
+	cleanup: SystemFn<U...>?,
+	initialized: boolean,
+	name: string,
+	deltaTime: number?,
+	lastTime: number?,
+	timeLastLogged: number?,
+	recentLogs: { [string]: boolean }?,
+	logs: { SystemLog<unknown> },
+	phase: Phase,
+}
+
+type Dependent<U...> = Pipeline | Phase | System<U...>
+type Dependency = Pipeline | Phase
 
 -- Recent errors in Planks itself
 local recentLogs = {}
 local timeLastLogged = os.clock()
 
---- @type SystemFn ((U...) -> ())
---- @within Scheduler
---- Standard system function that runs every time it's scheduled
-
---- @type InitializerSystemFn ((U...) -> (SystemFn<U...> | (SystemFn<U...>, CleanupFn)))
---- @within Scheduler
---- Initializer system that returns the runtime function, optionally with cleanup
-
---- @type CleanupFn (() -> ())
---- @within Scheduler
---- Cleanup function called when system is removed
-
---- @interface SystemTable
---- @within Scheduler
---- .system SystemFn<U...> | InitializerSystemFn<U...>
---- .phase Phase?
---- .name string?
---- .runConditions {RunCondition}?
---- .[any] any
-
---- @type System SystemFn<U...> | SystemTable<U...>
---- @within Scheduler
-
 --- @class Scheduler
 ---
 --- An Object which handles scheduling Systems to run within different
@@ -52,22 +90,270 @@ local timeLastLogged = os.clock()
 local Scheduler = {}
 Scheduler.__index = Scheduler
 
-Scheduler.Hooks = hooks.Hooks
-
 --- @method addPlugin
 --- @within Scheduler
 --- @param plugin PlanckPlugin
 ---
 --- Initializes a plugin with the scheduler, see the [Plugin Docs](/docs/plugins) for more information.
-function Scheduler:addPlugin(plugin)
-	plugin:build(self)
-	table.insert(self._plugins, plugin)
+function Scheduler.addPlugin<T, U...>(
+	self: Scheduler<U...>,
+	plugin: setmetatable<{}, BasePlugin<T>>
+)
+	local _plugin = plugin :: Plugin
+	_plugin:build(self)
+
+	table.insert(self._plugins, _plugin)
 	return self
 end
 
-function Scheduler:_addHook(hook, fn)
-	assert(self._hooks[hook], `Unknown Hook: {hook}`)
-	table.insert(self._hooks[hook], fn)
+type PartialHookContext = {
+	scheduler: Scheduler<...unknown>,
+}
+
+type Hook<T> = {
+	__T: T,
+}
+
+type Hooks = {
+	SystemAdd: Hook<(context: SystemHookContext) -> ()>,
+	SystemRemove: Hook<(context: SystemHookContext) -> ()>,
+	SystemReplace: Hook<(context: SystemReplaceContext) -> ()>,
+	SystemEdited: Hook<(context: SystemEditedContext) -> ()>,
+	SystemCleanup: Hook<(context: SystemErrorContext) -> ()>,
+	SystemError: Hook<(context: SystemErrorContext) -> ()>,
+	SystemTriedRun: Hook<(context: SystemHookContext) -> ()>,
+
+	OuterSystemCall: Hook<(context: SystemCallContext) -> SystemCallHookFn>,
+	InnerSystemCall: Hook<(context: SystemCallContext) -> SystemCallHookFn>,
+	SystemCall: Hook<(context: SystemCallContext) -> SystemCallHookFn>,
+
+	PhaseAdd: Hook<(context: PhaseContext) -> ()>,
+	PhaseBegan: Hook<(context: PhaseContext) -> ()>,
+}
+
+--- @prop Hooks { [string]: string }
+--- @within Scheduler
+--- @since 0.3.0
+---
+--- See [creating plugins](/docs/plugins/creating).
+Scheduler.Hooks = (
+	{
+		SystemAdd = "SystemAdd",
+		SystemRemove = "SystemRemove",
+		SystemReplace = "SystemReplace",
+		SystemEdited = "SystemEdited",
+		SystemCleanup = "SystemCleanup",
+		SystemError = "SystemError",
+		SystemTriedRun = "SystemTriedRun",
+
+		OuterSystemCall = "OuterSystemCall",
+		InnerSystemCall = "InnerSystemCall",
+		SystemCall = "SystemCall",
+
+		PhaseAdd = "PhaseAdd",
+		PhaseBegan = "PhaseBegan",
+	} :: any
+) :: Hooks
+
+type HookId = keyof<typeof(Scheduler.Hooks)>
+
+--- @within Scheduler
+--- @since 0.3.0
+---
+--- Allows for registering hooks, see [creating plugins](/docs/plugins/creating).
+Scheduler.addHook = function<T, U...>(self: Scheduler<U...>, hook: Hook<T>, fn: T)
+	local hookId: HookId = hook :: any
+
+	assert(self._hooks[hookId], `Unknown Hook: {hook}`)
+	table.insert(self._hooks[hookId], fn)
+end
+
+--- @method _addHook
+--- @within Scheduler
+--- @deprecated 0.3.0 -- Use `Scheduler:addHook()` instead
+--- @private
+---
+--- Internal method for adding hooks maintained for backwards compatibility.
+--- Use [Scheduler:addHook] instead.
+Scheduler._addHook = Scheduler.addHook
+
+local function callHooks<U...>(
+	hooks: Vec<(PartialHookContext) -> unknown>,
+	info: PartialHookContext
+)
+	for _, hook in hooks do
+		local success, err = pcall(hook, info)
+		if not success then
+			warn("Unexpected error in hook:", err)
+		end
+	end
+end
+
+export type SystemHookContext = PartialHookContext & {
+	system: SystemInfo<...any>,
+}
+
+function Scheduler._systemAdd<U...>(
+	self: Scheduler<U...>,
+	systemInfo: SystemInfo<U...>
+)
+	local context = {
+		scheduler = self,
+		system = systemInfo,
+	}
+
+	callHooks(self._hooks["SystemAdd"], context)
+end
+
+function Scheduler._systemRemove<U...>(
+	self: Scheduler<U...>,
+	systemInfo: SystemInfo<U...>
+)
+	local context: SystemHookContext = {
+		scheduler = self,
+		system = systemInfo :: any,
+	}
+
+	callHooks(self._hooks["SystemRemove"], context)
+end
+
+export type SystemReplaceContext = PartialHookContext & {
+	new: SystemInfo<...any>,
+	old: SystemInfo<...any>,
+}
+
+function Scheduler._systemReplace<U...>(
+	self: Scheduler<U...>,
+	oldSystemInfo: SystemInfo<U...>,
+	newSystemInfo: SystemInfo<U...>
+)
+	local context: SystemReplaceContext = {
+		scheduler = self,
+		new = newSystemInfo :: any,
+		old = oldSystemInfo :: any,
+	}
+
+	callHooks(self._hooks["SystemReplace"], context)
+end
+
+export type SystemEditedContext = SystemHookContext & {
+	old: Phase,
+	new: Phase,
+}
+
+function Scheduler._systemEdited<U...>(
+	self: Scheduler<U...>,
+	systemInfo: SystemInfo<U...>,
+	old: Phase,
+	new: Phase
+)
+	local context: SystemEditedContext = {
+		scheduler = self,
+		system = systemInfo :: any,
+		new = new,
+		old = old,
+	}
+
+	callHooks(self._hooks["SystemEdited"], context)
+end
+
+export type SystemErrorContext = PartialHookContext & {
+	system: SystemInfo<...any>,
+	error: SystemLog<unknown>?,
+}
+
+function Scheduler._systemCleanup<E, U...>(
+	self: Scheduler<U...>,
+	systemInfo,
+	cleanupError: SystemLog<E>?
+)
+	local context: SystemErrorContext = {
+		scheduler = self,
+		system = systemInfo,
+		error = cleanupError,
+	}
+
+	callHooks(self._hooks["SystemCleanup"], context)
+end
+
+function Scheduler._systemError<E, U...>(
+	self: Scheduler<U...>,
+	systemInfo,
+	err: SystemLog<E>
+)
+	local context: SystemErrorContext = {
+		scheduler = self,
+		system = systemInfo,
+		error = err,
+	}
+
+	callHooks(self._hooks["SystemError"], context)
+end
+
+function Scheduler._systemTriedRun<T, U...>(self: Scheduler<U...>, systemInfo)
+	local context: SystemHookContext = {
+		scheduler = self,
+		system = systemInfo,
+	}
+
+	callHooks(self._hooks["SystemTriedRun"], context)
+end
+
+type SystemHookId = "OuterSystemCall" | "InnerSystemCall" | "SystemCall"
+
+type SystemCallHookFn = () -> ()
+type SystemCallCallback = (SystemCallContext) -> SystemCallHookFn
+export type SystemCallContext = PartialHookContext & {
+	system: SystemInfo<...any>,
+	nextFn: SystemCallHookFn,
+}
+
+function Scheduler._systemCall<T, U...>(
+	self: Scheduler<U...>,
+	hookName: SystemHookId,
+	systemInfo: SystemInfo<U...>,
+	nextFn: SystemCallHookFn
+)
+	for _, hook in self._hooks[hookName] :: Vec<SystemCallCallback> do
+		local context: SystemCallContext = {
+			scheduler = self,
+			system = systemInfo :: any,
+			nextFn = nextFn,
+		}
+
+		nextFn = hook(context)
+
+		if not nextFn then
+			local source, line = debug.info(hook, "sl")
+			warn(
+				`{source}:{line}: Expected 'SystemCall' hook to return a function`
+			)
+		end
+	end
+
+	nextFn()
+end
+
+export type PhaseContext = PartialHookContext & {
+	phase: Phase,
+}
+
+function Scheduler._phaseAdd<U...>(self: Scheduler<U...>, phase: Phase)
+	local context: PhaseContext = {
+		scheduler = self,
+		phase = phase,
+	}
+
+	callHooks(self._hooks["PhaseAdd"], context)
+end
+
+function Scheduler._phaseBegan<U...>(self: Scheduler<U...>, phase: Phase)
+	local context: PhaseContext = {
+		scheduler = self,
+		phase = phase,
+	}
+
+	callHooks(self._hooks["PhaseBegan"], context)
 end
 
 --- @method getDeltaTime
@@ -76,7 +362,7 @@ end
 ---
 --- Returns the time since the system was ran last.
 --- This must be used within a registered system.
-function Scheduler:getDeltaTime()
+function Scheduler.getDeltaTime<U...>(self: Scheduler<U...>)
 	if self._currentSystem then
 		return self._currentSystem.deltaTime or 0
 	end
@@ -91,8 +377,35 @@ function Scheduler:getDeltaTime()
 	return self._systemInfo[systemFn].deltaTime or 0
 end
 
+function Scheduler._reportLog<E, U...>(
+	_: Scheduler<U...>,
+	systemInfo: SystemInfo<U...>,
+	log: SystemLog<E>,
+	-- A warning after the error providing context
+	context: string
+)
+	local recentLogs = systemInfo.recentLogs
+	local logMessage = log.log
+
+	assert(recentLogs)
+
+	if not recentLogs[logMessage] then
+		-- LUAU FUTURE: Inference bug
+		task.spawn<<(unknown, number)>>(error, logMessage, 0)
+		warn(
+			`Planck: {context},`
+				.. " "
+				.. `this error will be ignored for 10 seconds`
+		)
+		recentLogs[logMessage] = true
+	end
+end
+
 -- Inspiration from https://github.com/matter-ecs/matter <3
-function Scheduler:_handleLogs(systemInfo)
+function Scheduler._handleLogs<U...>(
+	self: Scheduler<U...>,
+	systemInfo: SystemInfo<U...>
+)
 	if not systemInfo.timeLastLogged then
 		systemInfo.timeLastLogged = os.clock()
 	end
@@ -101,6 +414,12 @@ function Scheduler:_handleLogs(systemInfo)
 		systemInfo.recentLogs = {}
 	end
 
+	-- selene: allow(incorrect_standard_library_use)
+	do
+		assert(systemInfo.timeLastLogged)
+		assert(systemInfo.recentLogs)
+	end
+
 	if os.clock() - systemInfo.timeLastLogged > 10 then
 		systemInfo.timeLastLogged = os.clock()
 		systemInfo.recentLogs = {}
@@ -108,20 +427,22 @@ function Scheduler:_handleLogs(systemInfo)
 
 	local name = systemInfo.name
 
-	for _, logMessage in systemInfo.logs do
-		if not systemInfo.recentLogs[logMessage] then
-			task.spawn(error, logMessage, 0)
-			warn(
-				`Planck: Error occurred in system{string.len(name) > 0 and ` '{name}'` or ""}, this error will be ignored for 10 seconds`
-			)
-			systemInfo.recentLogs[logMessage] = true
-		end
+	for _, log in systemInfo.logs do
+		self:_reportLog(
+			systemInfo,
+			log,
+			`Error occurred in system{string.len(name) > 0 and ` '{name}'` or ""}`
+		)
 	end
 
 	table.clear(systemInfo.logs)
 end
 
-function Scheduler:runSystem(system, justInitialized)
+function Scheduler.runSystem<U...>(
+	self: Scheduler<U...>,
+	system: InternalSystem<U...>,
+	justInitialized: boolean
+)
 	local systemInfo = self._systemInfo[system]
 	local now = os.clock()
 
@@ -133,6 +454,7 @@ function Scheduler:runSystem(system, justInitialized)
 
 	if justInitialized ~= true then
 		if self:_canRun(system) == false then
+			self:_systemTriedRun(systemInfo)
 			return
 		end
 
@@ -155,40 +477,54 @@ function Scheduler:runSystem(system, justInitialized)
 		coroutine.resume(self._thread)
 	end
 
+	-- selene: allow(incorrect_standard_library_use)
+	assert(self._thread)
+
 	local didYield = false
 	local hasSystem = false
 
 	local function systemCall()
 		local function noYield()
 			local success, errOrSys, cleanup
+
 			coroutine.resume(self._thread, function()
 				success, errOrSys, cleanup = xpcall(function()
 					return systemInfo.run(table.unpack(self._vargs))
 				end, function(e)
-					return debug.traceback(e)
+					return {
+						e = e,
+						log = debug.traceback(tostring(e)),
+						trace = debug.traceback(),
+					}
 				end)
 			end)
 
 			if success == false then
 				didYield = true
+
+				-- selene: allow(incorrect_standard_library_use)
+				assert(errOrSys)
 				table.insert(systemInfo.logs, errOrSys)
-				hooks.systemError(self, systemInfo, errOrSys)
+				self:_systemError(systemInfo, errOrSys)
+
 				return
 			end
 
 			if self._yielded then
 				didYield = true
+
 				local source, line = debug.info(self._thread, 1, "sl")
 				local errMessage = `{source}:{line}: System yielded`
-				table.insert(
-					systemInfo.logs,
-					debug.traceback(self._thread, errMessage, 2)
-				)
-				hooks.systemError(
-					self,
-					systemInfo,
-					debug.traceback(self._thread, errMessage, 2)
-				)
+				local err = debug.traceback(self._thread, errMessage, 2)
+
+				local log = {
+					e = err,
+					log = err,
+					trace = debug.traceback(self._thread, nil, 2),
+				}
+
+				table.insert(systemInfo.logs, log :: SystemLog<unknown>)
+				self:_systemError(systemInfo, log)
 				return
 			end
 
@@ -227,29 +563,32 @@ function Scheduler:runSystem(system, justInitialized)
 					end
 				end
 
-				local err = string.format(
-					"System '%s' initializer returned invalid type. "
-						.. "Expected: function, {system?, cleanup?}, or (function, function). "
-						.. "Got: %s, %s",
-					systemInfo.name,
-					type(errOrSys),
-					type(cleanup)
-				)
-				table.insert(systemInfo.logs, err)
-				hooks.systemError(self, systemInfo, err)
+				local errMessage = `System '{systemInfo.name}' initializer returned invalid type. `
+					.. "Expected: function, {system?, cleanup?}, or (function, function). "
+					.. `Got: {typeof(errOrSys)}, {typeof(cleanup)}`
+
+				local err = debug.traceback(errMessage)
+				local log = {
+					e = err,
+					log = err,
+					trace = debug.traceback(),
+				}
+
+				table.insert(systemInfo.logs, log :: SystemLog<unknown>)
+				self:_systemError(systemInfo, log)
 				systemInfo.initialized = true
 			end
 		end
 
-		hooks.systemCall(self, "SystemCall", systemInfo, noYield)
+		self:_systemCall("SystemCall", systemInfo, noYield)
 	end
 
 	local function inner()
-		hooks.systemCall(self, "InnerSystemCall", systemInfo, systemCall)
+		self:_systemCall("InnerSystemCall", systemInfo, systemCall)
 	end
 
 	local function outer()
-		hooks.systemCall(self, "OuterSystemCall", systemInfo, inner)
+		self:_systemCall("OuterSystemCall", systemInfo, inner)
 	end
 
 	if os.clock() - timeLastLogged > 10 then
@@ -257,18 +596,18 @@ function Scheduler:runSystem(system, justInitialized)
 		recentLogs = {}
 	end
 
-	local success, err: string? = pcall(outer)
-	if not success and not recentLogs[err] then
-		task.spawn(error, err, 0)
-		warn(
-			`Planck: Error occurred while running hooks, this error will be ignored for 10 seconds`
-		)
-		hooks.systemError(
-			self,
-			systemInfo,
-			`Error occurred while running hooks: {err}`
-		)
-		recentLogs[err] = true
+	-- LUAU FUTURE: Better types for pcalls
+	local success, err = xpcall(outer :: any, function(e)
+		return {
+			e = e,
+			log = debug.traceback(`Error occurred while running hooks: {e}`),
+			trace = debug.traceback(),
+		}
+	end)
+
+	if not success then
+		self:_systemError(systemInfo, err)
+		self:_reportLog(systemInfo, err, `Error occurred while running hooks`)
 	end
 
 	if didYield then
@@ -294,23 +633,23 @@ function Scheduler:runSystem(system, justInitialized)
 	end
 end
 
-function Scheduler:runPhase(phase)
+function Scheduler.runPhase<U...>(self: Scheduler<U...>, phase: Phase)
 	if self:_canRun(phase) == false then
 		return
 	end
 
-	hooks.phaseBegan(self, phase)
+	self:_phaseBegan(phase)
 
 	if not self._phaseToSystems[phase] then
 		self._phaseToSystems[phase] = {}
 	end
 
 	for _, system in self._phaseToSystems[phase] do
-		self:runSystem(system)
+		self:runSystem(system, false)
 	end
 end
 
-function Scheduler:runPipeline(pipeline)
+function Scheduler.runPipeline<U...>(self: Scheduler<U...>, pipeline: Pipeline)
 	if self:_canRun(pipeline) == false then
 		return
 	end
@@ -326,12 +665,12 @@ function Scheduler:runPipeline(pipeline)
 	end
 end
 
-function Scheduler:_canRun(dependent)
-	local conditions = self._runIfConditions[dependent]
+function Scheduler._canRun<U...>(self: Scheduler<U...>, dependent: Dependent<U...>)
+	local runConditions = self._runIfConditions[dependent :: any]
 
-	if conditions then
-		for _, runIf in conditions do
-			if runIf(table.unpack(self._vargs)) == false then
+	if runConditions then
+		for _, runIf in runConditions do
+			if runIf and not runIf(table.unpack(self._vargs)) then
 				return false
 			end
 		end
@@ -360,19 +699,20 @@ end
 --- @return Scheduler
 ---
 --- Runs the System, passing in the arguments of the Scheduler, `U...`.
-function Scheduler:run(dependent)
-	if not dependent then
-		error("No dependent specified in Scheduler:run(_)")
-	end
+function Scheduler.run<U...>(self: Scheduler<U...>, dependent: Dependent<U...>)
+	assert(
+		dependent ~= nil,
+		"No dependent specified in Scheduler:run(dependent?)"
+	)
 
 	self:runPipeline(Pipeline.Startup)
 
-	if getSystem(dependent) then
-		self:runSystem(dependent)
+	if isSystem(dependent) then
+		self:runSystem(dependent :: any, false)
 	elseif isPhase(dependent) then
-		self:runPhase(dependent)
+		self:runPhase(dependent :: any)
 	elseif isPipeline(dependent) then
-		self:runPipeline(dependent)
+		self:runPipeline(dependent :: any)
 	else
 		error("Unknown dependent passed into Scheduler:run(unknown)")
 	end
@@ -398,7 +738,7 @@ end
 --- Pipelines/Phases in these groups are still ordered by their dependencies
 --- and by the order of insertion.
 --- :::
-function Scheduler:runAll()
+function Scheduler.runAll<U...>(self: Scheduler<U...>)
 	local orderedDefaults = self._defaultDependencyGraph:getOrderedList()
 	assert(
 		orderedDefaults,
@@ -412,9 +752,10 @@ function Scheduler:runAll()
 	for identifier, dependencyGraph in self._eventDependencyGraphs do
 		local orderedList = dependencyGraph:getOrderedList()
 		assert(
-			orderedDefaults,
+			orderedList,
 			`Event Group '{identifier}' contains a circular dependency, check your Pipelines/Phases`
 		)
+
 		for _, dependency in orderedList do
 			self:run(dependency)
 		end
@@ -423,6 +764,52 @@ function Scheduler:runAll()
 	return self
 end
 
+type InsertFn =
+	& (<U...>(
+		self: Scheduler<U...>,
+		dependency: Phase | Pipeline
+	) -> Scheduler<U...>)
+	-- RBXScriptSignal & nil
+	& (<U...>(
+		self: Scheduler<U...>,
+		dependency: Phase | Pipeline,
+		signal: RBXScriptSignal<U...>
+	) -> Scheduler<U...>)
+	-- Instance & RBXScriptSignal
+	-- Instance & string
+	& (<U...>(
+		self: Scheduler<U...>,
+		dependency: Phase | Pipeline,
+		instance: Instance,
+		event: RBXScriptSignal<U...> | string
+	) -> Scheduler<U...>)
+	-- SignalLike & nil
+	& (<U...>(
+		self: Scheduler<U...>,
+		dependency: Phase | Pipeline,
+		signal: SignalLike<U...>
+	) -> Scheduler<U...>)
+	-- table & string
+	& (<U...>(
+		self: Scheduler<U...>,
+		dependency: Phase | Pipeline,
+		table: GenericTable,
+		event: string
+	) -> Scheduler<U...>)
+	-- table & connectable method
+	& (<T, U...>(
+		self: Scheduler<U...>,
+		dependency: Phase | Pipeline,
+		instance: GenericTable,
+		connectMethod: (GenericTable, Callback<U...>, ...any) -> T
+	) -> Scheduler<U...>)
+	-- connectable function
+	& (<T, U...>(
+		self: Scheduler<U...>,
+		dependency: Phase | Pipeline,
+		connectFn: (Callback<U...>, ...any) -> T
+	) -> Scheduler<U...>)
+
 --- @method insert
 --- @within Scheduler
 --- @param phase Phase
@@ -472,7 +859,12 @@ end
 --- local myScheduler = Scheduler.new()
 ---     :insert(myPipeline, RunService, "Heartbeat")
 --- ```
-function Scheduler:insert(dependency, instance, event)
+local insertFn: InsertFn = function<U...>(
+	self: Scheduler<U...>,
+	dependency: Phase | Pipeline,
+	instance: any,
+	event: any
+): Scheduler<U...>
 	assert(
 		isPhase(dependency) or isPipeline(dependency),
 		"Unknown dependency passed to Scheduler:insert(unknown, _, _)"
@@ -492,13 +884,15 @@ function Scheduler:insert(dependency, instance, event)
 	end
 
 	if isPhase(dependency) then
-		self._phaseToSystems[dependency] = {}
-		hooks.phaseAdd(self, dependency)
+		self._phaseToSystems[dependency :: Phase] = {}
+		self:_phaseAdd(dependency :: Phase)
 	end
 
 	return self
 end
 
+Scheduler.insert = insertFn
+
 --- @method insertAfter
 --- @within Scheduler
 --- @param phase Phase
@@ -517,7 +911,11 @@ end
 --- Initializes the Pipeline and it's Phases within the Scheduler,
 --- ordering the Pipeline explicitly by setting the after Phase/Pipeline
 --- as a dependent.
-function Scheduler:insertAfter(dependent, after)
+function Scheduler.insertAfter<U...>(
+	self: Scheduler<U...>,
+	dependent: Dependency,
+	after: Dependency
+)
 	assert(
 		isPhase(after) or isPipeline(after),
 		"Unknown dependency passed in Scheduler:insertAfter(_, unknown)"
@@ -531,8 +929,8 @@ function Scheduler:insertAfter(dependent, after)
 	dependencyGraph:insertAfter(dependent, after)
 
 	if isPhase(dependent) then
-		self._phaseToSystems[dependent] = {}
-		hooks.phaseAdd(self, dependent)
+		self._phaseToSystems[dependent :: Phase] = {}
+		self:_phaseAdd(dependent :: Phase)
 	end
 
 	return self
@@ -556,7 +954,11 @@ end
 --- Initializes the Pipeline and it's Phases within the Scheduler,
 --- ordering the Pipeline explicitly by setting the before Phase/Pipeline
 --- as a dependency.
-function Scheduler:insertBefore(dependent, before)
+function Scheduler.insertBefore<U...>(
+	self: Scheduler<U...>,
+	dependent: Dependency,
+	before: Dependency
+)
 	assert(
 		isPhase(before) or isPipeline(before),
 		"Unknown dependency passed in Scheduler:insertBefore(_, unknown)"
@@ -570,8 +972,8 @@ function Scheduler:insertBefore(dependent, before)
 	dependencyGraph:insertBefore(dependent, before)
 
 	if isPhase(dependent) then
-		self._phaseToSystems[dependent] = {}
-		hooks.phaseAdd(self, dependent)
+		self._phaseToSystems[dependent :: Phase] = {}
+		self:_phaseAdd(dependent :: Phase)
 	end
 
 	return self
@@ -605,12 +1007,13 @@ end
 ---     end
 --- end
 --- ```
-function Scheduler:addSystem(system, phase)
+function Scheduler.addSystem<U...>(
+	self: Scheduler<U...>,
+	system: System<U...>,
+	phase: Phase?
+)
 	local systemFn = getSystem(system)
-
-	if not systemFn then
-		error("Unknown system passed to Scheduler:addSystem(unknown, phase?)")
-	end
+	assert(systemFn, "Unknown system passed to Scheduler:addSystem(unknown, _)")
 
 	local name = getSystemName(system)
 
@@ -623,7 +1026,7 @@ function Scheduler:addSystem(system, phase)
 		scheduledPhase = self._defaultPhase
 	end
 
-	local systemInfo = {
+	local systemInfo: SystemInfo<U...> = {
 		system = systemFn,
 		run = systemFn,
 		cleanup = nil,
@@ -633,15 +1036,18 @@ function Scheduler:addSystem(system, phase)
 		initialized = false,
 	}
 
-	self._systemInfo[systemFn] = systemInfo
+	self._systemInfo[systemFn] = systemInfo :: any
 
 	if not self._phaseToSystems[systemInfo.phase] then
 		self._phaseToSystems[systemInfo.phase] = {}
 	end
 
-	table.insert(self._phaseToSystems[systemInfo.phase], systemFn)
+	table.insert(
+		self._phaseToSystems[systemInfo.phase],
+		systemFn :: InternalSystem<...any>
+	)
 
-	hooks.systemAdd(self, systemInfo)
+	self:_systemAdd(systemInfo)
 
 	if type(system) == "table" and system.runConditions then
 		for _, condition in system.runConditions do
@@ -662,10 +1068,15 @@ end
 ---
 --- Adds the Systems to the Scheduler, scheduling them to be ran
 --- implicitly within the provided Phase or on the default Main phase.
-function Scheduler:addSystems(systems, phase)
-	if type(systems) ~= "table" then
-		error("Unknown systems passed to Scheduler:addSystems(unknown, phase?)")
-	end
+function Scheduler.addSystems<U...>(
+	self: Scheduler<U...>,
+	systems: { System<U...> },
+	phase: Phase?
+)
+	assert(
+		type(systems) == "table",
+		"Unknown value passed to Scheduler:addSystems(unknown, _). This value should be an array."
+	)
 
 	local foundSystem = false
 	local n = 0
@@ -678,15 +1089,12 @@ function Scheduler:addSystems(systems, phase)
 		end
 	end
 
-	if n == 0 then
-		error("Empty table passed to Scheduler:addSystems({ }, phase?)")
-	end
+	assert(n ~= 0, "Empty table passed to Scheduler:addSystems({ }, _)")
 
-	if not foundSystem then
-		error(
-			"Unknown table passed to Scheduler:addSystems({ unknown }, phase?)"
-		)
-	end
+	assert(
+		foundSystem,
+		"Table containing unknown values passed to Scheduler:addSystems({ unknown }, _)"
+	)
 
 	return self
 end
@@ -697,22 +1105,32 @@ end
 --- @param newPhase Phase
 ---
 --- Changes the Phase that this system is scheduled on.
-function Scheduler:editSystem(system, newPhase)
+function Scheduler.editSystem<U...>(
+	self: Scheduler<U...>,
+	system: System<U...>,
+	newPhase: Phase
+)
 	local systemFn = getSystem(system)
+	assert(
+		systemFn,
+		"Unknown system passed to Scheduler:editSystem(unknown, _)"
+	)
+
 	local systemInfo = self._systemInfo[systemFn]
 	assert(
 		systemInfo,
-		"Attempt to edit a non-existent system in Scheduler:editSystem(_)"
+		"Attempt to edit a non-existent system in Scheduler:editSystem(system, _)"
 	)
 
 	assert(
 		newPhase and self._phaseToSystems[newPhase] ~= nil or true,
-		"Phase never initialized before using Scheduler:editSystem(_, Phase)"
+		"Phase never initialized before using Scheduler:editSystem(_, phase)"
 	)
 
-	local systems = self._phaseToSystems[systemInfo.phase]
+	local oldPhase = systemInfo.phase
+	local systems = self._phaseToSystems[oldPhase]
 
-	local index = table.find(systems, systemFn)
+	local index = table.find(systems, systemFn :: InternalSystem<...any>)
 	assert(index, "Unable to find system within phase")
 
 	table.remove(systems, index)
@@ -720,17 +1138,26 @@ function Scheduler:editSystem(system, newPhase)
 	if not self._phaseToSystems[newPhase] then
 		self._phaseToSystems[newPhase] = {}
 	end
-	table.insert(self._phaseToSystems[newPhase], systemFn)
+	table.insert(
+		self._phaseToSystems[newPhase],
+		systemFn :: InternalSystem<...any>
+	)
 
 	systemInfo.phase = newPhase
+	self:_systemEdited(systemInfo :: SystemInfo<U...>, oldPhase, newPhase)
+
 	return self
 end
 
-function Scheduler:_removeCondition(dependent, condition)
-	self._runIfConditions[dependent] = nil
+function Scheduler._removeCondition<U...>(
+	self: Scheduler<U...>,
+	dependent: Dependent<U...>,
+	condition: Condition<U...>
+)
+	self._runIfConditions[dependent :: any] = nil
 
 	for _, _conditions in self._runIfConditions do
-		if table.find(_conditions, condition) then
+		if table.find(_conditions :: any, condition) then
 			return
 		end
 	end
@@ -767,47 +1194,55 @@ end
 --- -- Later...
 --- scheduler:removeSystem(networkSystem) -- Cleanup executes here
 --- ```
-function Scheduler:removeSystem(system)
+function Scheduler.removeSystem<U...>(self: Scheduler<U...>, system: System<U...>)
 	local systemFn = getSystem(system)
+	assert(systemFn, "Invalid system passed to Scheduler:removeSystem(system)")
+
 	local systemInfo = self._systemInfo[systemFn]
 	assert(
 		systemInfo,
-		"Attempt to remove a non-existent system in Scheduler:removeSystem(_)"
+		"Attempt to remove a non-existent system in Scheduler:removeSystem(system)"
 	)
 
 	if systemInfo.cleanup then
-		local success, err =
-			pcall(systemInfo.cleanup, table.unpack(self._vargs))
+		local success: boolean, err: SystemLog<unknown> = xpcall<<unknown, (nil), (
+			SystemLog<unknown>
+		)>>(systemInfo.cleanup, function(e)
+			local errMessage =
+				`Cleanup failed for system '{systemInfo.name}': {e}`
+
+			return {
+				e = e,
+				log = debug.traceback(errMessage),
+				trace = debug.traceback(),
+			}
+		end, table.unpack(self._vargs))
+
 		if success then
-			hooks.systemCleanup(self, systemInfo, nil)
+			self:_systemCleanup(systemInfo, nil)
 		else
-			local errMsg = string.format(
-				"Cleanup failed for system '%s': %s",
-				systemInfo.name,
-				tostring(err)
-			)
-			hooks.systemError(self, systemInfo, errMsg)
-			hooks.systemCleanup(self, systemInfo, errMsg)
+			self:_systemError(systemInfo, err)
+			self:_systemCleanup(systemInfo, err)
 		end
 	end
 
 	local systems = self._phaseToSystems[systemInfo.phase]
 
-	local index = table.find(systems, systemFn)
+	local index = table.find(systems :: any, systemFn)
 	assert(index, "Unable to find system within phase")
 
 	table.remove(systems, index)
 	self._systemInfo[systemFn] = nil
 
-	if self._runIfConditions[system] then
-		for _, condition in self._runIfConditions[system] do
+	if self._runIfConditions[system :: any] then
+		for _, condition in self._runIfConditions[system :: any] do
 			self:_removeCondition(system, condition)
 		end
 
-		self._runIfConditions[system] = nil
+		self._runIfConditions[system :: any] = nil
 	end
 
-	hooks.systemRemove(self, systemInfo)
+	self:_systemRemove(systemInfo :: SystemInfo<U...>)
 
 	return self
 end
@@ -818,33 +1253,49 @@ end
 --- @param new System
 ---
 --- Replaces the System with a new System.
-function Scheduler:replaceSystem(old, new)
-	local oldSystemFn = getSystem(old)
+function Scheduler.replaceSystem<U...>(
+	self: Scheduler<U...>,
+	old: System<U...>,
+	new: System<U...>
+)
+	local oldSystemFn = getSystem(old) :: InternalSystem<...any>
+	assert(
+		oldSystemFn,
+		"Attempt to pass non-system in Scheduler:replaceSystem(unknown, _)"
+	)
+
 	local oldSystemInfo = self._systemInfo[oldSystemFn]
 	assert(
 		oldSystemInfo,
-		"Attempt to replace a non-existent system in Scheduler:replaceSystem(unknown, _)"
+		"Attempt to replace a non-existent system in Scheduler:replaceSystem(system, _)"
 	)
 
-	local newSystemFn = getSystem(new)
+	local newSystemFn = getSystem(new) :: InternalSystem<...any>
 	assert(
 		newSystemFn,
 		"Attempt to pass non-system in Scheduler:replaceSystem(_, unknown)"
 	)
 
 	if oldSystemInfo.cleanup then
-		local success, err =
-			pcall(oldSystemInfo.cleanup, table.unpack(self._vargs))
+		-- LUAU FUTURE: Better types for xpcalls
+		local success: boolean, err: SystemLog<unknown> = xpcall<<unknown, (nil), (
+			SystemLog<unknown>
+		)>>(oldSystemInfo.cleanup, function(e)
+			local errMessage =
+				`Cleanup failed for system '{oldSystemInfo.name}': {e}`
+
+			return {
+				e = e,
+				log = debug.traceback(errMessage),
+				trace = debug.traceback(),
+			}
+		end, table.unpack(self._vargs))
+
 		if success then
-			hooks.systemCleanup(self, oldSystemInfo, nil)
+			self:_systemCleanup(oldSystemInfo, nil)
 		else
-			local errMsg = string.format(
-				"Cleanup failed for system '%s': %s",
-				oldSystemInfo.name,
-				tostring(err)
-			)
-			hooks.systemError(self, oldSystemInfo, errMsg)
-			hooks.systemCleanup(self, oldSystemInfo, errMsg)
+			self:_systemError(oldSystemInfo, err)
+			self:_systemCleanup(oldSystemInfo, err)
 		end
 	end
 
@@ -864,7 +1315,10 @@ function Scheduler:replaceSystem(old, new)
 	oldSystemInfo.initialized = false
 	oldSystemInfo.name = getSystemName(new)
 
-	hooks.systemReplace(self, copy, oldSystemInfo)
+	self:_systemReplace(
+		copy :: SystemInfo<U...>,
+		oldSystemInfo :: SystemInfo<U...>
+	)
 
 	self._systemInfo[newSystemFn] = self._systemInfo[oldSystemFn]
 	self._systemInfo[oldSystemFn] = nil
@@ -875,7 +1329,7 @@ end
 --- @method addRunCondition
 --- @within Scheduler
 --- @param system System
---- @param fn (U...) -> boolean
+--- @param fn (U...) -> any
 ---
 --- Adds a Run Condition which the Scheduler will check before
 --- this System is ran.
@@ -883,7 +1337,7 @@ end
 --- @method addRunCondition
 --- @within Scheduler
 --- @param phase Phase
---- @param fn (U...) -> boolean
+--- @param fn (U...) -> any
 ---
 --- Adds a Run Condition which the Scheduler will check before
 --- any Systems within this Phase are ran.
@@ -891,14 +1345,18 @@ end
 --- @method addRunCondition
 --- @within Scheduler
 --- @param pipeline Pipeline
---- @param fn (U...) -> boolean
+--- @param fn (U...) -> any
 ---
 --- Adds a Run Condition which the Scheduler will check before
 --- any Systems within any Phases apart of this Pipeline are ran.
-function Scheduler:addRunCondition(dependent, fn)
+function Scheduler.addRunCondition<U...>(
+	self: Scheduler<U...>,
+	dependent: Dependent<U...>,
+	fn: Condition<U...>
+)
 	fn = if typeof(fn) == "table" then fn[1] else fn
 
-	local system = getSystem(dependent)
+	local system: SystemFn<...any>? = getSystem(dependent :: any) :: any
 	if system then
 		dependent = system
 	end
@@ -908,30 +1366,17 @@ function Scheduler:addRunCondition(dependent, fn)
 		"Attempt to pass unknown dependent into Scheduler:addRunCondition(unknown, _)"
 	)
 
-	if not self._runIfConditions[dependent] then
-		self._runIfConditions[dependent] = {}
+	if not self._runIfConditions[dependent :: any] then
+		self._runIfConditions[dependent :: any] = {}
 	end
 
-	table.insert(self._runIfConditions[dependent], fn)
+	table.insert(self._runIfConditions[dependent :: any], fn)
 
 	return self
 end
 
-function Scheduler:_addBuiltins()
-	self._defaultPhase = Phase.new("Default")
-	self._defaultDependencyGraph = DependencyGraph.new()
-
-	self._defaultDependencyGraph:insert(Pipeline.Startup)
-	self._defaultDependencyGraph:insert(self._defaultPhase)
-
-	self:addRunCondition(Pipeline.Startup, conditions.runOnce())
-	for _, phase in Pipeline.Startup.dependencyGraph.nodes do
-		self:addRunCondition(phase, conditions.runOnce())
-	end
-end
-
-function Scheduler:_scheduleEvent(instance, event)
-	local connect = utils.getConnectFunction(instance, event)
+function Scheduler._scheduleEvent<U...>(self: Scheduler<U...>, instance, event)
+	local connect = utils.getConnectFn(instance, event)
 	assert(
 		connect,
 		"Couldn't connect to event as no valid connect methods were found! Ensure the passed event has a 'Connect' or an 'on' method!"
@@ -948,24 +1393,32 @@ function Scheduler:_scheduleEvent(instance, event)
 			local err =
 				`Event Group '{identifier}' contains a circular dependency, check your Pipelines/Phases`
 			if not recentLogs[err] then
-				task.spawn(error, err, 0)
+				-- LUAU FUTURE: Inference bug
+				task.spawn<<(string, number?)>>(error, err, 0)
 				warn(
 					`Planck: Error occurred while running event, this error will be ignored for 10 seconds`
 				)
 				recentLogs[err] = true
 			end
+
+			return
 		end
 
 		for _, dependency in orderedList do
-			self:run(dependency)
+			self:run(dependency :: any)
 		end
 	end
 
 	self._connectedEvents[identifier] = connect(callback)
-	self._eventDependencyGraphs[identifier] = dependencyGraph
+	self._eventDependencyGraphs[identifier] =
+		dependencyGraph :: DependencyGraph<Dependency>
 end
 
-function Scheduler:_getEventDependencyGraph(instance, event)
+function Scheduler._getEventDependencyGraph<U...>(
+	self: Scheduler<U...>,
+	instance,
+	event
+)
 	local identifier = getEventIdentifier(instance, event)
 
 	if not self._connectedEvents[identifier] then
@@ -975,7 +1428,10 @@ function Scheduler:_getEventDependencyGraph(instance, event)
 	return self._eventDependencyGraphs[identifier]
 end
 
-function Scheduler:_getGraphOfDependency(dependency)
+function Scheduler._getGraphOfDependency<U...>(
+	self: Scheduler<U...>,
+	dependency: Dependency
+)
 	if table.find(self._defaultDependencyGraph.nodes, dependency) then
 		return self._defaultDependencyGraph
 	end
@@ -1008,14 +1464,16 @@ end
 --- These plugins are unable to properly be cleaned up, use
 --- them with caution.
 --- :::
-function Scheduler:cleanup()
+function Scheduler.cleanup<U...>(self: Scheduler<U...>)
 	for _, connection in self._connectedEvents do
 		utils.disconnectEvent(connection)
 	end
 
 	for _, plugin in self._plugins do
-		if plugin.cleanup then
-			plugin:cleanup()
+		-- LUAU FUTURE: Type solver doesn't play nice here
+		local cleanup: ((self: Plugin) -> ())? = plugin.cleanup
+		if cleanup then
+			cleanup(plugin)
 		end
 	end
 
@@ -1036,34 +1494,64 @@ end
 ---
 --- Creates a new Scheduler, the args passed will be passed to
 --- any System anytime it is ran by the Scheduler.
-function Scheduler.new(...)
-	local self = {}
-
-	self._hooks = {}
-
-	self._vargs = { ... }
-
-	self._eventDependencyGraphs = {}
-	self._connectedEvents = {}
-
-	self._phaseToSystems = {}
-	self._systemInfo = {}
-
-	self._runIfConditions = {}
-
-	self._plugins = {}
-
-	setmetatable(self, Scheduler)
-
-	for _, hookName in hooks.Hooks do
+function Scheduler.new<U...>(...: U...): Scheduler<U...>
+	local defaultPhase = Phase.new("Default")
+	local defaultDependencyGraph: DependencyGraph<Dependency> =
+		DependencyGraph.new() :: any
+
+	defaultDependencyGraph:insert(Pipeline.Startup)
+	defaultDependencyGraph:insert(defaultPhase)
+
+	local self: Scheduler<U...> = setmetatable({
+		_defaultPhase = defaultPhase,
+		_defaultDependencyGraph = defaultDependencyGraph,
+		_eventDependencyGraphs = {},
+		_connectedEvents = {},
+		_plugins = {},
+		_phaseToSystems = {},
+		_hooks = {},
+		_runIfConditions = {},
+		_systemInfo = {},
+		_thread = nil :: any,
+		_currentSystem = nil :: any,
+		_yielded = false,
+		_vargs = { ... },
+	}, Scheduler)
+
+	for _, hookName in self.Hooks :: any do
 		if not self._hooks[hookName] then
 			self._hooks[hookName] = {}
 		end
 	end
 
-	self:_addBuiltins()
+	self:addRunCondition(Pipeline.Startup, conditions.runOnce())
+	for _, phase in Pipeline.Startup.dependencyGraph.nodes do
+		self:addRunCondition(phase, conditions.runOnce())
+	end
 
-	return self
+	return self :: Scheduler<U...>
 end
 
+export type Scheduler<U...> = setmetatable<
+	{
+		_defaultPhase: Phase,
+		_defaultDependencyGraph: DependencyGraph<Dependency>,
+		_eventDependencyGraphs: { [string]: DependencyGraph<Dependency> },
+		_connectedEvents: { [string]: utils.ConnectionLike },
+		_plugins: Vec<Plugin>,
+		-- LUAU FIXME: Should be System<U...>
+		_phaseToSystems: Map<Phase, Vec<InternalSystem<...any>>>,
+		_hooks: Map<HookId, Vec<(PartialHookContext) -> unknown>>,
+		-- LUAU FIXME: Should be <Dependent<U...>, Condition<U...>>
+		_runIfConditions: Map<Dependent<...any>, Vec<Condition<...any>>>,
+		-- LUAU FIXME: Should be SystemInfo<U...>
+		_systemInfo: Map<InternalSystem<U...>, SystemInfo<...any>>,
+		_currentSystem: SystemInfo<...any>,
+		_thread: thread?,
+		_yielded: boolean,
+		_vargs: { any },
+	},
+	typeof(Scheduler)
+>
+
 return Scheduler