@ecsframework/core 0.0.1

package/out/framework/flamecs/registry.luau

@@ -0,0 +1,567 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local ecs = TS.import(script, TS.getModule(script, "@rbxts", "jecs").jecs)
+local createSignal = TS.import(script, script.Parent, "signal").createSignal
+local components = {}
+local IdTocomponents = {}
+local scheduleComponent = {}
+local worldSignals = {}
+--[[
+	*
+	 * Returns a signal that fires when a component is added to an entity.
+	 *
+	 * @template T - The type of the component.
+	 * @param key - Flamework autogenerated key for the component.
+	 * @returns A signal that fires when the component is added to any entity.
+	 * @metadata macro
+	 
+]]
+local component
+local function added(registery, key)
+	local id = component(registery, key)
+	local _registery = registery
+	return worldSignals[_registery].added[id]
+end
+--[[
+	*
+	 * Returns a signal that fires when a component is removed from an entity.
+	 *
+	 * @template T - The type of the component.
+	 * @param key - Flamework autogenerated key for the component.
+	 * @returns A signal that fires when the component is removed from any entity.
+	 * @metadata macro
+	 
+]]
+local function removed(registery, key)
+	local id = component(registery, key)
+	local _registery = registery
+	return worldSignals[_registery].removed[id]
+end
+--[[
+	*
+	 * Returns a signal that fires when a component's value changes on an entity.
+	 *
+	 * @template T - The type of the component.
+	 * @param key - Flamework autogenerated key for the component.
+	 * @returns A signal that fires when the component's value changes on any
+	 *   entity.
+	 * @metadata macro
+	 
+]]
+local function changed(registery, key)
+	local id = component(registery, key)
+	local _registery = registery
+	return worldSignals[_registery].changed[id]
+end
+local function hookListeners(registry, id)
+	local addedSignal = createSignal()
+	local removedSignal = createSignal()
+	local changedSignal = createSignal()
+	local _registry = registry
+	local _condition = worldSignals[_registry]
+	if _condition == nil then
+		_condition = {
+			added = {},
+			removed = {},
+			changed = {},
+		}
+	end
+	local signals = _condition
+	local _registry_1 = registry
+	worldSignals[_registry_1] = signals
+	local _added = signals.added
+	local _id = id
+	_added[_id] = addedSignal
+	local _removed = signals.removed
+	local _id_1 = id
+	_removed[_id_1] = removedSignal
+	local _changed = signals.changed
+	local _id_2 = id
+	_changed[_id_2] = changedSignal
+	registry:set(id, ecs.OnAdd, function(entity, _, data)
+		addedSignal:fire(entity, data)
+	end)
+	registry:set(id, ecs.OnRemove, function(entity)
+		removedSignal:fire(entity)
+	end)
+	registry:set(id, ecs.OnChange, function(entity, data)
+		changedSignal:fire(entity, data)
+	end)
+end
+--[[
+	*
+	 * Registers an existing entity to the component registry.
+	 *
+	 * @template T - The type of the component.
+	 * @param runtimeId - The runtime entity to be registered.
+	 * @param key - Flamework autogenerated key.
+	 * @metadata macro
+	 
+]]
+local function reserve(registry, runtimeId, key)
+	local _key = key
+	assert(_key ~= "" and _key)
+	local _key_1 = key
+	local _arg0 = not (components[_key_1] ~= nil)
+	local _arg1 = `A component with the key "{key}" already exists`
+	assert(_arg0, _arg1)
+	local _key_2 = key
+	local _runtimeId = runtimeId
+	components[_key_2] = _runtimeId
+	local _runtimeId_1 = runtimeId
+	local _key_3 = key
+	IdTocomponents[_runtimeId_1] = _key_3
+	if registry ~= nil then
+		hookListeners(registry, runtimeId)
+		return nil
+	end
+	local _runtimeId_2 = runtimeId
+	scheduleComponent[_runtimeId_2] = true
+end
+--[[
+	*
+	 * Defines a component that can be added to an entity. Components can either tag
+	 * an entity (e.g., "this entity is an NPC"), store data for an entity (e.g.,
+	 * "this entity is located at Vector3.new(10, 20, 30)"), or represent
+	 * relationships between entities <Pair<P, O>> (e.g., "bob Likes alice") that
+	 * may also store additional data (e.g., "bob Eats 10 apples").
+	 *
+	 * @template T - The type of the component.
+	 * @param key - Flamework autogenerated key.
+	 * @returns The component entity ID.
+	 * @metadata macro
+	 
+]]
+function component(registry, key)
+	local _key = key
+	assert(_key ~= "" and _key)
+	local _key_1 = key
+	local id = components[_key_1]
+	if id == nil then
+		id = ecs.component()
+		local _key_2 = key
+		local _id = id
+		components[_key_2] = _id
+		local _id_1 = id
+		local _key_3 = key
+		IdTocomponents[_id_1] = _key_3
+		if registry ~= nil then
+			hookListeners(registry, id)
+			return id
+		end
+		local _id_2 = id
+		scheduleComponent[_id_2] = true
+	end
+	return id
+end
+--[[
+	*
+	 * Retrieves the ID of a component or a pair relationship.
+	 *
+	 * @template T - The type of the component.
+	 * @param key - Flamework autogenerated key or pair key.
+	 * @returns The component or pair ID.
+	 * @metadata macro.
+	 
+]]
+local function getId(registry, key)
+	local _key = key
+	assert(_key ~= "" and _key)
+	local _key_1 = key
+	if type(_key_1) == "table" then
+		local pairKey = key
+		local object = component(registry, pairKey.obj)
+		local predicate = component(registry, pairKey.pred)
+		return ecs.pair(predicate, object)
+	end
+	return component(registry, key)
+end
+local function getKey(runtimeId)
+	local _runtimeId = runtimeId
+	return IdTocomponents[_runtimeId]
+end
+--[[
+	*
+	 * Creates a new empty entity.
+	 *
+	 * @returns The created entity.
+	 * @metadata macro
+	 
+]]
+--[[
+	*
+	 * Creates a new entity with the specified tag components.
+	 *
+	 * @template T - The type of the components.
+	 * @param keys - Flamework autogenerated keys.
+	 * @returns The created entity.
+	 * @metadata macro
+	 
+]]
+--[[
+	*
+	 * Creates a new entity with the specified components and their values.
+	 *
+	 * @template T - The type of the components.
+	 * @param values - The values to set for the components.
+	 * @param keys - Flamework autogenerated keys.
+	 * @returns The created entity.
+	 * @metadata macro
+	 
+]]
+local function spawn(registry, argument1, argument2)
+	local entity = registry:entity()
+	if argument2 ~= nil then
+		-- Spawn with components: spawn(values, keys)
+		local values = argument1
+		local keys = argument2
+		for index = 0, #keys - 1 do
+			local id = getId(registry, keys[index + 1])
+			local value = values[index + 1]
+			if value ~= nil then
+				registry:set(entity, id, value)
+			else
+				registry:add(entity, id)
+			end
+		end
+	elseif argument1 ~= nil then
+		-- Spawn with tags only: spawn(keys)
+		local keys = argument1
+		for _, key in keys do
+			registry:add(entity, getId(registry, key))
+		end
+	end
+	return entity
+end
+--[[
+	*
+	 * Deletes the specified entity and all associated components.
+	 *
+	 * @param entity - The entity to delete.
+	 
+]]
+local function despawn(registry, entity)
+	registry:delete(entity)
+end
+--[[
+	*
+	 * Adds or updates multiple components for the specified entity.
+	 *
+	 * @template T - The type of the components.
+	 * @param entity - The entity to modify.
+	 * @param keys - Flamework autogenerated keys.
+	 * @metadata macro
+	 
+]]
+--[[
+	*
+	 * Adds or updates multiple components for the specified entity.
+	 *
+	 * @template T - The type of the components.
+	 * @param entity - The entity to modify.
+	 * @param values - The values to set for the components.
+	 * @param keys - Flamework autogenerated keys.
+	 * @metadata macro
+	 
+]]
+local function insert(registry, entity, argument1, argument2)
+	local _arg0 = argument1 ~= nil
+	assert(_arg0)
+	if argument2 ~= nil then
+		-- Insert components: insert(entity, values, keys)
+		local values = argument1
+		local keys = argument2
+		for index = 0, #keys - 1 do
+			local id = getId(registry, keys[index + 1])
+			local value = values[index + 1]
+			if value ~= nil then
+				registry:set(entity, id, value)
+			else
+				registry:add(entity, id)
+			end
+		end
+	else
+		-- Insert tags only: insert(entity, keys)
+		local keys = argument1
+		for _, key in keys do
+			registry:add(entity, getId(registry, key))
+		end
+	end
+end
+--[[
+	*
+	 * Adds a pair relationship with a specific target entity.
+	 *
+	 * @template T - The type of the pair.
+	 * @param entity - The entity to which the pair relationship is added.
+	 * @param object - The target entity of the relationship (object of the pair).
+	 * @param key - Flamework autogenerated key.
+	 * @metadata macro
+	 
+]]
+--[[
+	*
+	 * Adds a fully defined pair to an entity. This is used when both the predicate
+	 * and object of the pair are known at compile-time.
+	 *
+	 * @template T - The type of the pair.
+	 * @param entity - The entity to which the pair component is added.
+	 * @param key - Flamework autogenerated key.
+	 * @metadata macro
+	 
+]]
+--[[
+	*
+	 * Adds a component to an entity.
+	 *
+	 * @template T - The type of the component.
+	 * @param entity - The entity to which the component is added.
+	 * @param key - Flamework autogenerated key.
+	 * @metadata macro
+	 
+]]
+local function add(registry, entity, argument1, argument2)
+	if argument2 ~= nil then
+		-- Pair<P, _> case: add(entity, object, key)
+		local object = argument1
+		local key = argument2
+		registry:add(entity, ecs.pair(component(registry, key), object))
+	else
+		-- Known component case: add(entity, key)
+		local key = argument1
+		registry:add(entity, getId(registry, key))
+	end
+end
+--[[
+	*
+	 * Removes a pair relationship with a specific target entity.
+	 *
+	 * @template T - The type of the pair.
+	 * @param entity - The entity from which the pair relationship is removed.
+	 * @param object - The target entity of the relationship (object of the pair).
+	 * @param key - Flamework autogenerated key.
+	 * @metadata macro
+	 
+]]
+--[[
+	*
+	 * Removes a fully defined pair from an entity. This is used when both the
+	 * predicate and object of the pair are known at compile-time.
+	 *
+	 * @template T - The type of the pair.
+	 * @param entity - The entity from which the pair component is removed.
+	 * @param key - Flamework autogenerated key.
+	 * @metadata macro
+	 
+]]
+--[[
+	*
+	 * Removes a component from an entity.
+	 *
+	 * @template T - The type of the component.
+	 * @param entity - The entity from which the component is removed.
+	 * @param key - Flamework autogenerated key.
+	 * @metadata macro
+	 
+]]
+local function remove(registry, entity, argument1, argument2)
+	if argument2 ~= nil then
+		-- Pair<P, _> case: remove(entity, object, key)
+		local object = argument1
+		local key = argument2
+		registry:remove(entity, ecs.pair(component(registry, key), object))
+	else
+		-- Known component case: remove(entity, key)
+		local key = argument1
+		registry:remove(entity, getId(registry, key))
+	end
+end
+--[[
+	*
+	 * Sets a value for a pair with a specific runtime target entity.
+	 *
+	 * @template T - The type of the pair.
+	 * @param entity - The entity to which the pair relationship is added.
+	 * @param object - The target entity of the relationship (object of the pair).
+	 * @param value - The value associated with the pair relationship.
+	 * @param key - Flamework autogenerated key.
+	 * @metadata macro
+	 
+]]
+--[[
+	*
+	 * Sets a value for a fully defined pair on an entity. This is used when both
+	 * the predicate and object of the pair are known at compile-time.
+	 *
+	 * @template T - The type of the pair.
+	 * @param entity - The entity to which the pair component is added.
+	 * @param value - The value associated with the pair component.
+	 * @param key - Flamework autogenerated key.
+	 * @metadata macro
+	 
+]]
+--[[
+	*
+	 * Sets a value for a component on an entity.
+	 *
+	 * @template T - The type of the component.
+	 * @param entity - The entity to which the component is added or updated.
+	 * @param value - The value associated with the component.
+	 * @param key - Flamework autogenerated key.
+	 * @metadata macro
+	 
+]]
+local function set(registry, entity, argument1, argument2, argument3)
+	if argument3 ~= nil then
+		-- Pair<P, _> case: set(entity, object, value, key)
+		local object = argument1
+		local value = argument2
+		local key = argument3
+		registry:set(entity, ecs.pair(component(registry, key), object), value)
+	else
+		-- Known component case: set(entity, value, key)
+		local value = argument1
+		local key = argument2
+		registry:set(entity, getId(registry, key), value)
+	end
+end
+--[[
+	*
+	 * Retrieves the value of a pair relationship for a specific entity and target.
+	 *
+	 * @template T - The type of the pair.
+	 * @param entity - The entity from which to retrieve the pair relationship.
+	 * @param object - The target entity of the relationship (object of the pair).
+	 * @param key - Flamework autogenerated key.
+	 * @returns The value associated with the pair relationship.
+	 * @metadata macro
+	 
+]]
+--[[
+	*
+	 * Retrieves the value of a component or pair for a specific entity.
+	 *
+	 * @template T - The type of the component or pair.
+	 * @param entity - The entity from which to retrieve the component or pair.
+	 * @param key - Flamework autogenerated key.
+	 * @returns The value associated with the component or pair.
+	 * @metadata macro
+	 
+]]
+local function get(registry, entity, argument1, argument2)
+	if argument2 ~= nil then
+		-- Pair<P, _> case: get(entity, object, key)
+		local object = argument1
+		local key = argument2
+		return registry:get(entity, ecs.pair(component(registry, key), object))
+	end
+	-- Known component case: get(entity, key)
+	local key = argument1
+	return registry:get(entity, getId(registry, key))
+end
+--[[
+	*
+	 * Checks if a pair relationship exists for a specific entity and target.
+	 *
+	 * @template T - The type of the pair.
+	 * @param entity - The entity to check for the pair relationship.
+	 * @param object - The target entity of the relationship (object of the pair).
+	 * @param key - Flamework autogenerated key.
+	 * @returns True if the pair relationship exists, false otherwise.
+	 * @metadata macro
+	 
+]]
+--[[
+	*
+	 * Checks if a component or pair exists for a specific entity.
+	 *
+	 * @template T - The type of the component or pair.
+	 * @param entity - The entity to check for the component or pair.
+	 * @param key - Flamework autogenerated key.
+	 * @returns True if the component or pair exists, false otherwise.
+	 * @metadata macro
+	 
+]]
+local function has(registry, entity, argument1, argument2)
+	if argument2 ~= nil then
+		-- Pair<P, _> case: has(entity, object, key)
+		local object = argument1
+		local key = argument2
+		return registry:has(entity, ecs.pair(component(registry, key), object))
+	end
+	-- Known component case: has(entity, key)
+	local key = argument1
+	return registry:has(entity, getId(registry, key))
+end
+--[[
+	*
+	 * Retrieves the target entity of a relationship involving the specified entity
+	 * and component.
+	 *
+	 * @template T - The type of the component.
+	 * @param entity - The entity to get the target for.
+	 * @param key - Flamework autogenerated key.
+	 * @returns The target entity if a relationship exists, or undefined otherwise.
+	 * @metadata macro
+	 
+]]
+local function target(registry, entity, key)
+	local id = component(registry, key)
+	return registry:target(entity, id)
+end
+--[[
+	*
+	 * Retrieves the parent entity (target of the ChildOf relationship) for the
+	 * given entity.
+	 *
+	 * @param entity - The entity for which to get the parent.
+	 * @returns The parent entity, or undefined if no parent exists.
+	 
+]]
+local function parent(registry, entity)
+	return target(registry, entity, "$ecsframework:core:framework/flamecs/registry@ChildOf")
+end
+--[[
+	*
+	 * Creates a pair relationship between a component and an entity.
+	 *
+	 * @template P - The type of the predicate component.
+	 * @template O - The type of the object component.
+	 * @param object - The object entity.
+	 * @param predicate - The predicate component key.
+	 * @returns The pair ID.
+	 * @metadata macro
+	 
+]]
+local function pair(registry, object, predicate)
+	local predicateId = component(registry, predicate)
+	return ecs.pair(predicateId, object)
+end
+local function initWorld(registry)
+	reserve(registry, ecs.Wildcard, "$ecsframework:core:framework/flamecs/registry@Wildcard")
+	reserve(registry, ecs.ChildOf, "$ecsframework:core:framework/flamecs/registry@ChildOf")
+end
+return {
+	added = added,
+	removed = removed,
+	changed = changed,
+	hookListeners = hookListeners,
+	reserve = reserve,
+	component = component,
+	getId = getId,
+	getKey = getKey,
+	spawn = spawn,
+	despawn = despawn,
+	insert = insert,
+	add = add,
+	remove = remove,
+	set = set,
+	get = get,
+	has = has,
+	target = target,
+	parent = parent,
+	pair = pair,
+	initWorld = initWorld,
+	scheduleComponent = scheduleComponent,
+	worldSignals = worldSignals,
+}

