mineflayer 4.13.0 → 4.15.0

package/.github/workflows/ci.yml

@@ -17,42 +17,44 @@ jobs:
       with:
         node-version: 18.x
     - run: npm i && npm run lint
+  
+  PrepareSupportedVersions:
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.set-matrix.outputs.matrix }}
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Use Node.js 18.x
+      uses: actions/setup-node@v1.4.4
+      with:
+        node-version: 18.x
+    - id: set-matrix
+      run: |
+        node -e "
+          const testedVersions = require('./lib/version').testedVersions;
+          console.log('matrix='+JSON.stringify({'include': testedVersions.map(mcVersion => ({mcVersion}))}))
+        " >> $GITHUB_OUTPUT
 
   MinecraftServer:
+    needs: PrepareSupportedVersions
     runs-on: ubuntu-latest
     strategy:
-      matrix:
-        javaVersion: [1.8]
-        mcVersion: ['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']
-        include:
-         - javaVersion: 16
-           mcVersion: '1.17.1'
-         - javaVersion: 17
-           mcVersion: '1.18.2'
-         - javaVersion: 17
-           mcVersion: '1.19'
-         - javaVersion: 17
-           mcVersion: '1.19.2'
-         - javaVersion: 17
-           mcVersion: '1.19.3'
-         - javaVersion: 17
-           mcVersion: '1.19.4'
-         - javaVersion: 17
-           mcVersion: '1.20.1'
+      matrix: ${{fromJson(needs.PrepareSupportedVersions.outputs.matrix)}}
       fail-fast: false
 
     steps:
       - uses: actions/checkout@v2
-      - name: Use Node.js ${{ matrix.node-version }}
+      - name: Use Node.js 18.x
         uses: actions/setup-node@v1.4.4
         with:
           node-version: 18.x
       - name: Setup Java JDK
         uses: actions/setup-java@v1.4.3
         with:
-          java-version: ${{ matrix.javaVersion }}
+          java-version: 17
           java-package: jre
       - name: Install Dependencies
         run: npm install
       - name: Start Tests
-        run: npm run mocha_test -- -g ${{ matrix.mcVersion }}
+        run: npm run mocha_test -- -g ${{ matrix.mcVersion }}v

package/README.md

