# @drama/render-pixi

`@drama/core` 定义的 `Renderer` 接口的 **PixiJS v8 后端**。core 每帧算出「每个角色每个 slot 的 2D 变换、相机状态、表情/朝向、特效指令」，本包把这些抽象落到具体的 Pixi 显示对象上。它是 core 与 Pixi 之间唯一的翻译层：core 那侧全是数字与字符串，本包这侧才出现 `PIXI.Sprite`。

任务文档：[`../../plan/tasks/drama-render-pixi.md`](../../plan/tasks/drama-render-pixi.md)。

## 公共面

```js
import { createPixiRenderer, createPixiRendererAuto } from '@drama/render-pixi'

// 浏览器 / 已装 pixi.js：自动注入 PIXI（player-vue / studio 用）
const renderer = await createPixiRendererAuto(app, { rig })

// 显式注入 PIXI（含 headless 单测注入 stub）
import * as PIXI from 'pixi.js'
const renderer = createPixiRenderer(app, { rig, PIXI })
```

返回对象满足 core `Renderer`（`applyActorPose`/`applyFace`/`applyFacing`/`applyCamera`/`setActorWorldPos`/`playEffect`/`stopEffect`/`resetActor`/`runTransition`），并挂出场/换场扩展方法 `addActor`/`removeActor`/`loadScene`/`updateEffects`。**接口方法签名零 Pixi 入参**——`PIXI` 仅在工厂处一次注入。

## 设计决策（实现二选一处写明）

- **PIXI 注入而非顶层静态 import**：`index.js` 不在模块顶层 `import * as PIXI from 'pixi.js'`，而是把 PIXI 命名空间作为工厂构造期注入项（`createPixiRenderer` 要求 `opts.PIXI`；`createPixiRendererAuto` 自动 `await import('pixi.js')`）。这让无 GPU 的 headless 单测可注入 stub Sprite 跑纯映射用例，且 Pixi 仍不外溢到任何接口方法签名（满足 §5.2「Pixi 只在本包」+ §3「零 Pixi 入参」）。
- **求值不重复（红线）**：本包不做骨骼世界矩阵求值、关键帧插值、镜头补间——那些全在 `@drama/core`。core 把世界矩阵 decompose 成 `SlotTransform`（`{x,y,rotation,scaleX,scaleY,zOrder?,mirror?}`），本包只把它写进 Sprite。facing/扭头镜像的反射轴计算属于「依赖具体贴图锚点的纯渲染几何」，按 §3 留在本包（`geom.js`）。

## 内部结构

`geom.js` 纯渲染几何（facing 翻转/扭头反射轴/纵深透视，接收数字返回写入值，最易测）·
`assets.js` 贴图加载缓存+容错 · `actor.js` 单角色 slot 装配+pose 落地+表情+道具+镜像 ·
`stage.js` 世界/背景/相机写入/遮挡/特效层 · `occluder.js` 背景像素裁多边形+zIndex=baseY ·
`effects.js` 屏幕特效帧轮播 · `renderer.js` core 接口实现外壳 · `index.js` 公共面。