@codehz/ecs 0.7.0 → 0.7.2

package/README.en.md

@@ -204,8 +204,10 @@ world.sync();
 ### Running Examples
 
 ```bash
-bun run examples/simple/demo.ts
-bun run examples/advanced-scheduling/demo.ts
+bun run examples/simple.ts
+bun run examples/advanced-scheduling.ts
+bun run examples/parent-child-hierarchy.ts
+bun run examples/inventory-system-relations.ts
 ```
 
 ## API Overview
@@ -410,11 +412,14 @@ src/
 └── __tests__/               # Unit tests & performance tests
 
 examples/
-├── simple/
-│   ├── demo.ts              # Basic example
-│   └── README.md            # Example documentation
-└── advanced-scheduling/
-    └── demo.ts              # Pipeline scheduling example
+├── advanced-scheduling.ts    # Pipeline scheduling example
+├── collision-detection.ts    # Collision detection example
+├── parent-child-hierarchy.ts # Parent-child hierarchy and transform propagation example
+├── serialization.ts          # Serialization example
+├── simple.ts                 # Basic example
+├── spatial-grid.ts           # Spatial grid example
+├── state-machine.ts          # State machine example
+└── tag-filtering.ts          # Tag filtering example
 
 scripts/
 ├── build.ts                 # Build script
@@ -427,7 +432,8 @@ scripts/
 bun install
 bun test                    # Run tests
 bunx tsc --noEmit           # Type check
-bun run examples/simple/demo.ts  # Run example
+bun run examples/simple.ts       # Run example
+bun run examples/parent-child-hierarchy.ts
 bun run scripts/build.ts    # Build
 ```
 

package/README.md

@@ -204,8 +204,10 @@ world.sync();
 ### 运行示例
 
 ```bash
-bun run examples/simple/demo.ts
-bun run examples/advanced-scheduling/demo.ts
+bun run examples/simple.ts
+bun run examples/advanced-scheduling.ts
+bun run examples/parent-child-hierarchy.ts
+bun run examples/inventory-system-relations.ts
 ```
 
 ## API 概述
@@ -410,11 +412,14 @@ src/
 └── __tests__/               # 单元测试 & 性能测试
 
 examples/
-├── simple/
-│   ├── demo.ts              # 基本示例
-│   └── README.md            # 示例说明
-└── advanced-scheduling/
-    └── demo.ts              # Pipeline 调度示例
+├── advanced-scheduling.ts   # Pipeline 调度示例
+├── collision-detection.ts   # 碰撞检测示例
+├── parent-child-hierarchy.ts # 父子层级与 Transform 传播示例
+├── serialization.ts         # 序列化示例
+├── simple.ts                # 基本示例
+├── spatial-grid.ts          # 空间网格示例
+├── state-machine.ts         # 状态机示例
+└── tag-filtering.ts         # 标签过滤示例
 
 scripts/
 ├── build.ts                 # 构建脚本
@@ -427,7 +432,8 @@ scripts/
 bun install
 bun test                    # 运行测试
 bunx tsc --noEmit           # 类型检查
-bun run examples/simple/demo.ts  # 运行示例
+bun run examples/simple.ts       # 运行示例
+bun run examples/parent-child-hierarchy.ts
 bun run scripts/build.ts    # 构建
 ```
 

package/builder.d.mts

