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

package/out/replecs/client/init.luau

@@ -1532,8 +1532,8 @@ local function prune_component_serialization(self: Client, component: Component,
 	end
 end
 
--- serdes take part in the handshake, preprocessors and delta serializers are
--- local to each side and never mark shared dirty
+-- serdes and preprocessors take part in the handshake and mark shared dirty,
+-- delta serializers are local to each side and never do
 function client.set_serdes(self: Client, component: Component, serdes: types.Serdes)
 	ensure_component_serialization(self, component).serdes = serdes
 	self.is_shared_dirty = true
@@ -1551,6 +1551,7 @@ end
 
 function client.set_preprocessor(self: Client, component: Component, preprocessor: types.Preprocessor)
 	ensure_component_serialization(self, component).preprocessor = preprocessor
+	self.is_shared_dirty = true
 end
 
 function client.remove_preprocessor(self: Client, component: Component)
@@ -1560,6 +1561,7 @@ function client.remove_preprocessor(self: Client, component: Component)
 	end
 	options.preprocessor = nil
 	prune_component_serialization(self, component, options)
+	self.is_shared_dirty = true
 end
 
 function client.set_delta_serializer(self: Client, component: Component, delta_serializer: types.DeltaSerializer)
@@ -1575,21 +1577,26 @@ function client.remove_delta_serializer(self: Client, component: Component)
 	prune_component_serialization(self, component, options)
 end
 
--- rebuilds the shared lookups (component ids, custom ids, serdes) when
--- flagged; cheap no-op otherwise, so every deserialize entry point calls it
+-- rebuilds the shared lookups (component ids, custom ids, serdes, preprocessors)
+-- when flagged; cheap no-op otherwise, so every deserialize entry point calls it
 function client.resolve_dirty(self: Client)
 	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
 

package/out/replecs/handshake.luau

@@ -13,6 +13,7 @@ function handshake.generate_handshake(shared: types.Shared): types.HandshakeInfo
 		components = {},
 		custom_ids = {},
 		serdes = {},
+		preprocessors = {},
 	}
 
 	for component_name, component in shared.components.lookup do
@@ -36,6 +37,16 @@ function handshake.generate_handshake(shared: types.Shared): types.HandshakeInfo
 		}
 	end
 
+	-- preprocessors are functions, so only their presence is shared
+	for component in shared.preprocessors do
+		local name = component_to_name[component]
+		if not name then
+			continue
+		end
+
+		handshake.preprocessors[name] = true
+	end
+
 	return handshake
 end
 
