ecsjs
Version:
An entity component system library for JavaScript
216 lines • 8.34 kB
TypeScript
import { ComponentClassesMap, ComponentMap } from './component-map.js';
import { ComponentIterator } from './iterators.js';
import { type Component, type ComponentClass, type ComponentInstances } from './types.js';
/**
* Class for storing entities and their relationships
* @category Maps
*/
export declare class EntityMap {
/**
* Registered component classes that contain the component instance data
*/
components: ComponentClassesMap;
private nextId;
/**
* Registers component classes with the {@link EntityMap}
* @throwsError {@link ComponentTypeKeyMissing} when the specified component type is missing a 'name' parameter
* @example
* // component class
* class MyComponent {
* constructor(x) {
* this.x = x;
* }
* }
*
* ecs.register(MyComponent);
* // or mulitple
* ecs.register(MyComponent1, MyComponent2);
*/
register<TComponentClasses extends ComponentClass<any>[]>(...componentClasses: TComponentClasses): this;
/**
* Gets a component class map
* @throwsError {@link ComponentNotRegistered} when the specified component is not registered
* @example
* const positionMap = ecs.getMap(Position)
* for(const [entityId, position] of positionMap) {
* position.x += 1
* }
*/
getMap<T>(component: ComponentClass<T>): ComponentMap<T> | undefined;
/**
* Gets the first entity entry for a component class
* @throwsError {@link ComponentNotRegistered} when the specified component is not registered
* @example
* // return the first entry
* const [entityId, player] = ecs.firstEntry(Player) ?? []
*
* // or return multiple related components in addition to the first entry
* const [entityId, player, position, direction] = ecs.firstEntry(
* Player,
* Position,
* Direction
* )
*/
firstEntry<TKey extends ComponentClass<any>, T extends ComponentClass<any>[]>(keyComponent: TKey, ...components: T): ComponentInstances<[ComponentClass<number>, TKey, ...T]> | undefined;
/**
* Gets the first entity id for a component class
* and optionally any related component data
* @throwsError {@link ComponentNotRegistered} when any of specified component(s) are not registered
* @example
* // return the first entity id
* const entityId = ecs.firstKey(Player)
*
* // or return multiple related component in addition to entity id
* const [entityId, position, direction] = ecs.firstKey(
* Player,
* Position,
* Direction
* ) ?? []
*/
firstKey<TKey extends ComponentClass<any>, T extends ComponentClass<any>[]>(keyComponent: TKey, ...components: T): ComponentInstances<[ComponentClass<number>, ...T]> | undefined;
/**
* Gets the first entity component data for a component class
* and optionally any related component data
* @throwsError {@link ComponentNotRegistered} when any of specified component(s) are not registered
* @example
* // return the first component value
* const player = ecs.firstValue(Player)
*
* // or multiple related values in addition to the first component
* const [player, position, direction] = ecs.firstValue(
* Player,
* Position,
* Direction
* )
*/
firstValue<TKey extends ComponentClass<any>, T extends ComponentClass<any>[]>(keyComponent: TKey, ...components: T): ComponentInstances<[TKey, ...T]> | undefined;
/**
* @throwsError {@link ComponentNotRegistered} when the specified component is not registered
*/
private getEntity;
/**
* Gets component values related to an entity id
* @throwsError {@link ComponentNotRegistered} when any of specified component(s) are not registered
* @example
* // get one
* const player = ecs.get(entityId, Player)
*
* // or get multiple
* const [player, position] = ecs.get(entityId, Player, Position) ?? []
*/
get<T extends ComponentClass<any>[]>(entityId: number, ...components: T): ComponentInstances<T> | undefined;
/**
* Check if a component exists for an entity
* @example
* const exists = ecs.has(entityId, Position)
*/
has<T>(entityId: number, component: ComponentClass<T>): boolean;
/**
* Checks if all of the specified components exist for an entity
* @example
* const hasAll = ecs.hasAll(entityId, Position, Velocity)
*/
hasAll<T extends ComponentClass<any>[]>(entityId: number, ...components: T): boolean;
/**
* Checks if any of the specified components exist for an entity
* @example
* const hasAny = ecs.hasAny(entityId, Position, Velocity)
*/
hasAny<T extends ComponentClass<any>[]>(entityId: number, ...components: T): boolean;
private setEntity;
/**
* Add or update multiple component values for an entity
* @example
* // set one
* const player = ecs.set(entityId, new Player());
*
* // or set multiple
* const [player, position] = ecs.set(
* entityId,
* new Player(),
* new Position()
* );
*/
set<T extends Component>(entityId: number, component: T): T;
set<T extends Component[]>(entityId: number, ...components: T): T;
/**
* Removes the specified component(s) from an entity
* @example
* ecs.remove(entityId, Position);
*/
remove<T extends ComponentClass<any>[]>(entityId: number, ...components: T): void;
/**
* Removes the specified component from an entity
* @throwsError {@link ComponentNotRegistered} when the specified component is not registered
* @example
* ecs.removeByKey(entityId, "Position");
*/
removeByKey(entityId: number, componentName: string): boolean;
/**
* Deletes all components from an entity
* @example
* const destroyedCount = ecs.destroyEntity(entityId1)
*
* // or multiple
* const destroyedCount = ecs.destroyEntity(entityId1, entityId2)
*/
destroyEntity(...entityIds: number[]): number;
/**
* Creates a new entity id for the EntityMap
* @example
* const newEntityId = ecs.getNextId()
* ecs.set(newEntityId, new Player())
*/
getNextId(): number;
/**
* Clears all registered components
*/
clear(): this;
/**
* Clears all component data
*/
clearComponents(): this;
/**
* Iterates over each component value that is related to the key component
* @throwsError {@link ComponentNotRegistered} when any of specified component(s) are not registered
* @example
* // iterate each component value that is related to the Player entity
* const iterator = ecs.iterator(Player, Position)
*
* for(const [playerId, player, position] of iterator) { }
*
* // you can also declare the type of iterator before it's assigned
* let iterator: IComponentIterator<[Player, Position]>
*
* // then with late bound assignment (keeping the iterator intellisense)
* iterator = ecs.iterator(Player, Position)
*
* for(const [playerId, player, position] of iterator) {
* const moving = player.isMoving
* }
*/
iterator<K extends ComponentClass<any>, T extends ComponentClass<any>[]>(keyComponent: K, ...components: T): ComponentIterator<K, T>;
/**
* Prints all component maps in a tabular format to the console
*/
printTable(): this;
/**
* Prints all component data for the specified entity id in a tabular format to the console
*/
printEntity(entityId: number): this;
/**
* Parse's the JSON and returns an EntityMap object
* @example
* const json = JSON.stringfy(ecs);
* const restoredMap = ecs.parse(json);
*/
static parse(json: string): EntityMap;
/**
* A tracing method used for debugging.
* Intercepts all functions specified and logs each call to the console.
* @param {Array} funcFilter A list of function names you want to intercept. If no function names are specified then will log all functions called
* @return {EntityMap} A new entity map with tracing enabled
*/
static createWithTracing(funcFilter: any): any;
}
//# sourceMappingURL=entity-map.d.ts.map