@codehz/ecs 0.8.2 → 0.10.0

package/README.en.md

@@ -78,7 +78,7 @@ const ChildOf = component({ exclusive: true, name: "ChildOf" });
 | `name`          | `string`            | Component name, used for serialization/debugging                                                                                                                                                                                           |
 | `exclusive`     | `boolean`           | Relation components only: an entity can have at most one relation of the same base component                                                                                                                                               |
 | `cascadeDelete` | `boolean`           | Entity relations only: when the target entity is deleted, the **entire referencing entity** is deleted. Differs from default behavior (default only cleans up the relation component, the entity survives). Supports transitive cascading. |
-| `dontFragment`  | `boolean`           | Relation components only: relations with different target entities are stored in the same Archetype, preventing excessive fragmentation                                                                                                    |
+| `sparse`        | `boolean`           | Relation components only: relations with different target entities are stored in the same Archetype, preventing excessive fragmentation (legacy `dontFragment` alias remains fully supported)                                              |
 | `merge`         | `(prev, next) => T` | Merge strategy when `set()` is called multiple times on the same component within a single sync batch                                                                                                                                      |
 
 ### Lifecycle Hooks
@@ -274,7 +274,7 @@ component<T>();
 // With a name
 component<T>("Name");
 // With options
-component<T>({ name?: string, exclusive?: boolean, cascadeDelete?: boolean, dontFragment?: boolean, merge?: (prev, next) => T });
+component<T>({ name?: string, exclusive?: boolean, cascadeDelete?: boolean, sparse?: boolean, dontFragment?: boolean /* legacy alias, fully compatible */, merge?: (prev, next) => T });
 ```
 
 ### relation()
@@ -288,6 +288,29 @@ relation(componentId, "*");
 relation(componentId, otherComponentId);
 ```
 
+### Relation & Hierarchy Companion Tools (New)
+
+To stop users from repeatedly hand-writing `buildChildrenByParent` + recursive descent for parent-child hierarchies and inventory systems, we now ship first-class helpers:
+
+```typescript
+const ChildOf = component<void>({ exclusive: true, sparse: true });
+const world = new World();
+// ... build hierarchy ...
+
+// Recommended usage (standalone functions removed to simplify API surface)
+const kids = world.getChildren(parent, ChildOf);
+const p = world.getParent(child, ChildOf);
+
+for (const { entity, depth } of world.iterateDescendants(root, ChildOf)) { ... }
+
+const items = world.getRelationTargets(player, InInventory);
+const owners = world.getRelationSources(sword, InInventory);
+```
+
+The same functionality is also available as methods on `World` instances. All helpers are fully compatible with data-bearing relations, exclusive/non-exclusive, and post-`sync()` semantics.
+
+See `src/relations/hierarchy.ts` and the new test suite for details.
+
 ### Component / Entity ID Rules
 
 - Component ID: `1` – `1023`
@@ -391,7 +414,7 @@ src/
 │   ├── component-registry.ts # Component registry
 │   ├── component-entity-store.ts # Singleton component storage
 │   ├── component-type-utils.ts   # Component type utilities
-│   ├── dont-fragment-store.ts    # DontFragment storage
+│   ├── store.ts                  # SparseStore (internal sparse storage)
 │   ├── entity.ts            # Entity/component/relation type exports (aggregate)
 │   ├── entity-types.ts      # Entity ID type definitions & constants
 │   ├── entity-relation.ts   # Relation ID encoding/decoding

package/README.md

@@ -78,7 +78,7 @@ const ChildOf = component({ exclusive: true, name: "ChildOf" });
 | `name`          | `string`            | 组件名称，用于序列化/调试                                                                                                      |
 | `exclusive`     | `boolean`           | 仅关系组件：同一实体对同一基础组件最多只能有一个关系                                                                           |
 | `cascadeDelete` | `boolean`           | 仅实体关系：删除目标实体时，持有该关系的**整个实体**也会被删除。区别于默认行为（默认仅清理关系组件，实体保留）。支持传递级联。 |
