mineflayer 3.17.0 → 4.1.0

package/docs/es/README_ES.md

@@ -17,7 +17,7 @@ Crea bots para Minecraft con una API de JavaScript potente, estable y de alto ni
 
 ## Características
 
- * Soporta Minecraft 1.8, 1.9, 1.10, 1.11, 1.12, 1.13, 1.14, 1.15 y 1.16.
+ * Soporta Minecraft 1.8, 1.9, 1.10, 1.11, 1.12, 1.13, 1.14, 1.15, 1.16, 1.17 y 1.18.
  * Rastreo e información de entidades.
  * Información sobre bloques. Puedes solicitar información de todo lo que te rodea. Encuentra bloques en milisegundos
  * Físicas y movimientos básicos - maneja todos los cuadros de colisión
@@ -34,6 +34,7 @@ Crea bots para Minecraft con una API de JavaScript potente, estable y de alto ni
 Echa un vistazo a nuestros [proyectos actuales](https://github.com/PrismarineJS/mineflayer/wiki/Big-Prismarine-projects)
 
 ## Instalación
+Primero instala Node.js >= 14 desde [nodejs.org](https://nodejs.org/)
 
 `npm install mineflayer`
 
@@ -66,10 +67,9 @@ Si quieres aprender más, puedes mirar [aquí, ](https://www.youtube.com/playlis
 
 **Empezando**
 
-Sin especificar una versión, la versión del servidor se detectará automáticamente, puedes configurar una versión específica utilizando la opción de versión.
-Por ejemplo `version:" 1.8 "`.
+Si no se especifica una versión, la versión del servidor se detectará automáticamente. Si no se especifica ningún tipo de autenticación, se utilizará el login de Mojang automáticamente. 
 
-### Ejemplo
+### Ejemplo: echo
 ```js
 const mineflayer = require('mineflayer')
 
@@ -92,7 +92,7 @@ bot.on('kicked', (reason, loggedIn) => console.log(reason, loggedIn))
 bot.on('error', err => console.log(err))
 ```
 
-### Mira lo que tu bot hace
+### Mira lo que hace tu bot
 
 Gracias al proyecto [prismarine-viewer](https://github.com/PrismarineJS/prismarine-viewer), puedes ver en una pestaña del navegador qué está haciendo tu bot.
 Solo tienes que ejecutar `npm install prismarine-viewer` y añadir lo siguiente a tu bot:
@@ -124,7 +124,7 @@ Más ejemplos en la carpeta de [ejemplos](https://github.com/PrismarineJS/minefl
 
 ### Módulos
 
-La mayoría del desarrollo se esta produciendo dentro de pequeños módulos npm que son usados por mineflayer
+La mayoría del desarrollo se está produciendo dentro de pequeños módulos npm que son usados por mineflayer
 
 #### The Node Way™
 

package/docs/history.md

@@ -1,3 +1,17 @@
+## 4.1.0
+
+* 1.18.2 support
+* Add nbt option to withdraw and deposit
+
+## 4.0.0
+
+* useEntity maintains sneak state
+* BREAKING: remove all callbacks in favor of promises
+
+## 3.18.0
+
+* remove callbacks from types and docs
+
 ## 3.17.0
 
 * callback are now depreciated with mineflayer. Any use of them will print a warning

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

@@ -229,7 +229,6 @@ export interface Bot extends TypedEmitter<BotEvents> {
 
   tabComplete: (
     str: string,
-    cb: (matches: string[]) => void,
     assumeCommand?: boolean,
     sendBlockInSight?: boolean
   ) => Promise<string[]>
@@ -248,11 +247,11 @@ export interface Bot extends TypedEmitter<BotEvents> {
 
   hasPlugin: (plugin: Plugin) => boolean
 
-  sleep: (bedBlock: Block, cb?: (err?: Error) => void) => Promise<void>
+  sleep: (bedBlock: Block) => Promise<void>
 
   isABed: (bedBlock: Block) => void
 
-  wake: (cb?: (err?: Error) => void) => Promise<void>
+  wake: () => Promise<void>
 
   setControlState: (control: ControlState, state: boolean) => void
 
@@ -262,38 +261,34 @@ export interface Bot extends TypedEmitter<BotEvents> {
 
   getExplosionDamages: (targetEntity: Entity, position: Vec3, radius: number, rawDamages?: boolean) => number | null
 
-  lookAt: (point: Vec3, force?: boolean, callback?: () => void) => Promise<void>
+  lookAt: (point: Vec3, force?: boolean) => Promise<void>
 
   look: (
     yaw: number,
     pitch: number,
-    force?: boolean,
-    callback?: () => void
+    force?: boolean
   ) => Promise<void>
 
   updateSign: (block: Block, text: string) => void
 
   equip: (
     item: Item | number,
-    destination: EquipmentDestination | null,
-    callback?: (error?: Error) => void
+    destination: EquipmentDestination | null
   ) => Promise<void>
 
   unequip: (
-    destination: EquipmentDestination | null,
-    callback?: () => void
+    destination: EquipmentDestination | null
   ) => Promise<void>
 
-  tossStack: (item: Item, callback?: (error?: Error) => void) => Promise<void>
+  tossStack: (item: Item) => Promise<void>
 
   toss: (
     itemType: number,
     metadata: number | null,
-    count: number | null,
-    callback?: (err?: Error) => void
+    count: number | null
   ) => Promise<void>
 
-  dig: ((block: Block, forceLook?: boolean | 'ignore', callback?: (err?: Error) => void) => Promise<void>) & ((block: Block, forceLook: boolean | 'ignore', digFace: 'auto' | Vec3 | 'raycast', callback?: (err?: Error) => void) => Promise<void>)
+  dig: ((block: Block, forceLook?: boolean | 'ignore') => Promise<void>) & ((block: Block, forceLook: boolean | 'ignore', digFace: 'auto' | Vec3 | 'raycast') => Promise<void>)
 
   stopDigging: () => void
 
@@ -303,15 +298,15 @@ export interface Bot extends TypedEmitter<BotEvents> {
 
   placeEntity: (referenceBlock: Block, faceVector: Vec3) => Promise<Entity>
 
-  activateBlock: (block: Block, callback?: (err?: Error) => void) => Promise<void>
+  activateBlock: (block: Block) => Promise<void>
 
-  activateEntity: (block: Entity, callback?: (err?: Error) => void) => Promise<void>
+  activateEntity: (block: Entity) => Promise<void>
 
-  activateEntityAt: (block: Entity, position: Vec3, callback?: (err?: Error) => void) => Promise<void>
+  activateEntityAt: (block: Entity, position: Vec3) => Promise<void>
 
-  consume: (callback?: (err?: Error) => void) => Promise<void>
+  consume: () => Promise<void>
 
-  fish: (callback?: (err?: Error) => void) => Promise<void>
+  fish: () => Promise<void>
 
   activateItem: (offhand?: boolean) => void
 
@@ -333,15 +328,13 @@ export interface Bot extends TypedEmitter<BotEvents> {
 
   craft: (
     recipe: Recipe,
-    count: number | null,
-    craftingTable: Block,
-    callback?: () => void
+    count?: number,
+    craftingTable?: Block
   ) => Promise<void>
 
   writeBook: (
     slot: number,
-    pages: string[],
-    callback?: (err?: Error) => void
+    pages: string[]
   ) => Promise<void>
 
   openContainer: (chest: Block | Entity) => Promise<Chest | Furnace | Dispenser>
@@ -363,8 +356,7 @@ export interface Bot extends TypedEmitter<BotEvents> {
   trade: (
     villagerInstance: Villager,
     tradeIndex: string | number,
-    times?: number,
-    cb?: (err?: Error) => void
+    times?: number
   ) => Promise<void>
 
   setCommandBlock: (pos: Vec3, command: string, trackOutput: boolean) => void
@@ -372,23 +364,21 @@ export interface Bot extends TypedEmitter<BotEvents> {
   clickWindow: (
     slot: number,
     mouseButton: number,
-    mode: number,
-    cb?: (err?: Error) => void
+    mode: number
   ) => Promise<void>
 
   putSelectedItemRange: (
     start: number,
     end: number,
     window: Window,
-    slot: any,
-    cb?: (err?: Error) => void
+    slot: any
   ) => Promise<void>
 
-  putAway: (slot: number, cb?: (err?: Error) => void) => Promise<void>
+  putAway: (slot: number) => Promise<void>
 
   closeWindow: (window: Window) => void
 
-  transfer: (options: TransferOptions, cb?: (err?: Error) => void) => Promise<void>
+  transfer: (options: TransferOptions) => Promise<void>
 
   openBlock: (block: Block, Class: new () => EventEmitter) => Promise<void>
 
@@ -396,15 +386,14 @@ export interface Bot extends TypedEmitter<BotEvents> {
 
   moveSlotItem: (
     sourceSlot: number,
-    destSlot: number,
-    cb?: (err?: Error) => void
+    destSlot: number
   ) => Promise<void>
 
   updateHeldItem: () => void
 
   getEquipmentDestSlot: (destination: string) => number
 
-  waitForChunksToLoad: (cb?: (err?: Error) => void) => Promise<void>
+  waitForChunksToLoad: () => Promise<void>
 
   nearestEntity: (filter?: (entity: Entity) => boolean) => Entity | null
 
@@ -579,11 +568,10 @@ export interface TransferOptions {
 export interface creativeMethods {
   setInventorySlot: (
     slot: number,
-    item: Item | null,
-    callback?: (error?: Error) => void
+    item: Item | null
   ) => Promise<void>
 
-  flyTo: (destination: Vec3, cb?: () => void) => Promise<void>
+  flyTo: (destination: Vec3) => Promise<void>
 
   startFlying: () => void
 
@@ -634,15 +622,13 @@ export class Chest extends (EventEmitter as new () => TypedEmitter<StorageEvents
   deposit (
     itemType: number,
     metadata: number | null,
-    count: number | null,
-    cb?: (err?: Error) => void
+    count: number | null
   ): Promise<void>;
 
   withdraw (
     itemType: number,
     metadata: number | null,
-    count: number | null,
-    cb?: (err?: Error) => void
+    count: number | null
   ): Promise<void>;
 
   count (itemType: number, metadata: number | null): number;
@@ -658,24 +644,22 @@ export class Furnace extends (EventEmitter as new () => TypedEmitter<FurnaceEven
 
   close (): void;
 
-  takeInput (cb: (err: Error | null, item: Item) => void): Promise<Item>;
+  takeInput (): Promise<Item>;
 
-  takeFuel (cb: (err: Error | null, item: Item) => void): Promise<Item>;
+  takeFuel (): Promise<Item>;
 
-  takeOutput (cb: (err: Error | null, item: Item) => void): Promise<Item>;
+  takeOutput (): Promise<Item>;
 
   putInput (
     itemType: number,
     metadata: number | null,
-    count: number,
-    cb?: (err?: Error) => void
+    count: number
   ): Promise<void>;
 
   putFuel (
     itemType: number,
     metadata: number | null,
-    count: number,
-    cb?: (err?: Error) => void
+    count: number
   ): Promise<void>;
 
   inputItem (): Item;
@@ -693,15 +677,13 @@ export class Dispenser extends (EventEmitter as new () => TypedEmitter<StorageEv
   deposit (
     itemType: number,
     metadata: number | null,
-    count: number | null,
-    cb?: (err?: Error) => void
+    count: number | null
   ): Promise<void>;
 
   withdraw (
     itemType: number,
     metadata: number | null,
-    count: number | null,
-    cb?: (err?: Error) => void
+    count: number | null
   ): Promise<void>;
 
   count (itemType: number, metadata: number | null): number;
@@ -719,15 +701,14 @@ export class EnchantmentTable extends (EventEmitter as new () => TypedEmitter<Co
   targetItem (): Item;
 
   enchant (
-    choice: string | number,
-    cb?: (err: Error | null, item: Item) => void
+    choice: string | number
   ): Promise<Item>;
 
-  takeTargetItem (cb?: (err: Error | null, item: Item) => void): Promise<Item>;
+  takeTargetItem (): Promise<Item>;
 
-  putTargetItem (item: Item, cb?: (err: Error | null) => void): Promise<Item>;
+  putTargetItem (item: Item): Promise<Item>;
 
-  putLapis (item: Item, cb?: (err: Error | null) => void): Promise<Item>;
+  putLapis (item: Item): Promise<Item>;
 }
 
 export class Anvil {