# @flare-engine/particles 中文文档

规范地址：https://npmcn.com/package/%40flare-engine/particles/

版本：0\.4\.12
npm 元数据更新时间：2026-11-12T19:45:54.992Z
中文译文更新时间：2026-11-14T22:50:52.081Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40flare-engine/particles
原文对照：https://npmcn.com/package/%40flare-engine/particles/?lang=original
项目主页：https://github.com/grzott/flare-engine#readme
源码仓库：https://github.com/grzott/flare-engine

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：130 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-06-09T16:19:43.543Z
- 最新版本发布：2026-11-12T19:45:54.608Z
- 近 30 天下载量：2236（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

粒子发射器、池、即时模具 Skia 渲染

## 安装

```sh
npm install @flare-engine/particles
```

也可以使用：`pnpm add @flare-engine/particles`、`yarn add @flare-engine/particles`、`bun add @flare-engine/particles`

## README

# @flare-engine/文章

预分配出颗粒池+放出物——颗粒被再生而不是再分配,因此一个稳态放出物不分配出每个颗粒. 目标:60英尺处有200至500个活颗粒. 这个软件包拥有粒子数据和生命周期;渲染通过宿主的即时-mode Skia地层(PictureRecorder)来进行.

每个框架的计量综合成本公布于 [基准](https://github.com/grzott/flare-engine/blob/main/docs/references/benchmarks.md),随着捕捉日期和跑到跑在每一行。 分配是用仪器进行的,而不是假设:抽取路径的对接套件读取 `ParticlePool.created` 每个框架和 `bun run check:perf` 如果一个稳定状态的发射器 给工厂打了一次电话, 建造失败了。 准确的整数在同一文档中公布.

## 安装

```sh
bun add @flare-engine/particles
```

## 使用量

```ts
import { ParticleEmitter } from '@flare-engine/particles';

const emitter = new ParticleEmitter({
  rate: 30, lifetime: 1.2,
  speed: 80, speedMax: 160,
  direction: -Math.PI / 2, spread: Math.PI / 4,
  startColor: { r: 1, g: 1, b: 1, a: 1 }, endColor: { r: 1, g: 1, b: 1, a: 1 },
  startAlpha: 1, endAlpha: 0, // opacity fades via start/endAlpha — Color.a is not read
  startSize: 4, endSize: 0,
  gravityY: 98,
});

// gravity is part of config; update takes only dt
emitter.update(1 / 60);
```

## 缩放形状

默认每个颗粒的产卵在发射者身上 `x`编号 :`y`A级 `shape` 样本 产卵量 转而.. `point` (默认), `circle`, (中文(简体) ), `ring`, (中文(简体) ), `rect`,或 `cone`数字 :

```ts
import { ParticleEmitter } from '@flare-engine/particles';

// An explosion: spawn on a ring, travel outward from the centre.
const blast = new ParticleEmitter({
  rate: 0, lifetime: 0.6,
  speed: 120, speedMax: 200,
  direction: 0, spread: 0.15,
  shape: { kind: 'ring', radius: 24, radial: true },
});
blast.x = 160;
blast.y = 120;
blast.burst(48);
```

**形状控制位置; `direction` 财务报告和审定财务报表 `spread` 仍然控制着速度.** 他们相当的作曲 而不是竞争。 外向正常的形状.. `circle`, (中文(简体) ), `ring`, (中文(简体) ), `cone` - 能够手 以速度到达它 `radial: true`,这就是一个环 漂移粒子与 一个爆炸。 没有它, 戒指产出 在戒指上,一切仍然飞走 `direction`。 。 。 .

| 形状 | 职位 | 页:1 |
| --- | --- | --- |
| `{ kind: 'point' }` | 发射源 | 默认 不绘制随机值,所以没有形状的放出器会在形状存在之前产生一个相同的序列. |
| `{ kind: 'circle', radius, radial? }` | 光碟内部的制服 | 制服 **按地区** 射线术语是 `sqrt`\- 重量级,所以粒子不会聚集在中心. |
| `{ kind: 'ring', radius, thickness?, radial? }` | 在戒指上, `thickness` 宽 | `thickness` 默认为 0(一光环),统一分布于整个乐队. |
| `{ kind: 'rect', width, height }` | 矩形内制服 | 以发射器为中心,而不是以一角为锚. 没有外出正常,所以 `radial` 不适用. |
| `{ kind: 'cone', radius, angle }` | 半角楔形制服 `angle` | 向着这里 `direction`一、结 论 _产卵点_ - 与 `spread`风扇的速度从一个点. |

`sampleEmitterShape(shape, rand, out, direction?)` 如果您想要放置其它东西,则导出 而不是颗粒。 写到一个打电话者拥有的 `ShapeSample` (单位:千美元)`createShapeSample()`和分配 没什么,所以它是安全的每颗粒子在一个稳定的状态循环。 每个形状绘制一个固定的数目 来自 `rand`,这就是保持种子发射器 准确的重放.

## 绘制成图示批次

`drawParticles` 将每个活粒子排入您拥有的批次, 因此粒子会随同冲出 而不是强迫第二次通过:

```ts
import { drawParticles, ParticleEmitter } from '@flare-engine/particles';
import type { ParticleBatchLike, ParticleFrameLike } from '@flare-engine/particles';

declare const emitter: ParticleEmitter;
declare const batch: ParticleBatchLike; // a @flare-engine/render SpriteBatch satisfies this
declare const atlasImage: unknown;
declare const frame: ParticleFrameLike; // e.g. a SpriteFrame from @flare-engine/assets

// each frame, before the batch flushes
drawParticles(emitter.pool, batch, atlasImage, frame);
```

批量和帧已打入 **结构**,所以这个包 仍然取决于什么,但 `@flare-engine/core` 财务报告和审定财务报表 `@flare-engine/math` 并且没有制造器可使用。 真实的 `SpriteBatch` 满意 `ParticleBatchLike` - 运行时间测试证实 `@flare-engine/engine`, (中文(简体) ), 不只是假设.

循环不分配每颗粒子,跳过插出大小或α的粒子 达到零,而不是支付 一个无形的抽取呼叫.

**不应用每个粒子的颜色 .** 池内插 `startR/G/B → endR/G/B`,但是一个批 保留效果 _参考文献_ 直到它冲出,所以一个单一的可重复使用的效果对象会给出每个 粒子 最后一个颜色 —— 每个相框一个对象就是这个分配 软件包的存在是为了避免。 阿尔法 _实值_ 适用,因为 `drawRaw` 把它当作数字。 如果你需要的话 今天的每颗粒子颜色, 写回循环 `pool.particles` 并承担成本.

见 [API 规格](https://github.com/grzott/flare-engine/blob/main/docs/design/api-specs.md#flare-engineparticles--4kb-gzip)。 。 。 .

## 许可证

阿帕奇 - 2.0

## 常见问题

### @flare-engine/particles 是什么？

粒子发射器、池、即时模具 Skia 渲染

### 如何安装 @flare-engine/particles？

在项目目录运行 npm install @flare-engine/particles，或使用 pnpm add / yarn add / bun add。

### @flare-engine/particles 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @flare-engine/particles 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @flare-engine/particles 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @flare-engine/particles 可以商用吗？

@flare-engine/particles 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @flare-engine/particles 的下载量有多少？

根据 npm 官方下载统计，@flare-engine/particles 在 2026/10/15 – 2026/11/13 这 30 天内被下载 2,236 次，日均约 75 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @flare-engine/particles 还在维护吗？

最新版本 0\.4\.12 发布于 2026/11/13（3 天前）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/06/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。