@rbxts/planck 0.1.3-rc.5 → 0.2.0

package/out/conditions.d.ts

@@ -0,0 +1,14 @@
+import { EventInstance, EventLike } from "./types";
+
+type Condition = () => boolean;
+
+declare const timePassed: (time: number) => Condition;
+
+declare const exported: {
+    timePassed: (time: number) => Condition;
+    runOnce: () => Condition;
+    onEvent: <T extends unknown[]>(instance: EventInstance | EventLike, event: string | EventLike) => LuaTuple<[Condition, IterableFunction<T>, () => void]>;
+    isNot: (condition: Condition) => Condition;
+    cleanupCondition: (condition: Condition) => void
+}
+export = exported

package/out/conditions.luau

@@ -0,0 +1,151 @@
+local utils = require("./utils")
+local getConnectFunction = utils.getConnectFunction
+
+type EventLike = utils.EventLike
+type EventInstance = utils.EventInstance
+type ConnectionLike = utils.ConnectionLike
+
+type Condition = () -> boolean
+
+--- @class Conditions
+---
+--- Conditions can be used in systems or as Run Conditions.
+
+--- @within Conditions
+--- @param time number -- Time in seconds
+--- @return hasTimePassed () -> boolean
+---
+--- A Throttle condition which checks whether the amount of
+--- time given has passed or not.
+local function timePassed(time: number): Condition
+	local storedTime
+
+	return function()
+		if storedTime == nil or os.clock() - storedTime >= time then
+			storedTime = os.clock()
+			return true
+		end
+
+		return false
+	end
+end
+
+--- @within Conditions
+--- @return hasRanOnce () -> boolean
+---
+--- Checks whether the condition has been called once before
+local function runOnce(): Condition
+	local hasRan = false
+
+	return function()
+		if not hasRan then
+			hasRan = true
+			return true
+		end
+
+		return false
+	end
+end
+
+type CollectEvents<U...> = () -> () -> (number, U...)
+
+local conditionToCleanupFn = {}
+
+local function cleanupCondition(condition: Condition)
+	local cleanup = conditionToCleanupFn[condition]
+	if cleanup then
+		cleanup()
+		conditionToCleanupFn[condition] = nil
+	end
+end
+
+--- @within Conditions
+--- @return hasNewEvent () -> boolean
+--- @return collectEvents () -> () -> (number, U...)
+--- @return getDisconnectFn () -> () -> ()
+---
+--- Checks for any new events and allows for the collection of
+--- those events.
+local function onEvent<U...>(
+	instance: EventInstance | EventLike,
+	event: string | EventLike
+): (Condition, CollectEvents<U...>, () -> () -> ())
+	local connect = getConnectFunction(instance, event)
+	assert(connect, "Event passed to .onEvent is not valid")
+
+	local newEvent = false
+	local queue = {}
+
+	local connection: ConnectionLike?
+
+	local function disconnect()
+		if not connection then
+			return
+		end
+
+		utils.disconnectEvent(connection)
+		connection = nil
+	end
+
+	local function callback(...)
+		newEvent = true
+		table.insert(queue, { ... })
+	end
+
+	connection = connect(callback)
+
+	local function hasNewEvent()
+		if newEvent then
+			newEvent = false
+			return true
+		end
+
+		table.clear(queue)
+		return false
+	end
+
+	local function collectEvents()
+		local n = 0
+		return function(): (number, U...)
+			n += 1
+
+			local args = table.remove(queue, 1)
+
+			if args then
+				return n, table.unpack(args)
+			end
+
+			return nil :: any
+		end
+	end
+
+	local function getDisconnectFn()
+		return disconnect
+	end
+
+	conditionToCleanupFn[hasNewEvent] = disconnect
+
+	return hasNewEvent, collectEvents, getDisconnectFn
+end
+
+--- @within Conditions
+--- @param condition () -> boolean
+--- @return inverseCondition () -> boolean
+---
+--- Inverses a given condition.
+
+-- selene: allow(unused_variable)
+local function isNot(condition: Condition, ...: any): Condition
+	return function()
+		return not condition()
+	end
+end
+
+return {
+	timePassed = timePassed,
+	runOnce = runOnce,
+	onEvent = onEvent,
+	isNot = isNot,
+
+	cleanupCondition = cleanupCondition,
+}

