@rbxts/replecs 0.0.1-rc.1 → 0.1.0-alpha2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 replecs authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/out/replecs/client.luau

@@ -1,9 +1,9 @@
 --!native
 --!optimize 2
 
-local jecs = require(script.Parent.Parent.jecs)
-local common = require(script.Parent.common)
-local utils = require(script.Parent.utils)
+local jecs = require "../jecs"
+local common = require "./common"
+local utils = require "./utils"
 
 local cursor = utils.cursor
 type Cursor = utils.Cursor
@@ -19,6 +19,7 @@ export type Client = {
 
 	components: common.Components,
 	shared: common.Shared,
+	global_id_parser: ((id: number) -> Entity)?,
 	server_ids: { [number]: Entity },
 	client_ids: { [Entity]: number },
 	ordered_creation: boolean,
@@ -27,16 +28,21 @@ export type Client = {
 	init: (self: Client, world: World?) -> (),
 	destroy: (self: Client) -> (),
 	after_replication: (self: Client, callback: () -> ()) -> (),
+	parse_global_id: (self: Client, parser: (id: number) -> Entity) -> (),
+	get_server_entity: (self: Client, client_entity: Entity) -> number?,
+	get_client_entity: (self: Client, server_entity: number) -> Entity?,
 
 	apply_updates: (self: Client, buf: buffer, all_variants: { { any } }?) -> (),
 	apply_unreliable: (self: Client, buf: buffer, all_variants: { { any } }?) -> (),
 	apply_full: (self: Client, buf: buffer, all_variants: { { any } }?) -> (),
 }
 
+local GLOBAL_ID_OFFSET = 10
 local ENTITY_ID_TYPES = {
-	id = 1,
+	entity = 1,
 	custom = 2,
 	shared = 3,
+	global = 4,
 }
 
 local ECS_NAME = jecs.Name
@@ -87,31 +93,46 @@ local function read_component_value(client: Client, c: Cursor, variants: { any }
 	end
 end
 
+local function resolve_global_id(client: Client, global_id: number): Entity
+	if not client.global_id_parser then
+		error "global id parser not set, consider using client:parse_global_id()"
+	end
+	local parsed = client.global_id_parser(global_id)
+	return parsed
+end
+
 local function read_entity_id(client: Client, c: Cursor, variants: { any }?): (Entity?, number?)
 	local id_type = cursor.readi8(c)
 
-	if id_type == ENTITY_ID_TYPES.id then
-		local server_id = cursor.readu24(c)
-		return client.server_ids[server_id], server_id
-	elseif id_type == ENTITY_ID_TYPES.custom then
-		local component, value = read_component_value(client, c, variants)
-		local custom_getter = client.custom_ids[component]
-		if not custom_getter then
-			error(
-				`received a custom id for a non custom component, consider adding custom_id to component: {client.world:get(
-					component,
-					ECS_NAME
-				) or "(no name)"} id: {component}`
-			)
+	if id_type <= 10 then
+		if id_type == ENTITY_ID_TYPES.entity then
+			local server_id = cursor.readu40(c)
+			return client.server_ids[server_id], server_id
+		elseif id_type == ENTITY_ID_TYPES.custom then
+			local component, value = read_component_value(client, c, variants)
+			local custom_getter = client.custom_ids[component]
+			if not custom_getter then
+				error(
+					`received a custom id for a non custom component, consider adding custom_id to component: {client.world:get(
+						component,
+						ECS_NAME
+					) or "(no name)"} id: {component}`
+				)
+			end
+			return custom_getter(value), nil
+		elseif id_type == ENTITY_ID_TYPES.shared then
+			return read_component_id(client, c), nil
+		elseif id_type == ENTITY_ID_TYPES.global then
+			local global_id = cursor.readu8(c) - GLOBAL_ID_OFFSET
+			return resolve_global_id(client, global_id), nil
 		end
-		return custom_getter(value), nil
-	elseif id_type == ENTITY_ID_TYPES.shared then
-		return read_component_id(client, c), nil
+		error(`malformed entity id {id_type} ` .. cursor.readu32(c))
+	else
+		return resolve_global_id(client, id_type - GLOBAL_ID_OFFSET), nil
 	end
-	error("malformed entity id" .. cursor.readu32(c))
 end
 
-local function process_entity_id(client: Client, c: Cursor, variants: { any }?)
+local function process_entity_id(client: Client, c: Cursor, variants: { any }?, v: boolean?)
 	local entity, server_id = read_entity_id(client, c, variants)
 	if entity then
 		return entity
@@ -124,23 +145,23 @@ local function process_entity(client: Client, c: Cursor, variants: { any }?)
 	local entity = process_entity_id(client, c, variants)
 
 	local total_tags = cursor.read_vlq(c)
-	for i = 1, total_tags do
+	for _ = 1, total_tags do
 		local tag = read_component_id(client, c)
 		client.world:add(entity, tag)
 	end
 
 	local total_components = cursor.read_vlq(c)
-	for i = 1, total_components do
+	for _ = 1, total_components do
 		local component, value = read_component_value(client, c, variants)
 		client.world:set(entity, component, value)
 	end
 
 	local total_pairs = cursor.read_vlq(c)
-	for i = 1, total_pairs do
+	for _ = 1, total_pairs do
 		local relation = read_component_id(client, c)
 		local total_targets = cursor.read_vlq(c)
 
-		for i = 1, total_targets do
+		for _ = 1, total_targets do
 			local target = process_entity_id(client, c, variants)
 			client.world:add(entity, PAIR(relation, target))
 		end
@@ -161,26 +182,26 @@ local function apply_updates(client: Client, buf: buffer, all_variants: { { any
 		end
 
 		local total_changed = cursor.read_vlq(c)
-		for i = 1, total_changed do
+		for _ = 1, total_changed do
 			local entity = process_entity_id(client, c, variants)
 			local total_tagged = cursor.read_vlq(c)
-			for i = 1, total_tagged do
+			for _ = 1, total_tagged do
 				local tag = read_component_id(client, c)
 				client.world:add(entity, tag)
 			end
 
 			local total_components = cursor.read_vlq(c)
-			for i = 1, total_components do
+			for _ = 1, total_components do
 				local component, value = read_component_value(client, c, variants)
 				client.world:set(entity, component, value)
 			end
 
 			local total_pairs = cursor.read_vlq(c)
-			for i = 1, total_pairs do
+			for _ = 1, total_pairs do
 				local relation = read_component_id(client, c)
 				local total_targets = cursor.read_vlq(c)
 
-				for t = 1, total_targets do
+				for _ = 1, total_targets do
 					local id_type = cursor.readi8(c)
 					-- here I use negative numbers to indicate removals
 					-- but "process_entity_id" expects a positive value
@@ -198,37 +219,37 @@ local function apply_updates(client: Client, buf: buffer, all_variants: { { any
 			end
 
 			local total_removed = cursor.read_vlq(c)
-			for i = 1, total_removed do
+			for _ = 1, total_removed do
 				local component = read_component_id(client, c)
 				client.world:remove(entity, component)
 			end
 		end
 
 		local total_component_deleted = cursor.read_vlq(c)
-		for i = 1, total_component_deleted do
+		for _ = 1, total_component_deleted do
 			local entity = process_entity_id(client, c, variants)
 
 			local total_tags = cursor.read_vlq(c)
-			for i = 1, total_tags do
+			for _ = 1, total_tags do
 				local tag = read_component_id(client, c)
 				client.world:remove(entity, tag)
 			end
 
 			local total_components = cursor.read_vlq(c)
-			for i = 1, total_components do
+			for _ = 1, total_components do
 				local component = read_component_id(client, c)
 				client.world:remove(entity, component)
 			end
 
 			local total_pairs = cursor.read_vlq(c)
-			for i = 1, total_pairs do
+			for _ = 1, total_pairs do
 				local relation = read_component_id(client, c)
 				utils.remove_all_relations(client.world, entity, relation)
 			end
 		end
 
 		local total_deleted = cursor.read_vlq(c)
-		for i = 1, total_deleted do
+		for _ = 1, total_deleted do
 			local entity, server_id = read_entity_id(client, c, variants)
 			if entity then
 				client.world:delete(entity)
@@ -249,7 +270,7 @@ local function apply_unreliable(client: Client, buf: buffer, all_variants: { { a
 		local total_entities = cursor.read_vlq(c)
 		local variants = all_variants and all_variants[variant_start - a]
 
-		for e = 1, total_entities do
+		for _ = 1, total_entities do
 			local entity = read_entity_id(client, c, variants)
 			local total_unreliable = cursor.read_vlq(c)
 
@@ -259,7 +280,7 @@ local function apply_unreliable(client: Client, buf: buffer, all_variants: { { a
 			else
 				-- dont apply unreliable updates to entities that dont exist in the client yet
 				-- but we still need to process the values to keep the cursor in the right place
-				for u = 1, total_unreliable do
+				for _ = 1, total_unreliable do
 					read_component_value(client, c, variants)
 				end
 			end
@@ -276,7 +297,7 @@ local function apply_full(client: Client, buf: buffer, all_variants: { { any } }
 		local total_entities = cursor.read_vlq(c)
 		local variants = all_variants and all_variants[variant_start - a]
 
-		for e = 1, total_entities do
+		for _ = 1, total_entities do
 			process_entity(client, c, variants)
 		end
 	end
@@ -315,6 +336,14 @@ local function after_replication(client: Client, callback: () -> ())
 	end
 end
 
+local function get_server_entity(client: Client, client_entity: Entity): number?
+	return client.client_ids[client_entity]
+end
+
+local function get_client_entity(client: Client, client_entity: number): Entity?
+	return client.server_ids[client_entity]
+end
+
 local function destroy(client: Client)
 	if client.inited == nil then
 		return warn "attempted to destroy a client twice"
@@ -324,6 +353,10 @@ local function destroy(client: Client)
 	-- right now this is kind of useless
 end
 
+local function parse_global_id(client: Client, parser: (id: number) -> Entity)
+	client.global_id_parser = parser
+end
+
 local client = {}
 client.__index = client
 client.init = init
@@ -332,6 +365,9 @@ client.after_replication = after_replication
 client.apply_updates = apply_updates
 client.apply_unreliable = apply_unreliable
 client.apply_full = apply_full
+client.get_server_entity = get_server_entity
+client.get_client_entity = get_client_entity
+client.parse_global_id = parse_global_id
 
 local function create(world: World?, components: common.Components): Client
 	local self = {} :: Client
@@ -341,6 +377,7 @@ local function create(world: World?, components: common.Components): Client
 	self.custom_ids = {}
 	self.server_ids = {}
 	self.client_ids = {}
+	self.global_id_parser = nil
 	self.world = world :: any
 	self.inited = false
 	self.is_replicating = false

package/out/replecs/common.luau

@@ -1,4 +1,4 @@
-local jecs = require(script.Parent.Parent.jecs)
+local jecs = require "../jecs"
 
 export type PlayerFilter = {
 	[Player]: boolean,
@@ -19,6 +19,7 @@ export type Components = {
 	serdes: jecs.Entity<Serdes>,
 	bytespan: jecs.Entity<number>,
 	custom_id: jecs.Entity<(value: any) -> jecs.Entity>,
+	global_id: jecs.Entity<number>,
 	__alive_tracking__: jecs.Entity,
 }
 

package/out/replecs/index.d.ts

@@ -10,7 +10,7 @@ declare namespace Replecs {
       added<T>(
          this: ObserverWorld,
          component: Id<T>,
-         callback: (e: Entity, id: Id<T>, value?: T) => void
+         callback: (e: Entity, id: Id<T>, value: T) => void
       ): () => void;
       removed<T>(
          this: ObserverWorld,
@@ -20,40 +20,43 @@ declare namespace Replecs {
       changed<T>(
          this: ObserverWorld,
          component: Id<T>,
-         callback: (e: Entity, id: Id<T>, value?: T) => void
+         callback: (e: Entity, id: Id<T>, value: T) => void
       ): () => void;
    }
 
-   type MemberFilter = Map<Player, boolean>;
+   type MemberFilterMap = Map<Player, boolean>;
+   type MemberFilter = Player | MemberFilterMap | undefined;
    type Member = unknown;
 
    interface MaskingController {
       register_member(member: Member): void;
       unregister_member(member: Member): void;
       active_member(member: Member): void;
-      member_is_active(member: Member): boolean
+      member_is_active(member: Member): boolean;
    }
 
    export interface Components {
       shared: Tag;
-      networked: Entity<MemberFilter | undefined>;
-      reliable: Entity<MemberFilter | undefined>;
-      unreliable: Entity<MemberFilter | undefined>;
-      pair: Entity<MemberFilter | undefined>;
+      networked: Entity<MemberFilter>;
+      reliable: Entity<MemberFilter>;
+      unreliable: Entity<MemberFilter>;
+      pair: Entity<MemberFilter>;
 
       serdes: Entity<SerdesTable>;
       bytespan: Entity<number>;
       custom_id: Entity<((value: any) => Entity) | undefined>;
+      global_id: Entity<number>;
 
       Shared: Tag;
-      Networked: Entity<MemberFilter | undefined>;
-      Reliable: Entity<MemberFilter | undefined>;
-      Unreliable: Entity<MemberFilter | undefined>;
-      Pair: Entity<MemberFilter | undefined>;
+      Networked: Entity<MemberFilter>;
+      Reliable: Entity<MemberFilter>;
+      Unreliable: Entity<MemberFilter>;
+      Pair: Entity<MemberFilter>;
 
       Serdes: Entity<SerdesTable>;
       Bytespan: Entity<number>;
-      CustomId: Entity<((value: any) => Entity) | undefined>;
+      CustomId: Entity<(value: any) => Entity>;
+      GlobalId: Entity<number>;
    }
 
    export interface Client {
@@ -67,6 +70,10 @@ declare namespace Replecs {
       apply_updates(buf: buffer, all_variants?: any[][]): void;
       apply_unreliable(buf: buffer, all_variants?: any[][]): void;
       apply_full(buf: buffer, all_variants?: any[][]): void;
+      parse_global_id(parser: (id: number) => Entity): void;
+
+      get_server_entity(client_entity: Entity): number | undefined;
+      get_client_entity(server_entity: number): Entity | undefined;
    }
 
    export interface Server {
@@ -78,7 +85,9 @@ declare namespace Replecs {
 
       get_full(player: Player): LuaTuple<[buffer, any[][]]>;
       collect_updates(): IterableFunction<LuaTuple<[Player, buffer, any[][]]>>;
-      collect_unreliable(): IterableFunction<LuaTuple<[Player, buffer, any[][]]>>;
+      collect_unreliable(): IterableFunction<
+         LuaTuple<[Player, buffer, any[][]]>
+      >;
       mark_player_ready(player: Player): void;
       is_player_ready(player: Player): boolean;
 
@@ -89,7 +98,7 @@ declare namespace Replecs {
       client: Client;
       server: Server;
 
-      after_replication(world: ObserverWorld): void;
+      after_replication(callback: () => void): void;
    }
 
    export interface Replecs extends Components {

package/out/replecs/init.luau

@@ -1,83 +1,88 @@
-local RunService = game:GetService "RunService"
-local jecs = require(script.Parent.jecs)
-local common = require(script.common)
-
-local client = require(script.client)
-local server = require(script.server)
-
-export type Server = server.Server
-export type Client = client.Client
-
-export type Replecs = {
-	server: Server,
-	client: Client,
-
-	after_replication: (self: Replecs, callback: () -> ()) -> (),
-}
-
-type MemberFilter = {
-	[Player]: boolean,
-}
-
-local replecs = {
-	shared = jecs.tag(),
-	networked = jecs.component() :: jecs.Entity<MemberFilter?>,
-	reliable = jecs.component() :: jecs.Entity<MemberFilter?>,
-	unreliable = jecs.component() :: jecs.Entity<MemberFilter?>,
-	pair = jecs.tag(),
-
-	serdes = jecs.component() :: jecs.Entity<common.Serdes>,
-	bytespan = jecs.component() :: jecs.Entity<number>,
-	custom_id = jecs.component() :: jecs.Entity<(any) -> jecs.Entity>,
-	__alive_tracking__ = jecs.tag(),
-}
-replecs.__index = replecs
-replecs.Serdes = replecs.serdes
-replecs.Bytespan = replecs.bytespan
-replecs.CustomId = replecs.custom_id
-replecs.Networked = replecs.networked
-replecs.Reliable = replecs.reliable
-replecs.Unreliable = replecs.unreliable
-replecs.Pair = replecs.pair
-replecs.Shared = replecs.shared
-
-jecs.meta(replecs.serdes, jecs.Name, "replecs.serdes")
-jecs.meta(replecs.bytespan, jecs.Name, "replecs.bytespan")
-jecs.meta(replecs.custom_id, jecs.Name, "replecs.custom_id")
-jecs.meta(replecs.networked, jecs.Name, "replecs.networked")
-jecs.meta(replecs.reliable, jecs.Name, "replecs.reliable")
-jecs.meta(replecs.unreliable, jecs.Name, "replecs.unreliable")
-jecs.meta(replecs.pair, jecs.Name, "replecs.pair")
-jecs.meta(replecs.shared, jecs.Name, "replecs.shared")
-
-function replecs.create_server(world: jecs.World?): Server
-	return server.create(world, replecs)
-end
-
-function replecs.create_client(world: jecs.World?): Client
-	return client.create(world, replecs)
-end
-
-function replecs.create(world: jecs.World?): Replecs
-	local lib = {} :: Replecs
-
-	if RunService:IsServer() then
-		lib.server = server.create(world, replecs)
-	end
-	if RunService:IsClient() then
-		lib.client = client.create(world, replecs)
-	end
-
-	return setmetatable(lib, replecs) :: any
-end
-
-function replecs.after_replication(lib: Replecs, callback: () -> ())
-	local lib_client = lib.client
-	if lib_client then
-		lib_client:after_replication(callback)
-	else
-		callback()
-	end
-end
-
-return replecs
+local jecs = require "./jecs"
+local common = require "@self/common"
+
+local client = require "@self/client"
+local server = require "@self/server"
+
+export type Server = server.Server
+export type Client = client.Client
+
+export type ReplecsLib = {
+	server: Server,
+	client: Client,
+
+	after_replication: (self: ReplecsLib, callback: () -> ()) -> (),
+}
+
+type MemberFilter = {
+	[Player]: boolean,
+}
+
+local replecs = {
+	shared = jecs.tag(),
+	networked = jecs.component() :: jecs.Entity<(MemberFilter | Player)?>,
+	reliable = jecs.component() :: jecs.Entity<(MemberFilter | Player)?>,
+	unreliable = jecs.component() :: jecs.Entity<(MemberFilter | Player)?>,
+	pair = jecs.tag(),
+
+	serdes = jecs.component() :: jecs.Entity<common.Serdes>,
+	bytespan = jecs.component() :: jecs.Entity<number>,
+	custom_id = jecs.component() :: jecs.Entity<(any) -> jecs.Entity>,
+	global_id = jecs.component() :: jecs.Entity<number>,
+	__alive_tracking__ = jecs.tag(),
+}
+
+replecs.__index = replecs
+replecs.Serdes = replecs.serdes
+replecs.Bytespan = replecs.bytespan
+replecs.CustomId = replecs.custom_id
+replecs.Networked = replecs.networked
+replecs.Reliable = replecs.reliable
+replecs.Unreliable = replecs.unreliable
+replecs.Pair = replecs.pair
+replecs.Shared = replecs.shared
+replecs.GlobalId = replecs.global_id
+
+jecs.meta(replecs.serdes, jecs.Name, "replecs.serdes")
+jecs.meta(replecs.bytespan, jecs.Name, "replecs.bytespan")
+jecs.meta(replecs.custom_id, jecs.Name, "replecs.custom_id")
+jecs.meta(replecs.networked, jecs.Name, "replecs.networked")
+jecs.meta(replecs.reliable, jecs.Name, "replecs.reliable")
+jecs.meta(replecs.unreliable, jecs.Name, "replecs.unreliable")
+jecs.meta(replecs.pair, jecs.Name, "replecs.pair")
+jecs.meta(replecs.shared, jecs.Name, "replecs.shared")
+
+function replecs.create_server(world: jecs.World?): Server
+	return server.create(world, replecs)
+end
+
+function replecs.create_client(world: jecs.World?): Client
+	return client.create(world, replecs)
+end
+
+function replecs.create(world: jecs.World?): ReplecsLib
+	assert(game, "This is a Roblox specific function")
+
+	local RunService = game:GetService "RunService"
+	local lib = {} :: ReplecsLib
+
+	if RunService:IsServer() then
+		lib.server = server.create(world, replecs)
+	end
+	if RunService:IsClient() then
+		lib.client = client.create(world, replecs)
+	end
+
+	return setmetatable(lib, replecs) :: any
+end
+
+function replecs.after_replication(lib: ReplecsLib, callback: () -> ())
+	local lib_client = lib.client
+	if lib_client then
+		lib_client:after_replication(callback)
+	else
+		callback()
+	end
+end
+
+return replecs