1. Installation

1. Drop Marionette-x.x.x.jar into your server's /plugins folder.
2. Restart the server. No other plugins are required.
3. A config.yml is generated in /plugins/Marionette/.

Works on Spigot, Paper, Purpur, Pufferfish and other forks, on every modern Minecraft version.

2. Quick start

• /marionette spawn — spawn a fake player at your position.
• /marionette list — see your fake players (click the buttons to TP / kill).
• /marionette attack continuous — make it keep attacking.
• /marionette kill -a — remove all of them.

Base command: /marionette (alias /mar). Type /marionette help in-game for the full list.

3. Targeting a fake player
Most commands accept an optional [name]. When you omit it, Marionette picks, in order:

1. the fake player you /marionette selected, then
2. your only fake player (if you have exactly one).

If you have several and don't specify a name, you'll be asked to provide one.
Use -a with /marionette kill to target all of them.

4. Command reference
Management

• spawn [name] [world] [x y z] — create a fake player (defaults to your location)
• kill [names|-a] — remove fake players · killall — remove every fake player on the server (OP)
• list [page] [size] — paginated list with TP / kill buttons
• select [name] / selection — choose / show your active fake player
• status [name] — show a fake player's settings
• distance [name] — distance between you and the fake player
• respawn [name] — respawn a dead fake player
• stop [name] — stop all running actions

Teleport

• tp [name] — teleport to the fake player · tphere [name] — bring it to you · tps [name]

Actions — each accepts a mode: once | continuous | interval <ticks> | stop

• attack · mine · use · jump · drop · dropstack · dropinv

Movement & posture

• move forward|backward|left|right [name]
• look north|south|west|east|up|down|at <x y z>|me|entity [name]
• turn left|right|back|to <yaw pitch> [name]
• sneak [name] [true|false] · sprint [name] [true|false]
• ride me|target|anything|vehicle|entity <selector>|stop [name]
• swap [name] · sleep [name] / wakeup [name] · hold <slot 1-9> [name]

Inventory & misc

• invsee [name] — open the fake player's inventory
• expme [name] — transfer the fake player's experience to you
• cmd <name> <command...> — make the fake player run a server command
• set <feature> <value> [name] — change a fake player feature
• config set|list — your personal defaults

Admin (OP)

• reload · reload-translation · debug ... · help

5. Permissions

• marionette.* — all permissions
• marionette.command.<name> — a single command (e.g. marionette.command.spawn, marionette.command.tp, marionette.command.kill …)

Admin commands (killall, reload, debug) require OP.

6. Configuration (config.yml)
Key options:

• follow-quiting (default false) — if true, a player's fake players are removed when that player goes offline. Leave false to keep them online.
• lifespan (default 0) — minutes before a fake player is auto-removed. 0 = never.
• persistent-data (default true) — save fake-player data across restarts.
• kick-on-dead (default true) — remove a fake player when it dies.
• prevent-kicking — protect fake players from being kicked by other plugins on spawn.
• server-limit / per-player limits — cap how many fake players can exist.
• drop-inventory-on-quiting — drop a fake player's inventory when it is removed.

After editing the file, run /marionette reload.

7. Notes & FAQ

• Do fake players stay online when I log off? Yes, by default (follow-quiting: false).
• Do I need CommandAPI / ProtocolLib / Adventure? No. Marionette is fully self-contained.
• Skins: skin copying is disabled in the cross-platform build (fake players use the default skin); the rest of the plugin is unaffected.
• Languages: English and Chinese (Simplified / Traditional) are bundled.