package/out/index.d.ts

@@ -1,11 +1,17 @@
 import phase from "./Phase";
 import pipeline from "./Pipeline";
 import schedular from "./Scheduler";
+import condition from "./conditions"
 
 interface Planck {
     Phase: typeof phase;
     Pipeline: typeof pipeline; 
     Scheduler: typeof schedular;
+
+    isNot: typeof condition.isNot;
+    timePassed: typeof condition.timePassed;
+    runOnce: typeof condition.runOnce;
+    onEvent: typeof condition.onEvent;
 }
 
 declare const planck: Planck;

package/out/init.luau

@@ -1,66 +1,48 @@
-local Phase = require(script:WaitForChild('Phase')):: any
-local Pipeline = require(script:WaitForChild('Pipeline')):: any
-local Scheduler = require(script:WaitForChild('Scheduler')):: any
+local Phase = require(script:FindFirstChild("Phase")) :: any
+local Pipeline = require(script:FindFirstChild("Pipeline")) :: any
+local Scheduler = require(script:FindFirstChild("Scheduler")) :: any
 
-type SystemFn<U...> = ((U...) -> any) | ((U...) -> ())
+local conditions = require(script:FindFirstChild("conditions"))
+local utils = require(script:FindFirstChild("utils"))
 
-type SystemTable<U...> = {
+type EventLike = utils.EventLike
+type EventInstance = utils.EventInstance
+
+export type SystemFn<U...> = ((U...) -> any) | ((U...) -> ())
+
+export type SystemTable<U...> = {
 	system: SystemFn<U...>,
 	phase: Phase?,
-	[any]: any
+	name: string?,
+	runConditions: { (U...) -> boolean }?,
+	[any]: any,
 }
 
-type System<U...> = SystemFn<U...> | SystemTable<U...>
-
-type EventLike = RBXScriptSignal | {
-	connect: (self: EventLike,...any) -> any,
-	[any]: any
-} | {
-	Connect: (self: EventLike,...any) -> any,
-	[any]: any
-} | {
-	on: (self: EventLike,...any) -> any,
-	[any]: any
-}
-
-type EventInstance = Instance | {
-	[any]: EventLike
-}
+export type System<U...> = SystemFn<U...> | SystemTable<U...>
 
-type Phase = {
+export type Phase = {
 	PreStartup: Phase,
 	Startup: Phase,
 	PostStartup: Phase,
 
-	PreRender: Phase,
-	PreAnimation: Phase,
-	PreSimulation: Phase,
-	PostSimulation: Phase,
-
-	First: Phase,
-	PreUpdate: Phase,
-	Update: Phase,
-	PostUpdate: Phase,
-	Last: Phase,
-
-	new: (debugName: string?) -> Phase
+	new: (debugName: string?) -> Phase,
 }
 
-type Pipeline = {
-	Main: Pipeline,
+export type Pipeline = {
 	Startup: Pipeline,
 
 	insert: (self: Pipeline, phase: Phase) -> Pipeline,
 	insertAfter: (self: Pipeline, phase: Phase, after: Phase) -> Pipeline,
-	new: (debugName: string?) -> Pipeline
+	new: (debugName: string?) -> Pipeline,
 }
 
 type Plugin<U...> = {
 	build: (self: Plugin<U...>, scheduler: Scheduler<U...>) -> (),
-	[any]: any
+	cleanup: ((self: Plugin<U...>) -> ())?,
+	[any]: any,
 }
 
-type Scheduler<U...> = {
+export type Scheduler<U...> = {
 	addPlugin: (self: Scheduler<U...>, plugin: Plugin<U...>) -> Scheduler<U...>,
 
 	addSystem: (
@@ -92,18 +74,21 @@ type Scheduler<U...> = {
 		system: System<U...>
 	) -> Scheduler<U...>,
 
-	setRunCondition: ((
+	addRunCondition: ((
 		self: Scheduler<U...>,
 		system: System<U...>,
-		fn: (U...) -> boolean
+		fn: (U...) -> boolean,
+		...any
 	) -> Scheduler<U...>) & ((
 		self: Scheduler<U...>,
 		phase: Phase,
-		fn: (U...) -> boolean
+		fn: (U...) -> boolean,
+		...any
 	) -> Scheduler<U...>) & ((
 		self: Scheduler<U...>,
 		pipeline: Pipeline,
-		fn: (U...) -> boolean
+		fn: (U...) -> boolean,
+		...any
 	) -> Scheduler<U...>),
 
 	run: ((self: Scheduler<U...>, system: System<U...>) -> Scheduler<U...>)
@@ -112,6 +97,8 @@ type Scheduler<U...> = {
 
 	runAll: (self: Scheduler<U...>) -> Scheduler<U...>,
 
+	getDeltaTime: (self: Scheduler<U...>) -> number,
+
 	insert: ((self: Scheduler<U...>, phase: Phase) -> Scheduler<U...>) & ((
 		self: Scheduler<U...>,
 		pipeline: Pipeline
@@ -137,13 +124,20 @@ type Scheduler<U...> = {
 		after: Phase | Pipeline
 	) -> Scheduler<U...>),
 
-	new: (U...) -> Scheduler<U...>
+	cleanup: (self: Scheduler<U...>) -> (),
+
+	new: (U...) -> Scheduler<U...>,
 }
 
 return {
 	Phase = Phase :: Phase,
 	Pipeline = Pipeline :: Pipeline,
 	Scheduler = Scheduler :: {
-		new: <U...>(U...) -> Scheduler<U...>	
-},
+		new: <U...>(U...) -> Scheduler<U...>,
+	},
+
+	isNot = conditions.isNot,
+	runOnce = conditions.runOnce,
+	timePassed = conditions.timePassed,
+	onEvent = conditions.onEvent,
 }

package/out/types.d.ts

@@ -85,6 +85,8 @@ export interface EventLike {
 } 
 
 export type EventInstance = Instance | EventLike | RBXScriptSignal;
+export type Disconnectable = RBXScriptConnection | { Disconnect(): void } | { disconnect(): void } | { Destroy(): void } | { destroy(): void; }
+export type ConnectFn = (callback: (...args: unknown[]) => void) => Disconnectable;
 
 
 export interface Utils {
@@ -93,7 +95,9 @@ export interface Utils {
     isPhase: (phase: Phase) => Phase | undefined
     isPipeline: (pipeline: Pipeline) => Pipeline | undefined
     getEventIdentifier: (instance: EventInstance, event?: EventLike) => string
-    isValidEvent: (instance: EventInstance, event?: EventLike) => boolean
+    isValidEvent: (instance: EventInstance, event: EventLike) => boolean
+    getConnectedFunction: (instance: EventInstance | EventLike, event: string | EventLike) => ConnectFn | undefined
+    disconnectEvent: (disconectable: Disconnectable) => void
 }
 
 export interface Plugin {

package/out/utils.luau

@@ -6,7 +6,7 @@ type SystemFn<U...> = ((U...) -> any) | ((U...) -> ())
 type SystemTable<U...> = {
 	system: SystemFn<U...>,
 	phase: Phase?,
-	[any]: any
+	[any]: any,
 }
 
 type System<U...> = SystemFn<U...> | SystemTable<U...>
@@ -24,7 +24,8 @@ end
 local function getSystemName(system: any): string
 	local name = debug.info(system, "n")
 	if not name or string.len(name) == 0 then
-		name = debug.info(system, "sl")
+		local source, line = debug.info(system, "sl")
+		name = `{source}:{line}`
 	end
 
 	return name
@@ -50,27 +51,102 @@ local function getEventIdentifier(instance, event)
 	return `{instance}{event and `@{event}` or ""}`
 end
 
-local validEventMethods = {
-	"Connect",
-	"connect",
-	"On",
-	"on",
+local EVENT_CONNECT_METHODS = { "Connect", "On", "on", "connect" }
+
+export type EventLike = RBXScriptSignal | {
+	connect: (self: EventLike, ...any) -> any,
+	[any]: any,
+} | {
+	Connect: (self: EventLike, ...any) -> any,
+	[any]: any,
+} | {
+	on: (self: EventLike, ...any) -> any,
+	[any]: any,
 }
 
-local function isValidEvent(instance, event)
-	local eventInstance = event and instance[event] or instance
-
-	if typeof(eventInstance) == "RBXScriptSignal" then
-		return true
-	elseif typeof(eventInstance) == "table" then
-		for _, method in validEventMethods do
-			if eventInstance[method] ~= nil then
-				return true
+export type EventInstance = Instance | {
+	[any]: EventLike,
+}
+
+export type ConnectionLike = RBXScriptConnection | {
+	disconnect: (self: ConnectionLike, ...any) -> any,
+	[any]: any,
+} | {
+	Disconnect: (self: ConnectionLike, ...any) -> any,
+	[any]: any,
+} | {
+	destroy: (self: ConnectionLike, ...any) -> any,
+	[any]: any,
+} | {
+	Destroy: (self: ConnectionLike, ...any) -> any,
+	[any]: any,
+} | (...any) -> any
+
+export type ConnectFn<U...> = (callback: (U...) -> ()) -> ConnectionLike
+
+local EVENT_DISCONNECT_METHODS =
+	{ "disconnect", "Disconnect", "destroy", "Destroy" }
+
+local function disconnectEvent(connection: ConnectionLike)
+	if type(connection) == "function" then
+		connection()
+		return
+	elseif typeof(connection) == "RBXScriptConnection" then
+		connection:Disconnect()
+		return
+	elseif type(connection) == "table" then
+		for _, method in EVENT_DISCONNECT_METHODS do
+			if
+				connection[method]
+				and type(connection[method]) == "function"
+			then
+				connection[method](connection)
+				return
 			end
 		end
 	end
+end
+
+-- This function is inspired by useEvent in Matter, a library by evaera (https://github.com/evaera)
+-- License: Copyright (c) 2021 Eryn L. K., MIT License
+-- Source: https://github.com/matter-ecs/matter/blob/main/lib/hooks/useEvent.luau
+local function getConnectFunction<U...>(
+	instance: EventInstance | EventLike,
+	event: string | EventLike
+): ConnectFn<U...>?
+	local eventInstance = instance
+
+	if typeof(event) == "RBXScriptSignal" or type(event) == "table" then
+		eventInstance = event
+	elseif type(event) == "string" then
+		eventInstance = (instance :: any)[event]
+	end
 
-	return false
+	if type(eventInstance) == "function" then
+		return eventInstance
+	elseif typeof(eventInstance) == "RBXScriptSignal" then
+		return function(callback)
+			return eventInstance:Connect(callback)
+		end
+	end
+
+	if type(eventInstance) == "table" then
+		for _, method in EVENT_CONNECT_METHODS do
+			if type(eventInstance[method]) ~= "function" then
+				continue
+			end
+
+			return function(callback)
+				return eventInstance[method](eventInstance, callback)
+			end
+		end
+	end
+
+	return nil
+end
+
+local function isValidEvent(instance, event)
+	return getConnectFunction(instance, event) ~= nil
 end
 
 return {
@@ -80,4 +156,6 @@ return {
 	isPipeline = isPipeline,
 	getEventIdentifier = getEventIdentifier,
 	isValidEvent = isValidEvent,
+	getConnectFunction = getConnectFunction,
+	disconnectEvent = disconnectEvent,
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/planck",
-  "version": "0.1.3-rc.5",
+  "version": "0.2.0",
   "description": "An agnostic scheduler for ECS",
   "main": "out/init.lua",
   "repository": {