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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rbxts/planck",
-	"version": "0.3.0-alpha.2",
+	"version": "0.3.0-rc.1",
 	"description": "An Agnostic Scheduler for ECS",
 	"main": "src",
 	"repository": {

package/src/DependencyGraph.luau

@@ -1,19 +1,7 @@
 local AdjacencyMatrix = {}
 AdjacencyMatrix.__index = AdjacencyMatrix
 
-export type AdjacencyMatrix = {
-	matrix: { { number } },
-	length: number,
-	width: number,
-
-	extend: (self: AdjacencyMatrix) -> (),
-	setEdge: (self: AdjacencyMatrix, i: number, j: number, v: number) -> (),
-	toAdjacencyList: (self: AdjacencyMatrix) -> { { number } },
-	topologicalSort: (self: AdjacencyMatrix) -> { number }?,
-	new: () -> AdjacencyMatrix,
-}
-
-function AdjacencyMatrix:__tostring()
+function AdjacencyMatrix.__tostring(self: AdjacencyMatrix)
 	local s = "\n"
 
 	for i = 1, self.length do
@@ -38,9 +26,9 @@ function AdjacencyMatrix:__tostring()
 	return s
 end
 
-function AdjacencyMatrix:extend()
-	self.length = (self.length :: number) + 1
-	self.width = (self.length :: number) + 1
+function AdjacencyMatrix.extend(self: AdjacencyMatrix)
+	self.length = self.length + 1
+	self.width = self.length + 1
 
 	self.matrix[self.length] = {}
 	for j = 1, self.width do
@@ -52,11 +40,16 @@ function AdjacencyMatrix:extend()
 	end
 end
 
-function AdjacencyMatrix:setEdge(i, j, val)
+function AdjacencyMatrix.setEdge(
+	self: AdjacencyMatrix,
+	i: number,
+	j: number,
+	val: number
+)
 	self.matrix[i][j] = val
 end
 
-function AdjacencyMatrix:toAdjacencyList()
+function AdjacencyMatrix.toAdjacencyList(self: AdjacencyMatrix): { { number } }
 	local list = {}
 
 	for i = 1, self.length do
@@ -71,7 +64,7 @@ function AdjacencyMatrix:toAdjacencyList()
 	return list
 end
 
-function AdjacencyMatrix:topologicalSort(): { number }?
+function AdjacencyMatrix.topologicalSort(self: AdjacencyMatrix): { number }?
 	local adjacencyList = self:toAdjacencyList()
 
 	local result = {}
@@ -114,34 +107,19 @@ function AdjacencyMatrix.new(): AdjacencyMatrix
 		matrix = {},
 		length = 0,
 		width = 0,
-	}, AdjacencyMatrix) :: any
+	}, AdjacencyMatrix)
 end
 
-export type DependencyGraph<T> = {
-	nodes: { T },
-	matrix: AdjacencyMatrix,
+export type AdjacencyMatrix = setmetatable<{
+	matrix: { { number } },
 	length: number,
 	width: number,
-
-	getOrderedList: (self: DependencyGraph<T>) -> { T }?,
-	insert: (self: DependencyGraph<T>, node: T) -> DependencyGraph<T>,
-	insertAfter: (
-		self: DependencyGraph<T>,
-		node: T,
-		afterNode: T
-	) -> DependencyGraph<T>,
-	insertBefore: (
-		self: DependencyGraph<T>,
-		node: T,
-		beforeNode: T
-	) -> DependencyGraph<T>,
-	new: () -> DependencyGraph<T>,
-}
+}, typeof(AdjacencyMatrix)>
 
 local DependencyGraph = {}
 DependencyGraph.__index = DependencyGraph
 
-function DependencyGraph:getOrderedList(): { any }?
+function DependencyGraph.getOrderedList<T>(self: DependencyGraph<T>): { T }?
 	local orderedList = {}
 
 	local topologicalSort = self.matrix:topologicalSort()
@@ -156,10 +134,13 @@ function DependencyGraph:getOrderedList(): { any }?
 	return orderedList
 end
 
