aiecsjs 0.1.1

package/STABILITY.md

@@ -0,0 +1,145 @@
+# Stability Contract
+
+[English](STABILITY.md) | [繁體中文](STABILITY_ZHTW.md)
+
+This document is the per-export stability promise for `aiecsjs`. It is the contract AI tools and human users can rely on when pinning versions and writing import paths.
+
+## Policy
+
+aiecsjs follows [semver](https://semver.org/). Within the **0.x** series:
+- **`stable`** exports do not change in breaking ways across minor versions (e.g. 0.1 → 0.2).
+- **`experimental`** exports may change shape, name, or behaviour in any minor release. Pin the exact version if you depend on them.
+- **`internal`** is not part of the API. May change in any patch release. Do not import.
+- **`deprecated`** still works as documented but is scheduled for removal. The deprecation notice states the target version.
+
+At **1.0**, the `stable` surface freezes for the entire 1.x series.
+
+The full machine-readable export list lives in [`api.json`](./api.json), with the `stability` and `since` fields on every entry.
+
+## By module
+
+The **root** entry (`aiecsjs`) is the stable core: world, entity, component, query, system. Everything under a sub-path (`aiecsjs/<name>`) is a **utility or adapter sub-path** — useful but non-essential, decoupled from the core, and importable a la carte. Tree-shakers should be able to drop any sub-path the application does not import.
+
+### `aiecsjs` (root core)
+
+| Export | Stability | Since | Notes |
+|---|---|---|---|
+| `createWorld` | stable | 0.1.0 | |
+| `destroyWorld` | stable | 0.1.0 | |
+| `resetWorld` | stable | 0.1.0 | |
+| `getWorldSize` | stable | 0.1.0 | |
+| `getWorldCapacity` | stable | 0.1.0 | |
+| `createEntity` | stable | 0.1.0 | |
+| `destroyEntity` | stable | 0.1.0 | |
+| `entityExists` | stable | 0.1.0 | |
+| `getEntityIndex` | stable | 0.1.0 | |
+| `getEntityGeneration` | stable | 0.1.0 | |
+| `packEntity` | stable | 0.1.0 | |
+| `defineComponent` | stable | 0.1.0 | |
+| `defineTag` | stable | 0.1.0 | |
+| `defineObjectComponent` | stable | 0.1.0 | AoS components are main-thread only; not SAB-shareable. |
+| `addComponent` | stable | 0.1.0 | Argument order `(world, eid, component, init?)` is final. |
+| `removeComponent` | stable | 0.1.0 | |
+| `hasComponent` | stable | 0.1.0 | |
+| `getComponent` | stable | 0.1.0 | |
+| `setComponent` | stable | 0.1.0 | |
+| `Types` | stable | 0.1.0 | Constant map; field names are part of the contract. |
+| `defineQuery` | stable | 0.1.0 | |
+| `runQuery` | stable | 0.1.0 | |
+| `forEachEntity` | stable | 0.1.0 | |
+| `iterQuery` | stable | 0.1.0 | |
+| `enterQuery` | stable | 0.1.0 | |
+| `exitQuery` | stable | 0.1.0 | |
+| `queryArchetypes` | **experimental** | 0.1.0 | `Archetype.id` is opaque-internal; the shape of `Archetype` may grow. |
+| `pipe` | stable | 0.1.0 | |
+| `VERSION` | stable | 0.1.0 | |
+| `IS_SAB_SUPPORTED` | stable | 0.1.0 | |
+| `isWorld` | stable | 0.1.0 | |
+| `isEntity` | stable | 0.1.0 | |
+
+### `aiecsjs/loop` (utility sub-path)
+
+Fixed-timestep accumulator loop. Drop this sub-path if you already drive frame updates yourself (PixiJS `Ticker`, requestAnimationFrame, server-side simulation).
+
+| Export | Stability | Since | Notes |
+|---|---|---|---|
+| `createLoop` | stable | 0.1.0 | |
+
+### `aiecsjs/commands` (utility sub-path)
+
+Deferred structural mutations so systems can mutate world structure mid-iteration without invalidating queries.
+
+| Export | Stability | Since | Notes |
+|---|---|---|---|
+| `createCommandBuffer` | stable | 0.1.0 | |
+| `flush` | stable | 0.1.0 | |
+| `withCommandBuffer` | stable | 0.1.0 | |
+
+### `aiecsjs/observers` (utility sub-path)
+
+Component lifecycle hooks. The core does not require observers; install this sub-path only if a system needs add/remove/set callbacks.
+
+| Export | Stability | Since | Notes |
+|---|---|---|---|
+| `observe` | stable | 0.1.0 | |
+| `onAdd` | stable | 0.1.0 | |
+| `onRemove` | stable | 0.1.0 | |
+| `onSet` | stable | 0.1.0 | |
+
+### `aiecsjs/serialize` (utility sub-path)
+
+| Export | Stability | Since | Notes |
+|---|---|---|---|
+| `serializeWorld` | stable | 0.1.0 | Binary format includes a version stamp. |
+| `deserializeWorld` | stable | 0.1.0 | |
+| `toJSON` | stable | 0.1.0 | |
+| `fromJSON` | stable | 0.1.0 | |
+| `createDeltaSerializer` | **experimental** | 0.1.0 | Wire format may change before 1.0. |
+
+### `aiecsjs/worker` (experimental adapter sub-path)
+
+The entire subpath is **experimental** in 0.1. **In 0.1 the implementation is a snapshot-copy transport** — serialize the world into the SAB on send, deserialize into a fresh world on adopt. It is not true shared-memory column aliasing. The API surface matches the documented contract; true shared columns ship in 0.2. Snapshot layout and capability flags may change.
+
+| Export | Stability | Since | Notes |
+|---|---|---|---|
+| `transferableSnapshot` | experimental | 0.1.0 | |
+| `adoptSnapshot` | experimental | 0.1.0 | |
+| `attachWorld` | experimental | 0.1.0 | |
+| `detachWorld` | experimental | 0.1.0 | |
+
+### `aiecsjs/relations` (experimental adapter sub-path)
+
+The entire subpath is **experimental** in 0.1 but implemented. Targeted for stabilization in 0.3.
+
+| Export | Stability | Since | Notes |
+|---|---|---|---|
+| `defineRelation` | experimental | 0.1.0 | |
+| `addRelation` | experimental | 0.1.0 | |
+| `removeRelation` | experimental | 0.1.0 | |
+| `getRelationTargets` | experimental | 0.1.0 | |
+| `ChildOf` (constant) | experimental | 0.1.0 | Built-in exclusive relation. |
+
+### `aiecsjs/internal/*`
+
+Everything under this prefix is **internal**. It exists for the implementation's own use and may break in any release. Do not import.
+
+## Roadmap
+
+| Version | Focus | Stability shift |
+|---|---|---|
+| 0.1.x | Core surface (world, entity, component, query, system, loop, commands, observers, serialize) | Initial publish; all marked experimental at the package level but per-export stable where listed. |
+| 0.2.x | Relations & hierarchies | `aiecsjs/relations` becomes implemented; still experimental. |
+| 0.3.x | Hardening, relations stabilization, multi-threading polish | `aiecsjs/relations` and `aiecsjs/worker` → stable. |
+| 1.0.0 | API freeze | All `stable` exports frozen for 1.x. |
+
+## How to check stability at runtime
+
+```ts
+import { VERSION } from 'aiecsjs'
+
+if (VERSION.startsWith('0.')) {
+  console.warn('aiecsjs is in pre-1.0; API surface may shift')
+}
+```
+
+For programmatic introspection, parse [`api.json`](./api.json) — each entry has `stability` and `since` fields.

package/STABILITY_ZHTW.md

@@ -0,0 +1,145 @@
+# 穩定度契約
+
+[English](STABILITY.md) | [繁體中文](STABILITY_ZHTW.md)
+
+本文件為 `aiecsjs` 中各匯出的穩定度承諾。AI 工具與人類使用者可依此契約來鎖定版本與書寫 import 路徑。
+
+## 規範
+
+aiecsjs 遵循 [semver](https://semver.org/)。在 **0.x** 系列內：
+- **`stable`** 匯出於 minor 版本之間（例如 0.1 → 0.2）不會破壞性變更。
+- **`experimental`** 匯出可能在任何 minor 釋出時改變形狀、命名或行為。若有依賴請鎖定明確版本。
+- **`internal`** 不屬於 API 表面，可能在任何 patch 釋出時改變。請勿匯入。
+- **`deprecated`** 仍可正常運作但已排入移除計畫。棄用通知中會載明目標版本。
+
+至 **1.0** 時，`stable` 表面為整個 1.x 系列凍結。
+
+完整機器可讀的匯出清單位於 [`api.json`](./api.json)，每筆都有 `stability` 與 `since` 欄位。
+
+## 依模組分類
+
+**根目錄** entry（`aiecsjs`）為穩定核心：world、entity、component、query、system。任何 sub-path（`aiecsjs/<名稱>`）為 **utility 或 adapter sub-path** — 實用但非核心，與 core 解耦，可單獨 a la carte import。Tree-shaker 應能丟掉未引用的任何 sub-path。
+
+### `aiecsjs`（根核心）
+
+| 匯出 | 穩定度 | 起始版本 | 備註 |
+|---|---|---|---|
+| `createWorld` | stable | 0.1.0 | |
+| `destroyWorld` | stable | 0.1.0 | |
+| `resetWorld` | stable | 0.1.0 | |
+| `getWorldSize` | stable | 0.1.0 | |
+| `getWorldCapacity` | stable | 0.1.0 | |
+| `createEntity` | stable | 0.1.0 | |
+| `destroyEntity` | stable | 0.1.0 | |
+| `entityExists` | stable | 0.1.0 | |
+| `getEntityIndex` | stable | 0.1.0 | |
+| `getEntityGeneration` | stable | 0.1.0 | |
+| `packEntity` | stable | 0.1.0 | |
+| `defineComponent` | stable | 0.1.0 | |
+| `defineTag` | stable | 0.1.0 | |
+| `defineObjectComponent` | stable | 0.1.0 | AoS 元件僅限主執行緒；不可跨 SAB 共享。 |
+| `addComponent` | stable | 0.1.0 | 參數順序 `(world, eid, component, init?)` 為最終定義。 |
+| `removeComponent` | stable | 0.1.0 | |
+| `hasComponent` | stable | 0.1.0 | |
+| `getComponent` | stable | 0.1.0 | |
+| `setComponent` | stable | 0.1.0 | |
+| `Types` | stable | 0.1.0 | 常數對應表；欄位名稱屬於契約。 |
+| `defineQuery` | stable | 0.1.0 | |
+| `runQuery` | stable | 0.1.0 | |
+| `forEachEntity` | stable | 0.1.0 | |
+| `iterQuery` | stable | 0.1.0 | |
+| `enterQuery` | stable | 0.1.0 | |
+| `exitQuery` | stable | 0.1.0 | |
+| `queryArchetypes` | **experimental** | 0.1.0 | `Archetype.id` 為 opaque 內部值；`Archetype` 的形狀可能增加欄位。 |
+| `pipe` | stable | 0.1.0 | |
+| `VERSION` | stable | 0.1.0 | |
+| `IS_SAB_SUPPORTED` | stable | 0.1.0 | |
+| `isWorld` | stable | 0.1.0 | |
+| `isEntity` | stable | 0.1.0 | |
+
+### `aiecsjs/loop`（utility sub-path）
+
+定步長累加迴圈。若應用層已自有 frame 更新驅動（PixiJS `Ticker`、requestAnimationFrame、伺服端模擬），可直接略過本 sub-path。
+
+| 匯出 | 穩定度 | 起始版本 | 備註 |
+|---|---|---|---|
+| `createLoop` | stable | 0.1.0 | |
+
+### `aiecsjs/commands`（utility sub-path）
+
+延後的結構性變更，讓系統可在迭代中安全改動 world 結構而不會讓查詢失效。
+
+| 匯出 | 穩定度 | 起始版本 | 備註 |
+|---|---|---|---|
+| `createCommandBuffer` | stable | 0.1.0 | |
+| `flush` | stable | 0.1.0 | |
+| `withCommandBuffer` | stable | 0.1.0 | |
+
+### `aiecsjs/observers`（utility sub-path）
+
+元件生命週期 hook。Core 不依賴 observers；只在系統需要 add/remove/set callback 時才安裝本 sub-path。
+
+| 匯出 | 穩定度 | 起始版本 | 備註 |
+|---|---|---|---|
+| `observe` | stable | 0.1.0 | |
+| `onAdd` | stable | 0.1.0 | |
+| `onRemove` | stable | 0.1.0 | |
+| `onSet` | stable | 0.1.0 | |
+
+### `aiecsjs/serialize`（utility sub-path）
+
+| 匯出 | 穩定度 | 起始版本 | 備註 |
+|---|---|---|---|
+| `serializeWorld` | stable | 0.1.0 | 二進位格式包含版本戳記。 |
+| `deserializeWorld` | stable | 0.1.0 | |
+| `toJSON` | stable | 0.1.0 | |
+| `fromJSON` | stable | 0.1.0 | |
+| `createDeltaSerializer` | **experimental** | 0.1.0 | Wire format 在 1.0 之前可能改變。 |
+
+### `aiecsjs/worker`（experimental adapter sub-path）
+
+整個 subpath 在 0.1 為 **experimental**。**0.1 的實作為 snapshot-copy 傳輸**——傳送時將 world 序列化進 SAB，接收端反序列化成全新 world，並非真正的共享記憶體欄位 aliasing。API 表面符合文件契約；真正的共享欄位將於 0.2 推出。Snapshot 佈局與能力旗標可能改變。
+
+| 匯出 | 穩定度 | 起始版本 | 備註 |
+|---|---|---|---|
+| `transferableSnapshot` | experimental | 0.1.0 | |
+| `adoptSnapshot` | experimental | 0.1.0 | |
+| `attachWorld` | experimental | 0.1.0 | |
+| `detachWorld` | experimental | 0.1.0 | |
+
+### `aiecsjs/relations`（experimental adapter sub-path）
+
+整個 subpath 在 0.1 為 **experimental** 但已實作。預期於 0.3 穩定。
+
+| 匯出 | 穩定度 | 起始版本 | 備註 |
+|---|---|---|---|
+| `defineRelation` | experimental | 0.1.0 | |
+| `addRelation` | experimental | 0.1.0 | |
+| `removeRelation` | experimental | 0.1.0 | |
+| `getRelationTargets` | experimental | 0.1.0 | |
+| `ChildOf`（常數） | experimental | 0.1.0 | 內建獨佔關係。 |
+
+### `aiecsjs/internal/*`
+
+此前綴底下的所有內容皆為 **internal**。它存在於實作自用，可能在任何 release 變更。請勿匯入。
+
+## Roadmap
+
+| 版本 | 焦點 | 穩定度變動 |
+|---|---|---|
+| 0.1.x | 核心表面（world、entity、component、query、system、loop、commands、observers、serialize） | 初次發佈；package 整體標 experimental，但各 export 表中列為 stable 者皆穩定。 |
+| 0.2.x | Relations 與階層 | `aiecsjs/relations` 落實實作；仍為 experimental。 |
+| 0.3.x | 硬化、Relations 穩定、多執行緒打磨 | `aiecsjs/relations` 與 `aiecsjs/worker` → stable。 |
+| 1.0.0 | API 凍結 | 所有 `stable` 匯出於 1.x 系列凍結。 |
+
+## 在執行時檢查穩定度
+
+```ts
+import { VERSION } from 'aiecsjs'
+
+if (VERSION.startsWith('0.')) {
+  console.warn('aiecsjs 處於 1.0 前；API 表面可能調整')
+}
+```
+
+如需程式化檢視，請解析 [`api.json`](./api.json) — 每筆都有 `stability` 與 `since` 欄位。