@@ -102,6 +113,30 @@ function handshake.verify_handshake(
 		end
 	end
 
+	for component_name in handshake.preprocessors do
+		local component = shared.components.lookup[component_name]
+		if not component then
+			common.log_warn(
+				`{handshake_side} registered a preprocessor for "{component_name}" that {verify_side} doesn't have`
+			)
+			continue
+		end
+
+		if not shared.preprocessors[component] then
+			return false, `missing preprocessor for component "{component_name}" in {verify_side}`
+		end
+	end
+	for component in shared.preprocessors do
+		local component_name = component_to_name[component]
+		if not component_name then
+			continue
+		end
+
+		if not handshake.preprocessors[component_name] then
+			return false, `missing preprocessor for component "{component_name}" in {handshake_side}`
+		end
+	end
+
 	return true, nil
 end
 

package/out/replecs/index.d.ts

@@ -34,10 +34,42 @@ declare namespace Replecs {
     | Player
     | MemberFilterMap
     | MemberFilterPredicate
+    | FilterNode
     | Record<string, never>
     | undefined;
   type Member = unknown;
 
+  /** What a filter combinator accepts: another node or a raw player / set. */
+  export type FilterOperand = FilterNode | Player | MemberFilterMap;
+
+  /**
+   * One node of the reactive filter graph. Sources own a player set; derived
+   * nodes combine their inputs and re-evaluate lazily on the next collect.
+   * Structure is fixed at construction, only the value is reactive.
+   */
+  export interface FilterNode {
+    /** Replaces the member set. A map of `false` values makes a blacklist. Sources only. */
+    set(filter: Player | MemberFilterMap): void;
+    /** Adds to the member set (on a blacklist source this excludes the player). Sources only. */
+    add(player: Player): void;
+    /** Sources only. */
+    remove(player: Player): void;
+    /** Sources only. */
+    clear(): void;
+
+    /** Players in this node and in every operand. */
+    filter(...operands: FilterOperand[]): FilterNode;
+    /** Players in this node or in any operand. */
+    extend(...operands: FilterOperand[]): FilterNode;
+    /** Players in this node and in no operand. */
+    exclude(...operands: FilterOperand[]): FilterNode;
+
+    /** Resolves the node and returns its current players. Errors if the node is not bound to a server yet. */
+    members(): Map<Player, true>;
+    /** Resolves the node and tests one player (aliases accepted). */
+    contains(player: Player): boolean;
+  }
+
   export interface SharedInfo<T> {
     lookup: Record<string, T>;
     keys: string[];
@@ -64,6 +96,7 @@ declare namespace Replecs {
     components: SharedInfo<Entity>;
     custom_ids: SharedInfo<CustomId>;
     serdes: Map<Id, SerdesTable>;
+    preprocessors: Map<Id, true>;
   }
   interface HandshakeSerdesInfo {
     includes_variants?: boolean;
@@ -74,6 +107,7 @@ declare namespace Replecs {
     components: Record<string, boolean>;
     custom_ids: Record<string, boolean>;
     serdes: Record<string, HandshakeSerdesInfo>;
+    preprocessors: Record<string, boolean>;
   }
 
   export interface Components {
@@ -194,6 +228,13 @@ declare namespace Replecs {
   }
 
   export interface ServerImp extends SerializationOptions {
+    /** A source filter bound to this server. */
+    filter(initial?: Player | MemberFilterMap): FilterNode;
+    /** A filter driven by a predicate over registered players, re-evaluated once per collect. */
+    filter_predicator(predicate: MemberFilterPredicate): FilterNode;
+    /** Every registered player; the base for blacklists. */
+    everyone(): FilterNode;
+
     set_networked(entity: Entity, filter?: MemberFilter): void;
     set_reliable(
       entity: Entity,
@@ -289,6 +330,8 @@ declare namespace Replecs {
       identifier: string,
       handler?: (ctx: HandleContext) => Entity,
     ) => CustomId;
+    /** An unbound source filter; it attaches to a server the first time a `set_*` call receives it. */
+    filter: (initial?: Player | MemberFilterMap) => FilterNode;
   }
 }
 

package/out/replecs/init.luau

@@ -10,6 +10,7 @@ local VERSION = require (script:WaitForChild('ver'))
 
 export type Server = server.Server
 export type Client = client.Client
+export type FilterNode = server.FilterNode
 
 type Entity = common.Entity
 type World = common.World
@@ -46,6 +47,7 @@ type Replecs = types.Components & {
 	create_server: (world: World?) -> Server,
 	create_client: (world: World?) -> Client,
 	create_custom_id: (identifier: string, handler: (ctx: HandleContext) -> Entity?) -> CustomId,
+	filter: (initial: types.FilterSimple?) -> FilterNode,
 }
 
 local replecs = {}
@@ -103,6 +105,12 @@ function replecs.create_custom_id(identifier: string, handler: (ctx: HandleConte
 	return customid.create(identifier, handler)
 end
 
+-- an unbound source filter: usable from any module, it attaches to the server
+-- the first time a set_* call receives it (directly or through a derived node)
+function replecs.filter(initial: types.FilterSimple?): FilterNode
+	return server.create_filter(initial)
+end
+
 function replecs.after_replication(lib: ReplecsLib, callback: () -> ())
 	local lib_client = lib.client
 	if lib_client then

package/out/replecs/server/filter_group.luau

@@ -1,196 +1,370 @@
+--!optimize 2
 local types = require (script.Parent.Parent:WaitForChild('types'))
 local registry = require (script.Parent:WaitForChild('registry'))
 local bitmasks = require (script.Parent:WaitForChild('bitmasks'))
 local utils = require (script.Parent:WaitForChild('utils'))
-local common = require (script.Parent.Parent:WaitForChild('common'))
 
 type Bitmask = buffer
+type Player = any
 
 type FilterSimple = types.FilterSimple
+type FilterPredicator = types.FilterPredicator
 
 type Set<T> = { [T]: boolean }
-type Map<K, V> = { [K]: V }
 type Array<T> = { T }
-
-type Listener = (Bitmask) -> ()
-
-type ListenerConnections = {
-	listeners: { Listener },
-	listeners_indexes: { [Listener]: number },
+type Registry = registry.Registry
+
+local KINDS = {
+	source = 1,
+	predicate = 2,
+	intersect = 3,
+	union = 4,
+	exclude = 5,
 }
 
-export type FilterMode = number
+export type FilterNodeClass = {
+	kind: number,
+	registry: Registry?,
 
-export type FilterEntry = {
-	mode: FilterMode,
-	filter: FilterSimple,
-}
+	inputs: Array<FilterNode>,
+	input_versions: Array<number>,
+	dependents: Set<FilterNode>,
 
-export type FilterGroupClass = {
-	registry: registry.Registry,
-	parent: FilterGroup?,
 
-	derived: Set<FilterGroup>,
-	assigned_filter: FilterEntry?,
-	connected_listeners: ListenerConnections,
-}
+	value: Bitmask?,
+	scratch: Bitmask?,
+	version: number,
+	dirty: boolean,
+	resolved_epoch: number,
+	resolved_cycle: number,
 
-local FILTER_MODES = {
-	extend = 1,
-	exclude = 2,
-	include = 3,
+	-- source only
+	member_set: Set<Player>?,
+	inverted: boolean?,
+	predicator: FilterPredicator?,
 }
 
-local filter_group = {}
-filter_group.__index = filter_group
+local filter_node = {}
+filter_node.__index = filter_node
 
-export type FilterGroup = FilterGroupClass & typeof(filter_group)
+export type FilterNode = FilterNodeClass & typeof(filter_node)
+export type FilterOperand = FilterNode | FilterSimple
 
-function filter_group.is_filter_group(value: any): boolean
-	return typeof(value) == "table" and getmetatable(value) == filter_group
+function filter_node.is_filter_node(value: any): boolean
+	return typeof(value) == "table" and getmetatable(value) == filter_node
 end
 
-local function fire_listeners(self: FilterGroup, bitmask: Bitmask)
-	for _, listener in self.connected_listeners.listeners do
-		listener(bitmask)
+function filter_node.bind(node: FilterNode, reg: Registry)
+	if node.registry == reg then
+		return
+	end
+	if node.registry then
+		error "filter is already bound to a different server"
+	end
+
+	node.registry = reg
+	node.value = buffer.create(reg.bitmask_size)
+	node.scratch = buffer.create(reg.bitmask_size)
+
+	for _, input in node.inputs do
+		filter_node.bind(input, reg)
 	end
 end
 
-function filter_group.connect(self: FilterGroup, listener: Listener)
-	local connected = self.connected_listeners
-	local index = #connected.listeners + 1
-	connected.listeners[index] = listener
-	connected.listeners_indexes[listener] = index
+local function create_node(kind: number, reg: Registry?): FilterNode
+	local self: FilterNodeClass = {
+		kind = kind,
+		registry = nil,
+
+		inputs = {},
+		input_versions = {},
+		dependents = setmetatable({}, { __mode = "k" }) :: any,
+
+		value = nil,
+		scratch = nil,
+		version = 0,
+		dirty = true,
+		resolved_epoch = -1,
+		resolved_cycle = -1,
+
+		member_set = nil,
+		inverted = nil,
+		predicator = nil,
+	}
+	setmetatable(self, filter_node)
+
+	local node = self :: any
+	if reg then
+		filter_node.bind(node, reg)
+	end
+	return node
 end
 
-function filter_group.disconnect(self: FilterGroup, listener: Listener)
-	local connected = self.connected_listeners
-	local index = connected.listeners_indexes[listener]
-	if not index then
+local function mark_dirty(node: FilterNode)
+	if node.dirty then
 		return
 	end
-
-	local last_listener = table.remove(connected.listeners)
-	if last_listener and last_listener ~= listener then
-		connected.listeners[index] = last_listener
-		connected.listeners_indexes[last_listener] = index
+	node.dirty = true
+	for dependent in node.dependents do
+		mark_dirty(dependent)
 	end
-	connected.listeners_indexes[listener] = nil
 end
 
-local function create_filter_bitmask(self: FilterGroup, filter: FilterSimple): Bitmask
-	if typeof(filter) == "table" then
-		return self.registry:create_bitmask_from_set(filter)
-	else
-		return self.registry:create_bitmask_from_member(filter)
+local function assert_source(node: FilterNode, method: string)
+	if node.kind ~= KINDS.source then
+		error(`{method}() is only available on source filters, derived filters are read only`)
 	end
 end
 
--- the filter bitmask is resolved from the raw filter here, at calculation
--- time, so clients registered after the filter was assigned still resolve
-function filter_group.apply_filter(self: FilterGroup, bitmask: Bitmask)
-	local filter = self.assigned_filter
-	if not filter then
-		return
+
+local function resolve_source(node: FilterNode, reg: Registry, scratch: Bitmask)
+	bitmasks.clear(scratch)
+	for member in node.member_set :: Set<Player> do
+		local index = registry.resolve_member(reg, member)
+		if index then
+			bitmasks.set(scratch, index)
+		end
 	end
+	if node.inverted then
+		bitmasks.exclude(reg.registered_bitmask, scratch, scratch)
+	end
+end
 
-	local filter_bitmask = create_filter_bitmask(self, filter.filter)
 
-	if filter.mode == FILTER_MODES.extend then
-		bitmasks.bor(bitmask, filter_bitmask, bitmask)
-	elseif filter.mode == FILTER_MODES.exclude then
-		bitmasks.exclude(bitmask, filter_bitmask, bitmask)
-	elseif filter.mode == FILTER_MODES.include then
-		bitmasks.band(bitmask, filter_bitmask, bitmask)
+local function resolve_predicate(node: FilterNode, reg: Registry, scratch: Bitmask)
+	bitmasks.clear(scratch)
+	local predicator = node.predicator :: FilterPredicator
+	for member, index in reg.client_indexes do
+		if predicator(member) then
+			bitmasks.set(scratch, index)
+		end
 	end
 end
 
-function filter_group.calculate_up(self: FilterGroup): Bitmask
-	local parent = self.parent
-	local bitmask: Bitmask
-	if parent then
-		bitmask = filter_group.calculate_up(parent)
-	else
-		bitmask = bitmasks.create_filled(self.registry.client_next_index)
+
+local function resolve_computed(node: FilterNode, scratch: Bitmask): boolean
+	local inputs = node.inputs
+	local input_versions = node.input_versions
+
+	local changed = false
+	for i, input in inputs do
+		filter_node.resolve(input)
+		if input.version ~= input_versions[i] then
+			changed = true
+		end
+	end
+	if not changed then
+		return false
+	end
+
+	for i, input in inputs do
+		input_versions[i] = input.version
 	end
 
-	filter_group.apply_filter(self, bitmask)
-	return bitmask
+	bitmasks.load(inputs[1].value :: Bitmask, scratch)
+	local kind = node.kind
+	local op: (Bitmask, Bitmask, Bitmask) -> () = if kind == KINDS.intersect
+		then bitmasks.band
+		elseif kind == KINDS.union then bitmasks.bor
+		else bitmasks.exclude
+	for i = 2, #inputs do
+		op(scratch, inputs[i].value :: Bitmask, scratch)
+	end
+	return true
 end
 
-function filter_group.calculate_down(self: FilterGroup, parent_bitmask: Bitmask)
-	local bitmask = bitmasks.clone(parent_bitmask, bitmasks.get_buffer_size(self.registry.client_next_index))
-	filter_group.apply_filter(self, bitmask)
 
-	fire_listeners(self, bitmask)
+function filter_node.resolve(node: FilterNode): Bitmask
+	local reg = node.registry
+	if not reg then
+		error "filter is not bound to a server, pass it to a set_* call first"
+	end
+	local value = node.value :: Bitmask
+	local kind = node.kind
+
+	if kind == KINDS.predicate then
+		if node.resolved_cycle == reg.cycle then
+			return value
+		end
+		node.resolved_cycle = reg.cycle
+	elseif not node.dirty and node.resolved_epoch == reg.epoch then
+		return value
+	end
+	node.dirty = false
+	node.resolved_epoch = reg.epoch
+
+	local scratch = node.scratch :: Bitmask
+	if kind == KINDS.source then
+		resolve_source(node, reg, scratch)
+	elseif kind == KINDS.predicate then
+		resolve_predicate(node, reg, scratch)
+	elseif not resolve_computed(node, scratch) then
+		return value
+	end
 
-	for derived in self.derived do
-		filter_group.calculate_down(derived, bitmask)
+	if bitmasks.equals(scratch, value) then
+		return value
 	end
+	node.value = scratch
+	node.scratch = value
+	node.version += 1
+	return scratch
 end
 
-local function recalculate_filter_group(group: FilterGroup)
-	local parent = group.parent
+function filter_node.set(self: FilterNode, filter: FilterSimple)
+	assert_source(self, "set")
 
-	local parent_bitmask: Bitmask
-	if parent then
-		parent_bitmask = filter_group.calculate_up(parent)
+	local members: Set<Player> = {}
+	local inverted = false
+	if typeof(filter) == "table" then
+		inverted = not utils.is_include_filter(filter)
+		for member, allow in filter :: Set<Player> do
+			if allow == inverted then
+				error "a filter set cannot mix included and excluded players"
+			end
+			members[member] = true
+		end
 	else
-		parent_bitmask = bitmasks.create_filled(group.registry.client_next_index)
+		members[filter] = true
 	end
 
-	filter_group.calculate_down(group, parent_bitmask)
+	self.member_set = members
+	self.inverted = inverted
+	mark_dirty(self)
 end
 
-function filter_group.extend(self: FilterGroup, filter: FilterSimple)
-	if not utils.get_used_filter_type(filter) then
-		common.log_error "extend() only accepts include filters"
+function filter_node.add(self: FilterNode, player: Player)
+	assert_source(self, "add")
+	local members = self.member_set :: Set<Player>
+	if members[player] then
+		return
 	end
+	members[player] = true
+	mark_dirty(self)
+end
 
-	self.assigned_filter = {
-		mode = FILTER_MODES.extend,
-		filter = filter,
-	}
-	recalculate_filter_group(self)
+function filter_node.remove(self: FilterNode, player: Player)
+	assert_source(self, "remove")
+	local members = self.member_set :: Set<Player>
+	if not members[player] then
+		return
+	end
+	members[player] = nil
+	mark_dirty(self)
+end
+
+function filter_node.clear(self: FilterNode)
+	assert_source(self, "clear")
+	local members = self.member_set :: Set<Player>
+	if next(members) == nil then
+		return
+	end
+	table.clear(members)
+	mark_dirty(self)
 end
 
-function filter_group.filter(self: FilterGroup, filter: FilterSimple)
-	local mode = FILTER_MODES.exclude
 
-	if utils.get_used_filter_type(filter) then
-		mode = FILTER_MODES.include
+function filter_node.create_source(reg: Registry?, initial: FilterSimple?): FilterNode
+	local node = create_node(KINDS.source, reg)
+	node.member_set = {}
+	node.inverted = false
+	if initial ~= nil then
+		filter_node.set(node, initial)
 	end
+	return node
+end
 
-	self.assigned_filter = {
-		mode = mode,
-		filter = filter,
-	}
-	recalculate_filter_group(self)
+function filter_node.create_everyone(reg: Registry?): FilterNode
+	local node = create_node(KINDS.source, reg)
+	node.member_set = {}
+	node.inverted = true
+	return node
 end
 
-function filter_group.create(client_registry: registry.Registry): FilterGroup
-	local self: FilterGroupClass = {
-		registry = client_registry,
+function filter_node.create_predicate(reg: Registry?, predicator: FilterPredicator): FilterNode
+	local node = create_node(KINDS.predicate, reg)
+	node.predicator = predicator
+	return node
+end
 
-		parent = nil,
-		connected_listeners = {
-			listeners = {},
-			listeners_indexes = {},
-		},
-		derived = setmetatable({}, { __mode = "k" }) :: any,
-		assigned_filter = nil,
-	}
+local function to_node(operand: FilterOperand): FilterNode
+	if filter_node.is_filter_node(operand) then
+		return operand :: FilterNode
+	end
+	return filter_node.create_source(nil, operand :: FilterSimple)
+end
+
+local function create_computed(kind: number, base: FilterNode, operands: Array<FilterOperand>): FilterNode
+	local node = create_node(kind, nil)
+	local inputs = node.inputs
+	local input_versions = node.input_versions
+
+	inputs[1] = base
+	input_versions[1] = -1	
+local reg = base.registry
+
+	for i, operand in operands do
+		local input = to_node(operand)
+		inputs[i + 1] = input
+		input_versions[i + 1] = -1		
+reg = reg or input.registry
+	end
 
-	setmetatable(self, filter_group)
-	return self :: any
+	for _, input in inputs do
+		input.dependents[node] = true
+	end
+	if reg then
+		filter_node.bind(node, reg)
+	end
+	return node
+end
+
+function filter_node.filter(self: FilterNode, ...: FilterOperand): FilterNode
+	return create_computed(KINDS.intersect, self, { ... })
+end
+
+function filter_node.extend(self: FilterNode, ...: FilterOperand): FilterNode
+	return create_computed(KINDS.union, self, { ... })
+end
+
+function filter_node.exclude(self: FilterNode, ...: FilterOperand): FilterNode
+	return create_computed(KINDS.exclude, self, { ... })
 end
 
-function filter_group.derive(self: FilterGroup): FilterGroup
-	local derived = filter_group.create(self.registry)
-	derived.parent = self
 
-	self.derived[derived] = true
-	return derived
+function filter_node.members(self: FilterNode): Set<Player>
+	local value = filter_node.resolve(self)
+	local index_clients = (self.registry :: Registry).index_clients
+
+	local members: Set<Player> = {}
+	bitmasks.iter_set(value, function(index)
+		local client = index_clients[index]
+		if client ~= nil then
+			members[client] = true
+		end
+	end)
+	return members
+end
+
+local function lookup_index(reg: Registry, player: Player): number?
+	local index = reg.client_indexes[player]
+	if index then
+		return index
+	end
+	local aliased = reg.client_aliases[player]
+	if aliased == nil then
+		return nil
+	end
+	return reg.client_indexes[aliased]
+end
+
+function filter_node.contains(self: FilterNode, player: Player): boolean
+	local value = filter_node.resolve(self)
+	local index = lookup_index(self.registry :: Registry, player)
+	if index == nil then
+		return false
+	end
+	return bitmasks.test(value, index)
 end
 
-return filter_group
+return filter_node

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)
@@ -2398,31 +2392,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 +2941,26 @@ 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 +3152,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 +3489,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 +3581,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 +3921,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 +3956,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.4"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/replecs",
-  "version": "0.4.0-rc.3",
+  "version": "0.4.0-rc.4",
   "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",