@combos-fun/plugin-renderer 0.0.5 → 0.0.7

package/README.md

@@ -1,3 +1,27 @@
 # @combos-fun/plugin-renderer
 
-Internal workspace package (Combos Fun monorepo).
+@combos-fun/plugin-renderer — part of the Combos Fun engine monorepo.
+
+Keywords: `pixi`, `rendering`, `canvas`, `2d`, `renderer-base`, `container`.
+
+## Documentation
+
+- Per-package agent / developer notes: [`agent-skill.md`](./agent-skill.md)
+- Machine-readable manifest: [`combos-plugin.json`](./combos-plugin.json)
+  (validated against `schemas/combos-plugin.schema.json` in the repo
+  root)
+- Entry skill (single source of truth for AI agents working with this
+  monorepo): `skills/combos-engine-development/SKILL.md`
+
+When consumed from npm, the manifest and agent notes are exposed as
+stable subpaths:
+
+```ts
+import manifest from '@combos-fun/plugin-renderer/plugin-manifest';
+// or fetch the markdown directly:
+// require.resolve('@combos-fun/plugin-renderer/agent-skill')
+```
+
+## License
+
+Internal workspace package, part of the Combos Fun engine monorepo.

package/agent-skill.md

@@ -0,0 +1,131 @@
+# `@combos-fun/plugin-renderer` — Agent notes
+
+2D rendering foundation for Combos Fun. Wraps Pixi v8 via
+`@combos-fun/renderer-adapter` and exposes the `RendererSystem`,
+`Renderer` base class, and the `containerManager` / `rendererManager`
+machinery that all 2D rendering sub-plugins extend.
+
+## When to read
+
+Read for any 2D rendering task: setting up a canvas, blank-canvas
+debugging, custom 2D renderer plugins, `Container` parenting / sorting.
+All `plugin-renderer-*` 2D sub-plugins assume this file is already
+loaded.
+
+## Public API
+
+```ts
+import {
+  RendererSystem,
+  Renderer,
+  RendererManager,
+  ContainerManager,
+  RENDERER_TYPE,
+} from '@combos-fun/plugin-renderer';
+```
+
+### `RendererSystem`
+
+`systemName = 'Renderer'`. Init params:
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| `canvas` | `HTMLCanvasElement` | — | **Required** |
+| `width` | `number` | — | Logical canvas width |
+| `height` | `number` | — | Logical canvas height |
+| `transparent` | `boolean` | `false` | |
+| `resolution` | `number` | — | Match `PhysicsSystem.resolution` |
+| `enableScroll` | `boolean` | `false` | |
+| `renderType` | `RENDERER_TYPE` | `UNKNOWN` | `WEBGL`, `CANVAS`, or `UNKNOWN` |
+
+System exposes `rendererManager` (collects all `Renderer` subclasses) and
+`containerManager` (per-`GameObject.id` Pixi `Container`).
+
+### `Renderer` base class
+
+Extend this for any custom 2D rendering plugin. Required overrides:
+
+- `init()` — call `this.rendererSystem = this.game.getSystem(RendererSystem)`
+  then `this.rendererSystem.rendererManager.register(this)`.
+- `componentChanged(changed)` — handle `OBSERVER_TYPE.ADD | CHANGE | REMOVE`,
+  manipulate Pixi display objects via
+  `this.rendererSystem.containerManager.getContainer(gameObject.id)`.
+- `rendererUpdate(gameObject)` — per-frame sync (transform, alpha, etc.).
+
+Combine with `@decorators.componentObserver({ MyFeature: ['prop'] })` from
+`@combos-fun/engine`.
+
+### `containerManager.getContainer(gameObject.id)`
+
+Returns the per-GameObject `Container` from `@combos-fun/renderer-adapter`.
+Always parent your display objects under this container, never directly to
+the Pixi stage.
+
+## Required setup
+
+`RendererSystem` **must** be the first system (or among the first) added to
+`Game.systems`, before any other 2D rendering / event / a11y sub-system that
+calls `getSystem(RendererSystem)` in `init`.
+
+Typical 2D system order:
+
+```ts
+new Game({
+  systems: [
+    new RendererSystem({ canvas, width, height }),
+    new RenderSystem(),         // visibility / alpha / zIndex
+    new ImgSystem(),             // images
+    new TextSystem(),            // text
+    new EventSystem(),           // pointer events
+    // ...physics, audio, a11y
+  ],
+});
+```
+
+## Runtime behaviour
+
+- Each `Renderer` subclass self-registers via `rendererManager.register(this)`
+  in its `init`. The base system iterates all registered renderers each
+  frame.
+- `containerManager` lazily creates a Pixi `Container` per `GameObject` on
+  first access and removes it when the `GameObject` is destroyed.
+- Don't mix conflicting drawables on a single `GameObject` (`Img` + `Sprite`
+  + `SpriteAnimation` on the same node fights for the same container slot).
+  Split across separate `GameObject`s.
+
+## Common pitfalls
+
+| Symptom | Fix |
+|---------|-----|
+| Blank canvas | Add `RendererSystem` to `systems`, ensure `autoStart: true` or call `game.start()` |
+| Nothing draws | Add the matching sub-system (`ImgSystem`, `TextSystem`, etc.) before adding the component |
+| Invisible / wrong alpha | Add `RenderSystem` from `plugin-renderer-render` for `visible` / `alpha` / `zIndex` |
+| Blurry / wrong scale | Match `resolution` between `RendererSystem` and `PhysicsSystem` |
+| `getSystem` undefined | Use class reference, not string: `game.getSystem(RendererSystem)` |
+| Stacked drawables fight | Split Img / Sprite / SpriteAnimation / NinePatch onto separate `GameObject`s |
+
+## Minimal example
+
+```ts
+import { Game } from '@combos-fun/engine';
+import { RendererSystem } from '@combos-fun/plugin-renderer';
+
+new Game({
+  systems: [
+    new RendererSystem({
+      canvas: document.querySelector('#canvas')!,
+      width: 750,
+      height: 1334,
+    }),
+  ],
+});
+```
+
+This alone is just an empty Pixi stage. Add `plugin-renderer-render`,
+`plugin-renderer-img`, etc. and matching components to render anything.
+
+## Verification
+
+- `pnpm --filter @combos-fun/plugin-renderer run build`
+- Run an example app from `examples/` and check for blank canvas / Pixi
+  WebGL errors in the browser console.

