Add a native mineflayer event for particles (#2813)

* Added particle stuff

* linting fix

* Changed from a class to a function

* Rename longDistance to forceRender, detail it more in api docs

* Rename particleData to speed

* Rename particles to count

* Bug fixes

* Doctoc regen

* Revert back to class, change forceRender to longDistanceRender

* Improve class

* Update docs

* Linting fix

* Remove extraData

* Remove unused variable

* Update definition

* Added internal test

* Better test

* Linting fix

docs/api.md

@@ -75,6 +75,14 @@
       - [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)
   - [Bot](#bot)
     - [mineflayer.createBot(options)](#mineflayercreatebotoptions)
     - [Properties](#properties)
@@ -239,6 +247,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 +734,36 @@ 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
+
 ## Bot
 
 ### mineflayer.createBot(options)
@@ -1465,6 +1504,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,26 @@ export class BossBar {
   );
 }
 
+export class Particle {
+    id: number
+    name: string
+    position: Vec3
+    offset: Vec3
+    count: number
+    movementSpeed: number
+    longDistanceRender: boolean
+    static fromNetwork(packet: Object): Particle
+
+    constructor (
+        id: number,
+        position: Vec3,
+        offset: Vec3,
+        count?: number,
+        movementSpeed?: number,
+        longDistanceRender?: boolean
+    );
+}
+
 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,30 @@
+const { Vec3 } = require('vec3')
+
+module.exports = loader
+
+function loader (registry) {
+  class Particle {
+    constructor (id, position, offset, count = 1, movementSpeed = 0, longDistanceRender = false) {
+      Object.assign(this, registry.particles[id])
+      this.id = id
+      this.position = position
+      this.offset = offset
+      this.count = count
+      this.movementSpeed = movementSpeed
+      this.longDistanceRender = longDistanceRender
+    }
+
+    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
+      )
+    }
+  }
+
+  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))
+  })
+}

test/externalTests/particles.js

@@ -0,0 +1,27 @@
+const assert = require('assert')
+
+module.exports = () => async (bot) => {
+  const particleData = bot.registry.particles[0]
+
+  return new Promise((resolve, reject) => {
+    function onParticleEvent (particle) {
+      assert.strictEqual(particle.id, particleData.id)
+      assert.strictEqual(particle.name, particleData.name)
+      assert.strictEqual(particle.position.x, bot.entity.position.x)
+      assert.strictEqual(particle.position.y, bot.entity.position.y)
+      assert.strictEqual(particle.position.z, bot.entity.position.z)
+      assert.strictEqual(particle.offset.x, 5)
+      assert.strictEqual(particle.offset.y, 5)
+      assert.strictEqual(particle.offset.z, 5)
+      assert.strictEqual(particle.count, 100)
+      assert.strictEqual(particle.movementSpeed, 0.5)
+      assert.strictEqual(particle.longDistanceRender, true)
+
+      resolve()
+    }
+
+    bot.on('particle', onParticleEvent)
+
+    bot.chat(`/particle ${particleData.name} ~ ~ ~ 5 5 5 0.5 100 force`)
+  })
+}