Puppets

Puppets

Stand-in players you control, for testing anything that needs more than one player on your own.

A puppet joins your world or server as a real player. It shows in the tab list, takes damage, needs air, gets hungry, rides things, and counts for teams, permissions and anything else that counts players. You can tell it what to do, record yourself and have it replay you, write it a script, or take it over and drive it with your own keys.

Puppets runs on:

Minecraft	Loaders
1.20.1	Fabric (needs Fabric API), Forge
1.21.1	Fabric (needs Fabric API), Forge, NeoForge
1.21.11	Fabric (needs Fabric API), Forge, NeoForge
26.3	Fabric (needs Fabric API), NeoForge

Only the server (or your singleplayer world) needs it. Install it in your own game too to get the menu and possession.

Getting started

1. In singleplayer, open your world to LAN with Allow Cheats on. On a server, you need to be an operator.
2. Press O, or type /puppet menu. Without Puppets on your game, use the commands; /puppet help lists the basics, and you can click any line to use it.
3. Type a name and press Spawn. Pick the puppet in the list, and use the buttons. Hovering a button shows what it does and the command it sends.

What a puppet can do

Every action is /puppet <name> <action>. /puppet all <action> does it for every puppet. /puppet group <prefix> <action> does it for every puppet whose name starts with the prefix.

