@codehz/ecs 0.6.5 → 0.6.6

package/builder.d.mts

@@ -436,21 +436,182 @@ declare class World {
   constructor(snapshot?: SerializedWorld);
   private deserializeSnapshot;
   private createArchetypeSignature;
+  /**
+   * Creates a new entity.
+   * The entity is created with an empty component set and can be configured using `set()`.
+   *
+   * @template T - The initial component type (defaults to void if not specified)
+   * @returns A unique identifier for the new entity
+   *
+   * @example
+   * const entity = world.new<MyComponent>();
+   * world.set(entity, MyComponent, { value: 42 });
+   * world.sync();
+   */
   new<T = void>(): EntityId<T>;
   private destroyEntityImmediate;
+  /**
+   * Checks if an entity exists in the world.
+   *
+   * @param entityId - The entity identifier to check
+   * @returns `true` if the entity exists, `false` otherwise
+   *
+   * @example
+   * if (world.exists(entityId)) {
+   *   console.log("Entity exists");
+   * }
+   */
   exists(entityId: EntityId): boolean;
+  /**
+   * Adds or updates a component on an entity (or marks void component as present).
+   * The change is buffered and takes effect after calling `world.sync()`.
+   * If the entity does not exist, throws an error.
+   *
+   * @overload set(entityId: EntityId, componentType: EntityId<void>): void
+   * Marks a void component as present on the entity
+   *
+   * @overload set<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void
+   * Adds or updates a component with data on the entity
+   *
+   * @throws {Error} If the entity does not exist
+   * @throws {Error} If the component type is invalid or is a wildcard relation
+   *
+   * @example
+   * world.set(entity, Position, { x: 10, y: 20 });
+   * world.set(entity, Marker); // void component
+   * world.sync(); // Apply changes
+   */
   set(entityId: EntityId, componentType: EntityId<void>): void;
   set<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void;
+  /**
+   * Removes a component from an entity.
+   * The change is buffered and takes effect after calling `world.sync()`.
+   * If the entity does not exist, throws an error.
+   *
+   * @template T - The component data type
+   * @param entityId - The entity identifier
+   * @param componentType - The component type to remove
+   *
+   * @throws {Error} If the entity does not exist
+   * @throws {Error} If the component type is invalid
+   *
+   * @example
+   * world.remove(entity, Position);
+   * world.sync(); // Apply changes
+   */
   remove<T>(entityId: EntityId, componentType: EntityId<T>): void;
+  /**
+   * Deletes an entity and all its components from the world.
+   * The change is buffered and takes effect after calling `world.sync()`.
+   * Related entities may trigger cascade delete hooks if configured.
+   *
+   * @param entityId - The entity identifier to delete
+   *
+   * @example
+   * world.delete(entity);
+   * world.sync(); // Apply changes
+   */
   delete(entityId: EntityId): void;
+  /**
+   * Checks if an entity has a specific component.
+   * Immediately reflects the current state without waiting for `sync()`.
+   *
+   * @template T - The component data type
+   * @param entityId - The entity identifier
+   * @param componentType - The component type to check
+   * @returns `true` if the entity has the component, `false` otherwise
+   *
+   * @example
+   * if (world.has(entity, Position)) {
+   *   const pos = world.get(entity, Position);
+   * }
+   */
   has<T>(entityId: EntityId, componentType: EntityId<T>): boolean;
+  /**
+   * Retrieves a component from an entity.
+   * For wildcard relations, returns all relations of that type.
+   * Throws an error if the component does not exist; use `has()` to check first or use `getOptional()`.
+   *
+   * @overload get<T>(entityId: EntityId<T>): T
+   * When called with only an entity ID, retrieves the entity's primary component.
+   *
+   * @overload get<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, T][]
+   * For wildcard relations, returns an array of [target entity, component value] pairs.
+   *
+   * @overload get<T>(entityId: EntityId, componentType: EntityId<T>): T
+   * Retrieves a specific component from the entity.
+   *
+   * @throws {Error} If the entity does not exist
+   * @throws {Error} If the component does not exist on the entity
+   *
+   * @example
+   * const position = world.get(entity, Position); // Throws if no Position
+   * const relations = world.get(entity, relation(Parent, "*")); // Wildcard relation
+   */
+  get<T>(entityId: EntityId<T>): T;
   get<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, T][];
   get<T>(entityId: EntityId, componentType: EntityId<T>): T;
