Add a test for title and improve the title functionality in mineflayer (#3653)

* start adding title test

* works

* cleanup

* implement missing tititle features

* fix clear for 1.18

* update example

* fix lint

* revert change to external test

* fix api md

* consistent format

* refactor

* add some content in llm contribute

Author: rom1504

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)
@@ -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"
 

docs/llm_contribute.md

@@ -186,6 +186,51 @@ module.exports = () => async (bot) => {
 - **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
+// 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:

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')
+})

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'))
+  }
 }

test/externalTests/title.js

@@ -0,0 +1,41 @@
+const { once } = require('../../lib/promise_utils')
+
+module.exports = () => async (bot) => {
+  // Test title
+  bot.chat('/title @a title {"text":"Test Title"}')
+  const [title, type] = await once(bot, 'title', 2000)
+  if (title !== 'Test Title' || type !== 'title') {
+    throw new Error(`Title test failed: expected "Test Title" but got "${title}" with type "${type}"`)
+  }
+
+  // Test subtitle
+  bot.chat('/title @a subtitle {"text":"Test Subtitle"}')
+  const [subtitle, subtitleType] = await once(bot, 'title', 20000)
+  if (subtitle !== 'Test Subtitle' || subtitleType !== 'subtitle') {
+    throw new Error(`Subtitle test failed: expected "Test Subtitle" but got "${subtitle}" with type "${subtitleType}"`)
+  }
+
+  // Test title_times event
+  bot.chat('/title @a times 10 20 30')
+  const [fadeIn, stay, fadeOut] = await once(bot, 'title_times', 20000)
+  if (fadeIn !== 10 || stay !== 20 || fadeOut !== 30) {
+    throw new Error(`title_times event failed: expected (10,20,30) but got (${fadeIn},${stay},${fadeOut})`)
+  }
+
+  // Test combined title and subtitle
+  bot.chat('/title @a title {"text":"Test Title"}')
+  const [combinedTitle, combinedTitleType] = await once(bot, 'title', 20000)
+  if (combinedTitle !== 'Test Title' || combinedTitleType !== 'title') {
+    throw new Error(`Combined title test failed: expected "Test Title" but got "${combinedTitle}" with type "${combinedTitleType}"`)
+  }
+
+  bot.chat('/title @a subtitle {"text":"Test Subtitle"}')
+  const [combinedSubtitle, combinedSubtitleType] = await once(bot, 'title', 20000)
+  if (combinedSubtitle !== 'Test Subtitle' || combinedSubtitleType !== 'subtitle') {
+    throw new Error(`Combined subtitle test failed: expected "Test Subtitle" but got "${combinedSubtitle}" with type "${combinedSubtitleType}"`)
+  }
+
+  // Test clearing title
+  bot.chat('/title @a clear')
+  await once(bot, 'title_clear', 2000)
+}