@combos-fun/engine 0.0.34 → 0.0.36

package/agent-skill.md

@@ -1,10 +1,12 @@
-# `@combos-fun/engine` — Agent notes
+# `@combos-fun/engine` — Agent short card
 
-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.
+ECS microkernel for Combos Fun. **Short card only** — do not re-cat after the first read. For authoring a new `@combos-fun/plugin-*`, read `@combos-fun/engine/plugin-authoring`.
 
 ## 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.
+Open this card **only when** an existing-project hard gate allows a plugin skill read (unfamiliar compile symbol / new plugin / real API conflict), or when starting from zero after mode detection. **Do not** load it every turn, and **do not** bulk-read sibling plugin skills with it.
+
+Public API tables, host `postMessage` protocol, and long bootstrap samples: [`references/public-api.md`](references/public-api.md), [`references/bootstrap-examples.md`](references/bootstrap-examples.md).
 
 ## Microkernel model
 
@@ -13,116 +15,14 @@ Read this every time before working on a Combos Fun project. The entry skill loa
 - **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`, `COMBOS_GAME_READY`, `COMBOS_GAME_SET_PLAYING`, `COMBOS_GAME_STATE_CHANGED`, `postParentPluginInitSuccess`, `postParentGameReady`, `postParentGameState`, `parseSetPlayingMessage`, `DEFAULT_ALLOWED_MESSAGE_HOST_SUFFIXES`, `isAllowedMessageOrigin`, `mergeAllowedMessageOrigins`.
-
-### Types
-
-`GameParams`, `PluginStruct`, `TransformParams`, `ComponentChanged`, `UpdateParams`, `ComponentParams`, `ObserverInfo`, `PureObserverInfo`, `ResourceBase`, `SystemConstructor`, `CombosGamePluginInitSuccessMessage`, `CombosGameReadyMessage`, `CombosGameStateChangedMessage`, `CombosGameSetPlayingMessage`.
-
-### `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`                 | `'*'`   | Outbound postMessage target (init / ready / state) |
-| `allowedMessageOrigins`        | `string[]`               | defaults | Inbound origins allowed to send `set-playing` (merged with defaults; `['*']` = any) |
-
-
-When the game runs inside an iframe (`window.parent !== window`), each `Game.addSystem` call posts to the parent after that system's `init` completes:
-
-```typescript
-{
-  type: 'combos-game:plugin-init-success',
-  systemName: string,       // System.systemName
-  engineVersion: string,    // @combos-fun/engine build version
-  packageName?: string,     // npm name, injected at plugin build
-  packageVersion?: string,  // semver from plugin package.json, injected at plugin build
-}
-```
-
-Official `@combos-fun/plugin-*` packages get `packageName` / `packageVersion` automatically via `scripts/build-package.mjs` (no hand-written static fields). Host pages can gate tooling on specific systems or versions using this payload. Types: `CombosGamePluginInitSuccessMessage`, helper `postParentPluginInitSuccess` in `bootstrapMessages.ts`.
-
-### Host lifecycle protocol (preload → hold → play)
-
-Core `Game` speaks a `postMessage` protocol with the embedding page so a host APP can preload, hold, then start the game on user intent. All outbound messages go to `pluginInitNotifyTargetOrigin`; the inbound command is origin-checked against `allowedMessageOrigins`.
-
-**Outbound (iframe → parent):**
-
-| Type | When | Payload |
-| ---- | ---- | ------- |
-| `combos-game:ready` | Bootstrap finished (systems `init`/`awake`, optional scene load & start). Sent once even with `autoStart:false`. | `{ engineVersion, error? }` |
-| `combos-game:state-changed` | After `start` / `pause` / `resume` | `{ playing, started }` |
-
-**Inbound (parent → iframe):**
-
-| Type | Effect | Payload |
-| ---- | ------ | ------- |
-| `combos-game:set-playing` | `true` → cold `start()` on first play, else `resume()`; `false` → `pause()` | `{ playing: boolean }` |
-
-Recommended flow: create the game with `autoStart:false`, wait for `combos-game:ready`, keep the game held at frame 0 (host shows a cover/loading overlay), then post `{ type: 'combos-game:set-playing', playing: true }` when the user taps play. `game.setPlaying(playing)` is the programmatic equivalent. Helpers: `postParentGameReady`, `postParentGameState`, `parseSetPlayingMessage`.
-
-> Note: play/pause is owned by the engine core here, **not** by `plugin-development-tool` (which now only handles pick mode + mute).
-
-
-### `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()`, `setPlaying(playing)` (host bridge: cold-start-or-resume / pause), `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`.
-
-> ⚠️ `addResource` only registers; it does **not** kick off network load. Components that reference an unloaded `resource` (e.g. `Img({ resource: 'logo' })`) silently render nothing — the canvas stays blank with no console error. Always pair it with `preload()` (and gate `new Game(...)` behind `resource.once(LOAD_EVENT.COMPLETE, ...)`), or skip the pair entirely and use `loadConfig(resources[])` which does both in one call.
-
 ## 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. Every `.on(...)` / `addEventListener(...)` subscription set up in `start` / `awake` must be torn down in `onDestroy`.
-
-### 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. Every custom Component subclass must set `static componentName`; every custom System reacts via `@decorators.componentObserver({ Name: ['prop'] })` and drains observations in `update()` — never via ad-hoc scans of the scene graph.
-
-### 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.
+1. **Entity state in Components** — no module-scope / closure entity stores. Destroying a `GameObject` must drop its state.
+2. **Behaviour in Component / System hooks** — no bootstrap event handlers, no `setInterval` / `game.ticker.add` for game logic; tear down listeners in `onDestroy`.
+3. **Bootstrap only wires** — create Game / Systems / GameObjects / Components; no game `if` / loops in entry files.
+4. **One concern per Component; cross-entity logic in Systems** — custom types need `static componentName` / observer drain, not ad-hoc scene scans.
+5. **No raw Pixi / Three / DOM outside Renderer pattern** — use `plugin-renderer-*` / `plugin-renderer-3d-*` or registered `Renderer` / `Renderer3D`.
+6. **Configure via constructor params** — runtime triggers from other Component hooks, not bootstrap.
 
 ## Decision flowchart
 
@@ -137,167 +37,18 @@ Runs only once at startup to wire things?
     └── Rendering integration → Renderer (2D) / Renderer3D (3D) subclass
 ```
 
