@combos-fun/engine 0.0.44 → 0.0.46

package/agent-skill.md

@@ -1,53 +1,35 @@
 # `@combos-fun/engine` — Agent short card
 
-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`.
+Combos Fun ECS microkernel. For new `@combos-fun/plugin-*` packages, read `plugin-authoring.md`.
 
 ## When to read
 
-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 and host `postMessage` protocol: [`references/public-api.md`](references/public-api.md).
+Read when starting an engine task or resolving an engine API/lifecycle question. Public API and host protocol details are in [`references/public-api.md`](references/public-api.md).
 
 ## Microkernel model
 
-- **Kernel** `@combos-fun/engine`: `Game`, `Scene`, `GameObject`, `Component`, `System`, `Transform`, `resource`, `decorators`. **No** built-in rendering / physics / audio.
-- **Extension**: `game.addSystem(new XxxSystem(...))` then `gameObject.addComponent(new Xxx(...))`.
-- **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.
-
-## ECS hard rules (mandatory)
-
-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
-
-```
-Runs only once at startup to wire things?
-├── YES: Only creates GameObjects/Components/Systems/resources?
-│   ├── YES → bootstrap / entry file
-│   └── NO (contains logic) → Component or System
-└── NO: Runs per-frame or reacts to events?
-    ├── Single-entity concern → Component
-    ├── Cross-entity concern → System with @componentObserver
-    └── Rendering integration → Renderer (2D) / Renderer3D (3D) subclass
-```
+- Core: `Game`, `Scene`, `GameObject`, `Component`, `System`, `Transform`, `resource`, `decorators`; rendering, physics, and audio come from plugins.
+- Register an instance with `await game.addSystem(new XxxSystem(...))`; `Game({ systems })` awaits each system's `init`. Avoid `addSystem(XxxSystem, [params])`: runtime passes the tuple as one constructor argument.
+- Observe components with `@decorators.componentObserver({ Name: ['prop'] })`, then drain `componentObserver.clear()` in `update()`.
+- Frame order: all `Component.update` → all `Component.lateUpdate` → all `System.update` → all `System.lateUpdate`. `start()` runs on the first update tick.
+
+## ECS hard rules
+
+1. Keep per-entity state in Components so destroying a `GameObject` removes it.
+2. Put single-entity behavior in Component hooks and cross-entity behavior in Systems; clean up listeners in `onDestroy`.
+3. Bootstrap only creates and wires resources, Systems, GameObjects, and Components.
+4. Use `static componentName` for custom Components and observers rather than ad-hoc scene scans.
+5. Game code uses renderer plugins or registered `Renderer` / `Renderer3D` subclasses, not raw Pixi, Three, or DOM. Host-owning plugins are exceptions.
+6. Configure through constructor params; trigger runtime actions from lifecycle/event Components.
 
 ## Common pitfalls
 
-| 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 |
+- Prefer `game.getSystem(SystemClass)`. String lookup matches `static systemName`, not the class name.
+- A blank canvas usually means the base renderer is missing or the game is not started; missing content usually means its renderer subsystem is absent.
+- Register resources with `resource.addResource`; `preload` only removes first-use delay.
+- `@Field` details belong to `@combos-fun/inspector-decorator`; engine `IDEProp` is legacy.
 
 ## See also
 
-- [`references/public-api.md`](references/public-api.md) — exports, `GameParams`, host lifecycle, `resource` API
-- `@combos-fun/engine/plugin-authoring` — new plugin package spec
+- [`references/public-api.md`](references/public-api.md)
+- [`plugin-authoring.md`](plugin-authoring.md)

package/dist/engine.cjs.js

@@ -1001,7 +1001,7 @@ class Scene extends GameObject {
 }
 
 /** Generated at build from package.json */
-const version = "0.0.44";
+const version = "0.0.46";
 
 /**
  * Sent to `window.parent` after each `System.init` completes during `Game.addSystem`
@@ -1652,6 +1652,8 @@ const SLOT_DEFAULT_TYPE = {
     model: 'glb',
     mtl: 'mtl',
     bin: 'bin',
+    vertex: 'vert',
+    fragment: 'frag',
 };
 const EXT_TO_TYPE = {
     png: 'png',
@@ -1676,6 +1678,9 @@ const EXT_TO_TYPE = {
     dae: 'dae',
     ply: 'ply',
     bin: 'bin',
+    vert: 'vert',
+    frag: 'frag',
+    glsl: 'glsl',
 };
 function extensionOf(url) {
     const path = url.split('?')[0].split('#')[0];
@@ -1694,6 +1699,8 @@ function defaultSlotForResourceType(resourceType) {
         return 'video';
     if (resourceType === 'MODEL' || resourceType === 'GLB')
         return 'model';
+    if (resourceType === 'SHADER')
+        return 'fragment';
     return 'image';
 }
 function wrapSlot(slot, value, resourceName) {
@@ -1873,6 +1880,7 @@ exports.RESOURCE_TYPE = void 0;
     RESOURCE_TYPE["VIDEO"] = "VIDEO";
     RESOURCE_TYPE["GLB"] = "GLB";
     RESOURCE_TYPE["MODEL"] = "MODEL";
+    RESOURCE_TYPE["SHADER"] = "SHADER";
 })(exports.RESOURCE_TYPE || (exports.RESOURCE_TYPE = {}));
 resourceLoader$1.XhrLoadStrategy.setExtensionXhrType('json', resourceLoader$1.XhrResponseType.Json);
 resourceLoader$1.XhrLoadStrategy.setExtensionXhrType('tex', resourceLoader$1.XhrResponseType.Json);
@@ -1890,6 +1898,9 @@ resourceLoader$1.XhrLoadStrategy.setExtensionXhrType('bin', resourceLoader$1.Xhr
 resourceLoader$1.XhrLoadStrategy.setExtensionXhrType('obj', resourceLoader$1.XhrResponseType.Text);
 resourceLoader$1.XhrLoadStrategy.setExtensionXhrType('mtl', resourceLoader$1.XhrResponseType.Text);
 resourceLoader$1.XhrLoadStrategy.setExtensionXhrType('dae', resourceLoader$1.XhrResponseType.Text);
+resourceLoader$1.XhrLoadStrategy.setExtensionXhrType('vert', resourceLoader$1.XhrResponseType.Text);
+resourceLoader$1.XhrLoadStrategy.setExtensionXhrType('frag', resourceLoader$1.XhrResponseType.Text);
+resourceLoader$1.XhrLoadStrategy.setExtensionXhrType('glsl', resourceLoader$1.XhrResponseType.Text);
 const RESOURCE_TYPE_STRATEGY = {
     png: resourceLoader$1.ImageLoadStrategy,
     jpg: resourceLoader$1.ImageLoadStrategy,
@@ -1909,6 +1920,9 @@ const RESOURCE_TYPE_STRATEGY = {
     dae: resourceLoader$1.XhrLoadStrategy,
     ply: resourceLoader$1.XhrLoadStrategy,
     bin: resourceLoader$1.XhrLoadStrategy,
+    vert: resourceLoader$1.XhrLoadStrategy,
+    frag: resourceLoader$1.XhrLoadStrategy,
+    glsl: resourceLoader$1.XhrLoadStrategy,
 };
 /**
  * Resource manager
@@ -2150,6 +2164,10 @@ class Resource extends EventEmitter__default.default {
 }
 /** Resource manager single instance */
 const resource = new Resource();
+resource.registerInstance(exports.RESOURCE_TYPE.SHADER, (res) => ({
+    vertex: typeof res.data?.vertex === 'string' ? res.data.vertex : '',
+    fragment: typeof res.data?.fragment === 'string' ? res.data.fragment : '',
+}));
 
 /** Decorators util */
 const decorators = {