Puppet | Take full control of players

Ever wanted to take full control of another player's character? Puppet is a Paper plugin for 1.21.11 that lets you literally "possess" someone else.




Requirements
You will need a few things to run this properly:

• Minecraft: 1.21.11
• Server: Paper (or forks like Purpur)
• Java: Java 21
• ProtocolLib 5.3.0+: This is strictly required. The plugin relies heavily on it for NMS packet interception, faking skins, and hiding entities without crashing clients.

How it works
When you start a session, the plugin saves all of your current stuff (your location, exact inventory, health, food, xp, and gamemode). Your real body is hidden from the server and gravity is disabled.

You are then teleported to the victim and instantly take on their identity. You get their inventory, their stats, and even their skin and nametag (this includes your F5 third-person view, thanks to ProtocolLib). To everyone else on the server, you are that player.

When you type /puppet stop (or if the session ends naturally), everything goes back to normal. You are teleported back to your original spot with your original gear. Any items you picked up or damage you took while controlling the victim will stay on the victim's character.

[hr]

Rules and Limits

• You can't just control someone across the server. Both of you must be in the same world and within a 100-block radius.
• Head rotation (yaw/pitch) and movements are constantly synced.
• Server admins can blacklist specific worlds in the config where this feature shouldn't be allowed.

[
Safety and Edge Cases
I added a bunch of fail-safes so this can't be heavily abused or break your server:

• Auto-cleanup: If either player dies, disconnects, or changes worlds, the session cancels immediately.
• Consent system: You can enable a feature in the config that forces the victim to type /puppet accept before they get controlled.
• Protection: You can block the victim from taking damage or chatting while they are being puppeted.
• The packet hiding (ENTITY_DESTROY, PLAYER_INFO, etc.) is handled cleanly so nobody gets randomly kicked for packet errors.

Config
Here is what the default config.yml looks like:


Commands
The main command is /puppet (you can also use /ppt).

For Players (puppet.use):

• /puppet - Opens a GUI to select a player.
• /puppet <player> - Starts controlling that player.
• /puppet stop - Ends your current session (you can also use end or release).
• /puppet status - Shows who you are currently controlling or who is controlling you.
• /puppet accept / /puppet deny - Respond to a control request.
• /puppet help - Shows the help menu.

For Admins (puppet.admin):

• /puppet settings - Opens a cool GUI to edit the config in-game.
• /puppet list - See all active puppet sessions right now.
• /puppet force <player> - Force stop someone's session.
• /puppet inspect <player> - Check if a player is secretly being controlled.
• /puppet fix [player] - Use this if someone's visibility gets glitched/desynced. It forces a refresh.
• /puppet reload - Reloads the config.

Links

• ProtocolLib Dev Builds
• Source Code on GitHub