@combos-fun/engine 0.0.35 → 0.0.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/engine",
-  "version": "0.0.35",
+  "version": "0.0.37",
   "description": "ECS microkernel",
   "main": "index.js",
   "module": "dist/engine.esm.js",
@@ -11,7 +11,8 @@
     "dist",
     "agent-skill.md",
     "plugin-authoring.md",
-    "combos-plugin.json"
+    "combos-plugin.json",
+    "references"
   ],
   "exports": {
     ".": {
@@ -21,7 +22,8 @@
     },
     "./plugin-manifest": "./combos-plugin.json",
     "./agent-skill": "./agent-skill.md",
-    "./plugin-authoring": "./plugin-authoring.md"
+    "./plugin-authoring": "./plugin-authoring.md",
+    "./references/*": "./references/*"
   },
   "combos": {
     "pluginManifest": "./combos-plugin.json"
@@ -39,11 +41,11 @@
   ],
   "author": "sun668 <q947692259@gmail.com>",
   "dependencies": {
+    "@combos-fun/inspector-decorator": "0.0.37",
     "eventemitter3": "^5.0.4",
     "lodash-es": "^4.17.21",
     "resource-loader": "^4.0.0-rc4",
-    "sprite-timeline": "^1.10.2",
-    "@combos-fun/inspector-decorator": "0.0.35"
+    "sprite-timeline": "^1.10.2"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.mjs"

package/references/bootstrap-examples.md

@@ -0,0 +1,111 @@
+# Bootstrap examples (on demand)
+
+Prefer the host template bootstrap. Use these only when starting from zero without a template.
+
+## 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
+

package/references/public-api.md

@@ -0,0 +1,87 @@
+# Engine Public API (on demand)
+
+Open only when the short `agent-skill` card is insufficient for a named symbol or host bridge.
+
+## 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.
+