-function DependencyGraph:insertBefore(node, beforeNode)
-	if not table.find(self.nodes, beforeNode) then
-		error("Node not found in DependencyGraph:insertBefore(_, unknown)")
-	end
+function DependencyGraph.insertBefore<T>(
+	self: DependencyGraph<T>,
+	node: T,
+	beforeNode: T
+)
+	local i = table.find(self.nodes, beforeNode)
+	assert(i, "Node not found in DependencyGraph:insertBefore(_, unknown)")
 
 	local j = table.find(self.nodes, node)
 	if not j then
@@ -167,7 +148,8 @@ function DependencyGraph:insertBefore(node, beforeNode)
 		j = #self.nodes
 	end
 
-	local i = table.find(self.nodes, beforeNode)
+	-- selene: allow(incorrect_standard_library_use)
+	assert(j)
 
 	self.matrix:extend()
 	self.matrix:setEdge(j, i, 1)
@@ -175,10 +157,13 @@ function DependencyGraph:insertBefore(node, beforeNode)
 	return self
 end
 
-function DependencyGraph:insertAfter(node, afterNode)
-	if not table.find(self.nodes, afterNode) then
-		error("Node not found in DependencyGraph:insertAfter(_, unknown)")
-	end
+function DependencyGraph.insertAfter<T>(
+	self: DependencyGraph<T>,
+	node: T,
+	afterNode: T
+)
+	local i = table.find(self.nodes, afterNode)
+	assert(i, "Node not found in DependencyGraph:insertAfter(_, unknown)")
 
 	local j = table.find(self.nodes, node)
 	if not j then
@@ -186,7 +171,8 @@ function DependencyGraph:insertAfter(node, afterNode)
 		j = #self.nodes
 	end
 
-	local i = table.find(self.nodes, afterNode)
+	-- selene: allow(incorrect_standard_library_use)
+	assert(j)
 
 	self.matrix:extend()
 	self.matrix:setEdge(i, j, 1)
@@ -194,7 +180,7 @@ function DependencyGraph:insertAfter(node, afterNode)
 	return self
 end
 
-function DependencyGraph:insert(node)
+function DependencyGraph.insert<T>(self: DependencyGraph<T>, node: T)
 	local i = #self.nodes
 	table.insert(self.nodes, node)
 	local j = #self.nodes
@@ -208,13 +194,20 @@ function DependencyGraph:insert(node)
 	return self
 end
 
-function DependencyGraph.new<T>(): DependencyGraph<T>
+function DependencyGraph.new(): DependencyGraph<any>
 	return setmetatable({
 		nodes = {},
 		matrix = AdjacencyMatrix.new(),
 		length = 0,
 		width = 0,
-	}, DependencyGraph) :: any
+	}, DependencyGraph)
 end
 
+export type DependencyGraph<T> = setmetatable<{
+	nodes: { T },
+	matrix: AdjacencyMatrix,
+	length: number,
+	width: number,
+}, typeof(DependencyGraph)>
+
 return DependencyGraph

package/src/Phase.luau

