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