Sovereignty/jecs
1
0
Fork 0
mirror of https://github.com/Ukendio/jecs.git synced 2026-02-04 15:15:21 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

ts type update

Browse source
This commit is contained in:
maeriil 2025-12-01 13:55:07 -05:00
parent 18b72149c7
commit b974dd9e52
1 changed files with 253 additions and 221 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

472
src/jecs.d.ts vendored
View file

@ -3,12 +3,12 @@
* The generic type T defines the data type when this entity is used as a component * The generic type T defines the data type when this entity is used as a component
*/ */
export type Entity<TData = unknown> = number & { export type Entity<TData = unknown> = number & {
readonly __nominal_Entity: unique symbol; readonly __nominal_Entity: unique symbol;
readonly __type_TData: TData; readonly __type_TData: TData;
}; };
type TagDiscriminator = { type TagDiscriminator = {
readonly __nominal_Tag: unique symbol; readonly __nominal_Tag: unique symbol;
}; };
/** /**
@ -22,23 +22,27 @@ export type Tag = Entity<TagDiscriminator>;
* - `obj` is the type of the "object" entity. * - `obj` is the type of the "object" entity.
*/ */
export type Pair<P = unknown, O = unknown> = number & { export type Pair<P = unknown, O = unknown> = number & {
readonly __nominal_Pair: unique symbol; readonly __nominal_Pair: unique symbol;
readonly __pred: P; readonly __pred: P;
readonly __obj: O; readonly __obj: O;
}; };
/** /**
* An `Id` can be either a single Entity or a Pair of Entities. * An `Id` can be either a single Entity or a Pair of Entities.
* By providing `TData`, you can specifically require an Id that yields that type. * By providing `TData`, you can specifically require an Id that yields that type.
*/ */
export type Id<TData = unknown> = Entity<TData> | Pair<TData, unknown> | Pair<TagDiscriminator, TData>; export type Id<TData = unknown> =
| Entity<TData>
| Pair<TData, unknown>
| Pair<TagDiscriminator, TData>;
export type InferComponent<E> = E extends Entity<infer D> export type InferComponent<E> =
? D E extends Entity<infer D>
: E extends Pair<infer P, infer O> ? D
? P extends TagDiscriminator : E extends Pair<infer P, infer O>
? O ? P extends TagDiscriminator
: P ? O
: never; : P
: never;
type FlattenTuple<T extends unknown[]> = T extends [infer U] ? U : LuaTuple<T>; type FlattenTuple<T extends unknown[]> = T extends [infer U] ? U : LuaTuple<T>;
type Nullable<T extends unknown[]> = { [K in keyof T]: T[K] | undefined }; type Nullable<T extends unknown[]> = { [K in keyof T]: T[K] | undefined };
@ -48,232 +52,260 @@ type ArchetypeId = number;
export type Column<T> = T[]; export type Column<T> = T[];
export type Archetype<T extends Id[]> = { export type Archetype<T extends Id[]> = {
id: number; id: number;
types: Entity[]; types: Entity[];
type: string; type: string;
entities: Entity[]; entities: Entity[];
columns: Column<unknown>[]; columns: Column<unknown>[];
columns_map: { [K in T[number]]: Column<InferComponent<K>> }; columns_map: { [K in T[number]]: Column<InferComponent<K>> };
}; };
type IterFn<T extends Id[]> = IterableFunction<LuaTuple<[Entity, ...InferComponents<T>]>>; type IterFn<T extends Id[]> = IterableFunction<LuaTuple<[Entity, ...InferComponents<T>]>>;
type Iter<T extends Id[]> = IterFn<T> & { type Iter<T extends Id[]> = IterFn<T> & {
/** /**
* This isn't callable * This isn't callable
* @hidden * @hidden
* @deprecated * @deprecated
*/ */
(): never (): never;
}; };
export type CachedQuery<T extends Id[]> = { export type CachedQuery<T extends Id[]> = {
/** /**
* Returns an iterator that produces a tuple of [Entity, ...queriedComponents]. * Returns an iterator that produces a tuple of [Entity, ...queriedComponents].
*/ */
iter(): IterFn<T>; iter(): IterFn<T>;
/** /**
* Returns the matched archetypes of the query * Returns the matched archetypes of the query
* @returns An array of archetypes of the query * @returns An array of archetypes of the query
*/ */
archetypes(): Archetype<T>[]; archetypes(): Archetype<T>[];
has(entity: Entity): boolean;
ids: Id<any>[];
filter_with?: Id<any>[];
filter_without?: Id<any>[];
archetypes_map: Map<number, number>;
} & Iter<T>; } & Iter<T>;
export type Query<T extends Id[]> = { export type Query<T extends Id[]> = {
/** /**
* Returns an iterator that produces a tuple of [Entity, ...queriedComponents]. * Returns an iterator that produces a tuple of [Entity, ...queriedComponents].
*/ */
iter(): IterFn<T>; iter(): IterFn<T>;
/** /**
* Creates and returns a cached version of this query for efficient reuse. * Creates and returns a cached version of this query for efficient reuse.
* Call refinement methods (with/without) on the query before caching. * Call refinement methods (with/without) on the query before caching.
* @returns A cached query * @returns A cached query
*/ */
cached(): CachedQuery<T>; cached(): CachedQuery<T>;
/** /**
* Modifies the query to include specified components. * Modifies the query to include specified components.
* @param components The components to include. * @param components The components to include.
* @returns A new Query with the inclusion applied. * @returns A new Query with the inclusion applied.
*/ */
with(...components: Id[]): Query<T>; with(...components: Id[]): Query<T>;
/** /**
* Modifies the Query to exclude specified components. * Modifies the Query to exclude specified components.
* @param components The components to exclude. * @param components The components to exclude.
* @returns A new Query with the exclusion applied. * @returns A new Query with the exclusion applied.
*/ */
without(...components: Id[]): Query<T>; without(...components: Id[]): Query<T>;
/** /**
* Returns the matched archetypes of the query * Returns the matched archetypes of the query
* @returns An array of archetypes of the query * @returns An array of archetypes of the query
*/ */
archetypes(): Archetype<T>[]; archetypes(): Archetype<T>[];
has(entity: Entity): boolean;
ids: Id<any>[];
filter_with?: Id<any>[];
filter_without?: Id<any>[];
} & Iter<T>; } & Iter<T>;
export class World { export class World {
/** /**
* Creates a new World. * Creates a new World.
*/ */
private constructor(); private constructor();
/** /**
* Enforces a check for entities to be created within a desired range. * Enforces a check for entities to be created within a desired range.
* @param range_begin The starting point * @param range_begin The starting point
* @param range_end The end point (optional) * @param range_end The end point (optional)
*/ */
range(range_begin: number, range_end?: number): void; range(range_begin: number, range_end?: number): void;
/** /**
* Creates a new entity. * Creates a new entity.
* @returns An entity (Tag) with no data. * @returns An entity (Tag) with no data.
*/ */
entity(): Tag; entity(): Tag;
entity<T extends Entity>(id: T): T; entity<T extends Entity>(id: T): T;
/** /**
* Creates a new entity in the first 256 IDs, typically used for static * Creates a new entity in the first 256 IDs, typically used for static
* components that need fast access. * components that need fast access.
* @returns A typed Entity with `TData`. * @returns A typed Entity with `TData`.
*/ */
component<TData = unknown>(): Entity<TData>; component<TData = unknown>(): Entity<TData>;
/** /**
* Gets the target of a relationship. For example, if we say * Gets the target of a relationship. For example, if we say
* `world.target(entity, ChildOf)`, this returns the parent entity. * `world.target(entity, ChildOf)`, this returns the parent entity.
* @param entity The entity using a relationship pair. * @param entity The entity using a relationship pair.
* @param relation The "relationship" component/tag (e.g., ChildOf). * @param relation The "relationship" component/tag (e.g., ChildOf).
* @param index If multiple targets exist, specify an index. Defaults to 0. * @param index If multiple targets exist, specify an index. Defaults to 0.
*/ */
target(entity: Entity, relation: Entity, index?: number): Entity | undefined; target(entity: Entity, relation: Entity, index?: number): Entity | undefined;
/** /**
* Deletes an entity (and its components/relationships) from the world entirely. * Deletes an entity (and its components/relationships) from the world entirely.
* @param entity The entity to delete. * @param entity The entity to delete.
*/ */
delete(entity: Entity): void; delete(entity: Entity): void;
/** /**
* Adds a component (with no value) to the entity. * Adds a component (with no value) to the entity.
* @param entity The target entity. * @param entity The target entity.
* @param component The component (or tag) to add. * @param component The component (or tag) to add.
*/ */
add<C>(entity: Entity, component: TagDiscriminator extends InferComponent<C> ? C : Id<TagDiscriminator>): void; add<C>(
entity: Entity,
component: TagDiscriminator extends InferComponent<C> ? C : Id<TagDiscriminator>,
): void;
/** /**
* Installs a hook on the given component. * Installs a hook on the given component.
* @param component The target component. * @param component The target component.
* @param hook The hook to install. * @param hook The hook to install.
* @param value The hook callback. * @param value The hook callback.
*/ */
set<T>(component: Entity<T>, hook: StatefulHook, value: (e: Entity, id: Id<T>, data: T) => void): void; set<T>(
set<T>(component: Entity<T>, hook: StatelessHook, value: (e: Entity, id: Id<T>) => void): void; component: Entity<T>,
/** hook: StatefulHook,
* Assigns a value to a component on the given entity. value: (e: Entity, id: Id<T>, data: T) => void,
* @param entity The target entity. ): void;
* @param component The component definition (could be a Pair or Entity). set<T>(component: Entity<T>, hook: StatelessHook, value: (e: Entity, id: Id<T>) => void): void;
* @param value The value to store with that component. /**
*/ * Assigns a value to a component on the given entity.
set<E extends Id<unknown>>(entity: Entity, component: E, value: InferComponent<E>): void; * @param entity The target entity.
* @param component The component definition (could be a Pair or Entity).
* @param value The value to store with that component.
*/
set<E extends Id<unknown>>(entity: Entity, component: E, value: InferComponent<E>): void;
/** /**
* Cleans up the world by removing empty archetypes and rebuilding the archetype collections. * Cleans up the world by removing empty archetypes and rebuilding the archetype collections.
* This helps maintain memory efficiency by removing unused archetype definitions. * This helps maintain memory efficiency by removing unused archetype definitions.
*/ */
cleanup(): void; cleanup(): void;
/** /**
* Removes all instances of specified component * Removes all instances of specified component
*/ */
// purge<T>(component: Id<T>): void // purge<T>(component: Id<T>): void
/** /**
* Clears all components and relationships from the given entity, but * Clears all components and relationships from the given entity, but
* does not delete the entity from the world. * does not delete the entity from the world.
* @param entity The entity to clear. * @param entity The entity to clear.
*/ */
clear(entity: Entity): void; clear(entity: Entity): void;
/** /**
* Removes a component from the given entity. * Removes a component from the given entity.
* @param entity The target entity. * @param entity The target entity.
* @param component The component to remove. * @param component The component to remove.
*/ */
remove(entity: Entity, component: Id): void; remove(entity: Entity, component: Id): void;
/** /**
* Retrieves the values of up to 4 components on a given entity. Missing * Retrieves the values of up to 4 components on a given entity. Missing
* components will return `undefined`. * components will return `undefined`.
* @param entity The entity to query. * @param entity The entity to query.
* @param components Up to 4 components/tags to retrieve. * @param components Up to 4 components/tags to retrieve.
* @returns A tuple of data (or a single value), each possibly undefined. * @returns A tuple of data (or a single value), each possibly undefined.
*/ */
get<T extends [Id] | [Id, Id] | [Id, Id, Id] | [Id, Id, Id, Id]>( get<T extends [Id] | [Id, Id] | [Id, Id, Id] | [Id, Id, Id, Id]>(
entity: Entity, entity: Entity,
...components: T ...components: T
): FlattenTuple<Nullable<InferComponents<T>>>; ): FlattenTuple<Nullable<InferComponents<T>>>;
/** /**
* Returns `true` if the given entity has all of the specified components. * Returns `true` if the given entity has all of the specified components.
* A maximum of 4 components can be checked at once. * A maximum of 4 components can be checked at once.
* @param entity The entity to check. * @param entity The entity to check.
* @param components Upto 4 components to check for. * @param components Upto 4 components to check for.
*/ */
has(entity: Entity, ...components: Id[]): boolean; has(entity: Entity, ...components: Id[]): boolean;
/** /**
* Gets the parent (the target of a `ChildOf` relationship) for an entity, * Gets the parent (the target of a `ChildOf` relationship) for an entity,
* if such a relationship exists. * if such a relationship exists.
* @param entity The entity whose parent is queried. * @param entity The entity whose parent is queried.
*/ */
parent(entity: Entity): Entity | undefined; parent(entity: Entity): Entity | undefined;
/** /**
* Checks if an entity exists in the world. * Checks if an entity exists in the world.
* @param entity The entity to verify. * @param entity The entity to verify.
*/ */
contains(entity: Entity): boolean; contains(entity: Entity): boolean;
/** /**
* Checks if an entity exists in the world. * Checks if an entity exists in the world.
* @param entity The entity to verify. * @param entity The entity to verify.
*/ */
contains(entity: number): entity is Entity; contains(entity: number): entity is Entity;
/** /**
* Checks if an entity with the given ID is currently alive, ignoring its generation. * Checks if an entity with the given ID is currently alive, ignoring its generation.
* @param entity The entity to verify. * @param entity The entity to verify.
* @returns boolean true if any entity with the given ID exists (ignoring generation), false otherwise * @returns boolean true if any entity with the given ID exists (ignoring generation), false otherwise
*/ */
exists(entity: Entity): boolean; exists(entity: Entity): boolean;
/** /**
* Returns an iterator that yields all entities that have the specified component or relationship. * Returns an iterator that yields all entities that have the specified component or relationship.
* @param id The component or relationship ID to search for * @param id The component or relationship ID to search for
* @returns An iterator function that yields entities * @returns An iterator function that yields entities
*/ */
each(id: Id): IterableFunction<Entity>; each(id: Id): IterableFunction<Entity>;
/** /**
* Returns an iterator that yields all child entities of the specified parent entity. * Returns an iterator that yields all child entities of the specified parent entity.
* Uses the ChildOf relationship internally. * Uses the ChildOf relationship internally.
* @param parent The parent entity to get children for * @param parent The parent entity to get children for
* @returns An iterator function that yields child entities * @returns An iterator function that yields child entities
*/ */
children(parent: Entity): IterableFunction<Entity>; children(parent: Entity): IterableFunction<Entity>;
/** /**
* Searches the world for entities that match specified components. * Searches the world for entities that match specified components.
* @param components The list of components to query. * @param components The list of components to query.
* @returns A Query object to iterate over results. * @returns A Query object to iterate over results.
*/ */
query<T extends Id[]>(...components: T): Query<T>; query<T extends Id[]>(...components: T): Query<T>;
added<T>(component: Entity<T>, listener: (e: Entity, id: Id<T>, value: T) => void): () => void; added<T>(component: Entity<T>, listener: (e: Entity, id: Id<T>, value: T) => void): () => void;
changed<T>(component: Entity<T>, listener: (e: Entity, id: Id<T>, value: T) => void): () => void; changed<T>(
removed<T>(component: Entity<T>, listener: (e: Entity, id: Id<T>) => void): () => void; component: Entity<T>,
listener: (e: Entity, id: Id<T>, value: T) => void,
): () => void;
removed<T>(component: Entity<T>, listener: (e: Entity, id: Id<T>) => void): () => void;
} }
export function world(): World; export function world(): World;
@ -320,10 +352,10 @@ export function ECS_PAIR_FIRST(pair: Pair): number;
export function ECS_PAIR_SECOND(pair: Pair): number; export function ECS_PAIR_SECOND(pair: Pair): number;
type StatefulHook = Entity<<T>(e: Entity<T>, id: Id<T>, data: T) => void> & { type StatefulHook = Entity<<T>(e: Entity<T>, id: Id<T>, data: T) => void> & {
readonly __nominal_StatefulHook: unique symbol; readonly __nominal_StatefulHook: unique symbol;
}; };
type StatelessHook = Entity<<T>(e: Entity<T>, id: Id<T>) => void> & { type StatelessHook = Entity<<T>(e: Entity<T>, id: Id<T>) => void> & {
readonly __nominal_StatelessHook: unique symbol; readonly __nominal_StatelessHook: unique symbol;
}; };
export declare const OnAdd: StatefulHook; export declare const OnAdd: StatefulHook;
@ -342,34 +374,34 @@ export declare const Exclusive: Tag;
export declare const Rest: Entity; export declare const Rest: Entity;
export type ComponentRecord = { export type ComponentRecord = {
records: Map<Id, number>; records: Map<Id, number>;
counts: Map<Id, number>; counts: Map<Id, number>;
size: number; size: number;
}; };
export function component_record(world: World, id: Id): ComponentRecord; export function component_record(world: World, id: Id): ComponentRecord;
type TagToUndefined<T> = T extends TagDiscriminator ? undefined : T type TagToUndefined<T> = T extends TagDiscriminator ? undefined : T;
type TrimOptional<T extends unknown[]> = T extends [...infer L, infer R] type TrimOptional<T extends unknown[]> = T extends [...infer L, infer R]
? unknown extends R ? unknown extends R
? L | T | TrimOptional<L> ? L | T | TrimOptional<L>
: R extends undefined : R extends undefined
? L | T | TrimOptional<L> ? L | T | TrimOptional<L>
: T : T
: T : T;
export function bulk_insert<const C extends Id[]>( export function bulk_insert<const C extends Id[]>(
world: World, world: World,
entity: Entity, entity: Entity,
ids: C, ids: C,
values: TrimOptional<{ [K in keyof C]: TagToUndefined<InferComponent<C[K]>> }>, values: TrimOptional<{ [K in keyof C]: TagToUndefined<InferComponent<C[K]>> }>,
): void; ): void;
export function bulk_remove(world: World, entity: Entity, ids: Id[]): void; export function bulk_remove(world: World, entity: Entity, ids: Id[]): void;
export type EntityRecord<T extends Id[]> = { export type EntityRecord<T extends Id[]> = {
archetype: Archetype<T>, archetype: Archetype<T>;
row: number, row: number;
dense: number, dense: number;
}; };
export function record<T extends Id[] = []>(world: World, entity: Entity): EntityRecord<T>; export function record<T extends Id[] = []>(world: World, entity: Entity): EntityRecord<T>;