@@ -1,41 +1,46 @@
---- @class Phase
----
---- Phases represent tags that tell the scheduler when to
---- schedule a set of systems.
-local Phase = {}
-Phase.__index = Phase
-
-function Phase:__tostring()
-	return self._name
-end
-
---- @within Phase
----
---- Creates a new Phase, with an optional name to use for debugging.
---- When no name is provided, the script and line number will be used.
-function Phase.new(name: string?)
-	name = name or debug.info(2, "sl")
-	return setmetatable({
-		_name = name,
-		_type = "phase",
-	}, Phase)
-end
-
---- @prop PreStartup Phase
---- @within Phase
---- Runs before the `Startup` Phase.
-
---- @prop Startup Phase
---- @within Phase
---- This Phase will run once, the first time the Scheduler is ran,
---- before any other Phases are ran.
-
---- @prop PostStartup Phase
---- @within Phase
---- Runs after the `Startup` phase.
-
-Phase.PreStartup = Phase.new("PreStartup")
-Phase.Startup = Phase.new("Startup")
-Phase.PostStartup = Phase.new("PostStartup")
-
-return Phase
+--- @class Phase
+---
+--- Phases represent tags that tell the scheduler when to
+--- schedule a set of systems.
+local Phase = {}
+Phase.__index = Phase
+
+function Phase.__tostring(self: Phase)
+	return self._name
+end
+
+--- @within Phase
+---
+--- Creates a new Phase, with an optional name to use for debugging.
+--- When no name is provided, the script and line number will be used.
+function Phase.new(name: string?): Phase
+	name = name or debug.info(2, "sl") :: string
+	return setmetatable({
+		_name = name,
+		_type = "phase",
+	}, Phase)
+end
+
+--- @prop PreStartup Phase
+--- @within Phase
+--- Runs before the `Startup` Phase.
+
+--- @prop Startup Phase
+--- @within Phase
+--- This Phase will run once, the first time the Scheduler is ran,
+--- before any other Phases are ran.
+
+--- @prop PostStartup Phase
+--- @within Phase
+--- Runs after the `Startup` phase.
+
+Phase.PreStartup = Phase.new("PreStartup")
+Phase.Startup = Phase.new("Startup")
+Phase.PostStartup = Phase.new("PostStartup")
+
+export type Phase = setmetatable<{
+	_name: string,
+	_type: "phase",
+}, typeof(Phase)>
+
+return Phase

package/src/Pipeline.luau

