@combos-fun/engine 0.0.6 → 0.0.8

package/README.md

@@ -1,3 +1,27 @@
 # @combos-fun/engine
 
-Internal workspace package (Combos Fun monorepo).
+@combos-fun/engine — part of the Combos Fun engine monorepo.
+
+Keywords: `engine`, `ecs`, `kernel`, `runtime`, `game`, `system`, `component`.
+
+## Documentation
+
+- Per-package agent / developer notes: [`agent-skill.md`](./agent-skill.md)
+- Machine-readable manifest: [`combos-plugin.json`](./combos-plugin.json)
+  (validated against `schemas/combos-plugin.schema.json` in the repo
+  root)
+- Entry skill (single source of truth for AI agents working with this
+  monorepo): `skills/combos-engine-development/SKILL.md`
+
+When consumed from npm, the manifest and agent notes are exposed as
+stable subpaths:
+
+```ts
+import manifest from '@combos-fun/engine/plugin-manifest';
+// or fetch the markdown directly:
+// require.resolve('@combos-fun/engine/agent-skill')
+```
+
+## License
+
+Internal workspace package, part of the Combos Fun engine monorepo.

package/agent-skill.md

@@ -0,0 +1,205 @@
+# `@combos-fun/engine` — Agent notes
+
+ECS microkernel for Combos Fun. This file is the canonical knowledge source for **using** the engine. For **authoring** a new `@combos-fun/plugin-*`, read `@combos-fun/engine/plugin-authoring` instead.
+
+## When to read
+
+Read this every time before working on a Combos Fun project. The entry skill loads this file as part of "Core" packages, regardless of 2D / 3D mode.
+
+## Microkernel model
+
+- **Kernel** `@combos-fun/engine`: `Game`, `Scene`, `GameObject`, `Component`, `System`, `Transform`, `resource`, `decorators`. **No** built-in rendering / physics / audio.
+- **Extension**: `game.addSystem(new XxxSystem(...))` then `gameObject.addComponent(new Xxx(...))`.
+- **Observer**: `@decorators.componentObserver({ Name: ['prop'] })` on a System; drain `this.componentObserver.clear()` in `update()` and switch on `OBSERVER_TYPE.ADD | CHANGE | REMOVE`.
+- **Frame order**: `Component.update` → `Component.lateUpdate` → `System.update` → `System.lateUpdate`. `start()` fires inline on the first `update` tick.
+
+## Public API
+
+### Values
+
+`Game`, `Scene`, `GameObject`, `Component`, `System`, `Transform`, `resource`, `resourceLoader`, `decorators`, `IDEProp`, `componentObserver`, `LOAD_EVENT`, `RESOURCE_TYPE`, `OBSERVER_TYPE`, `LOAD_SCENE_MODE`, `RESOURCE_TYPE_STRATEGY`, `version`, `COMBOS_GAME_PLUGIN_INIT_SUCCESS`, `postParentPluginInitSuccess`.
+
+### Types
+
+`GameParams`, `PluginStruct`, `TransformParams`, `ComponentChanged`, `UpdateParams`, `ComponentParams`, `ObserverInfo`, `PureObserverInfo`, `ResourceBase`, `SystemConstructor`, `CombosGamePluginInitSuccessMessage`.
+
+### `GameParams`
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `systems` | `System[]` | `[]` | Bootstrapped async in registration order |
+| `frameRate` | `number` | `60` | |
+| `autoStart` | `boolean` | `true` | |
+| `needScene` | `boolean` | `true` | Auto-creates `Scene('scene')` |
+| `onSystemsBootstrapComplete` | `(game, error?) => void` | — | After all systems init |
+| `pluginInitNotifyTargetOrigin` | `string` | `'*'` | postMessage target |
+
+### `Game` methods
+
+`addSystem(system)`, `removeSystem(system | class | string)` (calls `system.destroy()` internally), `getSystem(class | string)`, `loadScene({ scene, mode?, params? })` (`LOAD_SCENE_MODE.SINGLE | MULTI_CANVAS`), `start()`, `pause()`, `resume()`, `destroy()`.
+
+### `resource` singleton
+
+| Method | Notes |
+|--------|-------|
+| `addResource(resources[])` | Register (no load) |
+| `preload()` | Load all `preload: true` |
+| `loadConfig(resources[])` | `addResource` + `preload` |
+| `loadSingle(resource): Promise` | Add + load one |
+| `getResource(name): Promise` | Get loaded |
+| `destroy(name): Promise` | Destroy one |
+| `registerResourceType(type, value?)` | Custom type |
+| `registerInstance(type, cb)` / `registerDestroy(type, cb)` | Factory / destructor |
+
+Fields: `timeout` (6000ms), `resourcesMap`, `progress`.
+
+## ECS hard rules (mandatory)
+
+These rules apply to every code change. Violations must be fixed before the change is considered complete.
+
+### Rule 1: All entity state lives in Components
+
+Any data belonging to a game entity must be a field on a `Component` attached to a `GameObject`. No module-scope variables, closure captures, or shadow stores holding entity state. **Test:** if you `destroy()` a `GameObject`, does all its state disappear? If anything survives in a closure or module variable, violation.
+
+### Rule 2: All behaviour logic lives in Component / System hooks
+
+Code that runs per-frame, reacts to events, or mutates entity state must live in `Component` hooks (`init` / `awake` / `start` / `update` / `lateUpdate` / `onPause` / `onResume` / `onDestroy`) or `System` hooks (same set + `componentObserver` in `update`). No event callbacks in bootstrap, no `setInterval` outside Components, no `game.ticker.add` for game logic.
+
+### Rule 3: Bootstrap code only wires, never implements
+
+The entry file may: register resources, create `Game` with `systems`, create `GameObject`s + attach `Component`s, add to scene, call `game.start()`. The entry file must **not**: define event handlers, call component methods (`spriteAnim.play()`), hold component references for later use, or contain `if` / `switch` / loop game logic. When you need interaction logic, create a custom Component whose `start()` wires it and whose `onDestroy()` cleans it up.
+
+### Rule 4: Single concern per Component, cross-entity logic in Systems
+
+A Component holds data + self-contained behaviour for one concern on one entity. A System holds cross-entity logic reacting to component changes. Do not put multi-entity coordination inside a Component.
+
+### Rule 5: No direct Pixi / Three.js / DOM manipulation outside Renderer pattern
+
+2D display objects must come through `plugin-renderer-*` systems or a custom `Renderer` subclass registered via `rendererManager.register(this)`. 3D objects must come through `plugin-renderer-3d-*` systems or a custom `Renderer3D` subclass. No raw `new PIXI.Sprite(...)` / `new THREE.Mesh(...)` in bootstrap or plain Components.
+
+### Rule 6: Component configuration via params, not imperative calls
+
+Configure Components through constructor params (e.g. `autoPlay: true`). If behaviour must be triggered at runtime, do it from another Component's lifecycle hook, not from bootstrap code.
+
+## Decision flowchart
+
+```
+Runs only once at startup to wire things?
+├── YES: Only creates GameObjects/Components/Systems/resources?
+│   ├── YES → bootstrap / entry file
+│   └── NO (contains logic) → Component or System
+└── NO: Runs per-frame or reacts to events?
+    ├── Single-entity concern → Component
+    ├── Cross-entity concern → System with @componentObserver
+    └── Rendering integration → Renderer (2D) / Renderer3D (3D) subclass
+```
+
+## ECS compliance checklist
+
+Run after every change:
+
+- [ ] No game logic in entry file — only resource registration, `Game` / `System` creation, `GameObject` + `Component` wiring, scene setup
+- [ ] No retained component references — entry file does not store `addComponent()` returns for later use
+- [ ] No anonymous event handlers — all `.on(...)` / `addEventListener(...)` inside Component lifecycle hooks with cleanup in `onDestroy`
+- [ ] No module-scope mutable state holding entity data
+- [ ] All entity state accessible via `gameObject.getComponent(...)`
+- [ ] All per-frame logic in Component / System `update` / `lateUpdate`
+- [ ] Custom behaviour = named Component class with `static componentName`
+- [ ] Every event subscription has cleanup in `onDestroy`
+- [ ] Systems use `@decorators.componentObserver` and drain in `update()`
+- [ ] No direct Pixi / Three.js manipulation outside `Renderer` / `Renderer3D` subclasses
+
+## Inventory (mandatory after every task)
+
+After every development task, write or update three inventory tables in the **project memory**:
+
+**Component inventory** — for each custom Component:
+
+| Field | Description |
+|-------|-------------|
+| `componentName` | Static name string |
+| Purpose | One-sentence description |
+| Key params | Constructor params that affect behaviour |
+| Lifecycle hooks | Which of `init` / `awake` / `start` / `update` / `lateUpdate` / `onDestroy` it implements |
+
+**GameObject inventory** — for each GameObject:
+
+| Field | Description |
+|-------|-------------|
+| Name | Identifier or variable name |
+| Parent | Parent GameObject or scene root |
+| Components | Attached Components |
+| Purpose | Role in the game |
+
+**System inventory** — for each System:
+
+| Field | Description |
+|-------|-------------|
+| Class name | System class |
+| Order | Registration order in `systems` array |
+| What it owns | Components observed / coordinated |
+| Purpose | One-sentence description |
+
+Skipping inventory is treated with the same weight as the ECS hard rules.
+
+## Common pitfalls
+
+| Symptom | Fix |
+|---------|-----|
+| Blank canvas | Add the right base renderer system (`RendererSystem` for 2D, `Renderer3DSystem` for 3D); ensure `autoStart: true` or call `game.start()` |
+| Nothing draws | Add the matching sub-system (e.g. `ImgSystem`, `Graphics3DSystem`) before adding components |
+| `getSystem` returns undefined | Use class reference, not string: `game.getSystem(RendererSystem)` |
+| "Component already added" error | Use a new `Component` instance per `GameObject` |
+| Destroyed `GameObject` causes errors | Retained reference in a closure — move logic into a Component |
+| Cannot pause / resume behaviour | Logic in `setInterval` / `ticker.add` — move into `Component.update()` |
+| Resource name not found | Match `resource.addResource` `name` to component `resource` field |
+| TS: `onError` missing on `SoundSystem` | `SoundSystem` requires `onError` callback |
+| Stale render after async load | 3D: use `increaseAsyncId` / `validateAsyncId` to drop stale work |
+
+## Minimal 2D bootstrap
+
+```ts
+import { Game, resource } from '@combos-fun/engine';
+import { RendererSystem } from '@combos-fun/plugin-renderer';
+import { RenderSystem } from '@combos-fun/plugin-renderer-render';
+import { ImgSystem } from '@combos-fun/plugin-renderer-img';
+
+resource.addResource([{ name: 'logo', src: 'logo.png', preload: true }]);
+
+new Game({
+  systems: [
+    new RendererSystem({ canvas: document.querySelector('#canvas')!, width: 750, height: 1334 }),
+    new RenderSystem(),
+    new ImgSystem(),
+  ],
+});
+```
+
+## Minimal 3D bootstrap
+
+```ts
+import { Game } from '@combos-fun/engine';
+import { Renderer3DSystem } from '@combos-fun/plugin-renderer-3d';
+import { Graphics3DSystem } from '@combos-fun/plugin-renderer-3d-graphics';
+
+new Game({
+  systems: [
+    new Renderer3DSystem({ canvas: document.querySelector('#canvas')!, width: 750, height: 1000 }),
+    new Graphics3DSystem(),
+  ],
+});
+```
+
+## Verification
+
+After modifying engine code:
+
+1. `pnpm typecheck`
+2. `pnpm run build` (rebuild all packages in dependency order)
+3. `pnpm validate-plugin-manifests` (warn during migration, strict at GA)
+4. `pnpm plugin-index:check`
+5. Run an example app from `examples/` and verify no console errors
+
+## See also
+
+- `@combos-fun/engine/plugin-authoring` — full spec for writing a new `@combos-fun/plugin-*` package, including Component / System / Renderer / Renderer3D subclassing, manifest format, and publish requirements.

