@combos-fun/engine 0.0.11 → 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/dist/engine.cjs.js

@@ -35,6 +35,12 @@ function getComponentName(component) {
  * @public
  */
 class Component extends EventEmitter__default.default {
+    /**
+     * Get the game instance this component belongs to
+     */
+    get game() {
+        return this.gameObject?.scene?.game;
+    }
     constructor(params) {
         super();
         /**
@@ -80,8 +86,10 @@ function getObjectCache(component, keys) {
     }
     const keyIndex = keys.length - 1;
     let property = component;
-    // FIXME: Bug is here, property[keys[i]] maybe undefined
     for (let i = 0; i < keyIndex; i++) {
+        if (property[keys[i]] === undefined || property[keys[i]] === null) {
+            return { property: undefined, key: undefined };
+        }
         property = property[keys[i]];
     }
     cache[key] = { property, key: keys[keyIndex] };
@@ -321,7 +329,7 @@ class Transform extends Component {
         for (const key of props) {
             Object.assign(this[key], params[key]);
         }
-        this.rotation = params.rotation || this.rotation;
+        this.rotation = params.rotation ?? this.rotation;
     }
     set parent(val) {
         if (val) {
@@ -584,7 +592,7 @@ class GameObject {
         if (this.parent)
             return this.parent.removeChild(this);
     }
-    /** Destory this gameObject */
+    /** Destroy this gameObject */
     destroy() {
         if (!this.transform) {
             console.error('Cannot destroy gameObject that have already been destroyed.');
@@ -678,7 +686,7 @@ class System {
         const Ctor = this.constructor;
         this.name = Ctor.systemName;
     }
-    /** Default destory method */
+    /** Default destroy method */
     destroy() {
         this.componentObserver = null;
         this.__systemDefaultParams = null;
@@ -873,6 +881,7 @@ class Ticker {
             this._lastFrameTime = frameTime;
             const options = {
                 deltaTime,
+                delta: deltaTime,
                 time: frameTime,
                 currentTime: frameTime,
                 frameCount: ++this._frameCount,
@@ -1069,7 +1078,7 @@ const gameObjectPause = (gameObjects) => {
                 component.onPause && component.onPause();
             }
             catch (e) {
-                console.error(`gameObject: ${gameObject.name}, ${component.name}, onResume error`, e);
+                console.error(`gameObject: ${gameObject.name}, ${component.name}, onPause error`, e);
             }
         }
     }
@@ -1109,7 +1118,7 @@ class Game extends EventEmitter__default.default {
                 await this.addSystem(system);
             }
             if (needScene) {
-                this.loadScene(new Scene("scene"));
+                this.loadScene({ scene: new Scene("scene") });
             }
             if (autoStart) {
                 this.start();
@@ -1315,6 +1324,7 @@ class Game extends EventEmitter__default.default {
         if (!scene) {
             return;
         }
+        scene.game = this;
         switch (mode) {
             case exports.LOAD_SCENE_MODE.SINGLE:
                 this.scene = scene;
@@ -1538,7 +1548,7 @@ class Resource extends EventEmitter__default.default {
         const res = this.resourcesMap[name];
         return this.makeInstanceFunctions[res.type] && (await this.makeInstanceFunctions[res.type](res));
     }
-    /** destory this resource manager */
+    /** Destroy resource by name */
     async destroy(name) {
         await this._destroy(name);
     }