@rbxts/planck 0.2.5 → 0.3.0-alpha.2

package/{out → src}/Scheduler.luau

@@ -1,11 +1,11 @@
 --!nonstrict
-local DependencyGraph = require("./DependencyGraph")
-local Pipeline = require("./Pipeline")
-local Phase = require("./Phase")
+local DependencyGraph = require(script.Parent.DependencyGraph)
+local Pipeline = require(script.Parent.Pipeline)
+local Phase = require(script.Parent.Phase)
 
-local utils = require("./utils")
-local hooks = require("./hooks")
-local conditions = require("./conditions")
+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
@@ -20,13 +20,24 @@ local getEventIdentifier = utils.getEventIdentifier
 local recentLogs = {}
 local timeLastLogged = os.clock()
 
---- @type SystemFn ((U...) -> any)
+--- @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...>
+--- .system SystemFn<U...> | InitializerSystemFn<U...>
 --- .phase Phase?
+--- .name string?
+--- .runConditions {RunCondition}?
 --- .[any] any
 
 --- @type System SystemFn<U...> | SystemTable<U...>
@@ -66,6 +77,10 @@ end
 --- Returns the time since the system was ran last.
 --- This must be used within a registered system.
 function Scheduler:getDeltaTime()
+	if self._currentSystem then
+		return self._currentSystem.deltaTime or 0
+	end
+
 	local systemFn = debug.info(2, "f")
 	if not systemFn or not self._systemInfo[systemFn] then
 		error(
@@ -91,7 +106,7 @@ function Scheduler:_handleLogs(systemInfo)
 		systemInfo.recentLogs = {}
 	end
 
-	local name = debug.info(systemInfo.system, "n")
+	local name = systemInfo.name
 
 	for _, logMessage in systemInfo.logs do
 		if not systemInfo.recentLogs[logMessage] then
@@ -106,16 +121,26 @@ function Scheduler:_handleLogs(systemInfo)
 	table.clear(systemInfo.logs)
 end
 
-function Scheduler:runSystem(system)
-	if self:_canRun(system) == false then
-		return
-	end
-
+function Scheduler:runSystem(system, justInitialized)
 	local systemInfo = self._systemInfo[system]
 	local now = os.clock()
 
-	systemInfo.deltaTime = now - (systemInfo.lastTime or now)
+	if not systemInfo then
+		error(
+			"Attempted to run a non-registered system, make sure it is added to the Scheduler"
+		)
+	end
+
+	if justInitialized ~= true then
+		if self:_canRun(system) == false then
+			return
+		end
+
+		systemInfo.deltaTime = now - (systemInfo.lastTime or now)
+	end
+
 	systemInfo.lastTime = now
+	self._currentSystem = systemInfo
 
 	if not self._thread then
 		self._thread = coroutine.create(function()
@@ -131,20 +156,23 @@ function Scheduler:runSystem(system)
 	end
 
 	local didYield = false
+	local hasSystem = false
 
 	local function systemCall()
 		local function noYield()
-			local success, err
+			local success, errOrSys, cleanup
 			coroutine.resume(self._thread, function()
-				success, err = xpcall(system, function(e)
+				success, errOrSys, cleanup = xpcall(function()
+					return systemInfo.run(table.unpack(self._vargs))
+				end, function(e)
 					return debug.traceback(e)
-				end, table.unpack(self._vargs))
+				end)
 			end)
 
 			if success == false then
 				didYield = true
-				table.insert(systemInfo.logs, err)
-				hooks.systemError(self, systemInfo, err)
+				table.insert(systemInfo.logs, errOrSys)
+				hooks.systemError(self, systemInfo, errOrSys)
 				return
 			end
 
@@ -161,6 +189,55 @@ function Scheduler:runSystem(system)
 					systemInfo,
 					debug.traceback(self._thread, errMessage, 2)
 				)
+				return
+			end
+
+			if not systemInfo.initialized then
+				if errOrSys == nil and cleanup == nil then
+					systemInfo.initialized = true
+					return
+				end
+
+				if type(errOrSys) == "function" then
+					systemInfo.run = errOrSys
+					systemInfo.initialized = true
+					if type(cleanup) == "function" then
+						systemInfo.cleanup = cleanup
+					end
+
+					hasSystem = true
+					return
+				end
+
+				if type(errOrSys) == "table" then
+					hasSystem = type(errOrSys.system) == "function"
+					local hasCleanup = type(errOrSys.cleanup) == "function"
+
+					if hasSystem or hasCleanup then
+						if hasSystem then
+							systemInfo.run = errOrSys.system
+						end
+
+						if hasCleanup then
+							systemInfo.cleanup = errOrSys.cleanup
+						end
+
+						systemInfo.initialized = true
+						return
+					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)
+				systemInfo.initialized = true
 			end
 		end
 
