@combos-fun/engine 0.0.7 → 0.0.8

package/agent-skill.md

@@ -1,43 +1,27 @@
 # `@combos-fun/engine` — Agent notes
 
-ECS microkernel for Combos Fun. This file is the canonical knowledge source for
-the engine and the standard for authoring any new `@combos-fun/plugin-*`.
+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
 
-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.
+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.
 
 ## 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.
+- **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.
 
 ## 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`, `postParentPluginInitSuccess`.
+`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`, `postParentPluginInitSuccess`.
 
 ### Types
 
-`GameParams`, `PluginStruct`, `TransformParams`, `ComponentChanged`,
-`UpdateParams`, `ComponentParams`, `ObserverInfo`, `PureObserverInfo`,
-`ResourceBase`, `SystemConstructor`,
-`CombosGamePluginInitSuccessMessage`.
+`GameParams`, `PluginStruct`, `TransformParams`, `ComponentChanged`, `UpdateParams`, `ComponentParams`, `ObserverInfo`, `PureObserverInfo`, `ResourceBase`, `SystemConstructor`, `CombosGamePluginInitSuccessMessage`.
 
 ### `GameParams`
 
@@ -52,11 +36,7 @@ loads this file as part of "Core" packages, regardless of 2D / 3D mode.
 
 ### `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()`, `destroy()`.
+`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()`, `destroy()`.
 
 ### `resource` singleton
 
@@ -75,55 +55,31 @@ Fields: `timeout` (6000ms), `resourcesMap`, `progress`.
 
 ## ECS hard rules (mandatory)
 
-These rules apply to every code change. Violations must be fixed before the
-change is considered complete.
+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.
+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.
+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.
 
 ### 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.
+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.
+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.
 
 ### 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
 
-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.
+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.
 
 ## Decision flowchart
 
@@ -142,26 +98,20 @@ Runs only once at startup to wire things?
 
 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 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
+- [ ] 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**:
+After every development task, write or update three inventory tables in the **project memory**:
 
 **Component inventory** — for each custom Component:
 
@@ -192,206 +142,6 @@ After every development task, write or update three inventory tables in the
 
 Skipping inventory is treated with the same weight as the ECS hard rules.
 
