Book a Demo!
CoCalc Logo Icon
StoreFeaturesDocsShareSupportNewsAboutPoliciesSign UpSign In
PrismarineJS
GitHub Repository: PrismarineJS/mineflayer
 Path: blob/master/docs/update_to_1_21_5.md
2155 views

Mineflayer 1.21.5 Support Plan

🚩 Latest Progress (July 2025)

  • ✅ Chunk loading/parsing is now fixed in both node_modules and the local prismarine-chunk repo. The fix was applied to PaletteChunkSection.js and BitArrayNoSpan.js.

  • 🔗 Local development uses npm link to the local prismarine-chunk repo for immediate testing of fixes.

  • 🛠️ BitArrayNoSpan.js now validates the buffer size and logs a warning if it is invalid (e.g., Infinity), preventing crashes.

  • 🤖 The bot can now spawn and interact with the world in 1.21.5. Chunk parsing errors are resolved.

  • ✅ 12 tests pass for 1.21.5, confirming core protocol and chunk logic is working.

  • ❌ 4 tests fail, but these are due to higher-level Mineflayer/game logic (timeouts, creative set slot, etc.), not chunk/protocol errors.

  • 🚧 Current blockers:

    • Creative set slot protocol changes (UntrustedSlot)

    • declare_commands packet parsing (PartialReadError)

Current Status

As of July 2025, Mineflayer has partial 1.21.5 support with several critical issues remaining. The version is already listed in testedVersions but tests are failing due to protocol changes in 1.21.5.

Key Issues Identified

Based on the analysis of pull requests and issues, the main problems for 1.21.5 support are:

1. Chunk Protocol Changes (✅ FIXED)

  • Issue: Network has small changes to chunk format where size is now auto-computed to save a byte

  • Status: RESOLVED - Fixed size computation formula in prismarine-chunk

  • Fix Applied: Changed from Math.ceil(constants.BLOCK_SECTION_VOLUME * bitsPerValue / 64) to Math.ceil(constants.BLOCK_SECTION_VOLUME / Math.floor(64 / bitsPerValue))

  • Impact: Chunk loading now works correctly for 1.21.5

  • Files Modified:

    • prismarine-chunk/src/pc/common/PaletteContainer.js (both DirectPaletteContainer and IndirectPaletteContainer)

  • Dependencies: Updated package.json to point to fixed prismarine-chunk branch

2. Creative Set Slot Packet Behavior

  • Issue: Creative set slot packet behavior is the main breaking change (not working right now)

  • Status: Critical issue affecting creative mode functionality

  • Impact: bot.creative.setInventorySlot() fails

  • Location: lib/plugins/creative.js

3. Item Format Changes

  • Issue: New concepts of hashed items and unsecure items (related to components)

  • Status: Protocol changes need investigation

  • Impact: Item handling and inventory management

  • Dependencies: minecraft-data and minecraft-protocol updates needed

4. Entity Metadata Changes

  • Issue: Entity metadata may have changed

  • Status: Could cause issues with various listeners in mineflayer

  • Impact: Entity tracking and interaction

  • Location: lib/plugins/entities.js

Detailed Action Plan

Phase 1: Dependency Updates and Investigation

1.1 Investigate Chunk Protocol Issues

  • Task: Manually dump and decode chunk packets to understand the new format

  • Tools: Use packet analyzers or debug tools

  • Expected Outcome: Identify exact changes in chunk size computation

  • Files to Modify: lib/plugins/blocks.js (chunk handling)

1.2 Analyze Creative Set Slot Issues

  • Task: Debug creative set slot packet failures

  • Method: Compare packet structure between 1.21.4 and 1.21.5

  • Files to Modify: lib/plugins/creative.js

  • Test: test/externalTests/creative.js

Phase 2: Protocol Implementation

2.1 Fix Chunk Loading

// In lib/plugins/blocks.js
// Update chunk loading logic to handle auto-computed size
bot._client.on('map_chunk', (packet) => {
  // Handle new chunk format with auto-computed size
  // May need to adjust data parsing based on new format
})

2.2 Fix Creative Set Slot

// In lib/plugins/creative.js
// Update setInventorySlot to handle new packet format
async function setInventorySlot (slot, item, waitTimeout = 400) {
  // Investigate and fix packet structure changes
  // May need new packet format or different handling
}

2.3 Update Item Handling

// In lib/plugins/inventory.js
// Handle new hashed items and unsecure items concepts
// Update Item.fromNotch and Item.toNotch methods

2.4 Fix Entity Metadata

// In lib/plugins/entities.js
// Update entity metadata parsing for 1.21.5 changes
bot._client.on('entity_metadata', (packet) => {
  // Handle new metadata format
})