package/out/framework/flamecs/signal.d.ts

@@ -0,0 +1,5 @@
+export interface Signal<T extends Array<unknown>> {
+    connect(func: (...args: T) => void): () => void;
+    fire(...args: T): void;
+}
+export declare function createSignal<T extends Array<unknown>>(): Signal<T>;

package/out/framework/flamecs/signal.luau

@@ -0,0 +1,24 @@
+-- Compiled with roblox-ts v3.0.0
+local function createSignal()
+	local listeners = {}
+	return {
+		connect = function(self, func)
+			local _func = func
+			table.insert(listeners, _func)
+			return function()
+				local _func_1 = func
+				local index = (table.find(listeners, _func_1) or 0) - 1
+				local _ = index ~= -1 and table.remove(listeners, index + 1)
+			end
+		end,
+		fire = function(self, ...)
+			local args = { ... }
+			for _, listener in listeners do
+				listener(unpack(args))
+			end
+		end,
+	}
+end
+return {
+	createSignal = createSignal,
+}

package/out/framework/flamecs/topo.d.ts

@@ -0,0 +1,32 @@
+import { World } from "@rbxts/jecs";
+import { BaseSystem } from "../base-system";
+type Cleanup<T> = (state: T) => boolean;
+interface HookStorage<T> {
+    cleanup?: Cleanup<T>;
+    states: Map<string, T>;
+}
+/**
+ * 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.
+ */
+export declare function start(node: Record<string, HookStorage<unknown>>, system: BaseSystem, world: World, callback: () => void): void;
+export declare function useSystem(): BaseSystem;
+export declare function useWorld(): World;
+/**
+ * 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.
+ */
+export declare function useHookState<T>(key: string, discriminator: unknown, cleanup?: Cleanup<T>): T;
+export {};