mineflayer 4.0.0 → 4.1.0

package/.github/workflows/ci.yml

@@ -28,7 +28,7 @@ jobs:
          - javaVersion: 16
            mcVersion: '1.17.1'
          - javaVersion: 17
-           mcVersion: '1.18.1'
+           mcVersion: '1.18.2'
       fail-fast: false
 
     steps:

package/docs/api.md

@@ -20,8 +20,8 @@
     - [Biome](#biome)
     - [Item](#item)
     - [windows.Window (base class)](#windowswindow-base-class)
-      - [window.deposit(itemType, metadata, count)](#windowdeposititemtype-metadata-count)
-      - [window.withdraw(itemType, metadata, count)](#windowwithdrawitemtype-metadata-count)
+      - [window.deposit(itemType, metadata, count, nbt)](#windowdeposititemtype-metadata-count-nbt)
+      - [window.withdraw(itemType, metadata, count, nbt)](#windowwithdrawitemtype-metadata-count-nbt)
       - [window.close()](#windowclose)
     - [Recipe](#recipe)
     - [mineflayer.Container](#mineflayercontainer)
@@ -94,6 +94,8 @@
       - [bot.game.hardcore](#botgamehardcore)
       - [bot.game.maxPlayers](#botgamemaxplayers)
       - [bot.game.serverBrand](#botgameserverbrand)
+      - [bot.game.minY](#botgameminy)
+      - [bot.game.height](#botgameheight)
     - [bot.physicsEnabled](#botphysicsenabled)
     - [bot.player](#botplayer)
       - [bot.players](#botplayers)
@@ -113,6 +115,8 @@
         - [bot.settings.skinParts.showLeftPants - boolean](#botsettingsskinpartsshowleftpants---boolean)
         - [bot.settings.skinParts.showRightPants - boolean](#botsettingsskinpartsshowrightpants---boolean)
         - [bot.settings.skinParts.showHat - boolean](#botsettingsskinpartsshowhat---boolean)
+      - [bot.settings.enableTextFiltering - boolean](#botsettingsenabletextfiltering---boolean)
+      - [bot.settings.enableServerListing - boolean](#botsettingsenableserverlisting---boolean)
       - [bot.experience.level](#botexperiencelevel)
       - [bot.experience.points](#botexperiencepoints)
       - [bot.experience.progress](#botexperienceprogress)
@@ -418,21 +422,23 @@ See [prismarine-item](https://github.com/PrismarineJS/prismarine-item)
 
 See [prismarine-windows](https://github.com/PrismarineJS/prismarine-windows)
 
-#### window.deposit(itemType, metadata, count)
+#### window.deposit(itemType, metadata, count, nbt)
 
 This function returns a `Promise`, with `void` as its argument when done depositing.
 
  * `itemType` - numerical item id
  * `metadata` - numerical value. `null` means match anything.
  * `count` - how many to deposit. `null` is an alias to 1.
+ * `nbt` - match nbt data. `null` is do not match nbt.
 
-#### window.withdraw(itemType, metadata, count)
+#### window.withdraw(itemType, metadata, count, nbt)
 
-This function returns a `Promise`, with `void` as its argument when done withdrawing.
+This function returns a `Promise`, with `void` as its argument when done withdrawing. Throws and error if the bot has no free room in its inventory.
 
  * `itemType` - numerical item id
  * `metadata` - numerical value. `null` means match anything.
  * `count` - how many to withdraw. `null` is an alias to 1.
+ * `nbt` - match nbt data. `null` is do not match nbt.
 
 #### window.close()
 
@@ -745,6 +751,8 @@ Create and return an instance of the class bot.
  * [viewDistance](#bot.settings.viewDistance)
  * [difficulty](#bot.settings.difficulty)
  * [skinParts](#bot.settings.skinParts)
+ * [enableTextFiltering](#bot.settings.enableTextFiltering)
+ * [enableServerListing](#bot.settings.enableServerListing)
  * chatLengthLimit : the maximum amount of characters that can be sent in a single message. If this is not set, it will be 100 in < 1.11 and 256 in >= 1.11.
  * defaultChatPatterns: defaults to true, set to false to not add the patterns such as chat and whisper
 
@@ -881,6 +889,7 @@ Default true, whether or not you receive color codes in chats from the server.
 
 #### bot.settings.viewDistance
 
+Can be a string listed below or a postive number.
 Choices:
  * `far` (default)
  * `normal`
@@ -911,7 +920,10 @@ If you have a cape you can turn it off by setting this to false.
 
 ##### bot.settings.skinParts.showHat - boolean
 
-
+#### bot.settings.enableTextFiltering - boolean
+Unused, defaults to false in Notchian (Vanilla) client.
+#### bot.settings.enableServerListing - boolean
+This setting is sent to the server to determine whether the player should show up in server listings
 #### bot.experience.level
 
 #### bot.experience.points

package/docs/history.md

@@ -1,3 +1,8 @@
+## 4.1.0
+
+* 1.18.2 support
+* Add nbt option to withdraw and deposit
+
 ## 4.0.0
 
 * useEntity maintains sneak state

package/docs/tutorial.md

@@ -17,7 +17,7 @@
     - [Logging in](#logging-in)
   - [Passing along functions](#passing-along-functions)
   - [Listening for an event](#listening-for-an-event)
-  - [Callbacks](#callbacks)
+  - [Promises](#promises)
     - [Correct and incorrect approach](#correct-and-incorrect-approach)
 - [Advanced](#advanced)
   - [Asynchronousy](#asynchronousy)
@@ -430,18 +430,18 @@ To remove specific listener you can use `bot.removeListener()` method.
 
 Not only bot object, [`Chest`](http://mineflayer.prismarine.js.org/#/api?id=mineflayerchest), [`Furnace`](http://mineflayer.prismarine.js.org/#/api?id=mineflayerfurnace), [`Dispenser`](http://mineflayer.prismarine.js.org/#/api?id=mineflayerdispenser), [`EnchantmentTable`](http://mineflayer.prismarine.js.org/#/api?id=mineflayerenchantmenttable), [`Villager`](http://mineflayer.prismarine.js.org/#/api?id=mineflayervillager) object also have their own events!
 
-### Callbacks
-A [callback](https://en.wikipedia.org/wiki/Callback_(computer_programming)) is a function that you can give to another function, that is expected to be *called back*, generally when that function ends.  
-In Mineflayer, callbacks are often used to handle errors.
+### Promises
+A [promise](https://nodejs.dev/learn/understanding-javascript-promises) is a function that you can use the `await` variable to wait on until it's job is complete. (you can omit the await to not wait for results)
 
 ```js
-bot.consume((error) => {
-  if (error) { // This checks if an error occurred.
-    console.log(error)
-  } else {
+async function consume (bot) {
+  try {
+    await bot.consume()
     console.log('Finished consuming')
+  } catch (err) {
+    console.log(error)
   }
-})
+}
 ```
 
 The above code will try to consume what the bot is currently holding.  
@@ -456,91 +456,40 @@ Below is an example of a bot that will craft oak logs into oak planks and then i
 Incorect approach ❌:
 
 ```js
-const plankRecipe = bot.recipesFor(5)[0] // Get the first recipe for item id 5, which is oak planks.
-bot.craft(plankRecipe, 1) // ❌ start crafting oak planks.
+function craft (bot) {
+  const mcData = require('minecraft-data')(bot.version)
+  const plankRecipe = bot.recipesFor(mcData.itemsByName.oak_planks.id ?? mcData.itemsByName.planks.id)[0] // Get the first recipe for oak planks
+  bot.craft(plankRecipe, 1) // ❌ start crafting oak planks.
 
-const stickRecipe = bot.recipesFor(280)[0] // Get the first recipe for item id 5, which is sticks.
-bot.craft(stickRecipe, 1) // ❌ start crafting sticks.
+  const stickRecipe = bot.recipesFor(mcData.itemsByName.sticks.id)[0] // Get the first recipe for sticks
+  bot.craft(stickRecipe, 1) // ❌ start crafting sticks.
+}
 ```
 
-Correct approach with callbacks ✔️:
+Correct approach with promises ✔️:
 
 ```js
-const plankRecipe = bot.recipesFor(5)[0]
-
-bot.craft(plankRecipe, 1, null, (error) => {
-  // After bot.craft(plankRecipe, ...) is finished, this callback is called and we continue. ✔️
-  if (error) { // Check if an error happened.
-    console.log(error)
-  } else {
-    const stickRecipe = bot.recipesFor(280)[0]
-
-    bot.craft(stickRecipe, 1, null, (error) => {
-      // After bot.craft(stickRecipe, ...) is finished, this callback is called and we continue. ✔️
-      if (error) { // Check if an error happened.
-        console.log(error)
-      } else {
-        bot.chat('Crafting Sticks finished')
-      }
-    })
-  }
-})
+async function craft (bot) {
+  const mcData = require('minecraft-data')(bot.version)
+  const plankRecipe = bot.recipesFor(mcData.itemsByName.oak_planks.id ?? mcData.itemsByName.planks.id)[0]
+  await bot.craft(plankRecipe, 1, null)
+  const stickRecipe = bot.recipesFor(mcData.itemsByName.sticks.id)[0]
+  await bot.craft(stickRecipe, 1, null)
+  bot.chat('Crafting Sticks finished')
+}
 ```
 
 The reason the incorrect approach is wrong is because when `bot.craft()` is called, the code will continue below while the bot is crafting.  
 By the time the code reaches the second `bot.craft()`, the first probably hasn't finished yet, which means the wanted resource is not available yet.  
-Using callbacks can fix this because they will only be called after the `bot.craft()` is finished.
+Using promises can fix this because they will only be called after the `bot.craft()` is finished.
 
-More on the [bot.craft()](https://mineflayer.prismarine.js.org/#/api?id=botcraftrecipe-count-craftingtable-callback) method.
+More on the [bot.craft()](https://github.com/PrismarineJS/mineflayer/blob/master/docs/api.md#botcraftrecipe-count-craftingtable) method.
 
 ## Advanced
 
 The following concepts aren't necessary to create a Mineflayer bot, but they can be useful to understand and create more advanced bots.  
 We assume you have understood the [Basics](#basics) tutorial.
 
-### Asynchronousy
-In Javascript, asynchronousy is an important concept.  
-By default, Javascript will run everything line by line, and only go to the next line if the current line is done. This is called blocking.  
-However, sometimes you have to do something that takes a relatively long time, and you don't want your whole program to block and wait for it to finish.  
-
-Interacting with the filesystem is often done using asynchronousy, because reading and writing large files can take a long time.  
-
-```js
-const myPromise = new Promise((resolve, reject) => {
-  setTimeout(() => {
-    resolve('Success!') // Yay! Everything went well!
-  }, 1000)
-})
-
-myPromise.then((successMessage) => {
-  console.log(successMessage)
-})
-
-myPromise.catch((error) => {
-  console.log(error)
-})
-```
-
-The above codes uses what is called a Promise. A promise promises it will eventually complete.  
-The function given you a promise always has 2 parameters, a `resolve` function and a `reject` function.  
-If the promise is successful, it will call the `resolve` function, otherwise it will call the `reject` function.  
-The above code uses a `setTimeout`, which calls the given function after the set amount of milliseconds, 1000 in this case.  
-You can then tell the promise what it should do when it succeeds with `.then(function)` or when it fails with `.catch(function)`
-
-The `.then` and `.catch` function can also be chained together with the promise to simplify the code.
-
-```js
-const myPromise = new Promise((resolve, reject) => {
-  setTimeout(() => {
-    resolve('Success!') // Yay! Everything went well!
-  }, 1000)
-}).then((successMessage) => {
-  console.log(successMessage)
-}).catch((error) => {
-  console.log(error)
-})
-```
-
 ### Loop over an object
 
 The `for of` loop described in the [loops](#loops) chapter can also be used to loop over an object.

package/index.d.ts

@@ -328,8 +328,8 @@ export interface Bot extends TypedEmitter<BotEvents> {
 
   craft: (
     recipe: Recipe,
-    count: number | null,
-    craftingTable: Block
+    count?: number,
+    craftingTable?: Block
   ) => Promise<void>
 
   writeBook: (

package/lib/features.json

@@ -7,7 +7,7 @@
   {
     "name": "spawner",
     "description": "spawner is called spawner",
-    "versions": ["1.13", "1.18.1"]
+    "versions": ["1.13", "1.18.2"]
   },
   {
     "name": "blockMetadata",
@@ -17,12 +17,12 @@
   {
     "name": "blockStateId",
     "description": "block metadata is encoded as state id",
-    "versions": ["1.13", "1.18.1"]
+    "versions": ["1.13", "1.18.2"]
   },
   {
     "name": "creativeSleepNearMobs",
     "description": "can sleep near mobs in creative",
-    "versions": ["1.13", "1.18.1"]
+    "versions": ["1.13", "1.18.2"]
   },
   {
     "name": "fixedPointPosition",
@@ -32,7 +32,7 @@
   {
     "name": "doublePosition",
     "description": "Entity positions are represented with double",
-    "versions": ["1.9", "1.18.1"]
+    "versions": ["1.9", "1.18.2"]
   },
   {
     "name": "fixedPointDelta",
@@ -42,7 +42,7 @@
   {
     "name": "fixedPointDelta128",
     "description": "Delta of position are represented with fixed point numbers times 128",
-    "versions": ["1.9", "1.18.1"]
+    "versions": ["1.9", "1.18.2"]
   },
   {
     "name": "customChannelMCPrefixed",
@@ -52,12 +52,12 @@
   {
     "name": "customChannelIdentifier",
     "description": "custom channel is an identifier starting in minecraft namespace",
-    "versions": ["1.13", "1.18.1"]
+    "versions": ["1.13", "1.18.2"]
   },
   {
     "name": "dimensionDataIsAvailable",
     "description": "dimensionData is available, providing an additional information about the current dimension",
-    "versions": ["1.17", "1.18.1"]
+    "versions": ["1.17", "1.18.2"]
   },
   {
     "name": "useItemWithBlockPlace",
@@ -67,7 +67,7 @@
   {
     "name": "useItemWithOwnPacket",
     "description": "use item is done with its own packet",
-    "versions": ["1.9", "1.18.1"]
+    "versions": ["1.9", "1.18.2"]
   },
   {
     "name": "blockPlaceHasHeldItem",
@@ -87,7 +87,7 @@
   {
     "name": "blockPlaceHasInsideBlock",
     "description": "block_place packet has inside block",
-    "versions": ["1.14", "1.18.1"]
+    "versions": ["1.14", "1.18.2"]
   },
   {
     "name": "teleportUsesPositionPacket",
@@ -102,7 +102,7 @@
   {
     "name": "teleportUsesOwnPacket",
     "description": "teleport is done using its own packet",
-    "versions": ["1.9", "1.18.1"]
+    "versions": ["1.9", "1.18.2"]
   },
   {
     "name": "oneBlockForSeveralVariations",
@@ -112,7 +112,7 @@
   {
     "name": "blockSchemeIsFlat",
     "description": "all variations of a packet have their own id",
-    "versions": ["1.13", "1.18.1"]
+    "versions": ["1.13", "1.18.2"]
   },
   {
     "name": "tabCompleteHasNoToolTip",
@@ -122,7 +122,7 @@
   {
     "name": "tabCompleteHasAToolTip",
     "description": "tab complete has a tool tip",
-    "versions": ["1.13", "1.18.1"]
+    "versions": ["1.13", "1.18.2"]
   },
   {
     "name": "effectAreMinecraftPrefixed",
@@ -132,7 +132,7 @@
   {
     "name": "effectAreNotPrefixed",
     "description": "effect are not prefixed",
-    "versions": ["1.13", "1.18.1"]
+    "versions": ["1.13", "1.18.2"]
   },
   {
     "name": "itemsAreAlsoBlocks",
@@ -142,12 +142,12 @@
   {
     "name": "itemsAreNotBlocks",
     "description": "items are not block",
-    "versions": ["1.13", "1.18.1"]
+    "versions": ["1.13", "1.18.2"]
   },
   {
     "name": "fishingBobberCorrectlyNamed",
     "description": "the fishing hook entity is named fishing_bobber",
-    "versions": ["1.14", "1.18.1"]
+    "versions": ["1.14", "1.18.2"]
   },
   {
     "name": "editBookIsPluginChannel",
@@ -157,7 +157,7 @@
   {
     "name": "hasEditBookPacket",
     "description": "book editing is handled through a packet",
-    "versions": ["1.13", "1.18.1"]
+    "versions": ["1.13", "1.18.2"]
   },
   {
     "name": "clientUpdateBookIdWhenSign",
@@ -197,12 +197,12 @@
   {
     "name": "dimensionIsAWorld",
     "description": "description is a world name (string)",
-    "versions": ["1.16.2", "1.18.1"]
+    "versions": ["1.16.2", "1.18.2"]
   },
   {
     "name": "dimensionDataIsAvailable",
     "description": "dimensionData is available, describing additional dimension information",
-    "versions": ["1.17", "1.18.1"]
+    "versions": ["1.17", "1.18.2"]
   },
   {
     "name": "doesntHaveChestType",
@@ -227,22 +227,22 @@
   {
     "name": "hasAttackCooldown",
     "description": "if there is a cooldown after attacks to deal full damage",
-    "versions": ["1.9", "1.18.1"]
+    "versions": ["1.9", "1.18.2"]
   },
   {
     "name": "usesLoginPacket",
     "description": "uses the login packet as defined in mcData",
-    "versions": ["1.16", "1.18.1"]
+    "versions": ["1.16", "1.18.2"]
   },
   {
     "name": "usesMultiblockSingleLong",
     "description": "in the multi_block_change packet is stored as a single number",
-    "versions": ["1.16.2", "1.18.1"]
+    "versions": ["1.16.2", "1.18.2"]
   },
   {
     "name": "usesMultiblock3DChunkCoords",
     "description": "in the multi_block_change packet, all 3 axis coords are defined",
-    "versions": ["1.16.2", "1.18.1"]
+    "versions": ["1.16.2", "1.18.2"]
   },
   {
     "name": "setBlockUsesMetadataNumber",
@@ -257,7 +257,7 @@
   {
     "name": "selectingTradeMovesItems",
     "description": "selecting a trade automatically puts the required items into trading slots",
-    "versions": ["1.14", "1.18.1"]
+    "versions": ["1.14", "1.18.2"]
   },
   {
     "name": "resourcePackUsesHash",
@@ -272,7 +272,7 @@
   {
     "name": "teamUsesChatComponents",
     "description": "teams use chatcomponents for formatting",
-    "versions": ["1.13", "1.18.1"]
+    "versions": ["1.13", "1.18.2"]
   },
   {
     "name": "teamUsesScoreboard",
@@ -287,7 +287,7 @@
   {
     "name": "enderCrystalNameNoCapsWithUnderscore",
     "description": "this is when the end_crystal's entity name is end_crystal",
-    "versions": ["1.14", "1.18.1"]
+    "versions": ["1.14", "1.18.2"]
   },
   {
     "name": "entityNameUpperCaseNoUnderscore",
@@ -307,7 +307,7 @@
   {
     "name": "stateIdUsed",
     "description": "starting in 1.17.1, actionId has been replaced with stateId",
-    "versions": ["1.17.1", "1.18.1"]
+    "versions": ["1.17.1", "1.18.2"]
   },
   {
     "name": "actionIdUsed",
@@ -317,7 +317,7 @@
   {
     "name": "setSlotAsTransaction",
     "description": "use setslot as transaction instead of just hoping it'll work",
-    "versions": ["1.17", "1.18.1"]
+    "versions": ["1.17", "1.18.2"]
   },
   {
     "name": "armAnimationBeforeUse",
@@ -327,7 +327,7 @@
   {
     "name": "tallWorld",
     "description": "world starts at -64 and ends at 384",
-    "versions": ["1.18", "1.18.1"]
+    "versions": ["1.18", "1.18.2"]
   },
   {
     "name": "sendStringifiedSignText",

package/lib/plugins/inventory.js

@@ -306,16 +306,17 @@ function inject (bot, { version, hideErrors }) {
       window.emit('close')
       closeWindow(window)
     }
-    window.withdraw = async (itemType, metadata, count) => {
+
+    window.withdraw = async (itemType, metadata, count, nbt) => {
       if (bot.inventory.emptySlotCount() === 0) {
         throw new Error('Unable to withdraw, Bot inventory is full.')
       }
-
       const options = {
         window,
         itemType,
         metadata,
         count,
+        nbt,
         sourceStart: 0,
         sourceEnd: window.inventoryStart,
         destStart: window.inventoryStart,
@@ -323,12 +324,13 @@ function inject (bot, { version, hideErrors }) {
       }
       await transfer(options)
     }
-    window.deposit = async (itemType, metadata, count) => {
+    window.deposit = async (itemType, metadata, count, nbt) => {
       const options = {
         window: window,
         itemType,
         metadata,
         count,
+        nbt,
         sourceStart: window.inventoryStart,
         sourceEnd: window.inventoryEnd,
         destStart: 0,

package/lib/plugins/settings.js

@@ -23,13 +23,27 @@ const viewDistanceToBits = {
 function inject (bot, options) {
   function setSettings (settings) {
     extend(bot.settings, settings)
+
+    // chat
     const chatBits = chatToBits[bot.settings.chat]
     assert.ok(chatBits != null, `invalid chat setting: ${bot.settings.chat}`)
-    const viewDistanceBits = viewDistanceToBits[bot.settings.viewDistance]
+
+    // view distance
+    let viewDistanceBits = null
+    if (typeof bot.settings.viewDistance === 'string') {
+      viewDistanceBits = viewDistanceToBits[bot.settings.viewDistance]
+    } else if (typeof bot.settings.viewDistance === 'number' && bot.settings.viewDistance > 0) { // Make sure view distance is a valid # || should be 2 or more
+      viewDistanceBits = bot.settings.viewDistance
+    }
     assert.ok(viewDistanceBits != null, `invalid view distance setting: ${bot.settings.viewDistance}`)
+
+    // hand
     const handBits = handToBits[bot.settings.mainHand]
     assert.ok(handBits != null, `invalid main hand: ${bot.settings.mainHand}`)
-    bot.settings.showCape = !!bot.settings.showCape
+
+    // skin
+    // cape is inverted, not used at all (legacy?)
+    // bot.settings.showCape = !!bot.settings.showCape
     const skinParts = bot.settings.skinParts.showCape << 0 |
           bot.settings.skinParts.showJacket << 1 |
           bot.settings.skinParts.showLeftSleeve << 2 |
@@ -37,13 +51,17 @@ function inject (bot, options) {
           bot.settings.skinParts.showLeftPants << 4 |
           bot.settings.skinParts.showRightPants << 5 |
           bot.settings.skinParts.showHat << 6
+
+    // write the packet
     bot._client.write('settings', {
       locale: bot.settings.locale || 'en_US',
       viewDistance: viewDistanceBits,
       chatFlags: chatBits,
       chatColors: bot.settings.colorsEnabled,
       skinParts: skinParts,
-      mainHand: handBits
+      mainHand: handBits,
+      enableTextFiltering: bot.settings.enableTextFiltering,
+      enableServerListing: bot.settings.enableServerListing
     })
   }
 
@@ -67,7 +85,9 @@ function inject (bot, options) {
           showHat: true
         }
       : options.skinParts,
-    mainHand: options.mainHand || 'right'
+    mainHand: options.mainHand || 'right',
+    enableTextFiltering: options.enableTextFiltering || false,
+    enableServerListing: options.enableServerListing || true
   }
 
   bot._client.once('login', () => {

package/lib/version.js

@@ -1,4 +1,4 @@
 module.exports = {
   supportedVersions: ['1.8', '1.9', '1.10', '1.11', '1.12', '1.13', '1.14', '1.15', '1.16', '1.17', '1.18'],
-  testedVersions: ['1.8.8', '1.9.4', '1.10.2', '1.11.2', '1.12.2', '1.13.2', '1.14.4', '1.15.2', '1.16.5', '1.17.1', '1.18.1']
+  testedVersions: ['1.8.8', '1.9.4', '1.10.2', '1.11.2', '1.12.2', '1.13.2', '1.14.4', '1.15.2', '1.16.5', '1.17.1', '1.18.2']
 } // when updating testedVersions, make sure to update CI.yml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mineflayer",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "create minecraft bots with a stable, high level API",
   "main": "index.js",
   "types": "index.d.ts",
@@ -21,8 +21,8 @@
   },
   "license": "MIT",
   "dependencies": {
-    "minecraft-data": "^2.109.0",
-    "minecraft-protocol": "^1.26.5",
+    "minecraft-data": "^2.114.1",
+    "minecraft-protocol": "^1.31.0",
     "prismarine-biome": "^1.1.1",
     "prismarine-block": "^1.13.1",
     "prismarine-chat": "^1.3.3",