@rbxts/planck 0.1.0-rc.2

package/out/hooks.d.ts

@@ -0,0 +1,4 @@
+import { Hooks } from "./types";
+
+declare const hooks : Hooks;
+export = hooks;

package/out/hooks.luau

@@ -0,0 +1,145 @@
+-- Super-duper experimental Plugin Hooks API
+
+local function systemAdd(scheduler, systemInfo)
+	local hooks = scheduler._hooks[scheduler.Hooks.SystemAdd]
+	local info = {
+		scheduler = scheduler,
+		system = systemInfo,
+	}
+
+	for _, hook in hooks do
+		local success, err = pcall(hook, info)
+		if not success then
+			warn("Unexpected error in hook:", err)
+		end
+	end
+end
+
+local function systemRemove(scheduler, systemInfo)
+	local hooks = scheduler._hooks[scheduler.Hooks.SystemRemove]
+	local info = {
+		scheduler = scheduler,
+		system = systemInfo,
+	}
+
+	for _, hook in hooks do
+		local success, err = pcall(hook, info)
+		if not success then
+			warn("Unexpected error in hook:", err)
+		end
+	end
+end
+
+local function systemReplace(scheduler, oldSystemInfo, newSystemInfo)
+	local hooks = scheduler._hooks[scheduler.Hooks.SystemReplace]
+	local info = {
+		scheduler = scheduler,
+		new = newSystemInfo,
+		old = oldSystemInfo,
+	}
+
+	for _, hook in hooks do
+		local success, err = pcall(hook, info)
+		if not success then
+			warn("Unexpected error in hook:", err)
+		end
+	end
+end
+
+local function systemCall(scheduler, hookName, systemInfo, nextFn)
+	local hooks = scheduler._hooks[scheduler.Hooks[hookName] ]
+
+	if hooks then
+		for _, hook in hooks do
+			nextFn = hook({
+				scheduler = nil,
+				system = systemInfo,
+				nextFn = nextFn,
+			})
+
+			if not nextFn then
+				local source, line = debug.info(hook, "sl")
+				warn(
+					`{source}:{line}: Expected 'SystemCall' hook to return a function`
+				)
+			end
+		end
+	end
+
+	nextFn()
+end
+
+local function systemError(scheduler, systemInfo, err)
+	local hooks = scheduler._hooks[scheduler.Hooks["SystemError"] ]
+
+	if hooks then
+		for _, hook in hooks do
+			hook({
+				scheduler = scheduler,
+				system = systemInfo,
+				error = err,
+			})
+		end
+	end
+end
+
+type PhaseAdd = {
+	scheduler: any,
+	phase: any
+}
+
+local function phaseAdd(scheduler, phase)
+	local hooks = scheduler._hooks[scheduler.Hooks.PhaseAdd]
+	local info = {
+		scheduler = scheduler,
+		phase = phase,
+	}
+
+	for _, hook in hooks do
+		local success, err = pcall(hook, info)
+		if not success then
+			warn("Unexpected error in hook:", err)
+		end
+	end
+end
+
+local function phaseBegan(scheduler, phase)
+	local hooks = scheduler._hooks[scheduler.Hooks.PhaseBegan]
+	local info = {
+		scheduler = scheduler,
+		phase = phase,
+	}
+
+	for _, hook in hooks do
+		local success, err = pcall(hook, info)
+		if not success then
+			warn("Unexpected error in hook:", err)
+		end
+	end
+end
+
+local Hooks = {
+	SystemAdd = "SystemAdd",
+	SystemRemove = "SystemRemove",
+	SystemReplace = "SystemReplace",
+	SystemError = "SystemError",
+
+	OuterSystemCall = "OuterSystemCall",
+	InnerSystemCall = "InnerSystemCall",
+	SystemCall = "SystemCall",
+
+	PhaseAdd = "PhaseAdd",
+	PhaseBegan = "PhaseBegan",
+}
+
+return {
+	Hooks = Hooks,
+
+	systemAdd = systemAdd,
+	systemRemove = systemRemove,
+	systemReplace = systemReplace,
+	systemCall = systemCall,
+	systemError = systemError,
+	phaseAdd = phaseAdd,
+	phaseBegan = phaseBegan,
+}