-## Plugin authoring (the standard for `@combos-fun/plugin-*`)
-
-A plugin is `Component(s)` + optional `System(s)` + optional `Renderer` /
-`Renderer3D` subclass, shipped as an npm package or local package under the
-`@combos-fun/` namespace.
-
-### Required package layout
-
-```
-packages/<plugin-name>/
-  package.json
-  combos-plugin.json    # machine-readable manifest (see schemas/combos-plugin.schema.json)
-  agent-skill.md        # per-package agent notes
-  README.md             # human-facing docs
-  index.js              # CJS entry
-  lib/                  # TypeScript sources
-  dist/                 # built CJS / ESM / .d.ts (created by build-package.mjs)
-```
-
-### Required `package.json` fields
-
-```json
-{
-  "name": "@combos-fun/plugin-xxx",
-  "files": ["dist", "index.js", "agent-skill.md", "combos-plugin.json"],
-  "exports": {
-    ".": "./dist/plugin-xxx.esm.js",
-    "./plugin-manifest": "./combos-plugin.json",
-    "./agent-skill": "./agent-skill.md"
-  },
-  "combos": {
-    "pluginManifest": "./combos-plugin.json"
-  }
-}
-```
-
-The `./plugin-manifest` and `./agent-skill` subpaths are part of the public
-contract. External Agents resolve documentation via these stable subpaths.
-Renaming the underlying files without updating `exports` is a breaking
-change.
-
-### Component subclass
-
-Subclass `Component` from `@combos-fun/engine`. Set
-`static componentName = 'MyFeature'`.
-
-Lifecycle (all optional):
-
-| Hook | When |
-|------|------|
-| `init(params?)` | During construction |
-| `awake()` | When added to a GameObject |
-| `start()` | Inline on first `update` tick (same frame as first `update`) |
-| `update(frame)` | Every frame (`frame.deltaTime` in ms) |
-| `lateUpdate(frame)` | After all components' `update`, before any `System.update` |
-| `onPause()` / `onResume()` | Game pause / resume |
-| `onDestroy()` | Component or GameObject destroyed |
-
-`UpdateParams`: `deltaTime`, `frameCount`, `time`, `currentTime`, `fps`.
-
-### System subclass
-
-Subclass `System`. Set `static systemName = 'MyFeatureSystem'`.
-
-Decorate with `@decorators.componentObserver({ MyFeature: ['power'] })`:
-
-- `[]` (empty array) → ADD / REMOVE only
-- `['prop']` → CHANGE on set
-- `{ prop: ['a','b'], deep: true }` → deep change watching
-
-In `update()`:
-
-```ts
-const changes = this.componentObserver.clear();
-for (const c of changes) {
-  switch (c.type) {
-    case OBSERVER_TYPE.ADD:    /* c.component, c.gameObject */ break;
-    case OBSERVER_TYPE.CHANGE: /* c.prop?: { deep, prop: string[] } */ break;
-    case OBSERVER_TYPE.REMOVE: break;
-  }
-}
-```
-
-System lifecycle is the same as Component (`init` can be async). `init`
-receives constructor params; `this.game` is available.
-
-`System.destroy()` nulls internals and calls `onDestroy()` but **does not**
-remove the system from Game. Always call `game.removeSystem(system)`, which
-calls `destroy()` internally.
-
-### `ComponentChanged` shape
-
-`type: OBSERVER_TYPE`, `component`, `componentName`, `gameObject`,
-`prop?: { deep, prop: string[] }`.
-
-### 2D Pixi `Renderer` subclass (`@combos-fun/plugin-renderer`)
-
-Extend `Renderer` from `plugin-renderer` with `@decorators.componentObserver`.
-
-```ts
-class MyRenderer extends Renderer {
-  init() {
-    this.rendererSystem = this.game.getSystem(RendererSystem);
-    this.rendererSystem.rendererManager.register(this);
-  }
-  componentChanged(changed: ComponentChanged) {
-    const container = this.rendererSystem.containerManager.getContainer(
-      changed.gameObject.id,
-    );
-    switch (changed.type) {
-      case OBSERVER_TYPE.ADD: /* create pixi object, container.addChild(obj) */ break;
-      case OBSERVER_TYPE.CHANGE: /* mutate */ break;
-      case OBSERVER_TYPE.REMOVE: /* destroy + container.removeChild */ break;
-    }
-  }
-  rendererUpdate(gameObject) {
-    /* per-frame sync */
-  }
-}
-```
-
-`RendererSystem` must be added before any system calling
-`getSystem(RendererSystem)` in `init`.
-
-### 3D Three.js `Renderer3D` subclass (`@combos-fun/plugin-renderer-3d`)
-
-Extend `Renderer3D` with `@decorators.componentObserver`.
-
-```ts
-class MyRenderer3D extends Renderer3D {
-  init() {
-    this.rendererSystem = this.game.getSystem(Renderer3DSystem);
-    this.rendererSystem.rendererManager.register(this);
-  }
-  componentChanged(changed) {
-    const scene = this.threeContext.scene;
-    /* create / mutate / dispose THREE.Object3D */
-  }
-  rendererUpdate(gameObject) { /* per-frame */ }
-}
-```
-
-`Renderer3DSystem` must be added before any system calling
-`getSystem(Renderer3DSystem)` in `init`.
-
-**Async loading pattern** (3D only): use the inherited `increaseAsyncId(id)`
-before async work and `validateAsyncId(id, asyncId)` after each `await` to
-cancel stale operations when the component is removed mid-load.
-
-### `combos-plugin.json` (manifest)
-
-Validate against `schemas/combos-plugin.schema.json`. Required fields:
-`name`, `pluginId`, `category`, `dimension`, `agentSkill`. For non-core
-packages, `category` ∈ {`rendering`, `physics`, `audio`, `input`, `ui`,
-`a11y`, `animation`, `devtool`, `other`} and `dimension` ∈ {`2d`, `3d`,
-`shared`}.
-
-### `agent-skill.md` (per-plugin notes)
-
-Use this template:
-
-```md
-# <plugin-name> — Agent notes
-
-## When to read
-<!-- which tasks should load this -->
-
-## Public API
-<!-- exported components / systems / params -->
-
-## Required setup
-<!-- system registration order, dependencies -->
-
-## Runtime behaviour
-<!-- lifecycle interactions, frame-order specifics -->
-
-## Common pitfalls
-<!-- blank canvas, missing systems, async stale, etc -->
-
-## Minimal example
-<!-- shortest copy-pasteable snippet -->
-
-## Verification
-<!-- how to run / test the plugin after changes -->
-```
-
-### Build & publish requirements
-
-- Build: CJS / ESM + `.d.ts` to `dist/` via
-  `node ../../scripts/build-package.mjs`.
-- Peer / runtime deps: `@combos-fun/engine`, optionally `plugin-renderer` +
-  `pixi.js` (for 2D renderer plugins) or `plugin-renderer-3d` + `three` (for
-  3D renderer plugins).
-- `package.json`: include `agent-skill.md` and `combos-plugin.json` in
-  `files`; expose `./plugin-manifest` and `./agent-skill` in `exports`.
-- Run `pnpm validate-plugin-manifests --strict` and
-  `pnpm plugin-index:check` before publishing. The publish script does
-  this automatically.
-- Duplicate registration of the same System class is warned and skipped.
-
 ## Common pitfalls
 
 | Symptom | Fix |
