Skip to content

Add client_transfer example#1507

Open
mliem2k wants to merge 1 commit into
PrismarineJS:masterfrom
mliem2k:add-client-transfer-example
Open

Add client_transfer example#1507
mliem2k wants to merge 1 commit into
PrismarineJS:masterfrom
mliem2k:add-client-transfer-example

Conversation

@mliem2k

@mliem2k mliem2k commented Jul 17, 2026

Copy link
Copy Markdown

Summary

  • No example or doc mention of the Transfer packet (added in 1.20.5) existed anywhere in this repo, despite the protocol data already fully supporting it.
  • Adds examples/client_transfer, showing the correct way to follow a server-initiated transfer: end the current connection, wait for it to actually close, add a short grace period, then reconnect to the new host:port with the same username.
  • That reconnect timing matters: an immediate reconnect can race the server's own cleanup of the old session and get rejected with "already playing on the server" (Bukkit/Paper's duplicate-login check). Hit this myself while building the example and fixed it with the wait-for-end + delay shown here.
  • mineflayer has an open bug in the same area (Bug Report: Connection Error During Server Transfer mineflayer#3776: sends physics packets during the configuration phase a transfer triggers, which 1.21+ servers reject), so this seemed worth documenting at the protocol level directly.

Test plan

  • npx standard examples/client_transfer/client_transfer.js passes with no changes needed
  • Ran the example (using this repo's own src, not a published version) against a real Paper/Purpur 1.21.10 server performing a real transfer handoff between two hosts, confirmed both the initial login and the post-transfer login succeed:
    connecting to <host1>:25565
    logged in to <host1>:25565
    received transfer packet -> <host2>:25565, reconnecting
    connecting to <host2>:25565
    logged in to <host2>:25565
    

Demonstrates correctly following a server-initiated Transfer packet:
end the old connection and wait for it to fully close (plus a short
grace period) before reconnecting with the same username, since an
immediate reconnect can race the server's own session cleanup and get
rejected as "already playing on the server."

There was no existing example or doc mention of the Transfer packet
in this repo despite the protocol data already supporting it, and
mineflayer has an open bug specifically around this scenario
(PrismarineJS/mineflayer#3776, sending physics packets during the
configuration phase a transfer triggers). Tested against a real
Paper/Purpur 1.21.10 server doing a live catcher-to-relay handoff.
Copilot AI review requested due to automatic review settings July 17, 2026 08:38

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants