• 游戏开发
• 图形学
• AI 技能
• 图像处理

pixelfx 是一个纯代码实现的像素艺术特效库：230+ 个像素特效——火焰、爆炸、冰霜、闪电、天气、UI——全部是"一小段代码"，没有一个图片文件。它们可以直接在浏览器游戏里运行，也能一键换色、镜像、导出任意引擎都能用的 sprite sheet（精灵表）。这篇实战教程带你掌握 pixelfx 的三大核心：特效契约、Painter API和渲染流程，从零写出属于自己的像素特效。

🔍 先认识 pixelfx：特效是代码，不是图片

传统游戏开发里，像素特效通常是一张张手绘的精灵表；pixelfx 把这个思路翻转过来：每个特效只有一个.js文件，按分类放在 src/fx/ 目录下，形如src/fx/fire/candle.js。整个库覆盖 20 个分类（fire、explosions、ice、lightning、water、scifi、melee、status、weather、ui……），完整清单见 docs/CATALOG.md。

每个特效背后只有三个关键设计，理解了它们就理解了整个库：

零依赖，只需要 Node 18+，拷走src/core和任意特效文件就能用。

📜 特效契约：每个特效必须遵守的几条规则

完整契约写在 docs/AUTHORING.md#L46-L67，新手只要记住以下几点。

3.1 一个文件、一份 meta 描述

每个特效文件先导出一份meta，描述"这是个什么特效"：画布尺寸、原点、时长、是否循环、默认调色板。比如一个冰霜新星的 meta 大致长这样：

export const meta = { name: "Frost nova", desc: "Crystals erupt in a ring from the feet outward…", tags: ["ice", "one-shot"], size: [200, 192], origin: [100, 160], duration: 3.45, loop: false, fps: 30, bg: "ground", options: { palette: ["#0a1a33", "#1c4d8f", "#8fd0ff", "#e8f6ff"], seed: 1 }, };

options是调用方可以覆盖的旋钮，其中palette（由暗到亮的颜色斜坡）和seed最受用；x、y、flip、angle、light五个名字是系统保留字，别占用。

3.2 本地坐标：(0, 0) 就是"锚点"

特效永远围绕自己的原点绘制：角色双脚、撞击点、火炬底座。x 向右、y 向下、1 单位 = 1 像素。放置、镜像（flip）、旋转（angle）全由 Painter 负责——特效代码不需要知道自己出现在屏幕哪里。有方向的特效统一朝右，地面特效站在y = 0的地板上。

3.3 两种导出方式：纯函数 vs 模拟

• 纯特效（Pure）：导出draw(p, t, o)，第t秒的画面完全由t算出。光环、传送门、瀑布、火焰这类循环首选——循环天然无缝。见 src/fx/fire/candle.js#L75-L119 中蜡烛火焰如何用噪声函数摆动、拉长。
• 模拟特效（Simulated）：导出create(o)，返回{ update(dt), draw(p), drawBack(p) }。在create/update里生成粒子、碎片、灯光，运行时会以 120 Hz 或更细步进，火花会弹跳、烟会翻滚。爆炸、冲击、法术类一次性特效都走这条路，完整范例见 src/fx/explosions/small-explosion.js#L55-L150。

3.4 三条铁律

1. 时间：一次性特效在 0 到duration之间演出，t = duration时必须什么都没画（把duration留足，让最后一点烟散尽）；
2. 确定性：禁用Math.random()和Date，随机一律走种子的Rng/rand/burst；
3. 图层：角色背后的东西（光环远半、地面裂纹）放drawBack，其余放draw。

🎨 Painter API：画像素的那支笔

特效里所有的绘制都通过一个参数p（Painter 实例）完成，源码在 src/core/painter.js。它对特效而言像一支"像素画笔"，坐标是本地坐标，c是颜色、a是 0~1 的透明度。最常用的方法一览：

一个容易被忽视的技巧：颜色c和透明度a都可以传函数。例如p.disc(x, y, 8, (d, ang) => ..., (d, ang) => 1 - d)就能画出中心浓、边缘淡的体积感——烟和蒸汽全靠它，而不是抖动棋盘格。

🔄 渲染流程：草稿 → 渲染 → 审视 → 修正的循环

pixelfx 的方法论只有一句话：代码是黏土，相信你的眼睛。一次生成不出好特效，"渲染出来看看"才能。工具链在 tools/ 下，全部是零依赖的 Node 脚本。

7.1 一条命令生成脚手架

node tools/new.mjs arcane/my-spell # 生成可用的起始文件（循环特效加 --loop）

它会写入src/fx/arcane/my-spell.js（带 meta 和示例draw），模板见 tools/new.mjs#L29-L58。

7.2 渲染出接触表，用眼睛判断

node tools/render.mjs arcane/my-spell

tools/render.mjs 会按meta.fps逐帧渲染，输出一张接触表（contact sheet）records/arcane/my-spell/contact.png——所有关键帧按时间排好，每帧带帧号和时间戳，一眼看出节奏问题。常用参数：

• --all：接触表放每一帧；--gif/--mp4：看动起来的效果
• --opts '{"palette":["#102","#215","#43a","#8cf","#fff"]}'：不改代码直接换色试试
• --sheet：导出透明 PNG + Aseprite 风格 JSON 精灵表，供 Godot、Unity、Phaser 等引擎导入

7.3 用 check 自检，再导出

node tools/check.mjs arcane/my-spell

tools/check.mjs 专门抓眼睛看不见的错误：画出画布边界、一次性特效结尾不清空、循环接缝、未种子的随机数、超慢帧（目标单帧 < 2ms）。改到它全绿才算完成。

整个循环就是：渲染 → 打开接触表 → 修最糟的那个点 → 再渲染。文档建议至少三轮；展示级特效更多。

✅ 质量标准：怎么算"像一个好特效"

docs/AUTHORING.md#L114-L139 列了十条，浓缩成新手最好记的六条：

1. 线条和光，而非色块——用 1px 轮廓、环、拖尾和火花搭建，亮度交给光；大块饱和平涂几乎总是错的；
2. 光无处不在——核心一个紧而亮的热点，外围一大片低强度柔光，火花和闪光各自带光；
3. 体积感——烟、蒸汽、尘雾用真半透明（SMOKE、VAPOUR、p.disc），上亮下暗，膨胀又变薄；
4. 真实运动——火花随速度拉伸、落地弹跳；碎片翻滚、落地扬尘；火升腾冷却成烟；
5. 分幕编排——蓄力（元素聚拢）→ 释放（1~2 帧白色英雄帧 + 爆闪）→ 扩散 → 停留（余烬、星光）→ 长衰减；
6. 1x 下可读——有明确焦点，形状内部无噪点颗粒。

工具库（src/core/sim.js）把 4 的多数工作做好了：Particles提供SPARK、FIRE、SMOKE、EMBER等现成粒子，Bits处理翻滚碎片，Lights管理忽明忽暗的光点。

📚 上手路径速查

总结：pixelfx 的编写范式非常克制——一个文件、一份 meta、本地坐标、种子随机、结尾留白；画笔画什么由 Painter API 决定，好不好看由"渲染-审视-修正"循环决定。选一个meta，用tools/new.mjs起步，tools/render.mjs出图，tools/check.mjs兜底，你的第一个像素特效离得并不远。

• 游戏开发
• 图形学
• AI 技能
• 图像处理