@@ -1070,6 +1070,9 @@ declare class World {
    * @overload getOptional<T>(entityId: EntityId<T>): { value: T } | undefined
    * Retrieves the entity's primary component safely.
    *
+   * @overload getOptional<T>(entityId: EntityId, componentType: WildcardRelationId<T>): { value: [EntityId<unknown>, T][] } | undefined
+   * Retrieves all matching relation values safely.
+   *
    * @overload getOptional<T>(entityId: EntityId, componentType: EntityId<T>): { value: T } | undefined
    * Retrieves a specific component safely.
    *
@@ -1084,6 +1087,9 @@ declare class World {
   getOptional<T>(entityId: EntityId<T>): {
     value: T;
   } | undefined;
+  getOptional<T>(entityId: EntityId, componentType: WildcardRelationId<T>): {
+    value: [EntityId<unknown>, T][];
+  } | undefined;
   getOptional<T>(entityId: EntityId, componentType: EntityId<T>): {
     value: T;
   } | undefined;
@@ -1333,7 +1339,8 @@ declare class EntityBuilder {
    * builder.with(Position, { x: 10, y: 20 });
    * builder.with(Marker); // void component
    */
-  with<T>(componentId: EntityId<T>, ...args: T extends void ? [] | [void] : [T]): this;
+  with<T extends void>(componentId: EntityId<T>): this;
+  with<T>(componentId: EntityId<T>, value: T): this;
   /**
    * Add a relation component to the entity under construction.
    *
@@ -1347,7 +1354,8 @@ declare class EntityBuilder {
    * builder.withRelation(Parent, parentEntity);
    * builder.withRelation(ChildOf, childEntity, { order: 1 });
    */
-  withRelation<T>(componentId: ComponentId<T>, targetEntity: EntityId<any>, ...args: T extends void ? [] | [void] : [T]): this;
+  withRelation<T extends void>(componentId: ComponentId<T>, targetEntity: EntityId<any>): this;
+  withRelation<T>(componentId: ComponentId<T>, targetEntity: EntityId<any>, value: T): this;
   /**
    * Create the entity and enqueue all configured components.
    * The entity and components are only materialised after {@link World.sync} is called.

package/package.json

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

package/world.mjs

@@ -600,20 +600,7 @@ var EntityBuilder = class {
 	constructor(world) {
 		this.world = world;
 	}
-	/**
-	* Add a regular component to the entity under construction.
-	*
-	* @template T - The component data type
-	* @param componentId - The component type to add
-	* @param args - Component data (omit for void components)
-	* @returns This builder for chaining
-	*
-	* @example
-	* builder.with(Position, { x: 10, y: 20 });
-	* builder.with(Marker); // void component
-	*/
-	with(componentId, ...args) {
-		const value = args.length > 0 ? args[0] : void 0;
+	with(componentId, value) {
 		this.components.push({
 			type: "component",
 			id: componentId,
@@ -621,21 +608,7 @@ var EntityBuilder = class {
 		});
 		return this;
 	}
-	/**
-	* Add a relation component to the entity under construction.
-	*
-	* @template T - The relation data type
-	* @param componentId - The base component type for the relation
-	* @param targetEntity - The target entity or component for the relation
-	* @param args - Relation data (omit for void relations)
-	* @returns This builder for chaining
-	*
-	* @example
-	* builder.withRelation(Parent, parentEntity);
-	* builder.withRelation(ChildOf, childEntity, { order: 1 });
-	*/
-	withRelation(componentId, targetEntity, ...args) {
-		const value = args.length > 0 ? args[0] : void 0;
+	withRelation(componentId, targetEntity, value) {
 		this.components.push({
 			type: "relation",
 			componentId,
@@ -2036,10 +2009,16 @@ function collectMultiHookComponents(ctx, entityId, componentTypes) {
 /**
 * Reconstructs wildcard relation data by merging current data with removed components.
 * Returns an array of [targetId, value] tuples for the wildcard relation.
+*
+* This is used during "on_remove" hook invocation: the removed components have already
+* been taken out of the entity's archetype, but the hook callback expects to see the
+* full data as it existed *before* removal. We reconstruct that snapshot by taking the
+* current wildcard data (post-removal) and adding back the entries that were just removed.
 */
 function reconstructWildcardWithRemoved(ctx, entityId, wildcardId, removedComponents) {
 	const currentData = ctx.get(entityId, wildcardId);
-	const result = Array.isArray(currentData) ? [...currentData] : [];
+	if (!Array.isArray(currentData)) throw new Error(`Expected wildcard relation data to be an array, but got ${typeof currentData} for entity ${entityId} and wildcard ${wildcardId}. This indicates a HooksContext implementation that does not conform to the expected contract.`);
+	const result = [...currentData];
 	for (const [removedCompId, removedValue] of removedComponents.entries()) if (componentMatchesHookType(removedCompId, wildcardId)) {
 		const targetId = getTargetIdFromRelationId(removedCompId);
 		if (targetId !== void 0) result.push([targetId, removedValue]);