Add a native mineflayer event for particles

docs/api.md

@@ -75,6 +75,15 @@
       - [BossBar.isDragonBar](#bossbarisdragonbar)
       - [BossBar.createFog](#bossbarcreatefog)
       - [BossBar.color](#bossbarcolor)
+    - [mineflayer.Particle](#mineflayerparticle)
+      - [Particle.id](#particleid)
+      - [Particle.name](#particlename)
+      - [Particle.position](#particleposition)
+      - [Particle.offset](#particleoffset)
+      - [Particle.longDistanceRender](#particlelongdistancerender)
+      - [Particle.count](#particlecount)
+      - [Particle.movementSpeed](#particlemovementspeed)
+    - [Particle-specific properties](#particle-specific-properties)
   - [Bot](#bot)
     - [mineflayer.createBot(options)](#mineflayercreatebotoptions)
     - [Properties](#properties)
@@ -239,6 +248,7 @@
       - ["heldItemChanged" (heldItem)](#helditemchanged-helditem)
       - ["physicsTick" ()](#physicstick-)
       - ["chat:name" (matches)](#chatname-matches)
+      - ["particle"](#particle)
     - [Functions](#functions)
       - [bot.blockAt(point, extraInfos=true)](#botblockatpoint-extrainfostrue)
       - [bot.waitForChunksToLoad()](#botwaitforchunkstoload)
@@ -725,6 +735,40 @@ Determines whether or not boss bar creates fog
 
 Determines what color the boss bar color is, one of `pink`, `blue`, `red`, `green`, `yellow`, `purple`, `white`
 
+### mineflayer.Particle
+
+#### Particle.id
+
+Particle ID, as defined in the [protocol](https://wiki.vg/Protocol#Particle)
+
+#### Particle.name
+
+Particle Name, as defined in the [protocol](https://wiki.vg/Protocol#Particle)
+
+#### Particle.position
+
+Vec3 instance of where the particle was created
+
+#### Particle.offset
+
+Vec3 instance of the particle's offset
+
+#### Particle.longDistanceRender
+
+Determines whether or not to force the rendering of a particle despite client particle settings and increases maximum view distance from 256 to 65536
+
+#### Particle.count
+
+Amount of particles created
+
+#### Particle.movementSpeed
+
+Particle speed in a random direction
+
+### Particle-specific properties
+
+Certain particles also contain additional properties as defined in the [protocol](https://wiki.vg/Protocol#Particle)
+
 ## Bot
 
 ### mineflayer.createBot(options)
@@ -1465,6 +1509,10 @@ Fires every tick if bot.physicsEnabled is set to true.
 
 Fires when the all of a chat pattern's regexs have matches
 
+#### "particle"
+
+Fires when a particle is created
+
 ### Functions
 
 #### bot.blockAt(point, extraInfos=true)

index.d.ts

@@ -151,6 +151,7 @@ interface BotEvents {
   bossBarDeleted: (bossBar: BossBar) => Promise<void> | void
   bossBarUpdated: (bossBar: BossBar) => Promise<void> | void
   resourcePack: (url: string, hash: string) => Promise<void> | void
+  particle: (particle: Particle) => Promise<void> | void
 }
 
 export interface Bot extends TypedEmitter<BotEvents> {
@@ -826,6 +827,18 @@ export class BossBar {
   );
 }
 
+export class Particle {
+    id: number
+    name: string
+    longDistanceRender: boolean
+    position: Vec3
+    offset: Vec3
+    speed: number
+    count: number
+    data: Object | undefined
+    static fromNetwork(packet: Object): Particle
+}
+
 export let supportedVersions: string[]
 export let testedVersions: string[]
 

lib/loader.js

@@ -41,7 +41,8 @@ const plugins = {
   villager: require('./plugins/villager'),
   anvil: require('./plugins/anvil'),
   place_entity: require('./plugins/place_entity'),
-  generic_place: require('./plugins/generic_place')
+  generic_place: require('./plugins/generic_place'),
+  particle: require('./plugins/particle')
 }
 
 const supportedVersions = require('./version').supportedVersions
@@ -53,6 +54,7 @@ module.exports = {
   Painting: require('./painting'),
   ScoreBoard: require('./scoreboard'),
   BossBar: require('./bossbar'),
+  Particle: require('./particle'),
   supportedVersions,
   testedVersions,
   supportFeature: (feature, version) => require('prismarine-registry')(version).supportFeature(feature)

lib/particle.js

@@ -0,0 +1,32 @@
+const { Vec3 } = require('vec3')
+
+module.exports = loader
+
+function loader (registry) {
+  class Particle {
+    constructor (id, position, offset, count = 1, movementSpeed = 0, longDistanceRender = false, extraData = {}) {
+      Object.assign(this, registry.particles[id])
+      this.id = id
+      this.position = position
+      this.offset = offset
+      this.count = count
+      this.movementSpeed = movementSpeed
+      this.longDistanceRender = longDistanceRender
+      Object.assign(this, extraData) // Particle-specific data that can vary by version
+    }
+
+    static fromNetwork (packet) {
+      return new Particle(
+        packet.particleId,
+        new Vec3(packet.x, packet.y, packet.z),
+        new Vec3(packet.offsetX, packet.offsetY, packet.offsetZ),
+        packet.particles,
+        packet.particleData,
+        packet.longDistance,
+        packet.data
+      )
+    }
+  }
+
+  return Particle
+}

lib/plugins/particle.js

@@ -0,0 +1,9 @@
+module.exports = inject
+
+function inject (bot, { version }) {
+  const Particle = require('../particle')(bot.registry)
+
+  bot._client.on('world_particles', (packet) => {
+    bot.emit('particle', Particle.fromNetwork(packet))
+  })
+}