@@ -1,86 +1,105 @@
---!nonstrict
-local DependencyGraph = require(script.Parent.DependencyGraph)
-local Phase = require(script.Parent.Phase)
-
---- @class Pipeline
----
---- Pipelines represent a set of ordered Phases. Systems cannot be
---- assigned to Pipelines themselves, but rather to Phases within
---- those Pipelines.
-local Pipeline = {}
-Pipeline.__index = Pipeline
-
-function Pipeline:__tostring()
-	return self._name
-end
-
---- @method insert
---- @within Pipeline
---- @param phase Phase
---- @return Pipeline
----
---- Adds a Phase to the Pipeline, ordering it implicitly.
-function Pipeline:insert(phase)
-	self.dependencyGraph:insert(phase)
-	return self
-end
-
---- @method insertAfter
---- @within Pipeline
---- @param phase Phase
---- @param after Phase
---- @return Pipeline
----
---- Adds a Phase to the Pipeline after another Phase, ordering it explicitly.
-function Pipeline:insertAfter(phase, afterPhase)
-	local i = table.find(self.dependencyGraph.nodes, afterPhase)
-	assert(
-		i,
-		"Unknown Phase in Pipeline:insertAfter(_, unknown), try adding this Phase to the Pipeline."
-	)
-
-	self.dependencyGraph:insertAfter(phase, afterPhase)
-	return self
-end
-
---- @method insertBefore
---- @within Pipeline
---- @param phase Phase
---- @param before Phase
---- @return Pipeline
----
---- Adds a Phase to the Pipeline before another Phase, ordering it explicitly.
-function Pipeline:insertBefore(phase, beforePhase)
-	local i = table.find(self.dependencyGraph.nodes, beforePhase)
-	assert(
-		i,
-		"Unknown Phase in Pipeline:insertBefore(_, unknown), try adding this Phase to the Pipeline."
-	)
-
-	self.dependencyGraph:insertBefore(phase, beforePhase)
-	return self
-end
-
---- @within Pipeline
----
---- Creates a new Pipeline, with an optional name to use for debugging.
---- When no name is provided, the script and line number will be used.
-function Pipeline.new(name: string?)
-	name = name or debug.info(2, "sl")
-	return setmetatable({
-		_name = name,
-		_type = "pipeline",
-		dependencyGraph = DependencyGraph.new(),
-	}, Pipeline)
-end
-
---- @prop Startup Pipeline
---- @within Pipeline
----
---- A Pipeline containing the `PreStartup`, `Startup`, and `PostStartup` phases.
-Pipeline.Startup = Pipeline.new()
-	:insert(Phase.PreStartup)
-	:insert(Phase.Startup)
-	:insert(Phase.PostStartup)
-
-return Pipeline
+local DependencyGraph = require(script.Parent.DependencyGraph)
+local Phase = require(script.Parent.Phase)
+
+type DependencyGraph<T> = DependencyGraph.DependencyGraph<T>
+type Phase = Phase.Phase
+
+--- @class Pipeline
+---
+--- Pipelines represent a set of ordered Phases. Systems cannot be
+--- assigned to Pipelines themselves, but rather to Phases within
+--- those Pipelines.
+local Pipeline = {}
+Pipeline.__index = Pipeline
+
+function Pipeline.__tostring(self: Pipeline): string
+	return self._name
+end
+
+--- @method insert
+--- @within Pipeline
+--- @param phase Phase
+--- @return Pipeline
+---
+--- Adds a Phase to the Pipeline, ordering it implicitly.
+function Pipeline.insert(self: Pipeline, phase: Phase): Pipeline
+	self.dependencyGraph:insert(phase)
+	return self
+end
+
+--- @method insertAfter
+--- @within Pipeline
+--- @param phase Phase
+--- @param after Phase
+--- @return Pipeline
+---
+--- Adds a Phase to the Pipeline after another Phase, ordering it explicitly.
+function Pipeline.insertAfter(
+	self: Pipeline,
+	phase: Phase,
+	afterPhase: Phase
+): Pipeline
+	local i = table.find(self.dependencyGraph.nodes, afterPhase)
+	assert(
+		i,
+		"Unknown Phase in Pipeline:insertAfter(_, unknown), try adding this Phase to the Pipeline."
+	)
+
+	self.dependencyGraph:insertAfter(phase, afterPhase)
+	return self
+end
+
+--- @method insertBefore
+--- @within Pipeline
+--- @param phase Phase
+--- @param before Phase
+--- @return Pipeline
+---
+--- Adds a Phase to the Pipeline before another Phase, ordering it explicitly.
+function Pipeline.insertBefore(
+	self: Pipeline,
+	phase: Phase,
+	beforePhase: Phase
+): Pipeline
+	local i = table.find(self.dependencyGraph.nodes, beforePhase)
+	assert(
+		i,
+		"Unknown Phase in Pipeline:insertBefore(_, unknown), try adding this Phase to the Pipeline."
+	)
+
+	self.dependencyGraph:insertBefore(phase, beforePhase)
+	return self
+end
+
+--- @within Pipeline
+---
+--- Creates a new Pipeline, with an optional name to use for debugging.
+--- When no name is provided, the script and line number will be used.
+function Pipeline.new(name: string?): Pipeline
+	name = name or debug.info(2, "sl") :: string
+
+	local dependencyGraph: DependencyGraph<Phase> = DependencyGraph.new()
+
+	return setmetatable({
+		_name = name,
+		_type = "pipeline",
+		dependencyGraph = dependencyGraph,
+	}, Pipeline)
+end
+
+--- @prop Startup Pipeline
+--- @within Pipeline
+---
+--- A Pipeline containing the `PreStartup`, `Startup`, and `PostStartup` phases.
+Pipeline.Startup = Pipeline.new()
+	:insert(Phase.PreStartup)
+	:insert(Phase.Startup)
+	:insert(Phase.PostStartup)
+
+export type Pipeline = setmetatable<{
+	_name: string,
+	_type: "pipeline",
+	dependencyGraph: DependencyGraph<Phase>,
+}, typeof(Pipeline)>
+
+return Pipeline

package/src/Scheduler.d.ts

