@combos-fun/engine 0.0.12 → 0.0.13

package/agent-skill.md

@@ -1,6 +1,6 @@
 # `@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.
+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
 
@@ -25,14 +25,16 @@ Read this every time before working on a Combos Fun project. The entry skill loa
 
 ### `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 |
+
+| 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
 
@@ -40,19 +42,23 @@ Read this every time before working on a Combos Fun project. The entry skill loa
 
 ### `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 |
+
+| 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.
@@ -63,7 +69,7 @@ Any data belonging to a game entity must be a field on a `Component` attached to
 
 ### 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.
+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
 
@@ -71,11 +77,11 @@ The entry file may: register resources, create `Game` with `systems`, create `Ga
 
 ### 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.
+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.
+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
 
@@ -94,99 +100,154 @@ Runs only once at startup to wire things?
     └── 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 |
+
+| 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 |
+
+| 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 |
+
+| 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
+| 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                                                                         |
 
-```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 }]);
+## Minimal 2D bootstrap
 
-new Game({
-  systems: [
-    new RendererSystem({ canvas: document.querySelector('#canvas')!, width: 750, height: 1334 }),
-    new RenderSystem(),
-    new ImgSystem(),
-  ],
+```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 } from '@combos-fun/engine';
-import { Renderer3DSystem } from '@combos-fun/plugin-renderer-3d';
-import { Graphics3DSystem } from '@combos-fun/plugin-renderer-3d-graphics';
+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 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);
+  },
 });
 ```
 
@@ -202,3 +263,4 @@ After modifying engine code:
 ## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/engine",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "ECS microkernel",
   "main": "index.js",
   "module": "dist/engine.esm.js",
@@ -43,7 +43,7 @@
     "lodash-es": "^4.17.21",
     "resource-loader": "^4.0.0-rc4",
     "sprite-timeline": "^1.10.2",
-    "@combos-fun/inspector-decorator": "0.0.12"
+    "@combos-fun/inspector-decorator": "0.0.13"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.mjs"