mineflayer 4.27.0 → 4.28.0

package/README.md

@@ -205,6 +205,7 @@ higher level API on top of Mineflayer.
 
 The most updated and useful are :
 
+ * [minecraft-mcp-server](https://github.com/yuniko-software/minecraft-mcp-server) A MCP server for mineflayer, allowing using mineflayer from an LLM
  * [pathfinder](https://github.com/Karang/mineflayer-pathfinder) - advanced A* pathfinding with a lot of configurable features
  * [prismarine-viewer](https://github.com/PrismarineJS/prismarine-viewer) - simple web chunk viewer
  * [web-inventory](https://github.com/ImHarvol/mineflayer-web-inventory) - web based inventory viewer

package/docs/README.md

@@ -205,6 +205,7 @@ higher level API on top of Mineflayer.
 
 The most updated and useful are :
 
+ * [minecraft-mcp-server](https://github.com/yuniko-software/minecraft-mcp-server) A MCP server for mineflayer, allowing using mineflayer from an LLM
  * [pathfinder](https://github.com/Karang/mineflayer-pathfinder) - advanced A* pathfinding with a lot of configurable features
  * [prismarine-viewer](https://github.com/PrismarineJS/prismarine-viewer) - simple web chunk viewer
  * [web-inventory](https://github.com/ImHarvol/mineflayer-web-inventory) - web based inventory viewer

package/docs/api.md

@@ -170,6 +170,8 @@
       - ["game"](#game)
       - ["resourcePack" (url, hash)](#resourcepack-url-hash)
       - ["title" (title, type)](#title-title-type)
+      - ["title_times" (fadeIn, stay, fadeOut)](#title_times-fadein-stay-fadeout)
+      - ["title_clear"](#title_clear)
       - ["rain"](#rain)
       - ["weatherUpdate"](#weatherupdate)
       - ["time"](#time)
@@ -1089,7 +1091,7 @@ Day of the world.
 
 Whether it is day or not.
 
-Based on whether the current time of day is between 13000 and 23000 ticks.
+Based on whether the current time of day is between 0 and 13000 ticks (day + sunset).
 
 #### bot.time.moonPhase
 
@@ -1241,8 +1243,28 @@ Emitted when the server sends a resource pack.
 
 Emitted when the server sends a title
 
- * `title` - title's text
- * `type` - title's type "subtitle" or "title"
+* `title` - title's text
+* `type` - title's type "subtitle", "title"
+
+#### "title_times" (fadeIn, stay, fadeOut)
+
+Emitted when the server sends a title times packet (i.e., when the fade-in, stay, and fade-out times for titles are set or updated).
+
+ * `fadeIn` - fade-in time in ticks (number)
+ * `stay` - stay time in ticks (number)
+ * `fadeOut` - fade-out time in ticks (number)
+
+Example:
+
+```js
+bot.on('title_times', (fadeIn, stay, fadeOut) => {
+  console.log(`Title times: fadeIn=${fadeIn}, stay=${stay}, fadeOut=${fadeOut}`)
+})
+```
+
+#### "title_clear"
+
+Emitted when the server clears all titles.
 
 #### "rain"
 

package/docs/br/api_br.md

@@ -941,7 +941,7 @@ Dia do mundo.
 
 Se é dia ou não.
 
-Baseado no horário atual estar entre 13.000 e 23.000 ticks.
+Baseado no horário atual estar entre 0 e 13000 ticks (dia + pôr do sol).
 
 #### bot.time.moonPhase
 

package/docs/es/api_es.md

@@ -943,9 +943,9 @@ Día del mundo
 
 #### bot.time.isDay
 
-Si es de día o no
+Si es de día o no.
 
-Basado en si la hora actual está entre los 13000 y 23000 ticks.
+Basado en si la hora actual está entre 0 y 13000 ticks (día + atardecer).
 
 #### bot.time.moonPhase
 

package/docs/history.md

@@ -1,3 +1,11 @@
+## 4.28.0
+* [Add a test for title and improve the title functionality in mineflayer (#3653)](https://github.com/PrismarineJS/mineflayer/commit/4593da148afd84d9a298074123c5e022f1f8d3e4) (thanks @rom1504)
+* [Add experience test (#3652)](https://github.com/PrismarineJS/mineflayer/commit/32d9d8434465bcea6705d5d6b073a8497adb7c34) (thanks @rom1504)
+* [Add new external test for time. (#3650)](https://github.com/PrismarineJS/mineflayer/commit/52938fe604096887872a831a7ed0c8feca7ee272) (thanks @rom1504)
+* [Add minecraft-mcp-server: mineflayer mcp server to readme](https://github.com/PrismarineJS/mineflayer/commit/cab65b115f0f8737b6756e811995ea095e776858) (thanks @rom1504)
+* [Add Entity Attacker Detection into EntityHurt emitter (#3631)](https://github.com/PrismarineJS/mineflayer/commit/5688f18df4a7a5e47e6a3435902be1c7226e0b0a) (thanks @1tsMeMario)
+* [Added if(vehicle) check (#3619)](https://github.com/PrismarineJS/mineflayer/commit/52c622a4f006e3631f20e6cded236e4424c38d36) (thanks @SinanAkkoyun)
+
 ## 4.27.0
 * [Entity Passengers get pushed wrongly (#3601)](https://github.com/PrismarineJS/mineflayer/commit/deb03b52d1e015ece9df1f14536f168f64895c81) (thanks @SinanAkkoyun)
 * [Update bot.clickWindow documentation (#3574)](https://github.com/PrismarineJS/mineflayer/commit/188db17bbb95461743aec2823695c360685559b0) (thanks @kaduvert)

package/docs/llm_contribute.md

@@ -0,0 +1,245 @@
+# Contributing to Mineflayer Tests as an LLM
+
+This guide explains how to add and modify tests in Mineflayer, based on the experience of working with the time-related functionality. It provides a structured approach for LLMs to help with test development and debugging.
+
+## Test Structure
+
+### Location
+- Tests are located in `test/externalTests/`
+- Each test file corresponds to a specific functionality
+- Test files follow the naming convention of the feature they test (e.g., `time.js` for time-related tests)
+
+### Basic Test Template
+```javascript
+const assert = require('assert')
+const { once } = require('../../lib/promise_utils')
+
+module.exports = () => async (bot) => {
+  // Test implementation
+}
+```
+
+## Writing Tests
+
+### 1. Property Testing
+- Define expected properties and their types
+- Use `assert.strictEqual` for type checking
+- Verify value ranges where applicable
+
+Example:
+```javascript
+const timeProps = {
+  doDaylightCycle: 'boolean',
+  bigTime: 'bigint',
+  time: 'number'
+}
+
+Object.entries(timeProps).forEach(([prop, type]) => {
+  assert.strictEqual(typeof bot.time[prop], type)
+})
+```
+
+### 2. Helper Functions
+- Create reusable helper functions for common operations
+- Include functions for waiting and state verification
+- Use descriptive names that explain their purpose
+
+Example:
+```javascript
+const waitForTime = async () => {
+  await once(bot, 'time')
+  await bot.test.wait(200)
+}
+```
+
+### 3. Test Cases
+- Organize test cases in arrays for better maintainability
+- Include descriptive names and expected outcomes
+- Group related tests together
+
+Example:
+```javascript
+const timeTests = [
+  { time: 18000, name: 'midnight', isDay: false },
+  { time: 6000, name: 'noon', isDay: true }
+]
+```
+
+## Running Tests
+
+### Basic Test Execution
+```bash
+npm run mocha_test -- -g "mineflayer_external 1.20.4v.*time"
+```
+
+### Version-Specific Testing
+- Test against multiple Minecraft versions
+- Common versions to test: 1.14.4, 1.20.4, 1.21.3
+- Example:
+```bash
+# Test for 1.14.4
+npm run mocha_test -- -g "mineflayer_external 1.14.4v.*time"
+
+# Test for 1.21.3
+npm run mocha_test -- -g "mineflayer_external 1.21.3v.*time"
+```
+
+## Debugging Tests
+
+### 1. Adding Debug Logs
+- Use `console.log` for debugging (remove before final commit)
+- Log important state changes and values
+- Example:
+```javascript
+console.log('Time properties:', bot.time)
+```
+
+### 2. Common Issues
+- Timing issues: Adjust wait times if needed (default 200ms)
+- Version compatibility: Check packet formats across versions
+- State synchronization: Ensure proper event handling
+
+### 3. Test Output
+- Watch for server startup messages
+- Monitor bot commands and responses
+- Check for any error messages or warnings
+
+## Best Practices
+
+1. **Test Organization**
+   - Group related tests together
+   - Use descriptive test names
+   - Keep tests focused and atomic
+
+2. **Error Handling**
+   - Include clear error messages
+   - Test edge cases
+   - Verify state after each operation
+
+3. **Performance**
+   - Minimize wait times
+   - Clean up resources
+   - Avoid redundant tests
+
+4. **Documentation**
+   - Comment complex logic
+   - Explain test purposes
+   - Document version-specific behavior
+
+## Common Commands
+
+### Server Commands
+```javascript
+bot.test.sayEverywhere('/time set 0') // Set time
+bot.test.sayEverywhere('/gamerule doDaylightCycle false') // Toggle game rules
+```
+
+### Bot Operations
+```javascript
+async function f () {
+  await bot.test.wait(200) // Wait for specified milliseconds
+  await once(bot, 'time') // Wait for specific event
+}
+```
+
+## Version Compatibility
+
+- Test against multiple Minecraft versions
+- Handle version-specific packet formats
+- Consider backward compatibility
+- Document version-specific behavior
+
+## Adding a New Test
+
+When adding a new test, follow these steps:
+
+1. **Create a new test file** in the `test/externalTests` directory. For example, `experience.js`.
+2. **Write the test logic** using async/await. Avoid using the `done` callback if possible.
+3. **Handle version differences** if necessary. For example, the experience command syntax differs between Minecraft versions:
+   - For versions older than 1.13, use `/xp <amount> [player]`.
+   - For versions 1.13 and newer, use `/xp add <player> <amount> points` or `/xp add <player> <amount> levels`.
+4. **Add event listeners** for debugging if needed, and ensure they are removed at the end of the test to prevent memory leaks.
+5. **Use `bot.chat`** to issue commands directly instead of `bot.test.runCommand`.
+6. **Run the test** for different Minecraft versions to ensure compatibility.
+
+Example test structure:
+```javascript
+const assert = require('assert')
+const { once } = require('../../lib/promise_utils')
+
+module.exports = () => async (bot) => {
+  // Test logic here
+  // Example: Check bot's experience state
+  console.log('[experience test] Bot username:', bot.username)
+  await bot.test.becomeSurvival()
+  // ... more test logic ...
+  // Remove event listeners at the end
+  bot.removeListener('experience', expListener)
+  console.log('[experience test] All checks passed!')
+}
+```
+
+## Specific Details from Recent Experience
+
+- **Version-Specific Command Syntax**: Always check the Minecraft Wiki or existing tests for the correct command syntax for each version. For example, the experience command syntax changed in 1.13.
+- **Event Listener Cleanup**: Always remove event listeners at the end of the test to prevent memory leaks. Use `bot.removeListener('eventName', listenerFunction)`.
+- **Use `bot.chat`**: For issuing commands, use `bot.chat` directly instead of `bot.test.runCommand` to ensure commands are sent correctly.
+- **Debugging**: Use `console.log` for debugging, but remove these statements before finalizing the test.
+
+## Title Plugin Implementation Details
+
+### Version-Specific Title Handling
+- Title packets changed significantly between versions:
+  - 1.8.8 uses a single `title` packet with an action field
+  - 1.14.4+ uses separate packets for different title operations
+- Use `bot.supportFeature('titleUsesLegacyPackets')` to detect version
+- Handle both JSON and plain text title formats
+
+### Title Testing Strategy
+```javascript
+async function f () {
+  // Example of testing title functionality
+  const titleTests = [
+    { type: 'title', text: 'Main Title' },
+    { type: 'subtitle', text: 'Subtitle Text' },
+    { type: 'clear' }
+  ]
+  for (const test of titleTests) {
+    if (test.type === 'clear') {
+      bot.test.sayEverywhere('/title @a clear')
+    } else {
+      bot.test.sayEverywhere(`/title @a ${test.type} {"text":"${test.text}"}`)
+    }
+    await once(bot, 'title')
+    // Verify title state
+  }
+}
+```
+
+### Title-Specific Best Practices
+1. **Event Handling**
+   - Listen for both legacy and modern title events
+   - Handle title clear events separately
+   - Parse JSON title text properly
+
+2. **Version Compatibility**
+   - Test title display, subtitle, and clear operations
+   - Verify title timing settings work
+   - Check title text parsing across versions
+
+3. **Error Prevention**
+   - Handle malformed JSON in title text
+   - Provide fallbacks for unsupported operations
+   - Log title-related errors for debugging
+
+## Conclusion
+
+When adding or modifying tests:
+1. Understand the feature being tested
+2. Write clear, focused tests
+3. Test across multiple versions
+4. Include proper error handling
+5. Clean up debug code before committing
+6. Document any version-specific behavior
+
+Remember to remove any debugging `console.log` statements before finalizing the changes. 

package/docs/ru/api_ru.md

@@ -1121,7 +1121,7 @@ UUID существа, который определяется боссом.
 
 Определяет, сейчас день (`true`) или ночь (`false`).
 
-Основано на времени между `13000` и `23000` тиками.
+Основано на времени между `0` и `13000` тиками (день + закат).
 
 #### bot.time.moonPhase
 

package/examples/titles.js

@@ -1,5 +1,6 @@
 /*
  * An example of how to handle title events from the server.
+ * Demonstrates title, subtitle, timing, and clearing functionality.
  */
 const mineflayer = require('mineflayer')
 
@@ -15,8 +16,26 @@ const bot = mineflayer.createBot({
   password: process.argv[5]
 })
 
-// This event is triggered when the server sends a title to the client.
+// This event is triggered when the server sends a title or subtitle
 bot.on('title', (text, type) => {
   // type is either "title" or "subtitle"
   console.log(`Received ${type}: ${text}`)
 })
+
+// This event is triggered when the server sets title display times
+bot.on('title_times', (fadeIn, stay, fadeOut) => {
+  console.log(`Title timing: fadeIn=${fadeIn}ms, stay=${stay}ms, fadeOut=${fadeOut}ms`)
+})
+
+// This event is triggered when the server clears all titles
+bot.on('title_clear', () => {
+  console.log('All titles cleared')
+})
+
+bot.on('spawn', () => {
+  console.log('Bot spawned! Try these commands:')
+  console.log('/title @a title {"text":"Hello World"}')
+  console.log('/title @a subtitle {"text":"Welcome!"}')
+  console.log('/title @a times 10 20 30')
+  console.log('/title @a clear')
+})

package/index.d.ts

@@ -81,7 +81,7 @@ export interface BotEvents {
   health: () => Promise<void> | void
   breath: () => Promise<void> | void
   entitySwingArm: (entity: Entity) => Promise<void> | void
-  entityHurt: (entity: Entity) => Promise<void> | void
+  entityHurt: (entity: Entity, source: Entity) => Promise<void> | void
   entityDead: (entity: Entity) => Promise<void> | void
   entityTaming: (entity: Entity) => Promise<void> | void
   entityTamed: (entity: Entity) => Promise<void> | void

package/lib/plugins/entities.js

@@ -374,7 +374,8 @@ function inject (bot) {
 
   bot._client.on('damage_event', (packet) => { // 1.20+
     const entity = bot.entities[packet.entityId]
-    bot.emit('entityHurt', entity)
+    const source = bot.entities[packet.sourceCauseId - 1] // damage_event : SourceCauseId : The ID + 1 of the entity responsible for the damage, if present. If not present, the value is 0
+    bot.emit('entityHurt', entity, source)
   })
 
   bot._client.on('attach_entity', (packet) => {
@@ -813,7 +814,9 @@ function inject (bot) {
       originalVehicle.passengers.splice(index, 1)
     }
     passenger.vehicle = vehicle
-    vehicle.passengers.push(passenger)
+    if (vehicle) {
+      vehicle.passengers.push(passenger)
+    }
 
     if (packet.entityId === bot.entity.id) {
       const vehicle = bot.vehicle

package/lib/plugins/time.js

@@ -13,23 +13,21 @@ function inject (bot) {
     age: null
   }
   bot._client.on('update_time', (packet) => {
-    let time = longToBigInt(packet.time)
+    const time = longToBigInt(packet.time)
+    const age = longToBigInt(packet.age)
+    const doDaylightCycle = packet.tickDayTime !== undefined ? !!packet.tickDayTime : time >= 0n
+    // When doDaylightCycle is false, we need to take the absolute value of time
+    const finalTime = doDaylightCycle ? time : (time < 0n ? -time : time)
 
-    if (time < 0) {
-      bot.time.doDaylightCycle = false
-      time *= -1n
-    } else {
-      bot.time.doDaylightCycle = true
-    }
-
-    bot.time.bigTime = time
-    bot.time.time = Number(time)
+    bot.time.doDaylightCycle = doDaylightCycle
+    bot.time.bigTime = finalTime
+    bot.time.time = Number(finalTime)
     bot.time.timeOfDay = bot.time.time % 24000
     bot.time.day = Math.floor(bot.time.time / 24000)
-    bot.time.isDay = bot.time.timeOfDay < 13000 || bot.time.timeOfDay >= 23000
+    bot.time.isDay = bot.time.timeOfDay >= 0 && bot.time.timeOfDay < 13000
     bot.time.moonPhase = bot.time.day % 8
-    bot.time.bigAge = longToBigInt(packet.age)
-    bot.time.age = Number(bot.time.bigAge)
+    bot.time.bigAge = age
+    bot.time.age = Number(age)
 
     bot.emit('time')
   })

package/lib/plugins/title.js

@@ -1,14 +1,37 @@
 module.exports = inject
 function inject (bot) {
-  bot._client.on('title', (packet) => {
-    if (packet.action === 0 || packet.action === 1) {
-      bot.emit('title', packet.text, 'title')
+  function parseTitle (text) {
+    try {
+      const parsed = JSON.parse(text)
+      return typeof parsed === 'string' ? parsed : (parsed.text || text)
+    } catch {
+      return typeof text === 'string' ? text.replace(/^"|"$/g, '') : text
     }
-  })
-  bot._client.on('set_title_text', packet => {
-    bot.emit('title', packet.text, 'title')
-  })
-  bot._client.on('set_title_subtitle', packet => {
-    bot.emit('title', packet.text, 'subtitle')
-  })
+  }
+
+  if (bot.supportFeature('titleUsesLegacyPackets')) {
+    bot._client.on('title', (packet) => {
+      if (packet.action === 0) bot.emit('title', parseTitle(packet.text), 'title')
+      else if (packet.action === 1) bot.emit('title', parseTitle(packet.text), 'subtitle')
+      else if (packet.action === 2) bot.emit('title_times', packet.fadeIn, packet.stay, packet.fadeOut)
+      else if (packet.action === 3) {
+        if (packet.fadeIn !== undefined) bot.emit('title_times', packet.fadeIn, packet.stay, packet.fadeOut)
+        else bot.emit('title_clear')
+      } else if (packet.action === 4) bot.emit('title_clear')
+    })
+  } else if (bot.supportFeature('titleUsesNewPackets')) {
+    function getText (packet) {
+      let text = packet.text
+      if (typeof text === 'object' && text.value !== undefined) text = text.value
+      return parseTitle(text)
+    }
+    bot._client.on('set_title_text', (packet) => bot.emit('title', getText(packet), 'title'))
+    bot._client.on('set_title_subtitle', (packet) => bot.emit('title', getText(packet), 'subtitle'))
+    bot._client.on('set_title_time', (packet) => {
+      if (typeof packet.fadeIn === 'number' && typeof packet.stay === 'number' && typeof packet.fadeOut === 'number') {
+        bot.emit('title_times', packet.fadeIn, packet.stay, packet.fadeOut)
+      }
+    })
+    bot._client.on('clear_titles', () => bot.emit('title_clear'))
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mineflayer",
-  "version": "4.27.0",
+  "version": "4.28.0",
   "description": "create minecraft bots with a stable, high level API",
   "main": "index.js",
   "types": "index.d.ts",