Phase 3: Testing and Validation

3.1 Create 1.21.5 Specific Tests

// Add to test/externalTests/
// Create tests that specifically validate 1.21.5 functionality

3.2 Update Existing Tests

  • Task: Fix failing tests for 1.21.5

  • Focus: Creative mode, chunk loading, entity handling

  • Method: Run npm run mocha_test -- -g "mineflayer_external 1.21.5v"

3.3 Manual Testing

  • Task: Test core functionality manually

  • Areas: World loading, inventory management, entity interaction

  • Tools: Use examples in examples/ directory

Phase 4: Documentation and Cleanup

4.1 Update Documentation

  • Task: Update README and API docs for 1.21.5

  • Files: docs/README.md, docs/api.md

  • Content: Document any new features or breaking changes

4.2 Update Version Support

  • Task: Ensure 1.21.5 is properly listed as supported

  • Files: lib/version.js, package.json

Analysis of Current Fix Status

✅ Good News: Fix Already Implemented

The prismarine-chunk PR #289 has already implemented the 1.21.5 chunk protocol fix:

Key Changes in PR #289:

  1. Added noSizePrefix detection: Uses mcData.version['>=']('1.21.5') to detect 1.21.5+

  2. Modified chunk reading: All palette containers now handle the noSizePrefix option

  3. Dynamic size computation: When noSizePrefix is true, size is computed as Math.ceil(constants.BLOCK_SECTION_VOLUME * bitsPerValue / 64)

🔍 Current Status Check

Mineflayer is already using the experimental branches:

  • prismarine-chunk: extremeheat/prismarine-chunk#pc1.21.5 ✅

  • minecraft-protocol: extremeheat/node-minecraft-protocol#pcp1.21.5 ✅

✅ Chunk Loading Issue RESOLVED

FIXED: The chunk loading issue has been resolved by correcting the size computation formula.

Root Cause Analysis:

  1. ✅ Fix is implemented: noSizePrefix detection and logic is present in the code

  2. ✅ Version detection works: mcData.version['>=']('1.21.5') returns true correctly

  3. ✅ Size computation fixed: Changed from Math.ceil(constants.BLOCK_SECTION_VOLUME * bitsPerValue / 64) to Math.ceil(constants.BLOCK_SECTION_VOLUME / Math.floor(64 / bitsPerValue))

  4. ✅ Buffer reading works: No more "Target offset is beyond the bounds of the internal SmartBuffer data" errors

The Solution: The issue was in the readBuffer method in PaletteContainer.js. The formula needed to calculate the number of longs based on the actual BitArray logic used in the constructor.

Current Test Status

✅ Chunk Loading Fixed

  • Status: Chunk loading now works correctly for 1.21.5

  • Evidence: No more "Target offset is beyond the bounds of the internal SmartBuffer data" errors

  • Next: Focus on remaining test failures

🚨 New Test Failures Identified

After fixing chunk loading, new issues emerged:

  1. Test Setup Timeout: "Event message did not fire within timeout of 5000ms" in "before each" hook for "bed"

  2. Server Shutdown Issues: "Server shutdown took too long. Killing process."

  3. Potential Protocol Changes: Other 1.21.5 protocol changes may be affecting test functionality

Next Priority Issues

1. Investigate Test Setup Failures (High Priority)

  • Issue: Tests are timing out during setup phase

  • Location: test/externalTests/plugins/testCommon.js:127:21 - clearInventory function

  • Possible Causes:

    • Creative set slot packet changes

    • Inventory protocol changes

    • Entity metadata changes

2. Debug Creative Set Slot (High Priority - PROTOCOL CHANGE IDENTIFIED)

  • Issue: Creative mode functionality broken due to protocol change

  • Location: lib/plugins/creative.js

  • Test: test/externalTests/creative.js

  • Root Cause: set_creative_slot packet changed from Slot to UntrustedSlot type

  • Key Changes:

    • 1.21.4: packet_set_creative_slot.item type: Slot

    • 1.21.5: packet_set_creative_slot.item type: UntrustedSlot

    • UntrustedSlot has present boolean field first

    • Uses UntrustedSlotComponent instead of SlotComponent

    • New component system with addedComponentCount and removedComponentCount

  • Files to Modify: lib/plugins/creative.js (creative set slot handling)

3. Check Item Format Changes (Medium Priority - PROTOCOL CHANGES IDENTIFIED)

  • Issue: New hashed items and unsecure items concepts

  • Location: lib/plugins/inventory.js

  • Impact: Item handling and inventory management

  • Protocol Changes Found:

    • New vec3i type: Added for 3D integer vectors

    • Item component system: New component-based item system

    • Component reordering: Item component IDs have been reordered (e.g., hide_additional_tooltip → tooltip_display)

    • New components: Added blocks_attacks, weapon components

    • Entity metadata: item_stack type still uses Slot but may have component changes

4. Entity Metadata Changes (Medium Priority - MINIMAL CHANGES)

  • Issue: Entity metadata format changes

  • Location: lib/plugins/entities.js

  • Impact: Entity tracking and interaction

  • Protocol Analysis:

    • Good news: entity_metadata packet structure unchanged

    • Good news: item_stack type in metadata still uses Slot (not UntrustedSlot)

    • Minimal impact: Entity metadata changes appear to be minimal for 1.21.5

Protocol Analysis Summary

Based on the minecraft-data PR #1029 analysis, here are the key protocol changes for 1.21.5:

🔥 Critical Changes (Blocking Issues)

  1. Creative Set Slot Packet:

    • Change: packet_set_creative_slot.item type changed from Slot to UntrustedSlot

    • Impact: Creative mode inventory management completely broken

    • Fix Required: Update lib/plugins/creative.js to handle UntrustedSlot format

  2. New Packet Types:

    • Added: set_test_block (0x39) and test_instance_block_action (0x3c)

    • Impact: May affect block interaction tests

📦 Item System Changes

  1. Component System:

    • New: UntrustedSlot with component-based system

    • Components: addedComponentCount, removedComponentCount, UntrustedSlotComponent

    • Impact: Item serialization/deserialization needs updates

  2. Component Reordering:

    • Changed: Component IDs reordered (e.g., hide_additional_tooltip → tooltip_display)

    • Added: New components like blocks_attacks, weapon

🎯 Minimal Impact Changes

  1. Entity Metadata:

    • Status: Unchanged - still uses Slot for item_stack

    • Impact: Minimal - no changes needed

  2. New Types:

    • Added: vec3i type for 3D integer vectors

    • Impact: May be used in new packets but not critical

Implementation Steps

cd /media/documents/Documents/programmation/interlangage/minecraft/mineflayer
npm install

Step 2: Run Current Tests

# Test current 1.21.5 status
npm run mocha_test -- -g "mineflayer_external 1.21.5v"

Step 3: Investigate Specific Issues

# Debug chunk loading
DEBUG="minecraft-protocol" npm run mocha_test -- -g "mineflayer_external 1.21.5v.*blocks"

# Debug creative mode
npm run mocha_test -- -g "mineflayer_external 1.21.5v.*creative"

Step 4: Implement Fixes

  1. Start with chunk protocol fixes

  2. Fix creative set slot issues

  3. Update item handling

  4. Fix entity metadata

Step 5: Validate Fixes

# Run all 1.21.5 tests
npm run mocha_test -- -g "mineflayer_external 1.21.5v"

# Run specific functionality tests
npm run mocha_test -- -g "mineflayer_external 1.21.5v.*inventory"
npm run mocha_test -- -g "mineflayer_external 1.21.5v.*entities"

Success Criteria

  1. All 1.21.5 tests pass

  2. Core functionality works (world loading, inventory, entities)

  3. Creative mode functions properly

  4. No regressions in other versions

  5. Documentation is updated

Risk Mitigation

  1. Backward Compatibility: Ensure fixes don't break older versions

  2. Incremental Testing: Test each fix individually

  3. Fallback Mechanisms: Implement fallbacks for protocol changes

  4. Version Detection: Use bot.supportFeature() for version-specific code

Resources Needed

  1. Minecraft 1.21.5 Server: For testing

  2. Packet Analyzer: For debugging protocol changes

  3. Documentation: Minecraft 1.21.5 protocol changes

  4. Time: 1-2 weeks of focused development

Contributing Guidelines

For anyone wanting to contribute to 1.21.5 support:

  1. Read the Documentation: docs/llm_contribute.md and docs/README.md

  2. Understand the Test System: test/externalTests/

  3. Focus on One Issue: Pick one specific problem to solve

  4. Test Thoroughly: Run tests for multiple versions

  5. Document Changes: Update relevant documentation

Updated Timeline

  • Phase 1: ✅ COMPLETED (chunk protocol fix)

  • Phase 2: 2-3 days (investigate and fix test setup failures)

  • Phase 3: 2-3 days (fix creative set slot and other protocol issues)

  • Phase 4: 1-2 days (testing and validation)

  • Phase 5: 1 day (documentation and cleanup)

Total Estimated Time: 6-9 days remaining

Note: Chunk loading is now fixed! Focus is on remaining protocol changes and test failures.

References