-## 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`                                                                                          |
-| 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,
-  GameObject,
-  resource,
-  RESOURCE_TYPE,
-  LOAD_EVENT,
-} from "@combos-fun/engine";
-import { RendererSystem } from "@combos-fun/plugin-renderer";
-import { Render, RenderSystem } from "@combos-fun/plugin-renderer-render";
-import { Img, ImgSystem } from "@combos-fun/plugin-renderer-img";
-
-resource.once(LOAD_EVENT.COMPLETE, () => {
-  new Game({
-    systems: [
-      new RendererSystem({
-        canvas: document.querySelector("#canvas")!,
-        width: 750,
-        height: 1334,
-      }),
-      new RenderSystem(),
-      new ImgSystem(),
-    ],
-    // Safe place to wire the scene graph: every system has finished init.
-    onSystemsBootstrapComplete: (g) => {
-      // Transform values go through constructor params — never set them imperatively.
-      const logo = new GameObject("logo", {
-        position: { x: 100, y: 100 },
-        size: { width: 200, height: 200 },
-        origin: { x: 0.5, y: 0.5 },
-      });
-      logo.addComponent(new Img({ resource: "logo" }));
-      // Render is only needed when you want to hide / fade / reorder; without it the
-      // object is still drawn at alpha 1, zIndex 0. Requires RenderSystem registered.
-      logo.addComponent(new Render({ zIndex: 5 }));
-      // Use addChild — not addGameObject — so transform parent + scene are both wired.
-      g.scene.addChild(logo);
-    },
-  });
-});
-
-resource.loadConfig([
-  {
-    name: "logo",
-    type: RESOURCE_TYPE.IMAGE,
-    src: { image: { type: "png", url: "logo.png" } },
-    preload: true,
-  },
-]);
-```
-
-`ResourceBase` requires both `type: RESOURCE_TYPE` and a nested `src` object keyed by media slot (`image` / `json` / `audio` / `video` / `tex` / `ske` / …) where each slot is `{ type, url }`. A flat `src: 'logo.png'` is invalid.
-
-## Minimal 3D bootstrap
-
-```ts
-import { Game, GameObject } from "@combos-fun/engine";
-import { Renderer3DSystem } from "@combos-fun/plugin-renderer-3d";
-import {
-  Graphics3D,
-  Graphics3DSystem,
-} from "@combos-fun/plugin-renderer-3d-graphics";
-
-new Game({
-  systems: [
-    new Renderer3DSystem({
-      canvas: document.querySelector("#canvas")!,
-      width: 750,
-      height: 1000,
-    }),
-    new Graphics3DSystem(),
-  ],
-  // Safe place to wire the scene graph: every system has finished init.
-  onSystemsBootstrapComplete: (g) => {
-    // 3D position / rotation / scale go through the component's own params
-    // (positionX/Y/Z, rotationX/Y/Z, scaleX/Y/Z) — GameObject's TransformParams
-    // is 2D-only (Vector2 + Size2) and is not read by 3D renderers.
-    const box = new GameObject("box");
-    box.addComponent(
-      new Graphics3D({
-        shape: "box",
-        width: 1,
-        height: 1,
-        depth: 1,
-        color: 0xff0000,
-        positionX: 0,
-        positionY: 1,
-        positionZ: 0,
-      }),
-    );
-    // Use addChild — not addGameObject — so transform parent + scene are both wired.
-    g.scene.addChild(box);
-  },
-});
-```
-
-## Verification
-
-After modifying engine code:
-
-1. `pnpm typecheck`
-2. `pnpm run build` (rebuild all packages in dependency order)
-3. `pnpm validate-plugin-manifests:strict`
-4. Run an example app from `examples/` and verify no console errors
+| Symptom | Fix |
+| --- | --- |
+| Blank canvas | Base renderer system registered; `autoStart` or `game.start()` |
+| Nothing draws | Matching sub-system (e.g. `ImgSystem`) before components |
+| `getSystem` undefined | Pass class, not string |
+| Resource missing / blank sprite | `loadConfig` or `addResource` + `preload` + `LOAD_EVENT.COMPLETE` before use |
+| TS / runtime API guess wrong | Prefer `$combos-engine-development` → `references/api-guessing-cases.md`, not `node_modules` digs |
 
 ## 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.
-
+- [`references/public-api.md`](references/public-api.md) — exports, `GameParams`, host lifecycle, `resource` API
+- [`references/bootstrap-examples.md`](references/bootstrap-examples.md) — minimal 2D / 3D samples
+- `@combos-fun/engine/plugin-authoring` — new plugin package spec

package/dist/engine.cjs.js

@@ -1001,7 +1001,7 @@ class Scene extends GameObject {
 }
 
 /** Generated at build from package.json */
-const version = "0.0.34";
+const version = "0.0.36";
 
 /**
  * Sent to `window.parent` after each `System.init` completes during `Game.addSystem`