---
title: Particles
description: Spawn particles by name with typed payloads for the ones that carry colors, blocks or items.
---

A `Particle` is a registry ID followed by data whose shape depends on the type: nothing for `flame`, a block state for `block`, a color and scale for `dust`, a whole `Slot` for `item`. [LevelParticles](/packets/play/levelparticles) carries one, and entity metadata can carry one or a list. `helpers.createParticle` builds the value by name; `helpers.createParticlePacket` wraps it in the packet.

```ts
import { helpers } from "mc-protocol";

await client.sendPacket("LevelParticles", helpers.createParticlePacket("flame", { x: 0.5, y: 65, z: 0.5 }, {
  count: 20,
  offset: 0.5,
  speed: 0.1,
}));

await client.sendPacket("LevelParticles", helpers.createParticlePacket(
  helpers.createParticle("dust", { color: "#ff8800", scale: 1.5 }),
  { x: 0.5, y: 66, z: 0.5 },
));
```

## `createParticle(name, data?)`

`name` is any of the 125 entries in the 26.2 `minecraft:particle_type` registry, with or without the `minecraft:` prefix; the list is `helpers.PARTICLE_NAMES`. Unknown or miscased names throw. Particles without data take no second argument; passing one throws. Particles with data require it:

| Particle | Data | Wire |
| --- | --- | --- |
| `block`, `block_marker`, `falling_dust`, `dust_pillar`, `block_crumble` | `{ blockState }` | VarInt block state ID |
| `dust` | `{ color, scale? }` | Int RGB, Float (default `1`; the client clamps to 0.01–4) |
| `dust_color_transition` | `{ from, to, scale? }` | Int RGB, Int RGB, Float |
| `effect`, `instant_effect` | `{ color, power }` | Int RGB, Float |
| `entity_effect`, `tinted_leaves`, `flash` | `{ color }` | Int ARGB |
| `dragon_breath` | `{ power }` | Float |
| `item` | `{ item }` | [Slot](/docs/items); pass a `createSlot` result or an item name |
| `sculk_charge` | `{ roll }` | Float |
| `shriek` | `{ delay }` | VarInt ticks |
| `vibration` | `{ source, ticks }` | `source` is `{ block: { x, y, z } }` or `{ entityId, eyeHeight }` |
| `trail` | `{ target, color, duration }` | 3 Doubles, Int RGB, VarInt ticks |
| `geyser`, `geyser_plume` | `{ waterBlocks }` | Int |
| `geyser_base`, `geyser_poof` | `{ waterBlocks, burstImpulseBase }` | Int, Float |

Colors are `0xRRGGBB` numbers or `"#RRGGBB"` strings. ARGB fields also take `0xAARRGGBB` or `"#AARRGGBB"`; a six-digit string there means fully opaque. Out-of-range numbers throw rather than being masked, so an ARGB value passed to an RGB field is caught.

Payloads were checked against the 26.2 server's `*ParticleOption` codecs. Older references show `dust` as three floats and `trail` without a duration; that is not what 26.2 sends.

## `createParticlePacket(particle, position, options?)`

Returns the `LevelParticles` payload. `particle` is a data-less name or a `createParticle` result.

| Option | Default | Field |
| --- | --- | --- |
| `count` | `1` | `amount` |
| `offset` | `0` | `offsetX/Y/Z`; a number applies to all axes. Each is multiplied by a Gaussian random and added to the position per particle. |
| `speed` | `0` | `velocityOffset` |
| `longDistance` | `false` | render up to 65536 blocks away instead of 256 |
| `alwaysShow` | `false` | ignore the client's particle setting |

```ts
helpers.createParticlePacket("heart", { x: 0, y: 70, z: 0 });
// {
//   longDistance: false, alwaysShow: false,
//   x: 0, y: 70, z: 0, offsetX: 0, offsetY: 0, offsetZ: 0,
//   velocityOffset: 0, amount: 1,
//   particle: { type: "heart" },
// }
```

## In entity metadata

`createParticle` results go straight into metadata fields of type `particle` or `particles`, such as a living entity's potion particles:

```ts
helpers.createEntityMetadata("living_entity", {
  potionParticles: [helpers.createParticle("entity_effect", { color: "#ff0000" })],
});
```

See [Entity metadata](/docs/entity-metadata).

## Types

`Particle`, `ParticleName`, `DataParticleName`, `SimpleParticleName`, `ParticleDataMap`, `ParticlePacketOptions`, `LevelParticlesPacket`, `RgbColor`, `ArgbColor`, `Vec3`, all under `helpers`. `helpers.parseColor(value, alpha)` is the color parser if you need the signed int for another packet.