@rbxts/replecs 0.4.0-rc.3 → 0.4.0-rc.5

package/out/replecs/server/init.luau

@@ -21,10 +21,11 @@ type FilterAny = types.FilterAny
 type FilterSet = types.FilterSet
 type FilterPredicator = types.FilterPredicator
 type FilterPlayer = types.FilterPlayer
-type FilterGroup = filter_groups.FilterGroup
+type FilterSimple = types.FilterSimple
+export type FilterNode = filter_groups.FilterNode
 
 -- what the public set_* API accepts as a filter
-type FilterInput = FilterAny | FilterGroup
+type FilterInput = FilterAny | FilterNode
 
 type MaskHash = string
 
@@ -57,6 +58,10 @@ export type ServerImp = {
 
 	force_change: (self: Server, entity: Entity, component: Component) -> (),
 
+	filter: (self: Server, initial: FilterSimple?) -> FilterNode,
+	filter_predicator: (self: Server, predicator: FilterPredicator) -> FilterNode,
+	everyone: (self: Server) -> FilterNode,
+
 	set_global: (self: Server, entity: Entity, global_id: number) -> (),
 	remove_global: (self: Server, entity: Entity) -> (),
 	set_custom: (self: Server, entity: Entity, custom: Component | CustomId) -> (),
@@ -76,10 +81,10 @@ type StorageBase = {
 	filter: Bitmask?,
 	last_replicated: Bitmask?,
 
-	-- set while a filter group drives this storage's filter; the listener is
-	-- kept so it can be disconnected when the filter changes or the storage dies
-	filter_group: FilterGroup?,
-	filter_listener: ((Bitmask) -> ())?,
+	-- set while a filter node drives this storage's filter, with the slot of
+	-- this storage in the node's binding list so unbind is a swap remove
+	filter_node: FilterNode?,
+	binding_index: number?,
 	filter_input: FilterInput?,
 }
 
@@ -135,15 +140,23 @@ type PostponedComponent = {
 	once: boolean?,
 }
 
--- a predicate-driven filter, re-evaluated before every collect_updates cycle
-type FunctionFilterEntry = {
-	predicator: registry.MemberPredicator,
+-- a storage driven by a filter node, re-applied whenever the node's version moves
+type FilterBinding = {
 	entity: Entity,
 	networked: NetworkedStorage,
+	storage: StorageBase,
 
-	-- set for reliable component filters, nil for entity-level ones
+	-- set for component filters, nil for entity-level ones
 	tracking: Component?,
 	tracking_storage: TrackingStorageBase?,
+	-- node version last written into the storage filter
+	applied_version: number,
+}
+
+type NodeBindings = {
+	entries: Array<FilterBinding>,
+	-- every entry sits at this version once a resolve pass completes
+	applied_version: number,
 }
 
 type NetworkedReferencesInfo = {
@@ -204,7 +217,7 @@ export type Server = ServerImp & {
 	hooked_relations: Map<Component, HookedInfo>,
 
 	dirty_networked: Array<Entity>,
-	function_filters: Map<StorageBase, FunctionFilterEntry>,
+	filter_bindings: Map<FilterNode, NodeBindings>,
 
 	empty_bitmask: Bitmask,
 	draft_bitmask: Bitmask,
@@ -443,20 +456,28 @@ local function resolve_filter_bitmask(self: Server, filter: FilterAny): Bitmask
 	end
 end
 
-local function disconnect_filter_group(storage: StorageBase)
-	local group = storage.filter_group
-	local listener = storage.filter_listener
-	if group and listener then
-		group:disconnect(listener)
+-- releases the node driving this storage's filter, if any. the entry is swap
+-- removed and the moved entry's storage takes over the freed slot
+local function clear_filter_source(self: Server, storage: StorageBase)
+	local node = storage.filter_node
+	if not node then
+		return
 	end
-	storage.filter_group = nil
-	storage.filter_listener = nil
-end
+	local bindings = self.filter_bindings[node]
+	local index = storage.binding_index :: number
+	local entries = bindings.entries
 
--- releases whatever was driving this storage's filter (group or predicate)
-local function clear_filter_source(self: Server, storage: StorageBase)
-	disconnect_filter_group(storage)
-	self.function_filters[storage] = nil
+	local last = table.remove(entries)
+	if last and last.storage ~= storage then
+		entries[index] = last
+		last.storage.binding_index = index
+	end
+	if #entries == 0 then
+		self.filter_bindings[node] = nil
+	end
+
+	storage.filter_node = nil
+	storage.binding_index = nil
 end
 
 -- a nil-filter storage inherits entity visibility, so its replicated set is
@@ -528,29 +549,62 @@ local function edit_tracking_filter(
 	mark_tracking_storage_dirty(self, entity, component, networked, storage, DIRTY_FILTER_FLAG)
 end
 
-local function connect_networked_group(self: Server, entity: Entity, networked: NetworkedStorage, group: FilterGroup)
-	local function listener(bitmask: Bitmask)
-		edit_networked_filter(self, entity, networked, bitmask)
-	end
-	networked.filter_group = group
-	networked.filter_listener = listener
-	group:connect(listener)
+-- attaches a node to a storage and returns the node's current mask as the
+-- storage's own copy: storage filters get holes punched at remove_player and
+-- are snapshotted in place, so they never alias the node buffer
+local function bind_filter(
+	self: Server,
+	entity: Entity,
+	component: Component?,
+	networked: NetworkedStorage,
+	storage: StorageBase,
+	node: FilterNode
+): Bitmask
+	filter_groups.bind(node, self.registry)
+	local value = filter_groups.resolve(node)
+
+	local bindings = self.filter_bindings[node]
+	if not bindings then
+		bindings = { entries = {}, applied_version = node.version }
+		self.filter_bindings[node] = bindings
+	end
+	local entries = bindings.entries
+	table.insert(entries, {
+		entity = entity,
+		networked = networked,
+		storage = storage,
+		tracking = component,
+		tracking_storage = if component then storage :: TrackingStorageBase else nil,
+		applied_version = node.version,
+	})
+	storage.filter_node = node
+	storage.binding_index = #entries
+
+	return bitmasks.clone(value)
 end
 
-local function connect_tracking_group(
+-- resolves a filter input into a bitmask and, for nodes and predicates,
+-- binds the source so later changes keep driving the storage. nil means
+-- "replicate to all active clients", resolved at collect
+local function resolve_filter_input(
 	self: Server,
 	entity: Entity,
-	component: Component,
+	component: Component?,
 	networked: NetworkedStorage,
-	storage: TrackingStorageBase,
-	group: FilterGroup
-)
-	local function listener(bitmask: Bitmask)
-		edit_tracking_filter(self, entity, component, networked, storage, bitmask)
+	storage: StorageBase,
+	filter: FilterInput?
+): Bitmask?
+	if filter == nil then
+		return nil
+	end
+	-- a node is a table, so this check goes before the set one
+	if filter_groups.is_filter_node(filter) then
+		return bind_filter(self, entity, component, networked, storage, filter :: FilterNode)
+	elseif typeof(filter) == "function" then
+		local node = filter_groups.create_predicate(self.registry, filter :: FilterPredicator)
+		return bind_filter(self, entity, component, networked, storage, node)
 	end
-	storage.filter_group = group
-	storage.filter_listener = listener
-	group:connect(listener)
+	return resolve_filter_bitmask(self, filter :: FilterAny)
 end
 
 function ensure_hooked_component(self: Server, component: Component): HookedInfo
@@ -796,9 +850,6 @@ local function clear_networked_references(self: Server, entity: Entity, networke
 	end
 end
 
--- resolves a filter input into a bitmask and attaches its driving source
--- (group listener or predicate entry) to the storage; nil filter means
--- "replicate to all active clients", resolved at collect
 local function apply_tracking_filter(
 	self: Server,
 	entity: Entity,
@@ -807,31 +858,7 @@ local function apply_tracking_filter(
 	storage: TrackingStorageBase,
 	filter: FilterInput?
 ): Bitmask?
-	local bitmask: Bitmask?
-
-	if filter then
-		if filter_groups.is_filter_group(filter) then
-			local group = filter :: FilterGroup
-			bitmask = group:calculate_up()
-			connect_tracking_group(self, entity, component, networked, storage, group)
-		elseif typeof(filter) == "function" then
-			local predicator = filter :: registry.MemberPredicator
-			bitmask = self.registry:create_bitmask_from_function(predicator)
-
-			self.function_filters[storage] = {
-				predicator = predicator,
-				entity = entity,
-				networked = networked,
-
-				tracking = component,
-				tracking_storage = storage,
-			}
-		else
-			bitmask = resolve_filter_bitmask(self, filter :: FilterAny)
-		end
-	end
-
-	return bitmask
+	return resolve_filter_input(self, entity, component, networked, storage, filter)
 end
 
 local function change_tracking(
@@ -1097,28 +1124,8 @@ function start_networked(self: Server, entity: Entity, filter: FilterInput?)
 		-- get a removal delta instead of the pending deletion
 		change_networked(self, entity, networked, filter)
 	else
-		local bitmask: Bitmask?
-
-		if filter then
-			if filter_groups.is_filter_group(filter) then
-				local group = filter :: FilterGroup
-				bitmask = group:calculate_up()
-				connect_networked_group(self, entity, networked, group)
-			elseif typeof(filter) == "function" then
-				local predicator = filter :: registry.MemberPredicator
-				bitmask = self.registry:create_bitmask_from_function(predicator)
-
-				self.function_filters[networked] = {
-					predicator = predicator,
-					entity = entity,
-					networked = networked,
-				}
-			else
-				bitmask = resolve_filter_bitmask(self, filter :: FilterAny)
-			end
-			-- bitmask stays nil: replicate to all active clients, resolved at collect
-		
-end
+		-- nil bitmask: replicate to all active clients, resolved at collect
+		local bitmask = resolve_filter_input(self, entity, nil, networked, networked, filter)
 
 		networked.filter = bitmask
 		mark_networked_dirty(self, entity, networked, DIRTY_FILTER_FLAG)
@@ -1164,24 +1171,7 @@ function change_networked(self: Server, entity: Entity, networked: NetworkedStor
 	-- old filter source stops driving this storage before the new one takes over
 	clear_filter_source(self, networked)
 
-	local bitmask: Bitmask?
-	if filter then
-		if filter_groups.is_filter_group(filter) then
-			local group = filter :: FilterGroup
-			bitmask = group:calculate_up()
-			connect_networked_group(self, entity, networked, group)
-		elseif typeof(filter) == "function" then
-			local predicator = filter :: registry.MemberPredicator
-			bitmask = self.registry:create_bitmask_from_function(predicator)
-			self.function_filters[networked] = {
-				predicator = predicator,
-				entity = entity,
-				networked = networked,
-			}
-		else
-			bitmask = resolve_filter_bitmask(self, filter :: FilterAny)
-		end
-	end
+	local bitmask = resolve_filter_input(self, entity, nil, networked, networked, filter)
 
 	edit_networked_filter(self, entity, networked, bitmask)
 end
@@ -1605,8 +1595,11 @@ function server.remove_serdes(self: Server, component: Component)
 	self.is_shared_dirty = true
 end
 
+-- serdes and preprocessors take part in the handshake and mark shared dirty,
+-- delta serializers are local to each side and never do
 function server.set_preprocessor(self: Server, component: Component, preprocessor: types.Preprocessor)
 	ensure_component_serialization(self, component).preprocessor = preprocessor
+	self.is_shared_dirty = true
 end
 
 function server.remove_preprocessor(self: Server, component: Component)
@@ -1616,6 +1609,7 @@ function server.remove_preprocessor(self: Server, component: Component)
 	end
 	options.preprocessor = nil
 	prune_component_serialization(self, component, options)
+	self.is_shared_dirty = true
 end
 
 function server.set_delta_serializer(self: Server, component: Component, delta_serializer: types.DeltaSerializer)
@@ -1882,7 +1876,11 @@ function push_relation_updates(
 	local is_component = storage.is_component
 
 	for target in storage.dirty_targets do
-		if WORLD_HAS(world, entity, PAIR(rel, target)) then
+		-- the pair id only keeps the target's index: a target deleted and
+		-- recycled in the same frame aliases the live pair, so the pair must
+		-- resolve back to this exact generation to count as present
+		local id = PAIR(rel, target)
+		if WORLD_HAS(world, entity, id) and PAIR_SECOND(world, id) == target then
 			if is_component then
 				local changed = bucket.changed[rel]
 				if not changed then
@@ -1890,7 +1888,7 @@ function push_relation_updates(
 					bucket.changed[rel] = changed
 				end
 
-				local value = WORLD_GET(world, entity, PAIR(rel, target))
+				local value = WORLD_GET(world, entity, id)
 				table.insert(changed.targets, target)
 				table.insert(changed.values, SET_VALUE(value))
 			else
@@ -2398,31 +2396,47 @@ local function serialize_unreliable_group(
 	commit()
 end
 
-local function collect_updates_groups(self: Server): Map<MaskHash, SerializeGroup>
-	local client_registry = self.registry
-	for storage, entry in self.function_filters do
-		local bitmask = client_registry:create_bitmask_from_function(entry.predicator)
-		local current = storage.filter
-		if current and bitmasks.equals(current, bitmask) then
+-- resolves every bound filter node once and re-applies the ones that moved.
+-- steady state is one integer compare per distinct node. must run before
+-- dirty_networked is walked and before the active epoch rolls, since
+-- edit_*_filter snapshots against last_active_bitmask
+local function resolve_filters(self: Server)
+	self.registry.cycle += 1
+
+	for node, bindings in self.filter_bindings do
+		local value = filter_groups.resolve(node)
+		local version = node.version
+		if bindings.applied_version == version then
 			continue
 		end
 
-		local tracking_component = entry.tracking
-
-		if tracking_component then
-			-- routes to the right dirty list via the storage's track_type
-			edit_tracking_filter(
-				self,
-				entry.entity,
-				tracking_component,
-				entry.networked,
-				entry.tracking_storage :: TrackingStorageBase,
-				bitmask
-			)
-		else
-			edit_networked_filter(self, entry.entity, entry.networked, bitmask)
+		for _, entry in bindings.entries do
+			if entry.applied_version == version then
+				continue
+			end
+			entry.applied_version = version
+
+			local tracking_component = entry.tracking
+			if tracking_component then
+				-- routes to the right dirty list via the storage's track_type
+				edit_tracking_filter(
+					self,
+					entry.entity,
+					tracking_component,
+					entry.networked,
+					entry.tracking_storage :: TrackingStorageBase,
+					bitmasks.clone(value)
+				)
+			else
+				edit_networked_filter(self, entry.entity, entry.networked, bitmasks.clone(value))
+			end
 		end
+		bindings.applied_version = version
 	end
+end
+
+local function collect_updates_groups(self: Server): Map<MaskHash, SerializeGroup>
+	resolve_filters(self)
 
 	local serialize_groups: Map<MaskHash, SerializeGroup> = {}
 	local networked_entities = self.networked
@@ -2931,21 +2945,25 @@ local function serialize_unreliable_groups(self: Server, groups: Map<MaskHash, U
 	end
 end
 
--- rebuilds the shared lookups (component ids, custom ids, serdes) when
--- flagged; no-op otherwise.
+-- rebuilds the shared lookups (component ids, custom ids, serdes, preprocessors)
+-- when flagged; no-op otherwise.
 function server.resolve_dirty(self: Server)
 	if not self.is_shared_dirty then
 		return
 	end
 
 	local serdes: { [Component]: types.Serdes } = {}
+	local preprocessors: { [Component]: true } = {}
 	for component, options in self.component_serialization do
 		if options.serdes then
 			serdes[component] = options.serdes
 		end
+		if options.preprocessor then
+			preprocessors[component] = true
+		end
 	end
 
-	self.shared = shared.resolve_shared(self.world, self.components, self.registered_custom_ids, serdes)
+	self.shared = shared.resolve_shared(self.world, self.components, self.registered_custom_ids, serdes, preprocessors)
 	self.is_shared_dirty = false
 end
 
@@ -3137,6 +3155,7 @@ end
 
 function server.get_full(self: Server, player: Player): (buffer, Array<any>)
 	self:resolve_dirty()
+	resolve_filters(self)
 
 	local index = self.registry.client_indexes[player]
 	if index == nil then
@@ -3473,6 +3492,7 @@ end
 
 function server.collect_entity(self: Server, entity: Entity): PacketIterator
 	self:resolve_dirty()
+	resolve_filters(self)
 	local groups = collect_entity_groups(self, entity)
 
 	local member_updates: Map<number, MemberUpdatePackets> = {}
@@ -3564,11 +3584,24 @@ end
 
 function server.collect_unreliable(self: Server): PacketIterator
 	self:resolve_dirty()
+	resolve_filters(self)
 	local groups = collect_unreliable_groups(self)
 	serialize_unreliable_groups(self, groups)
 	return create_unreliable_packet_iterator(self, distribute_unreliable_groups(groups))
 end
 
+function server.filter(self: Server, initial: FilterSimple?): FilterNode
+	return filter_groups.create_source(self.registry, initial)
+end
+
+function server.filter_predicator(self: Server, predicator: FilterPredicator): FilterNode
+	return filter_groups.create_predicate(self.registry, predicator)
+end
+
+function server.everyone(self: Server): FilterNode
+	return filter_groups.create_everyone(self.registry)
+end
+
 function server.register_player(self: Server, player: Player)
 	self.registry:register_client(player)
 end
@@ -3891,7 +3924,7 @@ function server.create(world: World?, components: types.Components?, max_clients
 	self.hooked_unreliable_pairs = {}
 
 	self.dirty_networked = {}
-	self.function_filters = {}
+	self.filter_bindings = {}
 
 	self.empty_bitmask = buffer.create(self.bitmask_size)
 	self.draft_bitmask = buffer.create(self.bitmask_size)
@@ -3926,12 +3959,19 @@ return {
 	end,
 	collect_unreliable_groups = function(self: Server): Map<MaskHash, UnreliableSerializeGroup>
 		self:resolve_dirty()
+		resolve_filters(self)
 		return collect_unreliable_groups(self)
 	end,
 	serialize_update_groups = serialize_update_groups,
 	serialize_unreliable_groups = serialize_unreliable_groups,
 	collect_entity_groups = function(self: Server, entity: Entity): Map<MaskHash, EntitySerializeGroup>
 		self:resolve_dirty()
+		resolve_filters(self)
 		return collect_entity_groups(self, entity)
 	end,
+
+	-- unbound source for module level construction, binds on first set_*
+	create_filter = function(initial: FilterSimple?): FilterNode
+		return filter_groups.create_source(nil, initial)
+	end,
 }

package/out/replecs/server/registry.luau

@@ -29,6 +29,18 @@ type RegistryClass = {
 	-- exactly this many bits, so an index past it would fall off the buffer
 	max_clients: number,
 	bitmask_size: number,
+
+	-- bumped when a client registers, leaves or an alias changes: filter
+	-- nodes re-resolve their raw members against it
+	epoch: number,
+	-- bumped once per server resolve pass, predicate nodes recompute per cycle
+	cycle: number,
+	-- bit per registered client, the base a blacklist filter subtracts from
+	registered_bitmask: Bitmask,
+	-- clients dropped by unregister_client. a filter may still name them and
+	-- is_client_valid holds inside PlayerRemoving, so resolve_member must not
+	-- register them again (possibly onto their freed index)
+	departed: Set<Client>,
 }
 
 local registry = {}
@@ -56,20 +68,23 @@ local function resolve_member(self: Registry, member: Client): number?
 		end
 	end
 
-	if not utils.is_client_valid(member) then
+	if self.departed[member] or not utils.is_client_valid(member) then
 		return nil
 	end
 
 	registry.register_client(self, member)
 	return self.client_indexes[member]
 end
+registry.resolve_member = resolve_member
 
 function registry.add_alias(self: Registry, client: Client, alias: any)
 	self.client_aliases[alias] = client
+	self.epoch += 1
 end
 
 function registry.remove_alias(self: Registry, alias: any)
 	self.client_aliases[alias] = nil
+	self.epoch += 1
 end
 
 -- drops every alias pointing at the client
@@ -80,6 +95,7 @@ function registry.remove_client_aliases(self: Registry, client: Client)
 			aliases[alias] = nil
 		end
 	end
+	self.epoch += 1
 end
 
 
@@ -143,6 +159,10 @@ function registry.register_client(self: Registry, member: Client)
 	self.client_indexes[member] = index
 	self.index_clients[index] = member
 	self.client_count += 1
+
+	self.departed[member] = nil
+	bitmasks.set(self.registered_bitmask, index)
+	self.epoch += 1
 end
 
 function registry.unregister_client(self: Registry, member: Client)
@@ -155,6 +175,10 @@ function registry.unregister_client(self: Registry, member: Client)
 	self.client_indexes[member] = nil
 	self.index_clients[index] = nil
 	self.client_count -= 1
+
+	self.departed[member] = true
+	bitmasks.reset(self.registered_bitmask, index)
+	self.epoch += 1
 end
 
 local DEFAULT_MAX_CLIENTS = 128
@@ -172,6 +196,11 @@ function registry.create(max_clients: number?): Registry
 	self.free_indexes = {}
 	self.client_aliases = {}
 
+	self.epoch = 0
+	self.cycle = 0
+	self.registered_bitmask = buffer.create(self.bitmask_size)
+	self.departed = setmetatable({}, { __mode = "k" }) :: any
+
 	return setmetatable(self, registry) :: any
 end
 

package/out/replecs/shared.luau

@@ -38,7 +38,8 @@ function shared.resolve_shared(
 	world: World,
 	components: types.Components,
 	registered_custom_ids: { [customid.CustomId]: boolean },
-	serdes: { [Component]: types.Serdes }
+	serdes: { [Component]: types.Serdes },
+	preprocessors: { [Component]: true }
 ): types.Shared
 	local shared = {} :: types.Shared
 
@@ -61,6 +62,7 @@ function shared.resolve_shared(
 	end
 
 	shared.serdes = serdes
+	shared.preprocessors = preprocessors
 	shared.components = create_shared_lookup(components_lookup)
 	shared.custom_ids = create_shared_lookup(custom_ids_lookup) :: types.SharedInfo<customid.CustomId>
 

package/out/replecs/types.luau

@@ -29,6 +29,8 @@ export type HandshakeInfo = {
 		includes_variants: boolean?,
 		bytespan: number?,
 	} },
+	-- preprocessors are functions, so only their presence is compared
+	preprocessors: { [string]: boolean },
 }
 
 export type Serdes<T = any> = {
@@ -77,6 +79,7 @@ export type Shared = {
 	custom_ids: SharedInfo<customid.CustomId>,
 
 	serdes: { [Component]: Serdes },
+	preprocessors: { [Component]: true },
 }
 
 return nil

package/out/replecs/ver.luau

@@ -1 +1 @@
-return "v0.4.0-rc.3"
+return "v0.4.0-rc.5"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/replecs",
-  "version": "0.4.0-rc.3",
+  "version": "0.4.0-rc.5",
   "description": "Replication library for Jecs",
   "main": "out/init.luau",
   "types": "out/index.d.ts",
@@ -24,7 +24,8 @@
     "!**/*.tsbuildinfo"
   ],
   "scripts": {
-    "serve": "rojo sourcemap serve.project.json -o sourcemap.json --watch && rojo serve serve.project.json"
+    "serve": "rojo sourcemap serve.project.json -o sourcemap.json --watch && rojo serve serve.project.json",
+    "docs:dev": "npm run dev --prefix docs"
   },
   "repository": {
     "type": "git",