InventoryLink

Link two player inventories — live — with an opt-in request/accept flow and strong safeguards. Designed for PaperMC 1.21.x and Java 21.

⚠️ Irreversible: When a link is accepted, the accepting player’s current inventory is cleared and replaced with the requester’s. This cannot be undone. Linking to unknown players is not recommended.

---

✅ Supported Platforms & Requirements

• Minecraft server: PaperMC 1.21.x (API 1.21).
  • Works on Paper-compatible forks that maintain API parity (e.g., Purpur).
• Java runtime: Java 21 (server + build).
• Optional Bedrock play: GeyserMC + Floodgate (for Java↔Bedrock account linking use case).

---

✨ Features

• Two-player inventory sharing via /link → /link accept / /link deny.
• Live Sync toggle (live-sync: true|false)
  • true: both players can be online; inventories mirror in real-time (click, drag, drop, pickup).
  • false: only one linked player may be online; the second gets kicked with a configurable message.
• Clear on Death (with offline support): If one linked player dies, the partner’s inventory & ender chest are cleared. If the partner is offline, the clear is applied on next join.
• Request Expiry: Link requests expire after a configurable timeout.
• Block Linking While Linked: Already linked players can’t send or accept new /link.
• Per-player data folder:
  plugins/InventoryLink/playerdata/<PlayerName>/
  • inventory.yml — serialized snapshots
  • link.yml — partner name + flags (e.g., pendingClearOnJoin)
• Configurable Messages using classic & color codes.
• Admin Command to reload config without restarting.

---

🧩 Bedrock Use Case (Java ↔ Bedrock)

If your server supports Bedrock via GeyserMC + Floodgate, a Java player can link their own Bedrock account:

• Bedrock players typically appear as usernames with a Floodgate prefix (e.g., "." or a custom prefix).
• A Java player can run:

  /link <bedrockUsernameWithPrefix>
  

• The Bedrock player must accept the request:

  /link accept <javaPlayerName>
  

• After acceptance, the Bedrock account receives the Java inventory (and live sync applies if enabled).
• Tip: Keep your Floodgate prefix documented for players so they can type the correct Bedrock name.

This is ideal for players who switch between Java and Bedrock and want a single, shared inventory.

---

📦 Commands

• /link <player> — Send a link request to <player>
• /link accept <player> — Accept a pending request from <player>
• /link deny <player> — Deny a pending request from <player>
• /inventorylink reload — Reload config.yml (permission: inventorylink.admin)

Permissions

• inventorylink.link — default: true
• inventorylink.admin — default: op

---

⚙️ Configuration (plugins/InventoryLink/config.yml)

live-sync: true                 # Allow both linked players online & mirror live
sync-debounce-ms: 200           # Debounce mirroring to avoid loops
kick-message: "&cYour linked partner is already online. Live sync is disabled on this server."

clear-on-death: true            # Also clears partner on death; offline partners clear on next join

request-timeout-seconds: 60     # Expire pending /link requests
block-command-while-linked: true

messages:
  already-linked: "&cYou are already inventory-linked and cannot use /link."
  target-already-linked: "&cThat player is already inventory-linked and cannot accept new links."
  request-expired: "&cThat link request has expired. Please send a new one."
  request-sent: "&aLink request sent to %target%."
  request-received: "&e%sender% wants to link inventories with you. &cAccepting will CLEAR your current inventory and cannot be undone. Linking to unknown players is not a good idea."
  accept-hint: "&aType /link accept %sender%  or  /link deny %sender%"
  accepted: "&aYou are now linked with %other%. Inventories are now synced."
  denied: "&eYou denied the link request from %other%."
  partner-join-kick: "&cYour linked partner is already online. Live sync is disabled on this server."
  reloaded: "&aInventoryLink config reloaded."
  pending-cleared-on-join: "&eYour inventory was cleared due to your partner's recent death."

---

🧭 How it Works

1. Request: /link <player> — Target receives warnings + accept/deny instructions.
2. Accept: The accepting player’s current inventory is cleared and replaced with the requester’s.
3. Live Sync (optional): With live-sync: true, both inventories mirror in real-time.
4. Death Sync: On death, partner is cleared (immediately if online, or on next join).

---

📥 Installation

1. Drop the plugin jar into plugins/ on a Paper 1.21.x server.
2. Start the server to generate the config.
3. Edit plugins/InventoryLink/config.yml.
4. Apply changes with /inventorylink reload or restart.

---

🔒 Safety Notes

• This plugin deliberately performs destructive inventory operations on accept and on death (if enabled).
• Use where players explicitly consent; consider backups if you run custom item systems.

---

📄 License

MIT — keep the license and don’t hold the author liable. Contributions welcome.