package/out/index.d.ts

@@ -0,0 +1,12 @@
+import phase from "./Phase";
+import pipeline from "./Pipeline";
+import schedular from "./Scheduler";
+
+interface Planck {
+    Phase: typeof phase;
+    Pipeline: typeof pipeline; 
+    Scheduler: typeof schedular;
+}
+
+declare const planck: Planck;
+export = planck;

package/out/init.luau

@@ -0,0 +1,149 @@
+local Phase = require(script:WaitForChild('Phase')):: any
+local Pipeline = require(script:WaitForChild('Pipeline')):: any
+local Scheduler = require(script:WaitForChild('Scheduler')):: any
+
+type SystemFn<U...> = ((U...) -> any) | ((U...) -> ())
+
+type SystemTable<U...> = {
+	system: SystemFn<U...>,
+	phase: Phase?,
+	[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
+}
+
+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
+}
+
+type Pipeline = {
+	Main: Pipeline,
+	Startup: Pipeline,
+
+	insert: (self: Pipeline, phase: Phase) -> Pipeline,
+	insertAfter: (self: Pipeline, phase: Phase, after: Phase) -> Pipeline,
+	new: (debugName: string?) -> Pipeline
+}
+
+type Plugin<U...> = {
+	build: (self: Plugin<U...>, scheduler: Scheduler<U...>) -> (),
+	[any]: any
+}
+
+type Scheduler<U...> = {
+	addPlugin: (self: Scheduler<U...>, plugin: Plugin<U...>) -> Scheduler<U...>,
+
+	addSystem: (
+		self: Scheduler<U...>,
+		system: System<U...>,
+		phase: Phase?
+	) -> Scheduler<U...>,
+
+	addSystems: (
+		self: Scheduler<U...>,
+		systems: { System<U...> },
+		phase: Phase?
+	) -> Scheduler<U...>,
+
+	editSystem: (
+		self: Scheduler<U...>,
+		system: System<U...>,
+		new: Phase
+	) -> Scheduler<U...>,
+
+	replaceSystem: (
+		self: Scheduler<U...>,
+		system: System<U...>,
+		new: System<U...>
+	) -> Scheduler<U...>,
+
+	removeSystem: (
+		self: Scheduler<U...>,
+		system: System<U...>
+	) -> Scheduler<U...>,
+
+	setRunCondition: ((
+		self: Scheduler<U...>,
+		system: System<U...>,
+		fn: (U...) -> boolean
+	) -> Scheduler<U...>) & ((
+		self: Scheduler<U...>,
+		phase: Phase,
+		fn: (U...) -> boolean
+	) -> Scheduler<U...>) & ((
+		self: Scheduler<U...>,
+		pipeline: Pipeline,
+		fn: (U...) -> boolean
+	) -> Scheduler<U...>),
+
+	run: ((self: Scheduler<U...>, system: System<U...>) -> Scheduler<U...>)
+		& ((self: Scheduler<U...>, phase: Phase) -> Scheduler<U...>)
+		& ((self: Scheduler<U...>, pipeline: Pipeline) -> Scheduler<U...>),
+
+	runAll: (self: Scheduler<U...>) -> Scheduler<U...>,
+
+	insert: ((self: Scheduler<U...>, phase: Phase) -> Scheduler<U...>) & ((
+		self: Scheduler<U...>,
+		pipeline: Pipeline
+	) -> Scheduler<U...>) & ((
+		self: Scheduler<U...>,
+		phase: Phase,
+		instance: EventInstance | EventLike,
+		event: string | EventLike
+	) -> Scheduler<U...>) & ((
+		self: Scheduler<U...>,
+		Pipeline: Pipeline,
+		instance: EventInstance | EventLike,
+		event: string | EventLike
+	) -> Scheduler<U...>),
+
+	insertAfter: ((
+		self: Scheduler<U...>,
+		phase: Phase,
+		after: Phase | Pipeline
+	) -> Scheduler<U...>) & ((
+		self: Scheduler<U...>,
+		pipeline: Pipeline,
+		after: Phase | Pipeline
+	) -> Scheduler<U...>),
+
+	new: (U...) -> Scheduler<U...>
+}
+
+return {
+	Phase = Phase :: Phase,
+	Pipeline = Pipeline :: Pipeline,
+	Scheduler = Scheduler :: {
+		new: <U...>(U...) -> Scheduler<U...>	
+},
+}