-| `dontFragment`  | `boolean`           | 仅关系组件：不同目标实体的关系存放在同一 Archetype，防止因目标不同而过度碎片化                                                 |
+| `sparse`        | `boolean`           | 仅关系组件：不同目标实体的关系存放在同一 Archetype，防止因目标不同而过度碎片化（旧别名 `dontFragment` 仍完全兼容）             |
 | `merge`         | `(prev, next) => T` | 在同一 sync 批次中对同一组件反复 `set()` 时的合并策略                                                                          |
 
 ### 生命周期钩子
@@ -222,7 +222,7 @@ bun run examples/inventory-system-relations.ts
 | `spawnMany(count, configure)`         | 批量创建多个实体                                                                    |
 | `exists(entity)`                      | 检查实体是否存在                                                                    |
 | `set(entity, componentId, data?)`     | 添加/更新组件（缓冲，`sync()` 后生效）。对 `void` 组件可不传 data                   |
-| `set(componentId, data)`              | 单例组件简写：`world.set(GlobalConfig, { ... })`                                    |
+| `singleton(componentId)`              | 获取单例组件句柄，推荐用 `world.singleton(Config).set(value)`                       |
 | `get(entity, componentId?)`           | 获取组件数据。**若组件不存在会抛出异常**，请先用 `has()` 检查或使用 `getOptional()` |
 | `getOptional(entity, componentId?)`   | 安全获取组件，返回 `{ value: T } \| undefined`                                      |
 | `has(entity, componentId?)`           | 检查组件是否存在                                                                    |
@@ -236,6 +236,18 @@ bun run examples/inventory-system-relations.ts
 | `serialize()`                         | 序列化世界状态为快照对象                                                            |
 | `sync()`                              | 执行所有延迟命令                                                                    |
 
+单例组件推荐写法：
+
+```ts
+const config = world.singleton(GlobalConfig);
+config.set({ debug: true });
+world.sync();
+
+if (config.has()) {
+  console.log(config.get());
+}
+```
+
 ### Query
 
 查询通过 `world.createQuery()` 创建，应**跨帧复用**以获得最佳性能。
@@ -274,7 +286,7 @@ component<T>();
 // 指定名称
 component<T>("Name");
 // 带选项
-component<T>({ name?: string, exclusive?: boolean, cascadeDelete?: boolean, dontFragment?: boolean, merge?: (prev, next) => T });
+component<T>({ name?: string, exclusive?: boolean, cascadeDelete?: boolean, sparse?: boolean, dontFragment?: boolean /* 旧别名，完全兼容 */, merge?: (prev, next) => T });
 ```
 
 ### relation()
@@ -288,6 +300,31 @@ relation(componentId, "*");
 relation(componentId, otherComponentId);
 ```
 
+### 关系/层级配套工具（新）
+
+为避免用户在父子层级（`ChildOf`）和库存系统（`InInventory`）中反复手写 `buildChildrenByParent` + 递归遍历逻辑，我们提供了配套工具：
+
+```typescript
+const ChildOf = component<void>({ exclusive: true, sparse: true });
+const world = new World();
+// ... 创建层级 ...
+
+// 推荐直接在 World 实例上使用（API 表面已简化）
+const kids = world.getChildren(parent, ChildOf);
+const p = world.getParent(child, ChildOf);
+
+for (const { entity, depth, parent } of world.iterateDescendants(root, ChildOf)) {
+  // ...
+}
+
+const items = world.getRelationTargets(player, InInventory);
+const owners = world.getRelationSources(sword, InInventory);
+```
+
+这些工具全部在 `world` 实例方法上也有对应（`world.getChildren(...)` 等），并完整支持数据负载关系、独占/非独占、删除后一致性。
+
+详见 `src/relations/hierarchy.ts` 和新增的测试。
+
 ### 组件 / 实体 ID 规则
 
 - 组件 ID：`1` ~ `1023`
@@ -391,7 +428,7 @@ src/
 │   ├── component-registry.ts # 组件注册表
 │   ├── component-entity-store.ts # 单例组件存储
 │   ├── component-type-utils.ts   # 组件类型工具
-│   ├── dont-fragment-store.ts    # DontFragment 存储
+│   ├── store.ts                  # SparseStore (内部稀疏存储)
 │   ├── entity.ts            # 实体/组件/关系类型导出（聚合）
 │   ├── entity-types.ts      # 实体 ID 类型定义与常量
 │   ├── entity-relation.ts   # 关系 ID 编码/解码