@combos-fun/engine 0.0.35 → 0.0.37

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,120 +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: One render Component per GameObject
-
-A GameObject may carry at most one visible render Component. Do not attach multiple render Components such as `Img` + `Text`, `Graphics` + `Sprite`, or multiple sprite renderers to the same GameObject. Create child or sibling GameObjects for additional visible elements and use the Transform hierarchy to compose them. This keeps renderer ownership, bounds, picking, ordering, and destruction deterministic.
-
-### Rule 7: 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
 
@@ -141,166 +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.35";
+const version = "0.0.37";
 
 /**
  * Sent to `window.parent` after each `System.init` completes during `Game.addSystem`