+  /**
+   * Safely retrieves a component from an entity without throwing an error.
+   * Returns `undefined` if the component does not exist.
+   * For wildcard relations, returns `undefined` if there are no relations.
+   *
+   * @template T - The component data type
+   * @overload getOptional<T>(entityId: EntityId<T>): { value: T } | undefined
+   * Retrieves the entity's primary component safely.
+   *
+   * @overload getOptional<T>(entityId: EntityId, componentType: EntityId<T>): { value: T } | undefined
+   * Retrieves a specific component safely.
+   *
+   * @throws {Error} If the entity does not exist
+   *
+   * @example
+   * const position = world.getOptional(entity, Position);
+   * if (position) {
+   *   console.log(position.value.x);
+   * }
+   */
+  getOptional<T>(entityId: EntityId<T>): {
+    value: T;
+  } | undefined;
   getOptional<T>(entityId: EntityId, componentType: EntityId<T>): {
     value: T;
   } | undefined;
   /**
-   * @deprecated use array overload with LifecycleCallback
+   * Registers a lifecycle hook that responds to component changes.
+   * The hook callback is invoked when components matching the specified types are added, updated, or removed.
+   *
+   * @deprecated For single components, use the array overload with LifecycleCallback for better multi-component support
+   *
+   * @overload hook<T>(componentType: EntityId<T>, hook: LegacyLifecycleHook<T> | LegacyLifecycleCallback<T>): () => void
+   * Registers a hook for a single component type (legacy API).
+   *
+   * @overload hook<const T extends readonly ComponentType<any>[]>(
+   *   componentTypes: T,
+   *   hook: LifecycleHook<T> | LifecycleCallback<T>,
+   * ): () => void
+   * Registers a hook for multiple component types.
+   * The hook is triggered when all required components change together.
+   *
+   * @param componentTypesOrSingle - A single component type or an array of component types
+   * @param hook - Either a hook object with on_init/on_set/on_remove handlers, or a callback function
+   * @returns A function that unsubscribes the hook when called
+   *
+   * @throws {Error} If no required components are specified in array overload
+   *
+   * @example
+   * // Array overload (recommended)
+   * const unsubscribe = world.hook([Position, Velocity], {
+   *   on_init: (entityId, position, velocity) => console.log("Initialized"),
+   *   on_set: (entityId, position, velocity) => console.log("Updated"),
+   *   on_remove: (entityId, position, velocity) => console.log("Removed"),
+   * });
+   * unsubscribe(); // Remove hook
+   *
+   * // Callback style
+   * const unsubscribe = world.hook([Position], (event, entityId, position) => {
+   *   if (event === "init") console.log("Initialized");
+   * });
    */
   hook<T>(componentType: EntityId<T>, hook: LegacyLifecycleHook<T> | LegacyLifecycleCallback<T>): () => void;
   hook<const T extends readonly ComponentType<any>[]>(componentTypes: T, hook: LifecycleHook<T> | LifecycleCallback<T>): () => void;
