From f284cb59b40323442085f3486a53f85a10047b36 Mon Sep 17 00:00:00 2001
From: mliem2k <michael.liem2k@gmail.com>
Date: Fri, 17 Jul 2026 16:21:25 +0800
Subject: [PATCH] Add client_transfer example

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.
---
 examples/client_transfer/client_transfer.js | 44 +++++++++++++++++++++
 examples/client_transfer/package.json       |  8 ++++
 2 files changed, 52 insertions(+)
 create mode 100644 examples/client_transfer/client_transfer.js
 create mode 100644 examples/client_transfer/package.json

diff --git a/examples/client_transfer/client_transfer.js b/examples/client_transfer/client_transfer.js
new file mode 100644
index 000000000..c019d2eb9
--- /dev/null
+++ b/examples/client_transfer/client_transfer.js
@@ -0,0 +1,44 @@
+// Demonstrates following a server-initiated Transfer packet (added in 1.20.5, used by
+// the vanilla /transfer command and by proxies/plugins that hand a player off to a
+// different server, e.g. for load balancing or a low-latency regional server).
+//
+// The important part is the reconnect: end() the current connection and wait for it to
+// fully close, then wait a short beat, before connecting to the new host:port with the
+// same username. Reconnecting immediately 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), since the server hasn't necessarily finished processing the
+// old connection's teardown yet.
+const mc = require('minecraft-protocol')
+
+if (process.argv.length < 4 || process.argv.length > 6) {
+  console.log('Usage : node client_transfer.js <host> <port> [<name>]')
+  process.exit(1)
+}
+
+const host = process.argv[2]
+const port = parseInt(process.argv[3])
+const username = process.argv[4] || 'transfer_bot'
+
+function connect (host, port) {
+  const client = mc.createClient({ host, port, username })
+
+  client.on('connect', () => console.log(`connecting to ${host}:${port}`))
+  client.on('login', () => console.log(`logged in to ${host}:${port}`))
+  client.on('error', (err) => console.error('error:', err))
+  client.on('disconnect', (packet) => console.log('disconnected:', packet.reason))
+  client.on('kick_disconnect', (packet) => console.log('kicked:', packet.reason))
+
+  client.on('transfer', async (packet) => {
+    console.log(`received transfer packet -> ${packet.host}:${packet.port}, reconnecting`)
+    await new Promise((resolve) => {
+      client.once('end', resolve)
+      client.end()
+    })
+    await new Promise((resolve) => setTimeout(resolve, 500))
+    connect(packet.host, packet.port)
+  })
+
+  return client
+}
+
+connect(host, port)
diff --git a/examples/client_transfer/package.json b/examples/client_transfer/package.json
new file mode 100644
index 000000000..56fcdf265
--- /dev/null
+++ b/examples/client_transfer/package.json
@@ -0,0 +1,8 @@
+{
+  "name": "node-minecraft-protocol-example",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+  },
+  "description": "A node-minecraft-protocol example"
+}