> ## Documentation Index
> Fetch the complete documentation index at: https://comfytv.org/llms.txt
> Use this file to discover all available pages before exploring further.
# 粒子 (Particles)
> 一个 2D 粒子生成器——火花、余烬、烟雾、魔法尘埃——合成到你的素材上，带实时 Canvas2D 预览。
## 这个节点是做什么的
**Particles** 模拟一个 2D 粒子系统，并把它合成到 `COMFYTV_VIDEO` 上（若未接视频，则在空白/透明画面上渲染）。粒子从发射器诞生，被各种力（重力、风、湍流、吸引子、涡旋）推动，可选与地面碰撞，并绘制为发光精灵、拉伸条纹或拖尾。节点有实时 Canvas2D 预览，可在提交前调整效果；**▶ 运行** 把最终合成渲染为新的视频快照。
你也可以用蒙版驱动发射：接入 **mask\_video** 或 **mask\_image**，发射器会切换为 `mask_edge`，沿蒙版边缘生成粒子（很适合勾边或让主体「溶解」）。
输入输出为 `COMFYTV_VIDEO`。要与原生 ComfyUI 节点互通，请插入 **Bridge** — 见[桥接说明](https://github.com/jtydhr88/ComfyTV/blob/main/docs/bridges.md)。
## 适用场景
* 在实拍素材上叠加火焰余烬、火花、雪、雨、魔法尘埃或烟雾。
* 沿主体轮廓发射粒子（mask-edge）做溶解或能量勾边效果。
* 制作响应重力和风的循环背景运动（尘埃微粒、散景）。
## 参数说明
位置归一化为 `0..1`（画面宽/高的比例）。角度以度为单位。速度/力除注明外单位为像素/秒。
### emitter 与发射器形状
* **emitter**（发射器）——粒子在哪里生成：`point`、`line`、`rect`、`circle` 或 `mask_edge`。默认 `point`。（`mask_edge` 需接入蒙版，见下。）
* **e\_x0, e\_y0**——发射器第一锚点（默认 `0.5`、`0.85`）。用作点，或 line/rect/circle 的起点。
* **e\_x1, e\_y1**——第二锚点（默认 `0.5`、`0.85`），为 line/rect/circle 发射器定义远角/范围。
### 发射
* **rate**（速率）——每秒生成的粒子数，`0`–`2000`，默认 `120`。设为 `0` 时节点原样放行视频。
* **lifetime**（寿命）——每个粒子存活时长，单位秒，`0.1`–`10.0`，默认 `2.0`。
* **speed**（速度）——初始发射速度，`0`–`1200`，默认 `120`。
* **direction**（方向）——发射角度，单位度，`-180`–`180`，默认 `-90`（正上方）。
* **spread**（散布）——围绕 **direction** 的随机角度锥，`0`–`180`，默认 `30`。
* **warmup**（预热）——首个输出帧前先运行的模拟秒数，`0`–`10`，默认 `1`，使效果开场即「填满」而非空白。
* **seed**（随机种子）——`0`–`99999`，默认 `7`，用于可复现结果。
### 力
* **gravity**（重力）——向下拉力，`-600`–`600`，默认 `60`（负值上升）。
* **wind**（风）——水平推力，`-600`–`600`，默认 `0`。
* **turbulence**（湍流）——噪声驱动涡旋的强度，`0`–`600`，默认 `60`。
* **turb\_scale**（湍流尺度）——湍流噪声的空间尺度，`8`–`600`，默认 `120`（越大涡旋越宽）。
* **drag**（阻力）——每步速度阻尼，`0`–`0.99`，默认 `0.1`（越高粒子减速越快）。
* **swirl**（涡旋）——绕吸引子点的旋转力，`-600`–`600`，默认 `0`。
### 吸引子
* **attract\_strength**（吸引强度）——朝吸引子拉（正）或推离（负），`-600`–`600`，默认 `0`（关闭）。
* **attract\_x, attract\_y**——吸引子位置，`0..1`，默认 `0.5, 0.5`。
* **attract\_radius**（吸引半径）——吸引子衰减半径，`0.05`–`1.5`，默认 `0.5`。
### 碰撞
* **collide**（碰撞）——地面碰撞行为：`none`（默认）、`bounce`（反弹）、`die`（消亡）。
* **floor\_y**（地面高度）——地面高度占画面高度的比例，`0..1`，默认 `0.9`。
* **bounce**（弹性）——反弹恢复系数，`0`–`1`，默认 `0.5`（保留的速度比例）。
### 子发射（次级迸发）
* **sub\_mode**（子模式）——何时生成次级迸发：`none`（默认）、`on_death`（消亡时）、`on_collide`（碰撞时）。
* **sub\_count**（子数量）——每次迸发粒子数，`0`–`30`，默认 `8`。
* **sub\_speed**（子速度）——迸发发射速度，`0`–`600`，默认 `120`。
* **sub\_lifetime**（子寿命）——迸发粒子寿命，单位秒，`0.1`–`5.0`，默认 `0.6`。
* **sub\_size\_ratio**（子尺寸比）——迸发相对父粒子的尺寸，`0.1`–`2.0`，默认 `0.5`。
* **sub\_color**（子颜色）——迸发颜色，十六进制，默认 `#FFF2B0`。
### 尺寸、不透明度与颜色随寿命变化
* **size**（尺寸）——起始粒子尺寸，单位像素，`1`–`64`，默认 `12`。
* **size\_end\_ratio**（末尺寸比）——末尺寸相对起始的比例，`0`–`3`，默认 `0.4`（默认收缩）。
* **opacity\_start / opacity\_end**（起始/末不透明度）——诞生和消亡时的 alpha，各 `0`–`1`，默认 `1.0` / `0.0`（淡出）。
* **size\_curve / opacity\_curve**——可选自定义曲线，JSON `[{t,v}, ...]`（t = 寿命比例 0–1，v = 乘数）。留空则用上面的简单起止渐变。
* **color0 / color1**——起始和末尾颜色，十六进制，默认 `#FFD27A` / `#FF5A2A`（粒子随寿命从 color0 渐变到 color1）。
### 外观 / 渲染
* **sprite**（精灵）——粒子纹理：`glow`（柔和光点，默认）、`spark`、`star`。
* **renderer**（渲染器）——粒子如何绘制：`sprite`（默认）、`stretched`（运动拉伸）、`trail`（拖尾）。
* **stretch**（拉伸）——stretched 渲染器的拉伸量，`0`–`3`，默认 `1`。
* **trail\_len**（拖尾长度）——trail 渲染器的拖尾段数，`2`–`5`，默认 `4`。
* **blend**（混合）——叠加到视频上的混合模式：`additive`（默认，发光）或 `over`（正常 alpha）。
### 输入
* **video**（`COMFYTV_VIDEO`，可选）——要合成到的素材。没有它则粒子在自己的画面上渲染。
* **mask\_video**（`COMFYTV_VIDEO`，可选）/ **mask\_image**（`COMFYTV_IMAGE`，可选）——接入任一即从蒙版边缘生成，发射器强制为 `mask_edge`。若选了 `mask_edge` 发射器却未接蒙版，节点会报错。
## 输出说明
| 输出 | 类型 | 含义 |
| --------- | --------------- | ---------------- |
| **video** | `COMFYTV_VIDEO` | 合成了粒子的素材，作为新项目快照 |
## 使用提示
* **rate = 0** 会短路节点：原样放行输入视频。
* **warmup** 对「第 1 帧就该满屏」的效果很重要（下落的雪、上升的余烬）——没有它效果会从空白逐渐积累。
* `additive` 混合呈现为发光（火花、魔法）；不透明粒子（雪、碎屑）用 `over`。
* Canvas2D 预览可在（较慢的）**▶ 运行** 渲染前调好力和外观。
* Mask-edge 发射需要接蒙版到 **mask\_video** 或 **mask\_image**；仅选 `mask_edge` 发射器会报错。
## 相关节点
* **Blur / Sharpen**——柔化或锐化合成结果。
* **Video Denoise**——加粒子前清理底层素材。