@@ -210,6 +287,11 @@ function Scheduler:runSystem(system)
 	end
 
 	self:_handleLogs(systemInfo)
+	self._currentSystem = nil
+
+	if hasSystem and justInitialized ~= true then
+		self:runSystem(system, true)
+	end
 end
 
 function Scheduler:runPhase(phase)
@@ -278,7 +360,6 @@ 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(_)")
@@ -391,7 +472,6 @@ end
 --- local myScheduler = Scheduler.new()
 ---     :insert(myPipeline, RunService, "Heartbeat")
 --- ```
-
 function Scheduler:insert(dependency, instance, event)
 	assert(
 		isPhase(dependency) or isPipeline(dependency),
@@ -437,7 +517,6 @@ 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)
 	assert(
 		isPhase(after) or isPipeline(after),
@@ -477,7 +556,6 @@ 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)
 	assert(
 		isPhase(before) or isPipeline(before),
@@ -499,13 +577,34 @@ function Scheduler:insertBefore(dependent, before)
 	return self
 end
 
---- @method addSystems
+--- @method addSystem
 --- @within Scheduler
---- @param systems System
+--- @param system System
 --- @param phase Phase?
+--- @return Scheduler
 ---
 --- Adds the System to the Scheduler, scheduling it to be ran
 --- implicitly within the provided Phase or on the default Main phase.
+---
+--- **Initializer Systems**: Systems can optionally return a function on their
+--- first execution, which becomes the runtime system. This allows one-time
+--- setup logic without creating separate initialization phases.
+---
+--- ```lua
+--- local function renderSystem(world, state)
+---     -- This runs once on first execution
+---     local renderables = world:query(Transform, Model):cached()
+---
+---     -- This runs on each subsequent execution
+---     return function(world, state)
+---         for id, transform, model in renderables do
+---             render(transform, model)
+---         end
+---     end, function()
+---         -- Optional cleanup logic runs on removeSystem
+---     end
+--- end
+--- ```
 function Scheduler:addSystem(system, phase)
 	local systemFn = getSystem(system)
 
@@ -513,26 +612,27 @@ function Scheduler:addSystem(system, phase)
 		error("Unknown system passed to Scheduler:addSystem(unknown, phase?)")
 	end
 
-	local name = getSystemName(systemFn)
-	if type(system) == "table" and system.name then
-		name = system.name
+	local name = getSystemName(system)
+
+	local scheduledPhase
+	if phase then
+		scheduledPhase = phase
+	elseif type(system) == "table" and system.phase then
+		scheduledPhase = system.phase
+	else
+		scheduledPhase = self._defaultPhase
 	end
 
 	local systemInfo = {
 		system = systemFn,
-		phase = phase,
+		run = systemFn,
+		cleanup = nil,
+		phase = scheduledPhase,
 		name = name,
 		logs = {},
+		initialized = false,
 	}
 
-	if not phase then
-		if type(system) == "table" and system.phase then
-			systemInfo.phase = system.phase
-		else
-			systemInfo.phase = self._defaultPhase
-		end
-	end
-
 	self._systemInfo[systemFn] = systemInfo
 
 	if not self._phaseToSystems[systemInfo.phase] then
@@ -545,6 +645,9 @@ function Scheduler:addSystem(system, phase)
 
 	if type(system) == "table" and system.runConditions then
 		for _, condition in system.runConditions do
+			condition = if typeof(condition) == "table"
+				then condition[1]
+				else condition
 			self:addRunCondition(systemFn, condition)
 		end
 	end
@@ -599,7 +702,7 @@ function Scheduler:editSystem(system, newPhase)
 	local systemInfo = self._systemInfo[systemFn]
 	assert(
 		systemInfo,
-		"Attempt to remove a non-exist system in Scheduler:removeSystem(_)"
+		"Attempt to edit a non-existent system in Scheduler:editSystem(_)"
 	)
 
 	assert(
@@ -638,16 +741,56 @@ end
 --- @method removeSystem
 --- @within Scheduler
 --- @param system System
+--- @return Scheduler
 ---
 --- Removes the System from the Scheduler.
+---
+--- If the system provided a cleanup function during initialization,
+--- that cleanup function will be executed before removal.
+---
+--- ```lua
+--- -- System with cleanup
+--- local function networkSystem(world, state)
+---     local connection = Players.PlayerAdded:Connect(function(player)
+---         -- Player joined logic
+---     end)
+---
+---     return function(world, state)
+---         -- Runtime logic
+---     end, function()
+---         -- Cleanup runs on removeSystem
+---         connection:Disconnect()
+---     end
+--- end
+---
+--- scheduler:addSystem(networkSystem, Phase.Update)
+--- -- Later...
+--- scheduler:removeSystem(networkSystem) -- Cleanup executes here
+--- ```
 function Scheduler:removeSystem(system)
 	local systemFn = getSystem(system)
 	local systemInfo = self._systemInfo[systemFn]
 	assert(
 		systemInfo,
-		"Attempt to remove a non-exist system in Scheduler:removeSystem(_)"
+		"Attempt to remove a non-existent system in Scheduler:removeSystem(_)"
 	)
 
+	if systemInfo.cleanup then
+		local success, err =
+			pcall(systemInfo.cleanup, table.unpack(self._vargs))
+		if success then
+			hooks.systemCleanup(self, 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)
+		end
+	end
+
 	local systems = self._phaseToSystems[systemInfo.phase]
 
 	local index = table.find(systems, systemFn)
@@ -689,6 +832,22 @@ function Scheduler:replaceSystem(old, new)
 		"Attempt to pass non-system in Scheduler:replaceSystem(_, unknown)"
 	)
 
+	if oldSystemInfo.cleanup then
+		local success, err =
+			pcall(oldSystemInfo.cleanup, table.unpack(self._vargs))
+		if success then
+			hooks.systemCleanup(self, 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)
+		end
+	end
+
 	local systems = self._phaseToSystems[oldSystemInfo.phase]
 
 	local index = table.find(systems, oldSystemFn)
@@ -700,7 +859,10 @@ function Scheduler:replaceSystem(old, new)
 	local copy = table.clone(oldSystemInfo)
 
 	oldSystemInfo.system = newSystemFn
-	oldSystemInfo.name = getSystemName(newSystemFn)
+	oldSystemInfo.run = newSystemFn
+	oldSystemInfo.cleanup = nil
+	oldSystemInfo.initialized = false
+	oldSystemInfo.name = getSystemName(new)
 
 	hooks.systemReplace(self, copy, oldSystemInfo)
 
@@ -732,9 +894,10 @@ end
 --- @param fn (U...) -> boolean
 ---
 --- Adds a Run Condition which the Scheduler will check before
---- any Systems within any Phases apart of this Pipeline are ran.\
-
+--- any Systems within any Phases apart of this Pipeline are ran.
 function Scheduler:addRunCondition(dependent, fn)
+	fn = if typeof(fn) == "table" then fn[1] else fn
+
 	local system = getSystem(dependent)
 	if system then
 		dependent = system
@@ -903,4 +1066,4 @@ function Scheduler.new(...)
 	return self
 end
 
-return Scheduler
+return Scheduler