@@ -152,7 +152,79 @@ export interface SystemTable<T extends unknown[]> extends BaseSystemTable<T> {
  * };
  * ```
  */
-export type System<T extends unknown[]> = InitializerSystemFn<T> | SystemFn<T> | SystemTable<T>;
+export type System<T extends unknown[]> =
+  | InitializerSystemFn<T>
+  | SystemFn<T>
+  | SystemTable<T>;
+
+type InternalSystem<T extends unknown[]> = SystemFn<T> | InitializerSystemFn<T>;
+
+type SystemInfo<T extends unknown[]> = {
+  system: InternalSystem<T>;
+  run: InternalSystem<T>;
+  cleanup?: SystemFn<T>;
+  initialized: boolean;
+  name: string;
+  deltaTime?: number;
+  lastTime?: number;
+  timeLastLogged?: number;
+  recentLogs?: { [key: string]: boolean };
+  logs: any[];
+  phase: Phase;
+};
+
+type Hook<T, V = void> = {
+  readonly __context: T;
+  readonly __return: V;
+};
+
+type PartialHookContext<T extends unknown[]> = {
+  scheduler: Scheduler<T>;
+};
+
+type SystemHookContext<T extends unknown[]> = PartialHookContext<T> & {
+  system: SystemInfo<T>;
+};
+
+type SystemReplaceContext<T extends unknown[]> = PartialHookContext<T> & {
+  new: SystemInfo<T>;
+  old: SystemInfo<T>;
+};
+
+type SystemErrorContext<T extends unknown[]> = PartialHookContext<T> & {
+  system: SystemInfo<T>;
+  error?: unknown;
+};
+
+type SystemCallHookFn = () => void;
+type SystemCallCallback<T extends unknown[]> = (
+  context: SystemCallContext<T>
+) => SystemCallHookFn;
+
+type SystemCallContext<T extends unknown[]> = PartialHookContext<T> & {
+  system: SystemInfo<T>;
+  nextFn: SystemCallHookFn;
+};
+
+type PhaseContext<T extends unknown[]> = PartialHookContext<T> & {
+  phase: Phase;
+};
+
+interface Hooks<T extends unknown[]> {
+  SystemAdd: Hook<SystemHookContext<T>>;
+  SystemRemove: Hook<SystemHookContext<T>>;
+  SystemReplace: Hook<SystemReplaceContext<T>>;
+  SystemCleanup: Hook<SystemErrorContext<T>>;
+  SystemError: Hook<SystemErrorContext<T>>;
+  SystemTriedRun: Hook<SystemHookContext<T>>;
+
+  OuterSystemCall: Hook<SystemCallContext<T>, SystemCallHookFn>;
+  InnerSystemCall: Hook<SystemCallContext<T>, SystemCallHookFn>;
+  SystemCall: Hook<SystemCallContext<T>, SystemCallHookFn>;
+
+  PhaseAdd: Hook<PhaseContext<T>>;
+  PhaseBegan: Hook<PhaseContext<T>>;
+}
 
 /**
  * An Object which handles scheduling Systems to run within different Phases.
@@ -172,6 +244,19 @@ export class Scheduler<T extends unknown[]> {
    */
   addPlugin(plugin: Plugin<T>): this;
 
+  /**
+   * See [creating plugins](https://yetanotherclown.github.io/planck/docs/plugins/creating).
+   */
+  Hooks: Hooks<T>;
+
+  /**
+   * Allows for registering hooks, see [creating plugins](https://yetanotherclown.github.io/planck/docs/plugins/creating).
+   */
+  addHook<Context, Return>(
+    hook: Hook<Context, Return>,
+    fn: (context: Context) => Return
+  ): void;
+
   /**
    * Adds the System to the Scheduler, scheduling it to be ran implicitly within
    * the provided Phase or on the default Main phase.
@@ -244,7 +329,11 @@ export class Scheduler<T extends unknown[]> {
    * );
    * ```
    */
-  insert<E extends EventInstance>(phase: Phase, instance: E, event: ExtractEvents<E>): this;
+  insert<E extends EventInstance>(
+    phase: Phase,
+    instance: E,
+    event: ExtractEvents<E>
+  ): this;
   /**
    * Initializes the Phase within the Scheduler, ordering it implicitly by
    * setting it as a dependent of the previous Phase/Pipeline, and scheduling it
@@ -272,7 +361,11 @@ export class Scheduler<T extends unknown[]> {
    * );
    * ```
    */
-  insert<E extends EventInstance>(pipeline: Pipeline, instance: E, event: ExtractEvents<E>): this;
+  insert<E extends EventInstance>(
+    pipeline: Pipeline,
+    instance: E,
+    event: ExtractEvents<E>
+  ): this;
   /**
    * Initializes the Pipeline and it's Phases within the Scheduler, ordering the
    * Pipeline implicitly by setting it as a dependent of the previous