@ecsframework/core 0.0.1

package/out/framework/flamecs/topo.luau

@@ -0,0 +1,96 @@
+-- Compiled with roblox-ts v3.0.0
+local stack = {}
+local function cleanupUnused()
+	-- ▼ Array.pop ▼
+	local _length = #stack
+	local _result = stack[_length]
+	stack[_length] = nil
+	-- ▲ Array.pop ▲
+	local context = _result
+	assert(context, "No context to cleanup.")
+	for _, storage in pairs(context.node) do
+		for key, state in storage.states do
+			if not (context.activeKeys[key] ~= nil) and (not storage.cleanup or storage.cleanup(state)) then
+				storage.states[key] = nil
+			end
+		end
+	end
+end
+--[[
+	*
+	 * Starts a new stack frame for a function, ensuring cleanup after execution.
+	 * Intended to be used in systems.
+	 *
+	 * @param node - The node to store the state for the current function.
+	 * @param callback - The function to execute within the new stack frame.
+	 
+]]
+local function start(node, system, world, callback)
+	local _arg0 = {
+		activeKeys = {},
+		node = node,
+		world = world,
+		system = system,
+	}
+	table.insert(stack, _arg0)
+	callback()
+	cleanupUnused()
+	stack[#stack] = nil
+end
+local function useSystem()
+	local context = stack[#stack]
+	assert(context, "Hooks can only be used within a `start` function.")
+	return context.system
+end
+local function useWorld()
+	local context = stack[#stack]
+	assert(context, "Hooks can only be used within a `start` function.")
+	return context.world
+end
+--[[
+	*
+	 * Creates or retrieves a state object for a hook, keyed by a unique identifier.
+	 *
+	 * @template T The type of the hook state.
+	 * @param key - A unique string identifier for the hook state.
+	 * @param discriminator - An optional value to further distinguish different
+	 *   states within the same key. Defaults to the key itself.
+	 * @param cleanup - An optional function that determines whether the state
+	 *   should be cleaned up. It should return true if the state should be removed.
+	 *   If not provided, the state will be cleaned up when the hook was not
+	 *   accessed in the current context.
+	 * @returns The state object of type T.
+	 
+]]
+local function useHookState(key, discriminator, cleanup)
+	if discriminator == nil then
+		discriminator = key
+	end
+	local context = stack[#stack]
+	assert(context, "Hooks can only be used within a `start` function.")
+	local storage = context.node[key]
+	if not storage then
+		storage = {
+			cleanup = cleanup,
+			states = {},
+		}
+		context.node[key] = storage
+	end
+	local stringDiscriminator = tostring(discriminator)
+	local compositeKey = `{key}-{stringDiscriminator}`
+	context.activeKeys[compositeKey] = true
+	local state = storage.states[compositeKey]
+	if state == nil then
+		state = {}
+		local _states = storage.states
+		local _state = state
+		_states[compositeKey] = _state
+	end
+	return state
+end
+return {
+	start = start,
+	useSystem = useSystem,
+	useWorld = useWorld,
+	useHookState = useHookState,
+}

package/out/framework/hooks/query-change.d.ts

@@ -0,0 +1,11 @@
+import { Entity } from "@rbxts/jecs";
+import { ComponentKey } from "../flamecs/registry";
+import { Modding } from "@flamework/core";
+export interface QueryRecord<T> {
+    new?: T;
+    old?: T;
+}
+type Return<T> = [entity: Entity, record: QueryRecord<T>, isDestroyedEntity: boolean];
+/** @metadata macro */
+export declare function QueryChange<T>(componentTypeUd?: ComponentKey<T>, key?: Modding.Caller<"uuid">): IterableFunction<Return<T>>;
+export {};

package/out/framework/hooks/query-change.luau

@@ -0,0 +1,109 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _flamecs = TS.import(script, script.Parent.Parent, "flamecs")
+local useHookState = _flamecs.useHookState
+local useSystem = _flamecs.useSystem
+local useWorld = _flamecs.useWorld
+--* @metadata macro 
+local function QueryChange(componentTypeUd, key)
+	local storage = useHookState(key, componentTypeUd, function()
+		return false
+	end)
+	local world = useWorld()
+	local system = useSystem()
+	local _value = storage.componentTypeUd
+	if not (_value ~= "" and _value) then
+		storage.componentTypeUd = componentTypeUd
+		local componentId = system:GetComponentId(componentTypeUd)
+		local query = world:query(componentId)
+		local _result = storage.connections
+		if _result ~= nil then
+			-- ▼ ReadonlyArray.forEach ▼
+			local _callback = function(disconnect)
+				return disconnect()
+			end
+			for _k, _v in _result do
+				_callback(_v, _k - 1, _result)
+			end
+			-- ▲ ReadonlyArray.forEach ▲
+		end
+		storage.connections = {}
+		storage.changes = {}
+		storage.prevEntityDatas = {}
+		local _connections = storage.connections
+		local _arg0 = world:added(componentId, function(entity, _, data)
+			local record = {
+				old = nil,
+				new = data,
+			}
+			local _changes = storage.changes
+			local _arg0_1 = { entity, record, false }
+			table.insert(_changes, _arg0_1)
+		end)
+		table.insert(_connections, _arg0)
+		local _connections_1 = storage.connections
+		local _arg0_1 = world:changed(componentId, function(entity, _, data)
+			local _prevEntityDatas = storage.prevEntityDatas
+			local _entity = entity
+			local prevData = _prevEntityDatas[_entity]
+			local _changes = storage.changes
+			local _arg0_2 = { entity, {
+				old = prevData,
+				new = data,
+			}, false }
+			table.insert(_changes, _arg0_2)
+			local _prevEntityDatas_1 = storage.prevEntityDatas
+			local _entity_1 = entity
+			local _data = data
+			_prevEntityDatas_1[_entity_1] = _data
+		end)
+		table.insert(_connections_1, _arg0_1)
+		local _connections_2 = storage.connections
+		local _arg0_2 = world:removed(componentId, function(entity)
+			local _prevEntityDatas = storage.prevEntityDatas
+			local _entity = entity
+			local prevData = _prevEntityDatas[_entity]
+			local _changes = storage.changes
+			local _arg0_3 = { entity, {
+				old = prevData,
+				new = nil,
+			}, system:HasComponent(entity, "$ecsframework:core:framework/components/destroyed-component@DestroyComponent") }
+			table.insert(_changes, _arg0_3)
+		end)
+		table.insert(_connections_2, _arg0_2)
+		local iter = query:iter()
+		return function()
+			local entity, componentData = iter()
+			if componentData == nil then
+				return nil
+			end
+			storage.prevEntityDatas[entity] = componentData
+			return { entity, {
+				new = componentData,
+				old = nil,
+			}, false }
+		end
+	end
+	return function()
+		local result = table.remove(storage.changes, 1)
+		if result == nil then
+			return nil
+		end
+		local _prevEntityDatas = storage.prevEntityDatas
+		local _arg0 = result[1]
+		local _condition = not (_prevEntityDatas[_arg0] ~= nil)
+		if _condition then
+			_condition = result[2].new
+		end
+		if _condition ~= 0 and _condition == _condition and _condition ~= "" and _condition then
+			local _prevEntityDatas_1 = storage.prevEntityDatas
+			local _arg0_1 = result[1]
+			local _new = result[2].new
+			_prevEntityDatas_1[_arg0_1] = _new
+		end
+		return result
+	end
+end
+return {
+	QueryChange = QueryChange,
+}

package/out/framework/hooks/use-added.d.ts

@@ -0,0 +1,17 @@
+import type { Modding } from "@flamework/core";
+import { ComponentKey, Entity } from "../flamecs/registry";
+/**
+ * Utility for handling event-like objects.
+ *
+ * Connects to the provided event-like object and stores incoming events.
+ * Returns an iterable function that yields the stored events in the order they
+ * were received.
+ *
+ * @template T - The tuple type of event arguments.
+ * @param event - The event-like object to connect to.
+ * @param discriminator - An optional value to additionally key by.
+ * @param key - An automatically generated key to store the event state.
+ * @returns An iterable function that yields stored events.
+ * @metadata macro
+ */
+export declare function useAdded<T>(componentKey?: ComponentKey<T>, key?: Modding.Caller<"uuid">): IterableFunction<[Entity, T]>;

package/out/framework/hooks/use-added.luau

@@ -0,0 +1,54 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _flamecs = TS.import(script, script.Parent.Parent, "flamecs")
+local useHookState = _flamecs.useHookState
+local useSystem = _flamecs.useSystem
+--[[
+	*
+	 * Utility for handling event-like objects.
+	 *
+	 * Connects to the provided event-like object and stores incoming events.
+	 * Returns an iterable function that yields the stored events in the order they
+	 * were received.
+	 *
+	 * @template T - The tuple type of event arguments.
+	 * @param event - The event-like object to connect to.
+	 * @param discriminator - An optional value to additionally key by.
+	 * @param key - An automatically generated key to store the event state.
+	 * @returns An iterable function that yields stored events.
+	 * @metadata macro
+	 
+]]
+local function useAdded(componentKey, key)
+	local _key = key
+	assert(_key ~= "" and _key)
+	local storage = useHookState(key, componentKey, function()
+		return false
+	end)
+	local system = useSystem()
+	if storage.component ~= componentKey and storage.connection then
+		storage.connection()
+		storage.connection = nil
+	end
+	if not storage.connection then
+		storage.events = {}
+		for entity in system:Each(componentKey) do
+			local _events = storage.events
+			local _arg0 = { entity, system:GetComponent(entity, componentKey) }
+			table.insert(_events, _arg0)
+		end
+		storage.component = componentKey
+		storage.connection = system:Added(componentKey):connect(function(entity, data)
+			local _events = storage.events
+			local _arg0 = { entity, data }
+			table.insert(_events, _arg0)
+			return #_events
+		end)
+	end
+	return function()
+		return table.remove(storage.events, 1)
+	end
+end
+return {
+	useAdded = useAdded,
+}

package/out/framework/hooks/use-changed.d.ts

@@ -0,0 +1,17 @@
+import type { Modding } from "@flamework/core";
+import { ComponentKey, Entity } from "../flamecs/registry";
+/**
+ * Utility for handling event-like objects.
+ *
+ * Connects to the provided event-like object and stores incoming events.
+ * Returns an iterable function that yields the stored events in the order they
+ * were received.
+ *
+ * @template T - The tuple type of event arguments.
+ * @param event - The event-like object to connect to.
+ * @param discriminator - An optional value to additionally key by.
+ * @param key - An automatically generated key to store the event state.
+ * @returns An iterable function that yields stored events.
+ * @metadata macro
+ */
+export declare function useChanged<T>(componentKey?: ComponentKey<T>, key?: Modding.Caller<"uuid">): IterableFunction<[Entity, T]>;

package/out/framework/hooks/use-changed.luau

@@ -0,0 +1,54 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _flamecs = TS.import(script, script.Parent.Parent, "flamecs")
+local useHookState = _flamecs.useHookState
+local useSystem = _flamecs.useSystem
+--[[
+	*
+	 * Utility for handling event-like objects.
+	 *
+	 * Connects to the provided event-like object and stores incoming events.
+	 * Returns an iterable function that yields the stored events in the order they
+	 * were received.
+	 *
+	 * @template T - The tuple type of event arguments.
+	 * @param event - The event-like object to connect to.
+	 * @param discriminator - An optional value to additionally key by.
+	 * @param key - An automatically generated key to store the event state.
+	 * @returns An iterable function that yields stored events.
+	 * @metadata macro
+	 
+]]
+local function useChanged(componentKey, key)
+	local _key = key
+	assert(_key ~= "" and _key)
+	local storage = useHookState(key, componentKey, function()
+		return false
+	end)
+	local system = useSystem()
+	if storage.component ~= componentKey and storage.connection then
+		storage.connection()
+		storage.connection = nil
+	end
+	if not storage.connection then
+		storage.events = {}
+		for entity in system:Each(componentKey) do
+			local _events = storage.events
+			local _arg0 = { entity, system:GetComponent(entity, componentKey) }
+			table.insert(_events, _arg0)
+		end
+		storage.component = componentKey
+		storage.connection = system:Changed(componentKey):connect(function(entity, data)
+			local _events = storage.events
+			local _arg0 = { entity, data }
+			table.insert(_events, _arg0)
+			return #_events
+		end)
+	end
+	return function()
+		return table.remove(storage.events, 1)
+	end
+end
+return {
+	useChanged = useChanged,
+}

package/out/framework/hooks/use-event.d.ts

@@ -0,0 +1,30 @@
+import type { Modding } from "@flamework/core";
+type Callback<T extends Array<unknown>> = (...args: T) => void;
+type EventLike<T extends Array<unknown> = Array<unknown>> = ((callback: Callback<T>) => ConnectionLike) | {
+    Connect(callback: Callback<T>): ConnectionLike;
+} | {
+    connect(callback: Callback<T>): ConnectionLike;
+} | {
+    on(callback: Callback<T>): ConnectionLike;
+};
+type ConnectionLike = (() => void) | {
+    Disconnect(): void;
+} | {
+    disconnect(): void;
+};
+/**
+ * Utility for handling event-like objects.
+ *
+ * Connects to the provided event-like object and stores incoming events.
+ * Returns an iterable function that yields the stored events in the order they
+ * were received.
+ *
+ * @template T - The tuple type of event arguments.
+ * @param event - The event-like object to connect to.
+ * @param discriminator - An optional value to additionally key by.
+ * @param key - An automatically generated key to store the event state.
+ * @returns An iterable function that yields stored events.
+ * @metadata macro
+ */
+export declare function useEvent<T extends Array<unknown>>(event: EventLike<T>, discriminator?: unknown, key?: Modding.Caller<"uuid">): IterableFunction<T>;
+export {};

package/out/framework/hooks/use-event.luau

@@ -0,0 +1,92 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local useHookState = TS.import(script, script.Parent.Parent, "flamecs").useHookState
+local function connect(event, callback)
+	local _event = event
+	if type(_event) == "function" then
+		return event(callback)
+	else
+		local _event_1 = event
+		local _condition = typeof(_event_1) == "RBXScriptSignal"
+		if not _condition then
+			_condition = event.Connect ~= nil
+		end
+		if _condition then
+			return event:Connect(callback)
+		elseif event.connect ~= nil then
+			return event:connect(callback)
+		elseif event.on ~= nil then
+			return event:on(callback)
+		end
+	end
+	error("Event-like object does not have a supported connect method.")
+end
+local function disconnect(connection)
+	local _connection = connection
+	if type(_connection) == "function" then
+		connection()
+	else
+		local _connection_1 = connection
+		local _condition = typeof(_connection_1) == "RBXScriptConnection"
+		if not _condition then
+			_condition = connection.Disconnect ~= nil
+		end
+		if _condition then
+			connection:Disconnect()
+		elseif connection.disconnect ~= nil then
+			connection:disconnect()
+		else
+			error("Connection-like object does not have a supported disconnect method.")
+		end
+	end
+end
+local function cleanup(storage)
+	if storage.connection then
+		disconnect(storage.connection)
+	end
+	return false
+end
+--[[
+	*
+	 * Utility for handling event-like objects.
+	 *
+	 * Connects to the provided event-like object and stores incoming events.
+	 * Returns an iterable function that yields the stored events in the order they
+	 * were received.
+	 *
+	 * @template T - The tuple type of event arguments.
+	 * @param event - The event-like object to connect to.
+	 * @param discriminator - An optional value to additionally key by.
+	 * @param key - An automatically generated key to store the event state.
+	 * @returns An iterable function that yields stored events.
+	 * @metadata macro
+	 
+]]
+local function useEvent(event, discriminator, key)
+	local _key = key
+	assert(_key ~= "" and _key)
+	local storage = useHookState(key, discriminator, function()
+		return false
+	end)
+	if storage.event ~= event and storage.connection then
+		disconnect(storage.connection)
+		storage.connection = nil
+	end
+	if not storage.connection then
+		storage.events = {}
+		storage.event = event
+		storage.connection = connect(event, function(...)
+			local args = { ... }
+			local _events = storage.events
+			local _args = args
+			table.insert(_events, _args)
+			return #_events
+		end)
+	end
+	return function()
+		return table.remove(storage.events, 1)
+	end
+end
+return {
+	useEvent = useEvent,
+}

package/out/framework/hooks/use-removed.d.ts

@@ -0,0 +1,13 @@
+import type { Modding } from "@flamework/core";
+import { ComponentKey, Entity } from "../flamecs/registry";
+/**
+ * A hook that provides an iterable function that yields entities that have been removed.
+ * It works by connecting to the Removed event of the system and storing the incoming events.
+ * It returns the stored events in the order they were received.
+ *
+ * @param componentKey - The component key of the component to connect to.
+ * @param key - An automatically generated key to store the event state.
+ * @returns An iterable function that yields stored events.
+ * @metadata macro
+ */
+export declare function useRemoved<T>(componentKey?: ComponentKey<T>, key?: Modding.Caller<"uuid">): IterableFunction<[Entity, T]>;

package/out/framework/hooks/use-removed.luau

@@ -0,0 +1,52 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _flamecs = TS.import(script, script.Parent.Parent, "flamecs")
+local useHookState = _flamecs.useHookState
+local useSystem = _flamecs.useSystem
+--[[
+	*
+	 * A hook that provides an iterable function that yields entities that have been removed.
+	 * It works by connecting to the Removed event of the system and storing the incoming events.
+	 * It returns the stored events in the order they were received.
+	 *
+	 * @param componentKey - The component key of the component to connect to.
+	 * @param key - An automatically generated key to store the event state.
+	 * @returns An iterable function that yields stored events.
+	 * @metadata macro
+	 
+]]
+local function useRemoved(componentKey, key)
+	local _key = key
+	assert(_key ~= "" and _key)
+	local storage = useHookState(key, componentKey, function()
+		return false
+	end)
+	local system = useSystem()
+	if storage.component ~= componentKey and storage.connection then
+		storage.connection()
+		storage.connection = nil
+	end
+	if not storage.connection then
+		storage.events = {}
+		for entity in system:Each(componentKey) do
+			local _events = storage.events
+			local _arg0 = { entity, system:GetComponent(entity, componentKey) }
+			table.insert(_events, _arg0)
+		end
+		-- Store the component key and the connection.
+		storage.component = componentKey
+		storage.connection = system:Removed(componentKey):connect(function(entity)
+			local _events = storage.events
+			local _arg0 = { entity, system:GetComponent(entity, componentKey) }
+			table.insert(_events, _arg0)
+			return #_events
+		end)
+	end
+	-- Return an iterable function that yields the stored events.
+	return function()
+		return table.remove(storage.events, 1)
+	end
+end
+return {
+	useRemoved = useRemoved,
+}

package/out/framework/hooks/use-throttle.d.ts

@@ -0,0 +1,14 @@
+import type { Modding } from "@flamework/core";
+/**
+ * Utility for easy time-based throttling.
+ *
+ * Accepts a duration and returns `true` if it has been that long since the last
+ * time this function returned `true`. Always returns `true` the first time.
+ *
+ * @param seconds - The number of seconds to throttle for.
+ * @param discriminator - An optional value to additionally key by.
+ * @param key - An automatically generated key to store the throttle state.
+ * @returns - Returns true every x seconds, otherwise false.
+ * @metadata macro
+ */
+export declare function useThrottle(seconds: number, discriminator?: unknown, key?: Modding.Caller<"uuid">): boolean;

package/out/framework/hooks/use-throttle.luau

@@ -0,0 +1,33 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local useHookState = TS.import(script, script.Parent.Parent, "flamecs").useHookState
+local function cleanup(storage)
+	return os.clock() >= storage.expiry
+end
+--[[
+	*
+	 * Utility for easy time-based throttling.
+	 *
+	 * Accepts a duration and returns `true` if it has been that long since the last
+	 * time this function returned `true`. Always returns `true` the first time.
+	 *
+	 * @param seconds - The number of seconds to throttle for.
+	 * @param discriminator - An optional value to additionally key by.
+	 * @param key - An automatically generated key to store the throttle state.
+	 * @returns - Returns true every x seconds, otherwise false.
+	 * @metadata macro
+	 
+]]
+local function useThrottle(seconds, discriminator, key)
+	local storage = useHookState(key, discriminator, cleanup)
+	local currentTime = os.clock()
+	if storage.time == nil or currentTime - storage.time >= seconds then
+		storage.time = currentTime
+		storage.expiry = currentTime + seconds
+		return true
+	end
+	return false
+end
+return {
+	useThrottle = useThrottle,
+}

package/out/framework/index.d.ts

@@ -0,0 +1,28 @@
+import { Constructor } from "@flamework/core/out/utility";
+import { Entity } from "@rbxts/jecs";
+import { DependenciesContainer } from "./dependencies-container";
+import { Signal } from "./flamecs/signal";
+export declare class ECSFramework {
+    private container;
+    private systems;
+    private canCallEffect;
+    private isStarted;
+    private baseSystemCtor;
+    readonly componentsMap: ReadonlyMap<string, Constructor>;
+    private components;
+    private world;
+    readonly signals: {
+        added: ReadonlyMap<Entity, Signal<[Entity, unknown]>>;
+        changed: ReadonlyMap<Entity, Signal<[Entity, unknown]>>;
+        removed: ReadonlyMap<Entity, Signal<[Entity]>>;
+    };
+    constructor(container?: DependenciesContainer);
+    GetAllComponents(): Constructor[];
+    private initSystems;
+    private invokeStartup;
+    private initUpdate;
+    private initComponents;
+    private initComponentLifecycles;
+    private initEvents;
+    Start(): void;
+}