@@ -442,10 +192,14 @@ new Game({
 
 ## Verification
 
-After modifying engine code or plugin authoring rules:
+After modifying engine code:
 
 1. `pnpm typecheck`
 2. `pnpm run build` (rebuild all packages in dependency order)
 3. `pnpm validate-plugin-manifests` (warn during migration, strict at GA)
 4. `pnpm plugin-index:check`
 5. Run an example app from `examples/` and verify no console errors
+
+## 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.7",
+  "version": "0.0.8",
   "description": "@combos-fun/engine",
   "main": "index.js",
   "module": "dist/engine.esm.js",
@@ -10,6 +10,7 @@
     "index.js",
     "dist",
     "agent-skill.md",
+    "plugin-authoring.md",
     "combos-plugin.json"
   ],
   "exports": {
@@ -19,7 +20,8 @@
       "types": "./dist/engine.d.ts"
     },
     "./plugin-manifest": "./combos-plugin.json",
-    "./agent-skill": "./agent-skill.md"
+    "./agent-skill": "./agent-skill.md",
+    "./plugin-authoring": "./plugin-authoring.md"
   },
   "combos": {
     "pluginManifest": "./combos-plugin.json"
@@ -35,7 +37,7 @@
     "lodash-es": "^4.17.21",
     "resource-loader": "^4.0.0-rc4",
     "sprite-timeline": "^1.10.2",
-    "@combos-fun/inspector-decorator": "0.0.7"
+    "@combos-fun/inspector-decorator": "0.0.8"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.mjs"

package/plugin-authoring.md

@@ -0,0 +1,187 @@
+# `@combos-fun/engine` — Plugin authoring spec
+
+This file is the standard for authoring any new `@combos-fun/plugin-*` package — npm-published or project-local. Read it only when you are **creating** a plugin. Day-to-day engine usage is covered in `@combos-fun/engine/agent-skill`.
+
+A plugin is `Component(s)` + optional `System(s)` + optional `Renderer` / `Renderer3D` subclass, shipped under the `@combos-fun/` namespace as an npm package or as a folder inside a user project.
+
+## When to read
+
+- You are adding a new feature that does not match any existing `@combos-fun/plugin-*` keyword.
+- You are publishing a new plugin to npm under `@combos-fun/*`.
+- You are forking / extending an existing plugin's `Renderer` / `Renderer3D` subclass.
+
+For pure consumption of existing plugins, this file is not required — read `@combos-fun/engine/agent-skill` plus each plugin's `agent-skill` instead.
+
+## Required package layout
+
+```
+packages/<plugin-name>/
+  package.json
+  combos-plugin.json    # machine-readable manifest (validated against schemas/combos-plugin.schema.json)
+  agent-skill.md        # per-package agent notes
+  README.md             # human-facing docs
+  index.js              # CJS entry
+  lib/                  # TypeScript sources
+  dist/                 # built CJS / ESM / .d.ts (created by build-package.mjs)
+```
+
+Project-local plugins (not published to npm) may skip `dist/`, the build step, and `combos-plugin.json` — but adopting both unlocks the same selection logic the entry skill uses for official plugins.
+
+## Required `package.json` fields
+
+```json
+{
+  "name": "@combos-fun/plugin-xxx",
+  "files": ["dist", "index.js", "agent-skill.md", "combos-plugin.json"],
+  "exports": {
+    ".": "./dist/plugin-xxx.esm.js",
+    "./plugin-manifest": "./combos-plugin.json",
+    "./agent-skill": "./agent-skill.md"
+  },
+  "combos": {
+    "pluginManifest": "./combos-plugin.json"
+  }
+}
+```
+
+The `./plugin-manifest` and `./agent-skill` subpaths are part of the public contract. External Agents resolve documentation via these stable subpaths. Renaming the underlying files without updating `exports` is a breaking change.
+
+## Component subclass
+
+Subclass `Component` from `@combos-fun/engine`. Set `static componentName = 'MyFeature'`.
+
+Lifecycle (all optional):
+
+| Hook | When |
+|------|------|
+| `init(params?)` | During construction |
+| `awake()` | When added to a GameObject |
+| `start()` | Inline on first `update` tick (same frame as first `update`) |
+| `update(frame)` | Every frame (`frame.deltaTime` in ms) |
+| `lateUpdate(frame)` | After all components' `update`, before any `System.update` |
+| `onPause()` / `onResume()` | Game pause / resume |
+| `onDestroy()` | Component or GameObject destroyed |
+
+`UpdateParams`: `deltaTime`, `frameCount`, `time`, `currentTime`, `fps`.
+
+## System subclass
+
+Subclass `System`. Set `static systemName = 'MyFeatureSystem'`.
+
+Decorate with `@decorators.componentObserver({ MyFeature: ['power'] })`:
+
+- `[]` (empty array) → ADD / REMOVE only
+- `['prop']` → CHANGE on set
+- `{ prop: ['a','b'], deep: true }` → deep change watching
+
+In `update()`:
+
+```ts
+const changes = this.componentObserver.clear();
+for (const c of changes) {
+  switch (c.type) {
+    case OBSERVER_TYPE.ADD:    /* c.component, c.gameObject */ break;
+    case OBSERVER_TYPE.CHANGE: /* c.prop?: { deep, prop: string[] } */ break;
+    case OBSERVER_TYPE.REMOVE: break;
+  }
+}
+```
+
+System lifecycle is the same as Component (`init` can be async). `init` receives constructor params; `this.game` is available.
+
+`System.destroy()` nulls internals and calls `onDestroy()` but **does not** remove the system from Game. Always call `game.removeSystem(system)`, which calls `destroy()` internally.
+
+### `ComponentChanged` shape
+
+`type: OBSERVER_TYPE`, `component`, `componentName`, `gameObject`, `prop?: { deep, prop: string[] }`.
+
+## 2D Pixi `Renderer` subclass (`@combos-fun/plugin-renderer`)
+
+Extend `Renderer` from `plugin-renderer` with `@decorators.componentObserver`.
+
+```ts
+class MyRenderer extends Renderer {
+  init() {
+    this.rendererSystem = this.game.getSystem(RendererSystem);
+    this.rendererSystem.rendererManager.register(this);
+  }
+  componentChanged(changed: ComponentChanged) {
+    const container = this.rendererSystem.containerManager.getContainer(
+      changed.gameObject.id,
+    );
+    switch (changed.type) {
+      case OBSERVER_TYPE.ADD: /* create pixi object, container.addChild(obj) */ break;
+      case OBSERVER_TYPE.CHANGE: /* mutate */ break;
+      case OBSERVER_TYPE.REMOVE: /* destroy + container.removeChild */ break;
+    }
+  }
+  rendererUpdate(gameObject) {
+    /* per-frame sync */
+  }
+}
+```
+
+`RendererSystem` must be added before any system calling `getSystem(RendererSystem)` in `init`.
+
+## 3D Three.js `Renderer3D` subclass (`@combos-fun/plugin-renderer-3d`)
+
+Extend `Renderer3D` with `@decorators.componentObserver`.
+
+```ts
+class MyRenderer3D extends Renderer3D {
+  init() {
+    this.rendererSystem = this.game.getSystem(Renderer3DSystem);
+    this.rendererSystem.rendererManager.register(this);
+  }
+  componentChanged(changed) {
+    const scene = this.threeContext.scene;
+    /* create / mutate / dispose THREE.Object3D */
+  }
+  rendererUpdate(gameObject) { /* per-frame */ }
+}
+```
+
+`Renderer3DSystem` must be added before any system calling `getSystem(Renderer3DSystem)` in `init`.
+
+**Async loading pattern** (3D only): use the inherited `increaseAsyncId(id)` before async work and `validateAsyncId(id, asyncId)` after each `await` to cancel stale operations when the component is removed mid-load.
+
+## `combos-plugin.json` (manifest)
+
+Validate against `schemas/combos-plugin.schema.json`. Required fields: `name`, `pluginId`, `category`, `dimension`, `agentSkill`. For non-core packages, `category` ∈ {`rendering`, `physics`, `audio`, `input`, `ui`, `a11y`, `animation`, `devtool`, `other`} and `dimension` ∈ {`2d`, `3d`, `shared`}.
+
+## `agent-skill.md` template (per-plugin notes)
+
+```md
+# <plugin-name> — Agent notes
+
+## When to read
+<!-- which tasks should load this -->
+
+## Public API
+<!-- exported components / systems / params -->
+
+## Required setup
+<!-- system registration order, dependencies -->
+
+## Runtime behaviour
+<!-- lifecycle interactions, frame-order specifics -->
+
+## Common pitfalls
+<!-- blank canvas, missing systems, async stale, etc -->
+
+## Minimal example
+<!-- shortest copy-pasteable snippet -->
+
+## Verification
+<!-- how to run / test the plugin after changes -->
+```
+
+## Build & publish requirements (npm-published plugins only)
+
+- Build: CJS / ESM + `.d.ts` to `dist/` via `node ../../scripts/build-package.mjs`.
+- Peer / runtime deps: `@combos-fun/engine`, optionally `plugin-renderer` + `pixi.js` (for 2D renderer plugins) or `plugin-renderer-3d` + `three` (for 3D renderer plugins).
+- `package.json`: include `agent-skill.md` and `combos-plugin.json` in `files`; expose `./plugin-manifest` and `./agent-skill` in `exports`.
+- Run `pnpm validate-plugin-manifests --strict` and `pnpm plugin-index:check` before publishing. The publish script does this automatically.
+- Duplicate registration of the same System class is warned and skipped.
+
+Project-local plugins skip all of this: no build, no manifest, no schema validation, no exports, no publish. The Component / System / Renderer code itself is identical.