Particles

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 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.

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; 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

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:

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

See 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.