@@ -458,15 +619,128 @@ declare class World {
   unhook<T>(componentType: EntityId<T>, hook: LegacyLifecycleHook<T>): void;
   /** @deprecated use the unsubscribe function returned by hook() instead */
   unhook<const T extends readonly ComponentType<any>[]>(componentTypes: T, hook: LifecycleHook<T>): void;
+  /**
+   * Synchronizes all buffered commands (set/remove/delete) to the world.
+   * This method must be called after making changes via `set()`, `remove()`, or `delete()` for them to take effect.
+   * Typically called once per frame at the end of your game loop.
+   *
+   * @example
+   * world.set(entity, Position, { x: 10, y: 20 });
+   * world.remove(entity, OldComponent);
+   * world.sync(); // Apply all buffered changes
+   */
   sync(): void;
+  /**
+   * Creates a cached query for efficiently iterating entities with specific components.
+   * The query is cached internally and reused across calls with the same component types and filter.
+   *
+   * **Important:** Store the query reference and reuse it across frames for optimal performance.
+   * Creating a new query each frame defeats the caching mechanism.
+   *
+   * @param componentTypes - Array of component types to match
+   * @param filter - Optional filter for additional constraints (e.g., without specific components)
+   * @returns A Query instance that can be used to iterate matching entities
+   *
+   * @example
+   * // Create once, reuse many times
+   * const movementQuery = world.createQuery([Position, Velocity]);
+   *
+   * // In game loop
+   * movementQuery.forEach((entity) => {
+   *   const pos = world.get(entity, Position);
+   *   const vel = world.get(entity, Velocity);
+   *   pos.x += vel.x;
+   *   pos.y += vel.y;
+   * });
+   *
+   * // With filter
+   * const activeQuery = world.createQuery([Position], {
+   *   without: [Disabled]
+   * });
+   */
   createQuery(componentTypes: EntityId<any>[], filter?: QueryFilter): Query;
+  /**
+   * Creates a new entity builder for fluent entity configuration.
+   * Useful for building entities with multiple components in a single expression.
+   *
+   * @returns An EntityBuilder instance
+   *
+   * @example
+   * const entity = world.spawn()
+   *   .with(Position, { x: 0, y: 0 })
+   *   .with(Velocity, { x: 1, y: 1 })
+   *   .build();
+   * world.sync(); // Apply changes
+   */
   spawn(): EntityBuilder;
+  /**
+   * Spawns multiple entities with a configuration callback.
+   * More efficient than calling `spawn()` multiple times when creating many entities.
+   *
+   * @param count - Number of entities to spawn
+   * @param configure - Callback that receives an EntityBuilder and index; must return the configured builder
+   * @returns Array of created entity IDs
+   *
+   * @example
+   * const entities = world.spawnMany(100, (builder, index) => {
+   *   return builder
+   *     .with(Position, { x: index * 10, y: 0 })
+   *     .with(Velocity, { x: 0, y: 1 });
+   * });
+   * world.sync();
+   */
   spawnMany(count: number, configure: (builder: EntityBuilder, index: number) => EntityBuilder): EntityId[];
   _registerQuery(query: Query): void;
   _unregisterQuery(query: Query): void;
+  /**
+   * Releases a cached query and frees its resources if no longer needed.
+   * Call this when you're done using a query to allow the world to clean up its cache entry.
+   *
+   * @param query - The query to release
+   *
+   * @example
+   * const query = world.createQuery([Position]);
+   * // ... use query ...
+   * world.releaseQuery(query); // Optional cleanup
+   */
   releaseQuery(query: Query): void;
+  /**
+   * Returns all archetypes that contain entities with the specified components.
+   * Used internally for query optimization but can be useful for debugging.
+   *
+   * @param componentTypes - Array of component types to match
+   * @returns Array of Archetype objects containing matching components
+   * @internal
+   */
   getMatchingArchetypes(componentTypes: EntityId<any>[]): Archetype[];
   private getArchetypesWithComponents;
+  /**
+   * Queries entities with specific components.
+   * For simpler use cases, prefer using `createQuery()` with `forEach()` which is cached and more efficient.
+   *
+   * @overload query(componentTypes: EntityId<any>[]): EntityId[]
+   * Returns an array of entity IDs that have all specified components.
+   *
+   * @overload query<const T extends readonly EntityId<any>[]>(
+   *   componentTypes: T,
+   *   includeComponents: true,
+   * ): Array<{ entity: EntityId; components: ComponentTuple<T> }>
+   * Returns entities along with their component data.
+   *
+   * @param componentTypes - Array of component types to query
+   * @param includeComponents - If true, includes component data in results
+   * @returns Array of entity IDs or objects with entities and components
+   *
+   * @example
+   * // Just entity IDs
+   * const entities = world.query([Position, Velocity]);
+   *
+   * // With components
+   * const results = world.query([Position, Velocity], true);
+   * results.forEach(({ entity, components: [pos, vel] }) => {
+   *   pos.x += vel.x;
+   * });
+   */
   query(componentTypes: EntityId<any>[]): EntityId[];
   query<const T extends readonly EntityId<any>[]>(componentTypes: T, includeComponents: true): Array<{
     entity: EntityId;
@@ -483,6 +757,27 @@ declare class World {
   private archetypeReferencesEntity;
   private cleanupArchetypesReferencingEntity;
   private removeArchetype;
+  /**
+   * Serializes the entire world state to a plain JavaScript object.
+   * This creates a "memory snapshot" that can be stored or transmitted.
+   * The snapshot can be restored using `new World(snapshot)`.
+   *
+   * **Note:** This is NOT automatically persistent storage. To persist data,
+   * you must serialize the returned object to JSON or another format yourself.
+   *
+   * @returns A serializable object representing the world state
+   *
+   * @example
+   * // Create snapshot
+   * const snapshot = world.serialize();
+   *
+   * // Save to storage (example)
+   * localStorage.setItem('save', JSON.stringify(snapshot));
+   *
+   * // Later, restore from snapshot
+   * const savedData = JSON.parse(localStorage.getItem('save'));
+   * const newWorld = new World(savedData);
+   */
   serialize(): SerializedWorld;
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "repository": {
     "url": "https://github.com/codehz/ecs"
   },

package/world.mjs

@@ -1799,6 +1799,18 @@ var World = class {
 	createArchetypeSignature(componentTypes) {
 		return componentTypes.join(",");
 	}
+	/**
+	* Creates a new entity.
+	* The entity is created with an empty component set and can be configured using `set()`.
+	*
+	* @template T - The initial component type (defaults to void if not specified)
+	* @returns A unique identifier for the new entity
+	*
+	* @example
+	* const entity = world.new<MyComponent>();
+	* world.set(entity, MyComponent, { value: 42 });
+	* world.sync();
+	*/
 	new() {
 		const entityId = this.entityIdManager.allocate();
 		let emptyArchetype = this.ensureArchetype([]);
@@ -1829,6 +1841,17 @@ var World = class {
 			this.entityIdManager.deallocate(cur);
 		}
 	}
+	/**
+	* Checks if an entity exists in the world.
+	*
+	* @param entityId - The entity identifier to check
+	* @returns `true` if the entity exists, `false` otherwise
+	*
+	* @example
+	* if (world.exists(entityId)) {
+	*   console.log("Entity exists");
+	* }
+	*/
 	exists(entityId) {
 		return this.entityToArchetype.has(entityId);
 	}
@@ -1839,14 +1862,55 @@ var World = class {
 		if (detailedType.type === "wildcard-relation") throw new Error(`Cannot directly add wildcard relation components: ${componentType}`);
 		this.commandBuffer.set(entityId, componentType, component$1);
 	}
+	/**
+	* Removes a component from an entity.
+	* The change is buffered and takes effect after calling `world.sync()`.
+	* If the entity does not exist, throws an error.
+	*
+	* @template T - The component data type
+	* @param entityId - The entity identifier
+	* @param componentType - The component type to remove
+	*
+	* @throws {Error} If the entity does not exist
+	* @throws {Error} If the component type is invalid
+	*
+	* @example
+	* world.remove(entity, Position);
+	* world.sync(); // Apply changes
+	*/
 	remove(entityId, componentType) {
 		if (!this.exists(entityId)) throw new Error(`Entity ${entityId} does not exist`);
 		if (getDetailedIdType(componentType).type === "invalid") throw new Error(`Invalid component type: ${componentType}`);
 		this.commandBuffer.remove(entityId, componentType);
 	}
+	/**
+	* Deletes an entity and all its components from the world.
+	* The change is buffered and takes effect after calling `world.sync()`.
+	* Related entities may trigger cascade delete hooks if configured.
+	*
+	* @param entityId - The entity identifier to delete
+	*
+	* @example
+	* world.delete(entity);
+	* world.sync(); // Apply changes
+	*/
 	delete(entityId) {
 		this.commandBuffer.delete(entityId);
 	}
+	/**
+	* Checks if an entity has a specific component.
+	* Immediately reflects the current state without waiting for `sync()`.
+	*
+	* @template T - The component data type
+	* @param entityId - The entity identifier
+	* @param componentType - The component type to check
+	* @returns `true` if the entity has the component, `false` otherwise
+	*
+	* @example
+	* if (world.has(entity, Position)) {
+	*   const pos = world.get(entity, Position);
+	* }
+	*/
 	has(entityId, componentType) {
 		const archetype = this.entityToArchetype.get(entityId);
 		if (!archetype) return false;
@@ -1854,7 +1918,7 @@ var World = class {
 		if (isDontFragmentRelation(componentType)) return this.dontFragmentRelations.get(entityId)?.has(componentType) ?? false;
 		return false;
 	}
-	get(entityId, componentType) {
+	get(entityId, componentType = entityId) {
 		const archetype = this.entityToArchetype.get(entityId);
 		if (!archetype) throw new Error(`Entity ${entityId} does not exist`);
 		if (componentType >= 0 || componentType % 2 ** 42 !== 0) {
@@ -1864,7 +1928,7 @@ var World = class {
 		}
 		return archetype.get(entityId, componentType);
 	}
-	getOptional(entityId, componentType) {
+	getOptional(entityId, componentType = entityId) {
 		const archetype = this.entityToArchetype.get(entityId);
 		if (!archetype) throw new Error(`Entity ${entityId} does not exist`);
 		if (isWildcardRelationId(componentType)) {
@@ -1957,9 +2021,47 @@ var World = class {
 			}
 		}
 	}
+	/**
+	* Synchronizes all buffered commands (set/remove/delete) to the world.
+	* This method must be called after making changes via `set()`, `remove()`, or `delete()` for them to take effect.
+	* Typically called once per frame at the end of your game loop.
+	*
+	* @example
+	* world.set(entity, Position, { x: 10, y: 20 });
+	* world.remove(entity, OldComponent);
+	* world.sync(); // Apply all buffered changes
+	*/
 	sync() {
 		this.commandBuffer.execute();
 	}
+	/**
+	* Creates a cached query for efficiently iterating entities with specific components.
+	* The query is cached internally and reused across calls with the same component types and filter.
+	*
+	* **Important:** Store the query reference and reuse it across frames for optimal performance.
+	* Creating a new query each frame defeats the caching mechanism.
+	*
+	* @param componentTypes - Array of component types to match
+	* @param filter - Optional filter for additional constraints (e.g., without specific components)
+	* @returns A Query instance that can be used to iterate matching entities
+	*
+	* @example
+	* // Create once, reuse many times
+	* const movementQuery = world.createQuery([Position, Velocity]);
+	*
+	* // In game loop
+	* movementQuery.forEach((entity) => {
+	*   const pos = world.get(entity, Position);
+	*   const vel = world.get(entity, Velocity);
+	*   pos.x += vel.x;
+	*   pos.y += vel.y;
+	* });
+	*
+	* // With filter
+	* const activeQuery = world.createQuery([Position], {
+	*   without: [Disabled]
+	* });
+	*/
 	createQuery(componentTypes, filter = {}) {
 		const sortedTypes = [...componentTypes].sort((a, b) => a - b);
 		const filterKey = serializeQueryFilter(filter);
@@ -1976,9 +2078,38 @@ var World = class {
 		});
 		return query;
 	}
+	/**
+	* Creates a new entity builder for fluent entity configuration.
+	* Useful for building entities with multiple components in a single expression.
+	*
+	* @returns An EntityBuilder instance
+	*
+	* @example
+	* const entity = world.spawn()
+	*   .with(Position, { x: 0, y: 0 })
+	*   .with(Velocity, { x: 1, y: 1 })
+	*   .build();
+	* world.sync(); // Apply changes
+	*/
 	spawn() {
 		return new EntityBuilder(this);
 	}
+	/**
+	* Spawns multiple entities with a configuration callback.
+	* More efficient than calling `spawn()` multiple times when creating many entities.
+	*
+	* @param count - Number of entities to spawn
+	* @param configure - Callback that receives an EntityBuilder and index; must return the configured builder
+	* @returns Array of created entity IDs
+	*
+	* @example
+	* const entities = world.spawnMany(100, (builder, index) => {
+	*   return builder
+	*     .with(Position, { x: index * 10, y: 0 })
+	*     .with(Velocity, { x: 0, y: 1 });
+	* });
+	* world.sync();
+	*/
 	spawnMany(count, configure) {
 		const entities = [];
 		for (let i = 0; i < count; i++) {
@@ -1994,6 +2125,17 @@ var World = class {
 		const index = this.queries.indexOf(query);
 		if (index !== -1) this.queries.splice(index, 1);
 	}
+	/**
+	* Releases a cached query and frees its resources if no longer needed.
+	* Call this when you're done using a query to allow the world to clean up its cache entry.
+	*
+	* @param query - The query to release
+	*
+	* @example
+	* const query = world.createQuery([Position]);
+	* // ... use query ...
+	* world.releaseQuery(query); // Optional cleanup
+	*/
 	releaseQuery(query) {
 		for (const [k, v] of this.queryCache.entries()) if (v.query === query) {
 			v.refCount--;
@@ -2005,6 +2147,14 @@ var World = class {
 			return;
 		}
 	}
+	/**
+	* Returns all archetypes that contain entities with the specified components.
+	* Used internally for query optimization but can be useful for debugging.
+	*
+	* @param componentTypes - Array of component types to match
+	* @returns Array of Archetype objects containing matching components
+	* @internal
+	*/
 	getMatchingArchetypes(componentTypes) {
 		if (componentTypes.length === 0) return [...this.archetypes];
 		const regularComponents = [];
@@ -2148,6 +2298,27 @@ var World = class {
 		}
 		for (const query of this.queries) query.removeArchetype(archetype);
 	}
+	/**
+	* Serializes the entire world state to a plain JavaScript object.
+	* This creates a "memory snapshot" that can be stored or transmitted.
+	* The snapshot can be restored using `new World(snapshot)`.
+	*
+	* **Note:** This is NOT automatically persistent storage. To persist data,
+	* you must serialize the returned object to JSON or another format yourself.
+	*
+	* @returns A serializable object representing the world state
+	*
+	* @example
+	* // Create snapshot
+	* const snapshot = world.serialize();
+	*
+	* // Save to storage (example)
+	* localStorage.setItem('save', JSON.stringify(snapshot));
+	*
+	* // Later, restore from snapshot
+	* const savedData = JSON.parse(localStorage.getItem('save'));
+	* const newWorld = new World(savedData);
+	*/
 	serialize() {
 		const entities = [];
 		for (const archetype of this.archetypes) {