Action	What it does
`move forward\	back\
`jump\	sneak\
look <yaw> <pitch>, `look north\	south\
`leftclick once\	hold\
`rightclick once\	hold\
use, useblock [x y z face], useentity, attack, mine, release	One click on one thing. release lets go of a drawn bow or a half-eaten meal
slot <1-9>, swap, `drop [one\	stack\
inventory	Opens its inventory for you to give it things or take them. You can also sneak and right-click it
copygear	It gets a copy of everything you carry and wear
click <slot> [button] [mode], button <id>, trade <n>, close, `sign x y z front <line1\	line2>`
mount [entity], dismount	Rides the nearest boat, horse, minecart or vehicle
`follow [player\	me], goto , wander [radius], guard [radius], stay`
`skin \	none`
possess	You drive it: your keys and mouse move it, and you see through its eyes. O or /puppet release lets go. Needs Puppets on your game
run <command>	Runs any command as it (run say hi, run give @s bread)
say <text>, respawn, kill, wake, remove	Talks, comes back to life, dies, gets out of bed, leaves
status, `check health\	air\
play <script> [relative], stop	Plays a script. stop lets go of everything

Spawning takes options in any order: /puppet spawn Bob count 5 at 0 64 0 facing north in the_nether as survival skin jeb_. Add rejoin to have it come back where it last left. Spawning several gives Bob1 to Bob5 in a row.

Shadow. /puppet shadow logs you off and leaves a puppet with your own name and skin where you stood, holding what you held. Use it for AFK farms, or for testing what others see of you. When you log back in, you take its place.

Restarts. Puppets that were on when the server stopped come back when it starts, where they were.

Mob puppets

Any mob can be a puppet too: a horse, a villager, a zombie, a cow. Look at one and run /puppet mob take (or /puppet mob take @e[type=horse,limit=1,sort=nearest] as Star), or use Take the one I see on the menu's Mobs page. While it's a puppet, its own mind (wandering, fleeing, working, hunting) stands down and it does what it's told:

Action	What it does
`move forward\	back\
goto x y z, come, `follow [me\	player\
`attack [nearest\	player\
mount, dismount	Rides the nearest thing it can
possess	You drive it with your own keys; right-click does what its kind does. O lets go
play <script> [relative], stop	Scripts and your recordings work on mobs too
`ai on\	off`
letgo	An ordinary mob again

What only some kinds can do, as they really can: horses jump high and rear, farmer villagers harvest and plant (seeds from their inventory), tamed pets sit and stand, sheep graze, creepers ignite, endermen pickup and place.

Unrestricted (/puppet mob Bessie unrestricted on) lifts all of that: any mob may place <block>, break, fly on, say <text>, speed <n>, tp, hit things, and replay a recording exactly where you went. A cow that builds is one command away.

Recording and scripts

Run /puppet record start myroute (or press Record me), then play it out yourself. Walk, build, open chests, click in machines, drive, shoot. Then run /puppet record stop, and any puppet can replay it with /puppet Bob play myroute. Add relative to start from where Bob stands instead.

Everything your game tells the server goes into the recording, including mods' own key presses and buttons (vehicle keys, gun triggers, machine buttons), byte for byte. So recordings work with mods Puppets has never heard of. Requests that only fetch something to display (Jade, Xaero, JEI) are left out.

Scripts are text files in puppets/scripts/ on the server, one action per line. The example_ scripts come with the mod:

# Walks a square, then waits to be told
repeat 4
  move forward
  wait 1s
  move stop
  turn right
end
goto ~5 ~ ~          # ~ is where the puppet is
waituntil idle       # until it gets there
@Alice say Bob's back!
say Done

Line	Meaning
any action	As above, without /puppet <name>
wait 20, wait 3s	Pause, in ticks (20 a second) or seconds
repeat 3 ... end, loop ... end	Repeat (loop repeats until the script is stopped)
waituntil idle, waituntil health < 10	Hold here until it's done walking or mining, or until a check is true
@Alice <action>	Another puppet does it, so one script can direct several
log <text>, stop, # comment

A line that doesn't work is skipped and logged as PUPPET_SCRIPT_LINE_FAILED. It never crashes the server.

Mods

Recordings replay any mod's own packets. A few mods also get actions you can write by hand:

• Superb Warfare: sbw forward\|back\|left\|right\|space\|shift\|ctrl\|flares\|fire\|none holds vehicle keys
• TACZ: tacz draw\|shoot\|reload\|aim\|unaim\|fireselect\|melee\|bolt
• Trinkets (Fabric) and Curios (Forge, NeoForge): equip wears the held item in the first free slot that takes it
• Rackcraft: the jetpack and zero-g thrust follow jump and sneak

Tested with Rackcraft machines, Create (wrench), Farmer's Delight (cutting board), Traveler's Backpack, Artifacts, TACZ, Superb Warfare and the 300-mod Rackcraft Expanded pack.

For server owners

puppets/config.json explains each setting next to it:

Setting	Default
rejoinAfterRestart	true	Puppets that were on come back after a restart
maxPuppets	50	The most at once (0: no limit)
permissionLevel	2	Who may use /puppet (2: operators)
shadow	true	Whether players may leave a shadow

Puppets use offline-mode UUIDs from their names, so they never clash with real accounts. Skins come from Mojang's public profile service and are cached in puppets/skins.json.

For developers

ServerPlayerEntity bob = PuppetsApi.spawn(server, "Bob", world, new Vec3d(0, 64, 0));
PuppetsApi.act(server, "Bob", "move forward");        // any action, as its words
PuppetsApi.act(server, "Bob", "play example_square");
boolean isPuppet = PuppetsApi.isPuppet(player);
PuppetsApi.remove(server, "Bob");

The example uses the 1.20.1 and 1.21.1 names. On 1.21.11 and 26.3 they are ServerPlayer and Vec3.

A puppet is an ordinary server player, so anything that works on a player works on it. For automated tests, check lines (PUPPET_CHECK ... true|false in the log) pair with a command runner. Rackcraft DevTools' assert puppet Bob check air > 0 is one. Scripts log PUPPET_SCRIPT DONE, PUPPET_ARRIVED and PUPPET_LOG lines.

For your own actions and behaviours, see addon-template/: an example addon to copy, with a "wave" action, a "circle" behaviour and a join listener. It registers through the puppets Fabric entrypoint, or a META-INF/services file on Forge and NeoForge.

Build each Minecraft version from its folder: cd 1.20.1 && ./gradlew build (jars in fabric/build/libs and forge/build/libs), cd 1.21.1 && ./gradlew build or cd 1.21.11 && ./gradlew build (Fabric, Forge and NeoForge), or cd 26.3 && ./gradlew build (Fabric and NeoForge). Build with Java 25. tools/ingame_basic.txt is the in-game test every build passes.