Merge e8575a0db6 into eaafd27280

* Add support for components in both positions of pairs

* Export type function

* Rework query types

.github/workflows/styling.yaml

@@ -1,20 +0,0 @@
-name: Styling
-
-on: [push, pull_request, workflow_dispatch]
-
-jobs:
-    run:
-        name: Run Stylua
-        runs-on: ubuntu-latest
-
-        steps:
-            - name: Checkout Project
-              uses: actions/checkout@v4
-
-            - name: Run Stylua
-              uses: JohnnyMorganz/stylua-action@v4
-              with:
-                  token: ${{ secrets.GITHUB_TOKEN }}
-                  version: latest # NOTE: we recommend pinning to a specific version in case of formatting changes
-                  # CLI arguments
-                  args: --check jecs.luau

jecs.d.ts

@@ -1,40 +1,49 @@
+/*
+ * The base type for entities.
+ * This type indicates that the entity cannot be used to `tag` other entities
+ * and cannot be used used as a component to associate any kind of data with itself.
+ */
+export type Id = number & {
+    readonly __nominal_Id: unique symbol;
+};
+
+/*
+ * An entity with no associated data when used as a component.
+ * This entity however could still be used to 'tag' other entities.
+ *
+ * You could go further and downcast this type to `Id`
+ * indicating that the entity is intended to only store other entities.
+ */
+export type Tag = Id & {
+    readonly __nominal_Tag: unique symbol;
+};
+
 /**
  * A unique identifier in the world, entity.
- * The generic type T defines the data type when this entity is used as a component
+ * This identifier is associated with `TData` data when this entity is used as a component.
  */
