@rbxts/covenant 3.5.1 → 3.7.0

package/package.json

@@ -1,48 +1,48 @@
-{
-    "name": "@rbxts/covenant",
-    "version": "3.5.1",
-    "main": "src/init.luau",
-    "scripts": {
-        "build": "rbxtsc",
-        "watch": "rbxtsc -w",
-        "prepublishOnly": "npm run build"
-    },
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/cuberootmctoasted/covenant.git"
-    },
-    "keywords": [],
-    "author": "",
-    "license": "ISC",
-    "bugs": {
-        "url": "https://github.com/cuberootmctoasted/covenant/issues"
-    },
-    "homepage": "https://github.com/cuberootmctoasted/covenant#readme",
-    "description": "",
-    "types": "src/covenant.d.ts",
-    "files": [
-        "src",
-        "!**/*.tsbuildinfo"
-    ],
-    "publishConfig": {
-        "access": "public"
-    },
-    "devDependencies": {
-        "@rbxts/compiler-types": "^3.0.0-types.0",
-        "@rbxts/covenant": "^2.1.1",
-        "@rbxts/types": "^1.0.891",
-        "@typescript-eslint/eslint-plugin": "^8.47.0",
-        "@typescript-eslint/parser": "^8.47.0",
-        "eslint": "^9.39.1",
-        "eslint-config-prettier": "^10.1.8",
-        "eslint-plugin-prettier": "^5.5.4",
-        "eslint-plugin-roblox-ts": "^1.3.0",
-        "prettier": "^3.6.2",
-        "roblox-ts": "^3.0.0",
-        "typescript": "^5.9.3"
-    },
-    "dependencies": {
-        "@rbxts/jecs": "^0.9.0",
-        "@rbxts/services": "^1.6.0"
-    }
-}
+{
+    "name": "@rbxts/covenant",
+    "version": "3.7.0",
+    "main": "src/init.luau",
+    "scripts": {
+        "build": "rbxtsc",
+        "watch": "rbxtsc -w",
+        "prepublishOnly": "npm run build"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/cuberootmctoasted/covenant.git"
+    },
+    "keywords": [],
+    "author": "",
+    "license": "ISC",
+    "bugs": {
+        "url": "https://github.com/cuberootmctoasted/covenant/issues"
+    },
+    "homepage": "https://github.com/cuberootmctoasted/covenant#readme",
+    "description": "",
+    "types": "src/covenant.d.ts",
+    "files": [
+        "src",
+        "!**/*.tsbuildinfo"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "devDependencies": {
+        "@rbxts/compiler-types": "^3.0.0-types.0",
+        "@rbxts/covenant": "^2.1.1",
+        "@rbxts/types": "^1.0.891",
+        "@typescript-eslint/eslint-plugin": "^8.47.0",
+        "@typescript-eslint/parser": "^8.47.0",
+        "eslint": "^9.39.1",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-prettier": "^5.5.4",
+        "eslint-plugin-roblox-ts": "^1.3.0",
+        "prettier": "^3.6.2",
+        "roblox-ts": "^3.0.0",
+        "typescript": "^5.9.3"
+    },
+    "dependencies": {
+        "@rbxts/jecs": "^0.9.0",
+        "@rbxts/services": "^1.6.0"
+    }
+}

package/src/covenant.d.ts

@@ -4,8 +4,9 @@ import { Remove, Delete } from "./stringEnums";
 export * from "@rbxts/jecs";
 export type WorldChangesForReplication = Map<string, Delete | Map<string, defined | Remove>>;
 export type WorldChangesForPrediction = Map<string, Map<string, defined | Remove>>;
+export type LoggingOption = "FORCE_ON" | "FORCE_OFF" | "COMPONENT_CONTROLLED";
 export interface CovenantProps {
-    logging: boolean;
+    logging: LoggingOption;
     requestPayloadSend: () => void;
     requestPayloadConnect: (callback: (player: Player) => void) => void;
     replicationSend: (player: Player, worldChanges: WorldChangesForReplication) => void;
@@ -25,6 +26,7 @@ export declare class Covenant {
     private undefinedStringifiedComponents;
     private replicatedStringifiedComponents;
     private predictedStringifiedComponents;
+    private loggingStringfiedComponents;
     private stringfiedComponentsToNameMap;
     private started;
     private stringifiedComponentSubscribers;
@@ -41,9 +43,7 @@ export declare class Covenant {
     constructor({ logging, requestPayloadSend, requestPayloadConnect, replicationSend, replicationConnect, replicationSendAll, predictionSend, predictionConnect, }: CovenantProps);
     getClientEntity(entity: Entity): Entity | undefined;
     getServerEntity(entity: Entity): Entity | undefined;
-    private logging;
-    enableLogging(): void;
-    disableLogging(): void;
+    private loggingOption;
     private setupPredictionClient;
     private forEachComponentChanges;
     private setupPredictionServer;
@@ -63,14 +63,16 @@ export declare class Covenant {
     worldTag(): Entity<undefined>;
     private checkComponentDefined;
     private defineComponentNetworkBehavior;
-    defineComponent<T extends defined>({ component, queriedComponents, recipe, replicated, predictionValidator, }: {
+    defineComponent<T extends defined>({ logging, component, queriedComponents, recipe, replicated, predictionValidator, }: {
+        logging?: true;
         replicated: boolean;
         predictionValidator: ComponentPredictionValidator | false;
         component: Entity<T>;
         queriedComponents: Entity[][];
         recipe: (entity: Entity, lastState: T | undefined, updateId: number, hooks: CovenantHooks) => T | undefined;
     }): void;
-    defineIdentity<T extends defined>({ identityComponent, replicated, lifetime, factory, }: {
+    defineIdentity<T extends defined>({ logging, identityComponent, replicated, lifetime, factory, }: {
+        logging?: true;
         identityComponent: Entity<T>;
         replicated: boolean;
         lifetime: (entity: Entity, state: T, despawn: () => void) => (() => void) | undefined;

package/src/covenant.luau

@@ -46,13 +46,14 @@ do
 		self.undefinedStringifiedComponents = {}
 		self.replicatedStringifiedComponents = {}
 		self.predictedStringifiedComponents = {}
+		self.loggingStringfiedComponents = {}
 		self.stringfiedComponentsToNameMap = {}
 		self.started = false
 		self.stringifiedComponentSubscribers = {}
 		self.stringifiedComponentValidators = {}
 		self.clientToServerEntityMap = {}
 		self.serverToClientEntityMap = {}
-		self.logging = logging
+		self.loggingOption = logging
 		self.requestPayloadSend = requestPayloadSend
 		self.requestPayloadConnect = requestPayloadConnect
 		self.replicationSend = replicationSend
@@ -73,12 +74,6 @@ do
 		local _arg0 = tostring(entity)
 		return _clientToServerEntityMap[_arg0]
 	end
-	function Covenant:enableLogging()
-		self.logging = true
-	end
-	function Covenant:disableLogging()
-		self.logging = false
-	end
 	function Covenant:setupPredictionClient()
 		self:schedule(RunService.Heartbeat, function()
 			if next(self.worldChangesForPrediction) == nil then
@@ -378,7 +373,17 @@ do
 		else
 			self._world:set(entity, component, newState)
 		end
-		if self.logging and RunService:IsStudio() then
+		local _condition = RunService:IsStudio() and self.loggingOption ~= "FORCE_OFF"
+		if _condition then
+			local _condition_1 = self.loggingOption == "FORCE_ON"
+			if not _condition_1 then
+				local _loggingStringfiedComponents = self.loggingStringfiedComponents
+				local _arg0 = tostring(component)
+				_condition_1 = _loggingStringfiedComponents[_arg0] ~= nil
+			end
+			_condition = _condition_1
+		end
+		if _condition then
 			print(`{self:getComponentName(component)}.{entity}.[{if doNotReconcile then "remote" else "local"}]:{tableToString(lastState)}->{tableToString(newState)}`)
 		end
 		local _stringifiedComponentSubscribers = self.stringifiedComponentSubscribers
@@ -397,13 +402,13 @@ do
 		if doNotReconcile then
 			return nil
 		end
-		local _condition = RunService:IsServer()
-		if _condition then
+		local _condition_1 = RunService:IsServer()
+		if _condition_1 then
 			local _replicatedStringifiedComponents = self.replicatedStringifiedComponents
 			local _arg0_1 = tostring(component)
-			_condition = _replicatedStringifiedComponents[_arg0_1] ~= nil
+			_condition_1 = _replicatedStringifiedComponents[_arg0_1] ~= nil
 		end
-		if _condition then
+		if _condition_1 then
 			local _worldChangesForReplication = self.worldChangesForReplication
 			local _arg0_1 = tostring(entity)
 			local entityChanges = _worldChangesForReplication[_arg0_1]
@@ -421,13 +426,13 @@ do
 				_entityChanges[_arg0_2] = _arg1
 			end
 		end
-		local _condition_1 = RunService:IsClient()
-		if _condition_1 then
+		local _condition_2 = RunService:IsClient()
+		if _condition_2 then
 			local _predictedStringifiedComponents = self.predictedStringifiedComponents
 			local _arg0_1 = tostring(component)
-			_condition_1 = _predictedStringifiedComponents[_arg0_1] ~= nil
+			_condition_2 = _predictedStringifiedComponents[_arg0_1] ~= nil
 		end
-		if _condition_1 then
+		if _condition_2 then
 			local _worldChangesForPrediction = self.worldChangesForPrediction
 			local _arg0_1 = tostring(component)
 			local componentChanges = _worldChangesForPrediction[_arg0_1]
@@ -553,6 +558,7 @@ do
 		end
 	end
 	function Covenant:defineComponent(_param)
+		local logging = _param.logging
 		local component = _param.component
 		local queriedComponents = _param.queriedComponents
 		local recipe = _param.recipe
@@ -560,6 +566,11 @@ do
 		local predictionValidator = _param.predictionValidator
 		self:checkComponentDefined(component)
 		self:defineComponentNetworkBehavior(component, replicated, predictionValidator)
+		if logging then
+			local _loggingStringfiedComponents = self.loggingStringfiedComponents
+			local _arg0 = tostring(component)
+			_loggingStringfiedComponents[_arg0] = true
+		end
 		local queryThisComponent = self:worldQuery(component):cached()
 		local willUpdate = true
 		local function indicateUpdate()
@@ -567,21 +578,7 @@ do
 		end
 		local hooks = createHooks({
 			indicateUpdate = indicateUpdate,
-			subscribeComponent = function(component, subscriber)
-				self:subscribeComponent(component, subscriber)
-			end,
-			getPayloadQueue = function(component)
-				local queue = {}
-				for entity, state in self:worldQuery(component) do
-					local _arg0 = {
-						entity = entity,
-						state = state,
-						previousState = nil,
-					}
-					table.insert(queue, _arg0)
-				end
-				return queue
-			end,
+			covenant = self,
 		})
 		-- ▼ ReadonlyArray.map ▼
 		local _newValue = table.create(#queriedComponents)
@@ -681,11 +678,17 @@ do
 		end)
 	end
 	function Covenant:defineIdentity(_param)
+		local logging = _param.logging
 		local identityComponent = _param.identityComponent
 		local replicated = _param.replicated
 		local lifetime = _param.lifetime
 		local factory = _param.factory
 		self:checkComponentDefined(identityComponent)
+		if logging then
+			local _loggingStringfiedComponents = self.loggingStringfiedComponents
+			local _arg0 = tostring(identityComponent)
+			_loggingStringfiedComponents[_arg0] = true
+		end
 		self:defineComponentNetworkBehavior(identityComponent, replicated, false)
 		factory(function(state)
 			local entity = self:worldEntity()

package/src/hooks.d.ts

@@ -1,4 +1,5 @@
 import { Entity } from "@rbxts/jecs";
+import { Covenant } from "./covenant";
 type AsyncResult<T = unknown> = {
     completed: boolean;
     value: T | undefined;
@@ -13,6 +14,10 @@ export interface CovenantHooks {
         state: T | undefined;
         previousState: T | undefined;
     }[];
+    useComponentChangeOfEntity: <T extends defined>(updateId: number, entity: Entity, component: Entity<T>, payload: boolean) => {
+        state: T | undefined;
+        previousState: T | undefined;
+    } | undefined;
     useAsync: <T>(updateId: number, asnycFactory: () => T, dependencies: unknown[], discriminator: Discriminator) => AsyncResult<T>;
     useImperative: <T extends defined>(updateId: number, dirtyFactory: (indicateUpdate: () => void) => {
         value: T;
@@ -23,12 +28,7 @@ export interface CovenantHooks {
 }
 interface CovenantHooksProps {
     indicateUpdate: () => void;
-    subscribeComponent: <T extends defined>(component: Entity<T>, subscriber: (entity: Entity, state: T | undefined, previousState: T | undefined) => void) => void;
-    getPayloadQueue: <T extends defined>(component: Entity<T>) => {
-        entity: Entity;
-        state: T | undefined;
-        previousState: T | undefined;
-    }[];
+    covenant: Covenant;
 }
 export declare function createHooks(props: CovenantHooksProps): CovenantHooks;
 export {};

package/src/hooks.luau

@@ -77,9 +77,8 @@ local function createUseEventImmediately(_param)
 	end
 end
 local function createUseComponentChange(_param)
-	local subscribeComponent = _param.subscribeComponent
+	local covenant = _param.covenant
 	local indicateUpdate = _param.indicateUpdate
-	local getPayloadQueue = _param.getPayloadQueue
 	local queues = {}
 	local watchedStringifiedComponents = {}
 	local caches = {}
@@ -100,7 +99,7 @@ local function createUseComponentChange(_param)
 		if not (watchedStringifiedComponents[stringifiedComponent] ~= nil) then
 			watchedStringifiedComponents[stringifiedComponent] = true
 			queues[stringifiedComponent] = {}
-			subscribeComponent(component, function(entity, state, previousState)
+			covenant:subscribeComponent(component, function(entity, state, previousState)
 				local _exp = queues[stringifiedComponent]
 				local _arg0 = {
 					entity = entity,
@@ -114,7 +113,16 @@ local function createUseComponentChange(_param)
 			if not payload then
 				return {}
 			else
-				return getPayloadQueue(component)
+				local payloadQueue = {}
+				for entity, state in covenant:worldQuery(component) do
+					local _arg0 = {
+						entity = entity,
+						state = state,
+						previousState = nil,
+					}
+					table.insert(payloadQueue, _arg0)
+				end
+				return payloadQueue
 			end
 		end
 		local queue = queues[stringifiedComponent]
@@ -125,6 +133,64 @@ local function createUseComponentChange(_param)
 		return queue
 	end
 end
+local function createUseComponentChangeOfEntity(_param)
+	local covenant = _param.covenant
+	local indicateUpdate = _param.indicateUpdate
+	local changes = {}
+	local watchedStringifiedComponents = {}
+	local caches = {}
+	local lastUpdateId = -1
+	return function(updateId, entity, component, payload)
+		if payload == nil then
+			payload = false
+		end
+		if lastUpdateId ~= updateId then
+			table.clear(caches)
+			lastUpdateId = updateId
+		end
+		local stringifiedComponent = tostring(component)
+		local cache = caches[stringifiedComponent]
+		if cache ~= nil then
+			return if cache == false then nil else cache
+		end
+		if not (watchedStringifiedComponents[stringifiedComponent] ~= nil) then
+			watchedStringifiedComponents[stringifiedComponent] = true
+			covenant:subscribeComponent(component, function(anEntity, state, previousState)
+				if entity ~= anEntity then
+					return nil
+				end
+				local _arg1 = {
+					state = state,
+					previousState = previousState,
+				}
+				changes[stringifiedComponent] = _arg1
+				indicateUpdate()
+			end)
+			caches[stringifiedComponent] = false
+			if not payload then
+				return nil
+			else
+				if not covenant:worldContains(entity) then
+					return nil
+				end
+				local state = covenant:worldGet(entity, component)
+				if state == nil then
+					return nil
+				end
+				return {
+					state = state,
+					previousState = nil,
+				}
+			end
+		end
+		local change = changes[stringifiedComponent]
+		if change ~= nil then
+			changes[stringifiedComponent] = nil
+		end
+		caches[stringifiedComponent] = change
+		return change
+	end
+end
 local function equalsDependencies(a, b)
 	if a == b then
 		return true
@@ -357,6 +423,7 @@ local function createHooks(props)
 		useEvent = createUseEvent(props),
 		useEventImmediately = createUseEventImmediately(props),
 		useComponentChange = createUseComponentChange(props),
+		useComponentChangeOfEntity = createUseComponentChangeOfEntity(props),
 		useAsync = createUseAsync(props),
 		useImperative = createUseImperative(props),
 		useChange = createUseChange(),