package/combos-plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "@combos-fun/engine",
+  "pluginId": "engine",
+  "category": "core",
+  "dimension": "shared",
+  "isCore": true,
+  "keywords": ["engine", "ecs", "kernel", "runtime", "game", "system", "component"],
+  "agentSkill": "./agent-skill.md",
+  "exports": [
+    "Game",
+    "Scene",
+    "GameObject",
+    "Component",
+    "System",
+    "Transform",
+    "resource",
+    "decorators",
+    "OBSERVER_TYPE",
+    "RESOURCE_TYPE",
+    "LOAD_EVENT",
+    "LOAD_SCENE_MODE"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/engine",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "@combos-fun/engine",
   "main": "index.js",
   "module": "dist/engine.esm.js",
@@ -8,8 +8,24 @@
   "unpkg": "dist/CombosFun.min.js",
   "files": [
     "index.js",
-    "dist"
+    "dist",
+    "agent-skill.md",
+    "plugin-authoring.md",
+    "combos-plugin.json"
   ],
+  "exports": {
+    ".": {
+      "import": "./dist/engine.esm.js",
+      "require": "./index.js",
+      "types": "./dist/engine.d.ts"
+    },
+    "./plugin-manifest": "./combos-plugin.json",
+    "./agent-skill": "./agent-skill.md",
+    "./plugin-authoring": "./plugin-authoring.md"
+  },
+  "combos": {
+    "pluginManifest": "./combos-plugin.json"
+  },
   "types": "dist/engine.d.ts",
   "keywords": [
     "combos-fun",
@@ -21,7 +37,7 @@
     "lodash-es": "^4.17.21",
     "resource-loader": "^4.0.0-rc4",
     "sprite-timeline": "^1.10.2",
-    "@combos-fun/inspector-decorator": "0.0.6"
+    "@combos-fun/inspector-decorator": "0.0.8"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.mjs"

package/plugin-authoring.md

@@ -0,0 +1,187 @@
+# `@combos-fun/engine` — Plugin authoring spec
+
+This file is the standard for authoring any new `@combos-fun/plugin-*` package — npm-published or project-local. Read it only when you are **creating** a plugin. Day-to-day engine usage is covered in `@combos-fun/engine/agent-skill`.
+
+A plugin is `Component(s)` + optional `System(s)` + optional `Renderer` / `Renderer3D` subclass, shipped under the `@combos-fun/` namespace as an npm package or as a folder inside a user project.
+
+## When to read
+
+- You are adding a new feature that does not match any existing `@combos-fun/plugin-*` keyword.
+- You are publishing a new plugin to npm under `@combos-fun/*`.
+- You are forking / extending an existing plugin's `Renderer` / `Renderer3D` subclass.
+
+For pure consumption of existing plugins, this file is not required — read `@combos-fun/engine/agent-skill` plus each plugin's `agent-skill` instead.
+
+## Required package layout
+
+```
+packages/<plugin-name>/
+  package.json
+  combos-plugin.json    # machine-readable manifest (validated against schemas/combos-plugin.schema.json)
+  agent-skill.md        # per-package agent notes
+  README.md             # human-facing docs
+  index.js              # CJS entry
+  lib/                  # TypeScript sources
+  dist/                 # built CJS / ESM / .d.ts (created by build-package.mjs)
+```
+
+Project-local plugins (not published to npm) may skip `dist/`, the build step, and `combos-plugin.json` — but adopting both unlocks the same selection logic the entry skill uses for official plugins.
+
+## Required `package.json` fields
+
+```json
+{
+  "name": "@combos-fun/plugin-xxx",
+  "files": ["dist", "index.js", "agent-skill.md", "combos-plugin.json"],
+  "exports": {
+    ".": "./dist/plugin-xxx.esm.js",
+    "./plugin-manifest": "./combos-plugin.json",
+    "./agent-skill": "./agent-skill.md"
+  },
+  "combos": {
+    "pluginManifest": "./combos-plugin.json"
+  }
+}
+```
+
+The `./plugin-manifest` and `./agent-skill` subpaths are part of the public contract. External Agents resolve documentation via these stable subpaths. Renaming the underlying files without updating `exports` is a breaking change.
+
+## Component subclass
+
+Subclass `Component` from `@combos-fun/engine`. Set `static componentName = 'MyFeature'`.
+
+Lifecycle (all optional):
+
+| Hook | When |
+|------|------|
+| `init(params?)` | During construction |
+| `awake()` | When added to a GameObject |
+| `start()` | Inline on first `update` tick (same frame as first `update`) |
+| `update(frame)` | Every frame (`frame.deltaTime` in ms) |
+| `lateUpdate(frame)` | After all components' `update`, before any `System.update` |
+| `onPause()` / `onResume()` | Game pause / resume |
+| `onDestroy()` | Component or GameObject destroyed |
+
+`UpdateParams`: `deltaTime`, `frameCount`, `time`, `currentTime`, `fps`.
+
+## System subclass
+
+Subclass `System`. Set `static systemName = 'MyFeatureSystem'`.
+
+Decorate with `@decorators.componentObserver({ MyFeature: ['power'] })`:
+
+- `[]` (empty array) → ADD / REMOVE only
+- `['prop']` → CHANGE on set
+- `{ prop: ['a','b'], deep: true }` → deep change watching
+
+In `update()`:
+
+```ts
+const changes = this.componentObserver.clear();
+for (const c of changes) {
+  switch (c.type) {
+    case OBSERVER_TYPE.ADD:    /* c.component, c.gameObject */ break;
+    case OBSERVER_TYPE.CHANGE: /* c.prop?: { deep, prop: string[] } */ break;
+    case OBSERVER_TYPE.REMOVE: break;
+  }
+}
+```
+
+System lifecycle is the same as Component (`init` can be async). `init` receives constructor params; `this.game` is available.
+
+`System.destroy()` nulls internals and calls `onDestroy()` but **does not** remove the system from Game. Always call `game.removeSystem(system)`, which calls `destroy()` internally.
+
+### `ComponentChanged` shape
+
+`type: OBSERVER_TYPE`, `component`, `componentName`, `gameObject`, `prop?: { deep, prop: string[] }`.
+
+## 2D Pixi `Renderer` subclass (`@combos-fun/plugin-renderer`)
+
+Extend `Renderer` from `plugin-renderer` with `@decorators.componentObserver`.
+
+```ts
+class MyRenderer extends Renderer {
+  init() {
+    this.rendererSystem = this.game.getSystem(RendererSystem);
+    this.rendererSystem.rendererManager.register(this);
+  }
+  componentChanged(changed: ComponentChanged) {
+    const container = this.rendererSystem.containerManager.getContainer(
+      changed.gameObject.id,
+    );
+    switch (changed.type) {
+      case OBSERVER_TYPE.ADD: /* create pixi object, container.addChild(obj) */ break;
+      case OBSERVER_TYPE.CHANGE: /* mutate */ break;
+      case OBSERVER_TYPE.REMOVE: /* destroy + container.removeChild */ break;
+    }
+  }
+  rendererUpdate(gameObject) {
+    /* per-frame sync */
+  }
+}
+```
+
+`RendererSystem` must be added before any system calling `getSystem(RendererSystem)` in `init`.
+
+## 3D Three.js `Renderer3D` subclass (`@combos-fun/plugin-renderer-3d`)
+
+Extend `Renderer3D` with `@decorators.componentObserver`.
+
+```ts
+class MyRenderer3D extends Renderer3D {
+  init() {
+    this.rendererSystem = this.game.getSystem(Renderer3DSystem);
+    this.rendererSystem.rendererManager.register(this);
+  }
+  componentChanged(changed) {
+    const scene = this.threeContext.scene;
+    /* create / mutate / dispose THREE.Object3D */
+  }
+  rendererUpdate(gameObject) { /* per-frame */ }
+}
+```
+
+`Renderer3DSystem` must be added before any system calling `getSystem(Renderer3DSystem)` in `init`.
+
+**Async loading pattern** (3D only): use the inherited `increaseAsyncId(id)` before async work and `validateAsyncId(id, asyncId)` after each `await` to cancel stale operations when the component is removed mid-load.
+
+## `combos-plugin.json` (manifest)
+
+Validate against `schemas/combos-plugin.schema.json`. Required fields: `name`, `pluginId`, `category`, `dimension`, `agentSkill`. For non-core packages, `category` ∈ {`rendering`, `physics`, `audio`, `input`, `ui`, `a11y`, `animation`, `devtool`, `other`} and `dimension` ∈ {`2d`, `3d`, `shared`}.
+
+## `agent-skill.md` template (per-plugin notes)
+
+```md
+# <plugin-name> — Agent notes
+
+## When to read
+<!-- which tasks should load this -->
+
+## Public API
+<!-- exported components / systems / params -->
+
+## Required setup
+<!-- system registration order, dependencies -->
+
+## Runtime behaviour
+<!-- lifecycle interactions, frame-order specifics -->
+
+## Common pitfalls
+<!-- blank canvas, missing systems, async stale, etc -->
+
+## Minimal example
+<!-- shortest copy-pasteable snippet -->
+
+## Verification
+<!-- how to run / test the plugin after changes -->
+```
+
+## Build & publish requirements (npm-published plugins only)
+
+- Build: CJS / ESM + `.d.ts` to `dist/` via `node ../../scripts/build-package.mjs`.
+- Peer / runtime deps: `@combos-fun/engine`, optionally `plugin-renderer` + `pixi.js` (for 2D renderer plugins) or `plugin-renderer-3d` + `three` (for 3D renderer plugins).
+- `package.json`: include `agent-skill.md` and `combos-plugin.json` in `files`; expose `./plugin-manifest` and `./agent-skill` in `exports`.
+- Run `pnpm validate-plugin-manifests --strict` and `pnpm plugin-index:check` before publishing. The publish script does this automatically.
+- Duplicate registration of the same System class is warned and skipped.
+
+Project-local plugins skip all of this: no build, no manifest, no schema validation, no exports, no publish. The Component / System / Renderer code itself is identical.