Implement signed byte conversion for checksum to fix #3765

[brentspine]

Fix PrismarineJS/mineflayer#3765

[brentspine]

@copilot Review ? (idk if it works like that)

[Copilot]

Pull request overview

This PR implements signed byte conversion for chat checksums to fix issue #3765. The Minecraft 1.21.5+ protocol expects checksums to be signed bytes (range -128 to 127) rather than unsigned bytes (range 0-255), which was causing protocol validation issues.

• Adds a toSignedByte utility function to convert unsigned bytes to signed bytes
• Applies the conversion to the checksum field in chat command packets for version 1.21.5+

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Consider moving the toSignedByte function to src/datatypes/checksums.js and exporting it alongside computeChatChecksum. This would improve code organization by grouping related checksum functionality together and make the function reusable if needed elsewhere. The function is specifically designed to handle the signed byte requirement for checksums in the Minecraft protocol.

[brentspine]

@copilot coauthor pr #1442 based on this this feedback

[extremeheat]

Thanks

[extremeheat]

Please review comment

[extremeheat]

This branch specifically covers the chat commands only. Is this intentional? Your linked issue PrismarineJS/mineflayer#3765 seems to hint at normal chat messages too

[brentspine]

I only encountered this with commands. Would you mind using my fix yourself? It's easier than me doing it

[extremeheat]

It's also already clamped here https://github.com/PrismarineJS/node-minecraft-protocol/blob/master/src/datatypes/checksums.js#L16

[isas-spirit]

Great find on the checksum issue! We're experiencing a related but distinct overflow problem that might benefit from the same toSignedByte() approach.

The pending Counter Overflow

In addition to checksum, the offset/messageCount field in chat packets can also overflow the i8 range.

Root cause: client._lastSeenMessages.pending tracks unacknowledged inbound messages. While there's a flush at > 64, the counter can exceed 127 before the bot sends its first outbound message (e.g., on a busy server with many join messages).

Affected code (around line 380):

client.write('chat_command_signed', {
  // ...
  messageCount: client._lastSeenMessages.pending,  // Can exceed 127
  // ...
})

And in chat_message packets:

offset: client._lastSeenMessages.pending,  // Same issue

Reproduction:

1. Bot joins server that sends 100+ system messages on spawn
2. Bot receives messages → pending grows to ~150
3. Bot tries bot.chat("Hello")
4. 💥 ERR_OUT_OF_RANGE: value must be >= -128 and <= 127. Received 150

Suggested fix: Apply toSignedByte() to messageCount and offset as well, or cap pending at 127 before packet serialization.

Would you be open to extending this PR to cover these fields too? Happy to help with testing.