# `@combos-fun/renderer-adapter` — Agent notes

Pixi v8 display-object adapter layer used by `@combos-fun/plugin-renderer` and its 2D rendering sub-plugins. **Not** a game `System`. It exposes a stable shape over Pixi primitives so 2D rendering plugins are not coupled to a specific Pixi version.

## When to read

Read whenever a 2D rendering task touches `Container` parenting, low-level Pixi display object shape, or whenever the entry skill loads "Core" packages for any project.

## Public API

Wrappers re-exported from `@combos-fun/renderer-adapter`:

| Export | Wraps | Used by |
|--------|-------|---------|
| `Application` | `pixi.js` Application | `RendererSystem` (plugin-renderer) bootstrap |
| `Container` | `PIXI.Container` | All container parenting via `containerManager` |
| `Graphics` | `PIXI.Graphics` | `plugin-renderer-graphics` |
| `Sprite` | `PIXI.Sprite` | `plugin-renderer-sprite`, `plugin-renderer-img` |
| `SpriteAnimation` | Pixi animated sprite | `plugin-renderer-sprite-animation` |
| `NinePatch` | nine-slice sprite | `plugin-renderer-nine-patch` |
| `TilingSprite` | `PIXI.TilingSprite` | `plugin-renderer-tiling-sprite` |
| `Text` | `PIXI.Text` | `plugin-renderer-text` |

These are **adapter classes** — plugins consume them, end users typically do not import them directly.

## Required setup

None on the user side. Adapter is a dependency of `@combos-fun/plugin-renderer` and is loaded transitively. End users install the plugin packages, not the adapter directly.

## Runtime behaviour

- Each wrapper instantiates a Pixi display object and exposes a thin API used
  by the matching renderer plugin.
- All 2D rendering plugins reach Pixi via these wrappers; if you are
  authoring a custom 2D rendering plugin, prefer extending `Renderer` from
  `plugin-renderer` and constructing display objects via the matching adapter
  type. Do **not** import `pixi.js` directly in plugin code.

## Common pitfalls

- Coupling a custom 2D rendering plugin directly to `pixi.js` means a Pixi
  major bump can break the plugin. Use the adapter types instead.
- Mixing adapter `Container` and raw `PIXI.Container` in the same scene
  graph is not supported — `containerManager.getContainer(gameObject.id)`
  returns the adapter type.

## Minimal example

Inside a custom 2D rendering plugin's `Renderer` subclass:

```ts
import { Sprite } from '@combos-fun/renderer-adapter';
import { Renderer, RendererSystem } from '@combos-fun/plugin-renderer';

class MyRenderer extends Renderer {
  init() {
    this.rendererSystem = this.game.getSystem(RendererSystem);
    this.rendererSystem.rendererManager.register(this);
  }
  componentChanged(changed) {
    if (changed.type === OBSERVER_TYPE.ADD) {
      const sprite = new Sprite(/* ... */);
      const container = this.rendererSystem.containerManager.getContainer(
        changed.gameObject.id,
      );
      container.addChild(sprite);
    }
  }
}
```

## Verification

- `pnpm --filter @combos-fun/renderer-adapter run build` should succeed.
- After upgrading `pixi.js`, run any example app from `examples/` to verify
  no rendering regression.