package/out/types.d.ts

@@ -0,0 +1,150 @@
+
+export type SystemInfo<T extends unknown[]> = {
+    readonly system: SystemFn<T>;
+    readonly phase: Phase;
+    readonly name: string;
+    readonly logs: string[];
+}
+
+
+export interface Hooks {
+    readonly Hooks: {
+        readonly SystemAdd: "SystemAdd";
+        readonly SystemRemove: "SystemRemove";
+        readonly SystemReplace: "SystemReplace";
+        readonly SystemError: "SystemError";
+
+        readonly OuterSystemCall: "OuterSystemCall";
+        readonly InnerSystemCall: "InnerSystemCall";
+        readonly SystemCall: "SystemCall";
+
+        readonly PhaseAdd: "PhaseAdd";
+        readonly PhaseBegan: "PhaseBegan";
+    }
+    systemAdd: <T extends unknown[] = unknown[]>(scheduler: Scheduler<T>, systemInfo: SystemInfo<T>) => void;
+    systemRemove: <T extends unknown[] = unknown[]>(scheduler: Scheduler<T>, systemInfo: SystemInfo<T>) => void;
+    systemReplace: <T extends unknown[] = unknown[]>(scheduler: Scheduler<T>, oldSystemInfo: SystemInfo<T>, newSystemInfo: SystemInfo<T>) => void;
+    systemCall: <T extends unknown[] = unknown[]>(scheduler: Scheduler<T>, hookName: "OuterSystemCall" | "InnerSystemCall" | "SystemCall", systemInfo: SystemInfo<T>, nextFn: () => void) => void;
+    systemError: <T extends unknown[] = unknown[]>(scheduler: Scheduler<T>, systemInfo: SystemInfo<T>, error: string) => void;
+    phaseAdd: <T extends unknown[] = unknown[]>(scheduler: Scheduler<T>, phase: Phase) => void;
+    phaseBegan: <T extends unknown[] = unknown[]>(scheduler: Scheduler<T>, phase: Phase) => void;
+}
+type SystemAddHookArgs<T extends unknown[]> = {
+    scheduler: Scheduler<T>,
+    system: SystemInfo<T>
+}
+type SystemRemoveHookArgs<T extends unknown[]> = SystemAddHookArgs<T>;
+type SystemReplaceHookArgs<T extends unknown[]> = {
+    scheduler: Scheduler<T>,
+    old: SystemInfo<T>,
+    new: SystemInfo<T>
+}
+type SystemErrorHookArgs<T extends unknown[]> = SystemAddHookArgs<T> & { error: string };
+type SystemCallHookArgs<T extends unknown[]> = {
+    scheduler: undefined;
+    system: SystemInfo<T>;
+    nextFn: () => void;
+}
+type PhaseAddHookArgs<T extends unknown[]> = {
+    scheduler: Scheduler<T>;
+    phase: Phase;
+}
+type PhaseBeganHookArgs<T extends unknown[]> = PhaseAddHookArgs<T>;
+type HookFunctionMap<T extends unknown[] = unknown[]> = {
+    SystemAdd: SystemAddHookArgs<T>;
+    SystemRemove: SystemRemoveHookArgs<T>;
+    SystemReplace: SystemRemoveHookArgs<T>;
+    SystemError: SystemErrorHookArgs<T>;
+    OuterSystemCall: SystemCallHookArgs<T>;
+    InnerSystemCall: SystemCallHookArgs<T>;
+    SystemCall: SystemCallHookArgs<T>;
+    PhaseAdd: PhaseAddHookArgs<T>;
+    PhaseBegan: PhaseBeganHookArgs<T>;
+}
+// Utility type to get the correct function type based on the hook name
+type HookFunctionArgs<K extends keyof HookFunctionMap, T extends unknown[]> = HookFunctionMap<T>[K];
+
+export type SystemFn<T extends unknown[]> = ((...args: T) => unknown[]) | ((...args: T) => void);
+
+export interface SystemTable<T extends unknown[]> {
+    readonly system: SystemFn<T>;
+    readonly phase?: Phase
+    readonly [key: string]: unknown
+}
+
+export type System<T extends unknown[]> = SystemFn<T> | SystemTable<T>;
+
+export interface EventLike {
+    connect(callback: (...args: unknown[]) => void): void;
+    Connect(callback: (...args: unknown[]) => void): void;
+    on(callback: (...args: unknown[]) => void): void;
+    On(callback: (...args: unknown[]) => void): void;
+}
+
+export type EventInstance = Instance | EventLike;
+
+declare class Phase {
+    constructor(debugName?: string)
+    static readonly PreStartup: Phase
+    static readonly Startup: Phase
+    static readonly PostStartup: Phase
+    static readonly PreRender: Phase
+    static readonly PreAnimation: Phase
+    static readonly PreSimulation: Phase
+    static readonly PostSimulation: Phase
+    static readonly First: Phase
+    static readonly PreUpdate: Phase
+    static readonly Update: Phase
+    static readonly PostUpdate: Phase
+    static readonly Last: Phase
+}
+
+declare class Pipeline {
+    constructor(debugName?: string)
+    insert(phase: Phase) : Pipeline
+    insertAfter(phase: Phase, after: Phase): Pipeline
+    static readonly Main: Pipeline
+    static readonly Startup: Pipeline
+}
+
+export interface Utils {
+    getSystem: <T extends unknown[]>(system: System<T>) => SystemFn<T> | undefined   
+    getSystemName: <T extends unknown[]>(system: SystemFn<T>) => string
+    isPhase: (phase: Phase) => Phase | undefined
+    isPipeline: (pipeline: Pipeline) => Pipeline | undefined
+    getEventIdentifier: (instance: EventInstance, event?: EventLike) => string
+    isValidEvent: (instance: EventInstance, event?: EventLike) => boolean
+}
+
+export interface Plugin {
+    build<T extends unknown[]>(schedular: Scheduler<T>): void
+}
+
+declare class Scheduler<T extends unknown[]> {
+    Hooks: Hooks["Hooks"]
+    insertAfter(phase: Phase, after: Phase | Pipeline): Scheduler<T>
+    insertAfter(pipeline: Pipeline, after: Phase | Pipeline): Scheduler<T>
+    insert(phase: Phase): Scheduler<T>
+    insert(phase: Pipeline): Scheduler<T>
+    insert(phase: Phase, instance: EventInstance | EventLike): Scheduler<T>
+    insert(pipeline: Pipeline, instance: EventInstance | EventLike): Scheduler<T>
+    runAll(): Scheduler<T>
+    run(system: System<T>): Scheduler<T>
+    run(phase: Phase): Scheduler<T>
+    run(pipeline: Pipeline): Scheduler<T>
+    setRunCondition(system: System<T>, fn: (...args: T) => boolean): Scheduler<T>
+    setRunCondition(phase: Phase, fn: (...args: T) => boolean): Scheduler<T>
+    setRunCondition(pipeline: Pipeline, fn: (...args: T) => boolean): Scheduler<T>
+    removeSystem(system: System<T>): Scheduler<T>
+    replaceSystem(oldSystem: System<T>, newSystem: System<T>): Scheduler<T>
+    editSystem(system: System<T>, phase: Phase): Scheduler<T>
+    addSystem(system: System<T>, phase?: Phase): Scheduler<T>
+    addPlugin(plugin: Plugin): Scheduler<T>
+    /** @hidden */
+    _addHook<K extends keyof HookFunctionMap>(hook: K, fn: (info: HookFunctionArgs<K, T>) => void): void
+    constructor(...args: T)
+}
+
+
+
+

