# 引擎能力摘要（给生成 agent 的 ≤3KB 版）

引擎 = LittleJS 1.18.19。**你几乎不直接碰它**——重活（粒子/音频/物理/手感/调色）都被 L2 插件封装好了，你调 `plugins.<键>` 就行。这份摘要只让你知道「插件背后是什么、坑在哪」，以及极少数要经 `ctx.getEngine()` 够引擎时的事实。完整逐函数签名在 `game-runtime/docs/ENGINE-CAPABILITIES.md`（277KB 引擎 .d.ts 的抽取版），本篇是够用的地板。

## 铁律：先找插件，别碰引擎
- 画面：画在 `render(g)` 的 `g`（= 引擎 `mainContext`，一块 Canvas2D 叠加层）。用 `g.fillRect/drawImage/fillText` 直接画即可，**别** `ctx.getContext2d()`（那是另一块 overlay）。
- 粒子/打击感 → `plugins.juice`；音乐音效 → `plugins.audioMusic`；缓动手感 → `plugins.gamefeel`；碰撞 → `plugins.collision`；运动 → `plugins.physics`；调色 → `plugins.palettePost`。**这些引擎里都有，但一律走插件**——直接碰引擎会踩下面的坐标系坑。
- 时间走 `ctx.time()`（或 `.nowMs()`）、随机走 `ctx.random()`（或 `.next()/.range(a,b)`）——**确定性可复现**，别用引擎全局 `time`/`rand`（受暂停/timeScale 污染、不可复现）。

## `ctx.getEngine()`：极少用，用则容错
返回一条受控透传通道（粒子发射器 / 音频合成核 / 数学缓动库）——**但这三样插件都已封装**，正常你用不到。`getEngine()` 在无引擎环境（node/桩）返回 `null`，碰它必须先判空降级，别裸调。真要用数学缓动，`plugins.gamefeel.easing` 有 13 条曲线，比引擎全（引擎只有 lerp/smoothStep/oscillate，没有 elastic/back/cubic）。

## 坐标系坑（碰引擎才会踩，也是插件封装它的原因）
- 引擎默认**世界坐标**、几何是 `Vector2` 类；插件受控面是朴素 `{x,y}` number 对。
- 引擎 AABB 用 `size`=**全宽全高**；插件 AABB 用 `{x,y,hw,hh}`=中心+**半宽半高**——差 **2× 换算**。混用必错，所以一律走插件的 `{x,y,w,h}`/`{x,y,hw,hh}` 形状。
- 引擎碰撞查询只返 bool 或命中位置，**没有**穿透深度/MTV 法线/标量 t；要 `{hit,depth,nx,ny}` 这种结构化结果走 `plugins.collision`（它替你补齐）。

## 几个「引擎有 vs 没有」的事实（省得你猜）
- 音乐**没有** `Music` 类——引擎是 `ZzFXMusic`/`Sound.playMusic()`；你走 `audioMusic` 就别管这个。
- **没有** `engineUpdate` 导出——主循环是引擎内部 RAF；你只在 `update(dt)` 里 `bundle.tick(dt)` 驱动插件，别想手摇引擎帧。
- 成就/勋章系统（Medal）、GLSL 后处理注入引擎里有，但**非本档范围**，别用。