@@ -8,8 +8,8 @@
 
 [![Official Discord](https://img.shields.io/static/v1.svg?label=OFFICIAL&message=DISCORD&color=blue&logo=discord&style=for-the-badge)](https://discord.gg/GsEFRM8)
 
-| <sub>EN</sub> [English](README.md) | <sub>RU</sub> [русский](ru/README_RU.md) | <sub>ES</sub> [Español](es/README_ES.md) | <sub>FR</sub> [Français](fr/README_FR.md) | <sub>TR</sub> [Türkçe](tr/README_TR.md) | <sub>ZH</sub> [中文](zh/README_ZH_CN.md) |
-|-------------------------|----------------------------|----------------------------|----------------------------|----------------------------|----------------------------|
+| <sub>EN</sub> [English](README.md) | <sub>RU</sub> [русский](ru/README_RU.md) | <sub>ES</sub> [Español](es/README_ES.md) | <sub>FR</sub> [Français](fr/README_FR.md) | <sub>TR</sub> [Türkçe](tr/README_TR.md) | <sub>ZH</sub> [中文](zh/README_ZH_CN.md) | <sub>BR</sub> [Português](br/README_BR.md) |
+|-------------------------|----------------------------|----------------------------|----------------------------|----------------------------|-------------------------|--------------------|
 
 Create Minecraft bots with a powerful, stable, and high level JavaScript [API](api.md), also usable from Python.
 

package/docs/README.md

@@ -8,8 +8,8 @@
 
 [![Official Discord](https://img.shields.io/static/v1.svg?label=OFFICIAL&message=DISCORD&color=blue&logo=discord&style=for-the-badge)](https://discord.gg/GsEFRM8)
 
-| <sub>EN</sub> [English](README.md) | <sub>RU</sub> [русский](ru/README_RU.md) | <sub>ES</sub> [Español](es/README_ES.md) | <sub>FR</sub> [Français](fr/README_FR.md) | <sub>TR</sub> [Türkçe](tr/README_TR.md) | <sub>ZH</sub> [中文](zh/README_ZH_CN.md) |
-|-------------------------|----------------------------|----------------------------|----------------------------|----------------------------|----------------------------|
+| <sub>EN</sub> [English](README.md) | <sub>RU</sub> [русский](ru/README_RU.md) | <sub>ES</sub> [Español](es/README_ES.md) | <sub>FR</sub> [Français](fr/README_FR.md) | <sub>TR</sub> [Türkçe](tr/README_TR.md) | <sub>ZH</sub> [中文](zh/README_ZH_CN.md) | <sub>BR</sub> [Português](br/README_BR.md) |
+|-------------------------|----------------------------|----------------------------|----------------------------|----------------------------|-------------------------|--------------------|
 
 Create Minecraft bots with a powerful, stable, and high level JavaScript [API](api.md), also usable from Python.
 

package/docs/api.md

@@ -136,6 +136,7 @@
       - [bot.foodSaturation](#botfoodsaturation)
       - [bot.oxygenLevel](#botoxygenlevel)
       - [bot.physics](#botphysics)
+      - [bot.fireworkRocketDuration](#botfireworkrocketduration)
       - [bot.simpleClick.leftMouse (slot)](#botsimpleclickleftmouse-slot)
       - [bot.simpleClick.rightMouse (slot)](#botsimpleclickrightmouse-slot)
       - [bot.time.doDaylightCycle](#bottimedodaylightcycle)
@@ -197,6 +198,7 @@
       - ["entityEquip" (entity)](#entityequip-entity)
       - ["entitySleep" (entity)](#entitysleep-entity)
       - ["entitySpawn" (entity)](#entityspawn-entity)
+      - ["entityElytraFlew" (entity)](#entityelytraflew-entity)
       - ["itemDrop" (entity)](#itemdrop-entity)
       - ["playerCollect" (collector, collected)](#playercollect-collector-collected)
       - ["entityGone" (entity)](#entitygone-entity)
@@ -223,6 +225,7 @@
       - ["blockBreakProgressEnd" (block, entity)](#blockbreakprogressend-block-entity)
       - ["diggingCompleted" (block)](#diggingcompleted-block)
       - ["diggingAborted" (block)](#diggingaborted-block)
+      - ["usedFirework"](#usedfirework)
       - ["move"](#move)
       - ["forcedMove"](#forcedmove)
       - ["mount"](#mount)
@@ -293,6 +296,7 @@
       - [bot.unequip(destination)](#botunequipdestination)
       - [bot.tossStack(item)](#bottossstackitem)
       - [bot.toss(itemType, metadata, count)](#bottossitemtype-metadata-count)
+      - [bot.elytraFly()](#botelytrafly)
       - [bot.dig(block, [forceLook = true], [digFace])](#botdigblock-forcelook--true-digface)
       - [bot.stopDigging()](#botstopdigging)
       - [bot.digTime(block)](#botdigtimeblock)
@@ -1037,6 +1041,10 @@ Number in the range [0, 20] respresenting the number of water-icons known as oxy
 Edit these numbers to tweak gravity, jump speed, terminal velocity, etc.
 Do this at your own risk.
 
+#### bot.fireworkRocketDuration
+
+How many physics ticks worth of firework rocket boost are left.
+
 #### bot.simpleClick.leftMouse (slot)
 
 abstraction over `bot.clickWindow(slot, 0, 0)`
@@ -1301,6 +1309,10 @@ Fires when an attribute of an entity changes.
 #### "entityEquip" (entity)
 #### "entitySleep" (entity)
 #### "entitySpawn" (entity)
+#### "entityElytraFlew" (entity)
+
+An entity started elytra flying.
+
 #### "itemDrop" (entity)
 #### "playerCollect" (collector, collected)
 
@@ -1384,7 +1396,7 @@ Fires when a note block goes off somewhere.
  * `pitch`: The pitch of the note (between 0-24 inclusive where 0 is the
    lowest and 24 is the highest). More information about how the pitch values
    correspond to notes in real life are available on the
-   [official Minecraft wiki](http://www.minecraftwiki.net/wiki/Note_Block).
+   [official Minecraft wiki](http://minecraft.wiki/w/Note_Block).
 
 #### "pistonMove" (block, isPulling, direction)
 
@@ -1417,6 +1429,12 @@ This occurs whether the process was completed or aborted.
 
  * `block` - the block that still exists
 
+#### "usedFirework" (fireworkEntityId)
+
+Fires when the bot uses a firework while elytra flying.
+
+ * `fireworkEntityId` - the entity id of the firework.
+
 #### "move"
 
 Fires when the bot moves. If you want the current position, use
@@ -1851,6 +1869,11 @@ This function returns a `Promise`, with `void` as its argument once tossing is c
    to match any metadata
  * `count` - how many you want to toss. `null` is an alias for `1`.
 
+#### bot.elytraFly()
+
+This function returns a `Promise`, with `void` as its argument once activating
+elytra flight is complete. It will throw an Error if it fails.
+
 #### bot.dig(block, [forceLook = true], [digFace])
 
 This function returns a `Promise`, with `void` as its argument when the block is broken or you are interrupted.
@@ -1946,7 +1969,9 @@ Use fishing rod
 
 #### bot.activateItem(offHand=false)
 
-Activates the currently held item. This is how you eat, shoot bows, throw an egg, etc.
+Activates the currently held item. This is how you eat, shoot bows, throw an
+egg, activate firework rockets, etc.
+
 Optional parameter is `false` for main hand and `true` for off hand.
 
 #### bot.deactivateItem()

package/docs/br/CONTRIBUTING_BR.md

@@ -0,0 +1,84 @@
+# Contribuir
+
+O Mineflayer foi originalmente criado principalmente por [andrewrk](http://github.com/andrewrk), mas tem sido muito aprimorado e corrigido por muitos [contribuidores](https://github.com/andrewrk/mineflayer/graphs/contributors). Portanto, é importante saber a melhor maneira de contribuir para o Mineflayer.
+
+## Organização de Problemas
+
+Temos 3 etiquetas para 3 fases de organização de problemas:
+
+* Estágio 1: (Fase 1) criado por alguém novo no projeto, não sabemos se merece uma implementação / solução
+* Estágio 2: (Fase 2) ideia promissora, mas é necessário pensar mais sobre o assunto antes de implementá-lo
+* Estágio 3: (Fase 3) a ideia é muito precisa, só precisa ser programada
+
+Links como https://github.com/PrismarineJS/mineflayer/issues?q=is%3Aopen+is%3Aissue+-label%3AStage1 podem ser usados como filtro para a fase 1 se você estiver procurando coisas prontas para serem contribuídas.
+
+## Criando Testes
+O Mineflayer possui dois tipos de testes:
+
+ * [Testes internos](test/internalTest.js): testes feitos com um servidor simples criado com o node-minecraft-protocol
+ * [Testes externos](test/externalTests/): testes feitos com um servidor Vanilla
+ 
+O objetivo desses testes é determinar automaticamente o que funciona e o que não funciona no Mineflayer, tornando mais fácil a correção de problemas.
+
+### Criando um Teste Externo
+
+Para criar um teste externo, basta criar um arquivo em [test/externalTests](test/externalTests).
+
+Um exemplo: [test/externalTests/digAndBuild.js](https://github.com/PrismarineJS/mineflayer/blob/master/test/externalTests/digAndBuild.js)
+
+Esse arquivo deve exportar uma função que retorna uma função ou um array de funções que recebem o objeto bot e um callback como parâmetros, e deve conter verificações para determinar se a função testada falhou.
+
+## Criando um Plugin de Terceiros
+O Mineflayer suporta plugins; qualquer pessoa pode criar um plugin que adiciona uma API de nível mais alto acima do Mineflayer.
+
+Vários plugins de terceiros foram [criados](https://github.com/andrewrk/mineflayer#third-party-plugins).
+
+Para criar um novo plugin, você deve:
+
+1. Criar um novo repositório.
+2. No seu arquivo index.js, exportar uma função para inicializar o plugin com o argumento Mineflayer ([exemplo](https://github.com/andrewrk/mineflayer-navigate/blob/e24cb6a868ce64ae43bea2d035832c15ed01d301/index.js#L18)).
+3. Essa função deve retornar uma função para introduzir o plugin com o objeto bot ([exemplo](https://github.com/andrewrk/mineflayer-navigate/blob/e24cb6a868ce64ae43bea2d035832c15ed01d301/index.js#L23)).
+4. A partir dessa função, você pode adicionar mais funcionalidades ao bot ([exemplo](https://github.com/andrewrk/mineflayer-navigate/blob/e24cb6a868ce64ae43bea2d035832c15ed01d301/index.js#L32)).
+
+Como o objeto Mineflayer é passado como argumento, esse plugin de terceiros não deve depender do Mineflayer (não deve haver referência ao Mineflayer no package.json).
+
+Veja um [exemplo completo](https://github.com/andrewrk/mineflayer-navigate/tree/e24cb6a868ce64ae43bea2d035832c15ed01d301) aqui.
+
+## Relatando Bugs
+O Mineflayer funciona bem na maioria das situações, mas às vezes ainda pode ter bugs.
+
+Ao encontrar um bug, é melhor relatar o erro fornecendo as seguintes informações:
+
+* O que você está tentando fazer (o objetivo em inglês).
+* O que você tentou (o código).
+* O que aconteceu.
+* O que você esperava que acontecesse.
+
+## Código do Mineflayer
+Aqui estão algumas coisas a se considerar ao criar uma solicitação de pull (pull request) ou fazer um commit:
+
+### Tratamento de Erros
+Na maioria dos casos, o Mineflayer não deve quebrar ou travar o bot. Mesmo se algo der errado, o bot pode seguir uma rota alternativa para alcançar o objetivo.
+
+Isso significa que não devemos usar `throw new Error("erro")`, mas sim passar o erro junto com o callback.
+
+Por exemplo:
+
+```js
+function myfunction (param1, callback) {
+  let toDo = 1
+  toDo = 2
+  if (toDo === 2) { // everything worked (todo está funcionado)
+    callback()
+  } else {
+    callback(new Error('something failed')) // (algo falhou)
+  }
+}
+```
+
+Veja outro exemplo no [código do Mineflayer](https://github.com/andrewrk/mineflayer/blob/a8736c4ea473cf1a609c5a29046c0cdad006d429/lib/plugins/bed.js#L10).
+
+### Atualizando a Documentação
+A tabela de conteúdo no arquivo docs/api.md é gerada com o Doctoc. Após atualizar o arquivo, você deve executar doctoc docs/api.md para atualizar a tabela de conteúdo.
+
+Esta documentação não é oficialmente mantida; para ver as informações mais recentes, consulte a documentação original: [unstable_api](../CONTRIBUTING.md).

package/docs/br/FAQ_BR.md

@@ -0,0 +1,169 @@
+## Perguntas Frequentes
+
+Este documento de perguntas frequentes tem o objetivo de ajudar as pessoas com informações básicas.
+
+## Como ocultar erros?
+
+Para ocultar erros, você pode adicionar a opção `hideErrors: true` nas configurações ao criar o bot. Também é possível usar os seguintes eventos:
+
+```js
+client.on('error', () => {})
+client.on('end', () => {})
+```
+
+## Meu evento de chat não está sendo emitido em um servidor personalizado. Como posso resolver isso?
+
+Alguns servidores Spigot, em particular certos plugins, utilizam formatos personalizados de chat. Nesse caso, é necessário analisar esses formatos com expressões regulares personalizadas. Recomenda-se ler e modificar o arquivo [chat_parsing.js](https://github.com/PrismarineJS/mineflayer/blob/master/examples/chat_parsing.js) para que funcione com o plugin de chat específico do seu servidor. Você também pode consultar http://prismarinejs.github.io/mineflayer/#/tutorial?id=custom-chat para obter mais informações.
+
+## Como posso coletar informações de um plugin de chat personalizado?
+
+A maioria dos servidores de Minecraft possui plugins que enviam mensagens ao chat quando ocorrem eventos. Se a informação enviada for simples, você pode utilizar a solução mencionada anteriormente. No entanto, se as mensagens contêm muita informação em um único bloco de texto, outra opção é utilizar o evento `"messagestr"`, que permite analisar as mensagens de forma mais fácil.
+
+**Exemplo:**
+
+Suponha que a mensagem seja semelhante a esta:
+
+```
+(!) U9G ganhou o /jackpot e recebeu
+$26,418,402,450! Eles compraram 2,350,000 (76.32%) bilhetes
+de um total de 3,079,185 bilhetes vendidos!
+```
+
+```js
+const regex = {
+  first: /\(!\) (.+) ganhou o \/jackpot e recebeu +/,
+  second: /\$(.+)! Eles compraram (.+) \((.+)%\) bilhetes do total de /,
+  third: /(.+) bilhetes vendidos!/
+}
+
+let jackpot = {}
+bot.on('messagestr', msg => {
+  if (regex.first.test(msg)) {
+    const username = msg.match(regex.first)[1]
+    jackpot.username = username
+  } else if (regex.second.test(msg)) {
+    const [, moneyWon, boughtTickets, winPercent] = msg.match(regex.second)
+    jackpot.moneyWon = parseInt(moneyWon.replace(/,/g, ''))
+    jackpot.boughtTickets = parseInt(boughtTickets.replace(/,/g, ''))
+    jackpot.winPercent = parseFloat(winPercent)
+  } else if (regex.third.test(msg)) {
+    const totalTickets = msg.match(regex.third)[1]
+    jackpot.totalTickets = parseInt(totalTickets.replace(/,/g, ''))
+    onDone(jackpot)
+    jackpot = {}
+  }
+})
+```
+
+## Como posso enviar um comando?
+
+Usando `bot.chat()`.
+
+**Exmemplo:**
+```js
+bot.chat('/give @p diamond')
+```
+
+### É possível criar vários bots e controlá-los separadamente?
+
+Você pode criar bots diferentes com a função `createBot` e executar ações diferentes para cada um deles. Dê uma olhada no arquivo `multiple.js` para mais informações.
+
+### Como faço para o bot largar todo o seu inventário?
+
+Você pode usar a função `bot.inventory.items()` para obter uma matriz dos itens no inventário do bot. Você pode criar uma função recursiva para largar cada item usando `bot.toss()`. Veja um exemplo [aqui](https://gist.github.com/dada513/3d88f772be4224b40f9e5d1787bd63e9).
+
+### Como vejo os pacotes que foram enviados/recebidos?
+
+Você pode ativar o modo de depuração. Para obter mais informações, consulte [este link](https://github.com/PrismarineJS/mineflayer/blob/master/docs/br/README_BR.md#depuraci%C3%B3n).
+
+### Quero evitar desconexões devido a lag no servidor, como posso fazer isso?
+
+Uma maneira de evitar desconexões devido à latência no servidor é aumentar o valor na opção `checkTimeoutInterval` (por exemplo, `300*1000`, que representa 5 minutos, em vez do valor padrão, que é 30 segundos). Se mesmo assim você continuar sendo desconectado do servidor, você pode se reconectar automaticamente usando este exemplo [aqui](https://github.com/PrismarineJS/mineflayer/blob/master/examples/reconnector.js).
+
+### Como posso obter a descrição/texto de um item?
+
+Você pode usar a propriedade `item.nbt`. É recomendável utilizar a biblioteca `prismarine-nbt`. O método `nbt.simplify()` pode ser útil para simplificar a obtenção da descrição de um item.
+
+**Exemplo:**
+```js
+function getLore (item) {
+  let message = ''
+  if (item.nbt == null) return message
+
+  const nbt = require('prismarine-nbt')
+  const ChatMessage = require('prismarine-chat')(bot.version)
+
+  const data = nbt.simplify(item.nbt)
+  const display = data.display
+  if (display == null) return message
+
+  const lore = display.Lore
+  if (lore == null) return message
+  for (const line of lore) {
+    message += new ChatMessage(line).toString()
+    message += '\n'
+  }
+
+  return message
+}
+```
+
+### Como posso enviar uma mensagem do console para o servidor?
+
+Você pode usar uma biblioteca como `repl` para ler o que você escreve no console e usar `bot.chat()` para enviá-lo para o servidor. Você pode encontrar um exemplo [aqui](https://github.com/PrismarineJS/mineflayer/blob/master/examples/repl.js).
+
+### Ao criar um plugin, como posso especificar outro plugin como dependência?
+
+Na função `inject()` do seu plugin, você pode executar a função `bot.loadPlugin()` para carregar esse plugin. Se o plugin já estiver carregado anteriormente, nada acontecerá.
+
+Nota: a ordem em que os plugins são carregados é dinâmica; você nunca deve chamar outro plugin em sua função `inject()`.
+
+### Como posso usar um proxy SOCKS5?
+
+Nas opções de `mineflayer.createBot(opções)`, remova o seu `host` das opções e coloque as informações necessárias nas variáveis `PROXY_IP`, `PROXY_PORT`, `PROXY_USERNAME`, `PROXY_PASSWORD`, `MC_SERVER_IP` e `MC_SERVER_PORT`. Em seguida, adicione o seguinte ao seu objeto de opções:
+
+```js
+connect: (client) => {
+  socks.createConnection({
+    proxy: {
+      host: PROXY_IP,
+      port: PROXY_PORT,
+      type: 5,
+      userId: PROXY_USERNAME,
+      password: PROXY_PASSWORD
+    },
+    command: 'connect',
+    destination: {
+      host: MC_SERVER_IP,
+      port: MC_SERVER_PORT
+    }
+  }, (err, info) => {
+    if (err) {
+      console.log(err)
+      return
+    }
+    client.setSocket(info.socket)
+    client.emit('connect')
+  })
+}
+```
+
+# Erros Comuns
+
+### `UnhandledPromiseRejectionWarning: Error: Failed to read asymmetric key`
+
+Isso ocorre quando você fornece uma versão incorreta ao mineflayer, ou o mineflayer detecta a versão errada.
+
+### `TypeError: Cannot read property '?' of undefined`
+
+Você pode estar tentando acessar uma propriedade do bot que ainda não existe; tente acessar a propriedade após o evento `spawn`.
+
+### `SyntaxError: Unexpected token '?'`
+
+Atualize a versão do seu Node.js.
+
+### O bot não consegue quebrar/colocar blocos ou abrir baús
+
+Verifique se a proteção do spawn não está impedindo o bot de realizar a ação.
+
+Esta documentação não é oficial. Para as informações mais atualizadas, consulte a documentação original: [FAQ](../FAQ.md).