-export type Entity<T = undefined | unknown> = number & { __jecs_value: T };
+export type Entity<TData = unknown> = Tag & {
-
+    readonly __nominal_Entity: unique symbol;
-/**
+    readonly __type_TData: TData;
- * An entity with no associated data when used as a component
- */
-export type Tag = Entity<undefined>;
-
-/**
- * A pair of entities
- * P is the type of the predicate, O is the type of the object, and V is the type of the value (defaults to P)
- */
-export type Pair<P = undefined, O = undefined, V = P> = number & {
-	__jecs_pair_pred: P;
-	__jecs_pair_obj: O;
-	__jecs_pair_value: V;
 };
 
-/**
+type InferComponent<TValue> = TValue extends Entity<infer TData> ? TData : never;
- * Either an Entity or a Pair
- */
-export type Id<T = unknown> = Entity<T> | Pair<unknown, unknown, T>;
 
-type InferComponent<E> = E extends Id<infer T> ? T : never;
+type FlattenTuple<TItems extends any[]> = TItems extends [infer TValue] ? TValue : LuaTuple<TItems>;
-type FlattenTuple<T extends any[]> = T extends [infer U] ? U : LuaTuple<T>;
+
-type Nullable<T extends unknown[]> = { [K in keyof T]: T[K] | undefined };
+type Undefinedable<TItems extends any[]> = {
-type InferComponents<A extends Id[]> = {
+    [TKey in keyof TItems]: TItems[TKey] | undefined;
-	[K in keyof A]: InferComponent<A[K]>;
 };
-type TupleForWorldGet = [Id] | [Id, Id] | [Id, Id, Id] | [Id, Id, Id, Id];
 
-type Iter<T extends unknown[]> = IterableFunction<LuaTuple<[Entity, ...T]>>;
+type InferComponents<TComponents extends Entity[]> = {
+	[TKey in keyof TComponents]: InferComponent<TComponents[TKey]>;
+};
 
-export type Query<T extends unknown[]> = {
+type TupleForWorldGet = [Entity] | [Entity, Entity] | [Entity, Entity, Entity] | [Entity, Entity, Entity, Entity];
+
+type Iter<T extends any[]> = IterableFunction<LuaTuple<[Entity, ...T]>>;
+
+export type Query<T extends any[]> = {
 	/**
 	 * Returns an iterator that returns a tuple of an entity and queried components
 	 */
@@ -45,14 +54,14 @@ export type Query<T extends unknown[]> = {
 	 * @param components The components to include
 	 * @returns Modified Query
 	 */
-	with(...components: Id[]): Query<T>;
+	with(...components: Tag[]): Query<T>;
 
 	/**
 	 * Modifies the Query to exclude specified components
 	 * @param components The components to exclude
 	 * @returns Modified Query
 	 */
-	without(...components: Id[]): Query<T>;
+	without(...components: Tag[]): Query<T>;
 } & Iter<T>;
 
 export class World {
@@ -62,26 +71,31 @@ export class World {
 	constructor();
 
 	/**
-	 * Creates a new entity
+	 * Creates a new entity.
+     *
+     * If your intention is to use this entity as a component associated with some data
+     * then you should provide the type parameter.
+     *
 	 * @returns Entity
 	 */
-	entity(): Tag;
+	entity<TData = never>(): [TData] extends [never] ? Id : Entity<TData>;
 
 	/**
 	 * Creates a new entity located in the first 256 ids.
+     *
 	 * These should be used for static components for fast access.
-	 * @returns Entity<T>
+	 * @returns Entity<TData>
 	 */
-	component<T = unknown>(): Entity<T>;
+	component<TData = unknown>(): Entity<TData>;
 
 	/**
 	 * Gets the target of a relationship. For example, when a user calls
-	 * `world.target(entity, ChildOf(parent))`, you will obtain the parent entity.
+	 * `world.target(entity, ChildOf)`, you will obtain the parent entity.
 	 * @param entity Entity
 	 * @param relation The Relationship
 	 * @returns The Parent Entity if it exists
 	 */
-	target(entity: Entity, relation: Entity): Entity | undefined;
+	target(entity: Id, relation: Entity): Entity | undefined;
 
 	/**
 	 * Gets the target of a relationship at a specific index.
@@ -92,26 +106,27 @@ export class World {
 	 * @param index Target index
 	 * @returns The Parent Entity if it exists
 	 */
-	target(entity: Entity, relation: Entity, index: number): Entity | undefined;
+	target(entity: Id, relation: Entity, index: number): Entity | undefined;
 
 	/**
-	 * Clears an entity from the world
+	 * Clears an entity from the world.
 	 * @param entity Entity to be cleared
 	 */
-	clear(entity: Entity): void;
+	clear(entity: Id): void;
 
 	/**
-	 * Deletes an entity and all its related components and relationships
+	 * Deletes an entity and all its related components and relationships.
 	 * @param entity Entity to be destroyed
 	 */
-	delete(entity: Entity): void;
+	delete(entity: Id): void;
 
 	/**
-	 * Adds a component to the entity with no value
+	 * Adds a component to the entity with no value.
+     *
 	 * @param entity Target Entity
-	 * @param component Component
+	 * @param tag Tag
 	 */
-	add(entity: Entity, component: Id): void;
+	add(entity: Id, tag: Tag): void;
 
 	/**
 	 * Assigns a value to a component on the given entity
@@ -119,40 +134,41 @@ export class World {
 	 * @param component Target Component
 	 * @param value Component Value
 	 */
-	set<E extends Id<unknown>>(entity: Entity, component: E, value: InferComponent<E>): void;
+	set<TData>(entity: Id, component: Entity<TData>, value: TData): void;
 
 	/**
 	 * Removes a component from the given entity
 	 * @param entity Target Entity
 	 * @param component Target Component
 	 */
-	remove(entity: Entity, component: Id): void;
+	remove(entity: Id, component: Tag): void;
 
 	/**
 	 * Retrieves the values of specified components for an entity.
 	 * Some values may not exist when called.
 	 * A maximum of 4 components are allowed at a time.
-	 * @param id Target Entity
+	 * @param entity Target Entity
 	 * @param components Target Components
 	 * @returns Data associated with target components if it exists.
 	 */
-	get<T extends TupleForWorldGet>(id: Entity, ...components: T): FlattenTuple<Nullable<InferComponents<T>>>;
+	get<TComponents extends TupleForWorldGet>(entity: Id, ...components: TComponents): FlattenTuple<Undefinedable<InferComponents<TComponents>>>;
 
 	/**
 	 * Returns whether the entity has the specified components.
 	 * A maximum of 4 components are allowed at a time.
+     *
 	 * @param entity Target Entity
 	 * @param components Target Components
 	 * @returns If the entity contains the components
 	 */
-	has(entity: Entity, ...components: Id[]): boolean;
+	has(entity: Id, ...components: Tag[]): boolean;
 
 	/**
 	 * Checks if an entity exists in the world
 	 * @param entity Entity to check
 	 * @returns Whether the entity exists in the world
 	 */
-	contains(entity: Entity): boolean;
+	contains(entity: Id): boolean;
 
 	/**
 	 * Get parent (target of ChildOf relationship) for entity.
@@ -160,48 +176,51 @@ export class World {
 	 * @param entity Target Entity
 	 * @returns Parent Entity or undefined
 	 */
-	parent(entity: Entity): Entity | undefined;
+	parent(entity: Id): Entity | undefined;
 
 	/**
 	 * Searches the world for entities that match a given query
 	 * @param components Queried Components
 	 * @returns Query
 	 */
-	query<T extends Id[]>(...components: T): Query<InferComponents<T>>;
+	query<TComponents extends Entity[]>(...components: TComponents): Query<InferComponents<TComponents>>;
 }
 
 /**
- * Creates a composite key (pair)
+ * Creates a composite key (pair).
+ *
  * @param pred The first entity (predicate)
  * @param obj The second entity (object)
  * @returns The composite key (pair)
  */
-export function pair<P, O, V = P>(pred: Entity<P>, obj: Entity<O>): Pair<P, O, V>;
+export function pair<TPredicate, TObject>(pred: Entity<TPredicate>, obj: Entity<TObject>): Entity<TPredicate>;
 
 /**
  * Checks if the entity is a composite key (pair)
  * @param value The entity to check
  * @returns If the entity is a pair
  */
-export function IS_PAIR(value: Id): value is Pair;
+export function IS_PAIR(value: Id): value is Entity;
 
 /**
  * Gets the first entity (predicate) of a pair
  * @param pair The pair to get the first entity from
  * @returns The first entity (predicate) of the pair
  */
-export function pair_first<P, O, V = P>(pair: Pair<P, O, V>): Entity<P>;
+export function pair_first(world: World, pair: Entity): Entity;
 
 /**
  * Gets the second entity (object) of a pair
  * @param pair The pair to get the second entity from
  * @returns The second entity (object) of the pair
  */
-export function pair_second<P, O, V = P>(pair: Pair<P, O, V>): Entity<O>;
+export function pair_second(world: World, pair: Entity): Entity;
 
-export const OnAdd: Entity<(e: Entity) => void>;
+export const Component: Entity;
-export const OnRemove: Entity<(e: Entity) => void>;
+
-export const OnSet: Entity<(e: Entity, value: unknown) => void>;
+export const OnAdd: Entity<(entity: Entity) => void>;
+export const OnRemove: Entity<(entity: Entity) => void>;
+export const OnSet: Entity<(entity: Entity, value: unknown) => void>;
 export const ChildOf: Entity;
 export const Wildcard: Entity;
 export const w: Entity;

jecs.luau

@@ -257,7 +257,7 @@ local function archetype_move(entity_index: EntityIndex, to: Archetype, dst_row:
 	local src_entities = from.entities
 
 	local last = #src_entities
-	local types = from.types
+	local id_types = from.types
 	local records = to.records
 
 	for i, column in src_columns do
@@ -266,12 +266,13 @@ local function archetype_move(entity_index: EntityIndex, to: Archetype, dst_row:
 		end
 		-- Retrieves the new column index from the source archetype's record from each component
 		-- We have to do this because the columns are tightly packed and indexes may not correspond to each other.
-		local tr = records[types[i]]
+		local tr = records[id_types[i]]
 
 		-- Sometimes target column may not exist, e.g. when you remove a component.
 		if tr then
 			dst_columns[tr.column][dst_row] = column[src_row]
 		end
+
 		-- If the entity is the last row in the archetype then swapping it would be meaningless.
 		if src_row ~= last then
 			-- Swap rempves columns to ensure there are no holes in the archetype.
@@ -475,7 +476,8 @@ local function id_record_ensure(world: World, id: number): IdRecord
 	if not idr then
 		local flags = ECS_ID_MASK
 		local relation = id
-		if ECS_IS_PAIR(id) then
+		local is_pair = ECS_IS_PAIR(id)
+		if is_pair then
 			relation = ecs_pair_first(world, id)
 		end
 
@@ -492,6 +494,10 @@ local function id_record_ensure(world: World, id: number): IdRecord
 
 		local is_tag = not world_has_one_inline(world, relation, EcsComponent)
 
+		if is_tag and is_pair then
+			is_tag = not world_has_one_inline(world, ecs_pair_second(world, id), EcsComponent)
+		end
+
 		flags = bit32.bor(
 			flags,
 			if on_add then ECS_ID_HAS_ON_ADD else 0,
@@ -535,15 +541,15 @@ local function archetype_append_to_records(
 	end
 end
 
-local function archetype_create(world: World, types: { i24 }, ty, prev: i53?): Archetype
+local function archetype_create(world: World, id_types: { i24 }, ty, prev: i53?): Archetype
 	local archetype_id = (world.nextArchetypeId :: number) + 1
 	world.nextArchetypeId = archetype_id
 
-	local length = #types
+	local length = #id_types
 	local columns = (table.create(length) :: any) :: { Column }
 
 	local records: { ArchetypeRecord } = {}
-	for i, componentId in types do
+	for i, componentId in id_types do
 		local idr = id_record_ensure(world, componentId)
 		archetype_append_to_records(idr, archetype_id, records, componentId, i)
 
@@ -572,7 +578,7 @@ local function archetype_create(world: World, types: { i24 }, ty, prev: i53?): A
 		id = archetype_id,
 		records = records,
 		type = ty,
-		types = types,
+		types = id_types,
 
 		add = {},
 		remove = {},
@@ -593,22 +599,22 @@ local function world_parent(world: World, entity: i53)
 	return world_target(world, entity, EcsChildOf, 0)
 end
 
-local function archetype_ensure(world: World, types): Archetype
+local function archetype_ensure(world: World, id_types): Archetype
-	if #types < 1 then
+	if #id_types < 1 then
 		return world.ROOT_ARCHETYPE
 	end
 
-	local ty = hash(types)
+	local ty = hash(id_types)
 	local archetype = world.archetypeIndex[ty]
 	if archetype then
 		return archetype
 	end
 
-	return archetype_create(world, types, ty)
+	return archetype_create(world, id_types, ty)
 end
 
-local function find_insert(types: { i53 }, toAdd: i53): number
+local function find_insert(id_types: { i53 }, toAdd: i53): number
-	for i, id in types do
+	for i, id in id_types do
 		if id == toAdd then
 			return -1
 		end
@@ -616,7 +622,7 @@ local function find_insert(types: { i53 }, toAdd: i53): number
 			return i
 		end
 	end
-	return #types + 1
+	return #id_types + 1
 end
 
 local function find_archetype_with(world: World, node: Archetype, id: i53): Archetype
@@ -886,7 +892,7 @@ end
 local function archetype_delete(world: World, archetype: Archetype, row: number, destruct: boolean?)
 	local entityIndex = world.entity_index
 	local columns = archetype.columns
-	local types = archetype.types
+	local id_types = archetype.types
 	local entities = archetype.entities
 	local column_count = #entities
 	local last = #entities
@@ -905,7 +911,7 @@ local function archetype_delete(world: World, archetype: Archetype, row: number,
 
 	-- TODO: if last == 0 then deactivate table
 
-	for _, id in types do
+	for _, id in id_types do
 		local on_remove: (entity: i53) -> () = world_get_one_inline(world, id, EcsOnRemove)
 		if on_remove then
 			on_remove(delete)
@@ -913,9 +919,9 @@ local function archetype_delete(world: World, archetype: Archetype, row: number,
 	end
 
 	if row == last then
-		archetype_fast_delete_last(columns, column_count, types, delete)
+		archetype_fast_delete_last(columns, column_count, id_types, delete)
 	else
-		archetype_fast_delete(columns, column_count, row, types, delete)
+		archetype_fast_delete(columns, column_count, row, id_types, delete)
 	end
 end
 
@@ -1769,23 +1775,21 @@ function World.new()
 	return self
 end
 
-export type Id<T = unknown> = Entity<T> | Pair<Entity<T>, Entity<unknown>>
+export type Id<T = unknown> = Entity<T>
 
-export type Pair<First, Second> = number & {
+type function ecs_entity_t(entity)
-	__relation: First,
+	return entity:components()[2]:readproperty(types.singleton("__T"))
-}
+end
 
--- type function _Pair(first, second)
+export type function Pair(first, second)
---     local thing = first:components()[2]
+    local thing = first:components()[2]
 
--- 	if thing:readproperty(types.singleton("__T")):is("nil") then
+	if thing:readproperty(types.singleton("__T")):is("nil") then
--- 		return second
+		return second
--- 	else
+	else
--- 		return first
+		return first
--- 	end
+	end
--- end
+end
-
--- type TestPair = _Pair<Entity<number>, Entity<Vector3>>
 
 type Item<T...> = (self: Query<T...>) -> (Entity, T...)
 
@@ -1854,42 +1858,14 @@ export type World = {
 	children: (self: World, id: Id) -> () -> Entity,
 
 	--- Searches the world for entities that match a given query
-	query: (<A>(self: World, Id<A>) -> Query<A>)
+	query: (<A>(World, A) -> Query<ecs_entity_t<A>>)
-		& (<A, B>(self: World, Id<A>, Id<B>) -> Query<A, B>)
+        & (<A, B>(World, A, B) -> Query<ecs_entity_t<A>, ecs_entity_t<B>>)
-		& (<A, B, C>(self: World, Id<A>, Id<B>, Id<C>) -> Query<A, B, C>)
+        & (<A, B, C>(World, A, B, C) -> Query<ecs_entity_t<A>, ecs_entity_t<B>, ecs_entity_t<C>>)
-		& (<A, B, C, D>(self: World, Id<A>, Id<B>, Id<C>, Id<D>) -> Query<A, B, C, D>)
+        & (<A, B, C, D>(World, A, B, C, D) -> Query<ecs_entity_t<A>, ecs_entity_t<B>, ecs_entity_t<C>, ecs_entity_t<D>>)
-		& (<A, B, C, D, E>(self: World, Id<A>, Id<B>, Id<C>, Id<D>, Id<E>) -> Query<A, B, C, D, E>)
+        & (<A, B, C, D, E>(World, A, B, C, D, E) -> Query<ecs_entity_t<A>, ecs_entity_t<B>, ecs_entity_t<C>, ecs_entity_t<D>, ecs_entity_t<E>>)
-		& (<A, B, C, D, E, F>(
+        & (<A, B, C, D, E, F>(World, A, B, C, D, E, F) -> Query<ecs_entity_t<A>, ecs_entity_t<B>, ecs_entity_t<C>, ecs_entity_t<D>, ecs_entity_t<E>, ecs_entity_t<F>>)
-			self: World,
+        & (<A, B, C, D, E, F, G>(World, A, B, C, D, E, F, G) -> Query<ecs_entity_t<A>, ecs_entity_t<B>, ecs_entity_t<C>, ecs_entity_t<D>, ecs_entity_t<E>, ecs_entity_t<F>, ecs_entity_t<G>>)
-			Id<A>,
+        & (<A, B, C, D, E, F, G, H>(World, A, B, C, D, E, F, G, H) -> Query<ecs_entity_t<A>, ecs_entity_t<B>, ecs_entity_t<C>, ecs_entity_t<D>, ecs_entity_t<E>, ecs_entity_t<F>, ecs_entity_t<G>, ecs_entity_t<H>>)
-			Id<B>,
-			Id<C>,
-			Id<D>,
-			Id<E>,
-			Id<F>
-		) -> Query<A, B, C, D, E, F>)
-		& (<A, B, C, D, E, F, G>(
-			self: World,
-			Id<A>,
-			Id<B>,
-			Id<C>,
-			Id<D>,
-			Id<E>,
-			Id<F>,
-			Id<G>
-		) -> Query<A, B, C, D, E, F, G>)
-		& (<A, B, C, D, E, F, G, H>(
-			self: World,
-			Id<A>,
-			Id<B>,
-			Id<C>,
-			Id<D>,
-			Id<E>,
-			Id<F>,
-			Id<G>,
-			Id<H>,
-			...Id<any>
-		) -> Query<A, B, C, D, E, F, G, H>),
 }
 
 return {

package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "@rbxts/jecs",
-    "version": "0.4.0-rc.0",
+	"version": "0.4.1-rc.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@rbxts/jecs",
-            "version": "0.4.0-rc.0",
+			"version": "0.4.1-rc.0",
 			"license": "MIT",
 			"devDependencies": {
 				"@rbxts/compiler-types": "^2.3.0-types.1",

test/tests.luau

@@ -165,8 +165,7 @@ TEST("world:entity()", function()
 		CHECK(ECS_GENERATION(e) == 1) -- 1
 	end
 
-	do
+	do CASE("pairs")
-		CASE("pairs")
 		local world = jecs.World.new()
 		local _e = world:entity()
 		local e2 = world:entity()
@@ -175,11 +174,17 @@ TEST("world:entity()", function()
 		-- Incomplete pair, must have a bit flag that notes it is a pair
 		CHECK(IS_PAIR(world:entity()) == false)
 
-		local pair = pair(e2, e3)
+		local p = pair(e2, e3)
-		CHECK(IS_PAIR(pair) == true)
+		CHECK(IS_PAIR(p) == true)
 
-		CHECK(ecs_pair_first(world, pair) == e2)
+		CHECK(ecs_pair_first(world, p) == e2)
-		CHECK(ecs_pair_second(world, pair) == e3)
+		CHECK(ecs_pair_second(world, p) == e3)
+
+		world:delete(e2)
+		local e2v2 = world:entity()
+		CHECK(IS_PAIR(e2v2) == false)
+
+		CHECK(IS_PAIR(pair(e2v2, e3)) == true)
 	end
 
 	do CASE "Recycling"
@@ -281,7 +286,7 @@ TEST("world:set()", function()
 
 		CHECK(world:get(e, pair(C1, C2)))
 		CHECK(world:get(e, pair(C1, T1)))
-		CHECK(not world:get(e, pair(T1, C1)))
+		CHECK(world:get(e, pair(T1, C1)))
 		CHECK(not world:get(e, pair(T1, T2)))
 
 		local e2 = world:entity()
@@ -399,7 +404,7 @@ TEST("world:query()", function()
 		for id, a, b, c, d in world:query(pair(C1, C2), pair(C1, T1), pair(T1, C1), pair(T1, T2)) do
 			CHECK(a == true)
 			CHECK(b == true)
-			CHECK(c == nil)
+			CHECK(c == true)
 			CHECK(d == nil)
 		end
 	end