package/combos-plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "@combos-fun/plugin-renderer",
+  "pluginId": "renderer",
+  "category": "rendering",
+  "dimension": "2d",
+  "isCore": false,
+  "keywords": ["pixi", "rendering", "canvas", "2d", "renderer-base", "container"],
+  "agentSkill": "./agent-skill.md",
+  "requires": ["@combos-fun/engine", "@combos-fun/renderer-adapter"],
+  "exports": [
+    "RendererSystem",
+    "Renderer",
+    "RendererManager",
+    "ContainerManager",
+    "RENDERER_TYPE"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/plugin-renderer",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "@combos-fun/plugin-renderer",
   "main": "index.js",
   "module": "dist/plugin-renderer.esm.js",
@@ -8,8 +8,22 @@
   "unpkg": "dist/CombosFun.plugin.renderer.min.js",
   "files": [
     "index.js",
-    "dist"
+    "dist",
+    "agent-skill.md",
+    "combos-plugin.json"
   ],
+  "exports": {
+    ".": {
+      "import": "./dist/plugin-renderer.esm.js",
+      "require": "./index.js",
+      "types": "./dist/plugin-renderer.d.ts"
+    },
+    "./plugin-manifest": "./combos-plugin.json",
+    "./agent-skill": "./agent-skill.md"
+  },
+  "combos": {
+    "pluginManifest": "./combos-plugin.json"
+  },
   "types": "dist/plugin-renderer.d.ts",
   "keywords": [
     "combos-fun",
@@ -21,8 +35,8 @@
     "lodash-es": "^4.17.21",
     "pixi.js": "^8.18.1",
     "resource-loader": "^4.0.0-rc4",
-    "@combos-fun/engine": "0.0.5",
-    "@combos-fun/renderer-adapter": "0.0.5"
+    "@combos-fun/renderer-adapter": "0.0.7",
+    "@combos-fun/engine": "0.0.7"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.mjs"