package/out/utils.d.ts

@@ -0,0 +1,4 @@
+import { Utils } from "./types";
+
+declare const utils : Utils;
+export = utils;

package/out/utils.luau

@@ -0,0 +1,83 @@
+type Phase = any
+type Pipeline = any
+
+type SystemFn<U...> = ((U...) -> any) | ((U...) -> ())
+
+type SystemTable<U...> = {
+	system: SystemFn<U...>,
+	phase: Phase?,
+	[any]: any
+}
+
+type System<U...> = SystemFn<U...> | SystemTable<U...>
+
+local function getSystem<U...>(system: any): SystemTable<U...>?
+	if type(system) == "function" then
+		return system
+	elseif type(system) == "table" and system.system then
+		return system.system
+	else
+		return nil
+	end
+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")
+	end
+
+	return name
+end
+
+local function isPhase(phase: any): Phase?
+	if type(phase) == "table" and phase._type == "phase" then
+		return phase
+	else
+		return nil
+	end
+end
+
+local function isPipeline(pipeline: any): Pipeline?
+	if type(pipeline) == "table" and pipeline._type == "pipeline" then
+		return pipeline
+	else
+		return nil
+	end
+end
+
+local function getEventIdentifier(instance, event)
+	return `{instance}{event and `@{event}` or ""}`
+end
+
+local validEventMethods = {
+	"Connect",
+	"connect",
+	"On",
+	"on",
+}
+
+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
+			end
+		end
+	end
+
+	return false
+end
+
+return {
+	getSystem = getSystem,
+	getSystemName = getSystemName,
+	isPhase = isPhase,
+	isPipeline = isPipeline,
+	getEventIdentifier = getEventIdentifier,
+	isValidEvent = isValidEvent,
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@rbxts/planck",
+  "version": "0.1.0-rc.2",
+  "description": "An agnostic scheduler for ECS",
+  "main": "out/init.lua",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yetanotherclown/planck"
+  },
+  "homepage": "https://yetanotherclown.github.io/planck",
+  "keywords": [
+    "ECS",
+    "Entity Component System",
+    "Scheduler",
+    "@rbxts",
+    "Roblox",
+    "Roblox-TS",
+    "roblox ts",
+    "roblox-ts"
+  ],
+  "author": "YetAnotherClown",
+  "license": "MIT",
+  "types": "out/index.d.ts",
+  "files": [
+    "out",
+    "!**/*.tsbuildinfo",
+    "!out/__tests__",
+    "!out/__tests__/**/*",
+    "!out/jest.config.luau"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@rbxts/compiler-types": "3.0.0-types.0",
+    "@rbxts/types": "^1.0.813",
+    "@typescript-eslint/eslint-plugin": "^8.19.0",
+    "@typescript-eslint/parser": "^8.19.0",
+    "eslint": "^9.17.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.2.1",
+    "eslint-plugin-roblox-ts": "^0.0.36",
+    "prettier": "^3.4.2",
+    "roblox-ts": "^3.0.0",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "rbxtsc",
+    "watch": "rbxtsc -w"
+  }
+}