PuppetPlayers

Puppet Players

A fabric mod for fake ‘puppet’ players in Minecraft

About The Project

Modern, simple implementation of the fake players implemented originally in Carpet Mod.

There are some fundamental differences to how these fake players are implemented in comparison to the original implementation in Carpet Mod.

This mod can be used alongside Carpet Mod, carpet’s fake player actions will work on these puppet players; however, it’s recommended to use the provided actions instead.

The aim of this mod is to keep the behaviour of the puppet players as accurate as possible to a real player:

• All the player ticking is done in the correct tick phase.
• The client code for player actions is simulated on the server.
• Puppet players send packets to interact with the server, like a real player.
• Maintaining compatibility with all mods.

Usage

This documentation covers the latest version of the mod, for versions prior to 2.0.0

please see the old documentation

After installing the mod the /puppet command should become available to operators.
The /puppet command can also be made available to all players by changing the config,
see the config section for more details.

We can make a puppet player join the world using one of the following commands:

/puppet <username> join
/puppet <username> spawn
/puppet <username> spawn at <position> facing <rotation> in <dimension> in <gamemode>
/puppet <username> shadow

• The join subcommand spawns the specified puppet at its previous log-off position, this essentially simulates

as if the player were joining the server themselves.

• The spawn subcommand spawns the specified puppet at either a specified position or the position of the

command executor if the position is not specified.

• The shadow subcommand makes a puppet player join in the place of a currently online player.

Once a player has joined the world, we can make the player leave by running the following command:

/puppet <player> leave

Puppeteering

Players can take over a puppet and play as it, leaving their own body behind in the world:

/puppet <player>

You can only specify puppets to puppeteer, or yourself if you are currently puppeteering
which puts you back in your original body. This feature is disabled by default and must be
enabled by setting enable_puppeteering, see the config section.

While puppeteering you will appear to other players as the puppet, and you resume the position
that the puppet was in with their inventory. Anything done to the puppet will persist after you
stop puppeting them. Stats and advancements however are still tied to your account. The same
is true for chat, messages are still sent through your account.

Your original body while puppeteering will become a puppet, so you can run /puppet on them
like you could with any other puppet, except for the leave command. Because on the server
you are still playing on your account when someone runs a command specifying your name it
will target the player you are puppeteering. For example, if the player senseiwells is
puppeteering SuperSanta and someone runs /tp senseiwells they will teleport to the player
SuperSanta. The exception to this is the /puppet command which will refer to whoever is going
by that name.

If you die while puppeteering or if the puppet disconnects then you will stop puppeteering. If
you log off while puppeteering then your original body will be logged off and the puppet will remain online.

Actions

Puppet players are able to run actions mimicking real player behaviour.
Certain actions can also be run on real players.

Here is a list of all available actions:

| Action | Description | Arguments | Works stand-alone | Puppet only |
|———————————|——————————————————|—————————————————————————|——————-|————-|
| "minecraft:attack" | Makes the player attack (left click). | <once\|hold\|release> | Yes | No |
| "minecraft:delay" | Adds a delay between chained actions. | <delay> | No | No |
| "minecraft:drop" | Makes the player drop their selected item. | <entire_stack> | Yes | No |
| "minecraft:interrupt_look_at" | Interrupts the current look at target. | None | Yes | Yes |
| "minecraft:interrupt_move_to" | Interrupts the players current pathfinding. | None | Yes | Yes |
| "minecraft:jump" | Makes the player jump. | <once\|hold\|release> | Yes | Yes |
| "minecraft:look" | Makes the player look in a direction. | <rotation> | Yes | No |
| "minecraft:look_at" | Makes the player look towards the specified target. | position <pos> <lock?> or entity <entity> <lock?> | Yes | Yes |
| "minecraft:move_to" | Makes the player pathfind to a position or entity. | position <pos> <sprint?> <jump?> or entity <entity> <sprint?> <jump?> | Yes | Yes |
| "minecraft:offhand" | Makes the player swap their item with their offhand. | None | Yes | No |
| "minecraft:sneak" | Makes the player sneak. | <sneaking> | Yes | Yes |
| "minecraft:sprint" | Makes the player sprint. | <sprinting> | Yes | Yes |
| "minecraft:swap_slot" | Makes the player swap to a slot. | <slot> | Yes | No |
| "minecraft:use" | Makes the player use (right click). | <once\|hold\|release> | Yes | No |

To run an action, we can run it stand-alone with the following command:

/puppet <player> actions run <action> ...

This makes the player run the action immediately.

For example, to make a player hold attack, you would run:

/puppet <player> actions run minecraft:attack hold

We can also chain multiple actions together by running the following command:

/puppet <player> actions chain add <action> ...

Once you’ve added actions to the chain, we can also run the following commands to
control the chained behaviour:

/puppet <player> actions chain loop <true|false> # Whether to infinitely loop the chained actions
/puppet <player> actions chain pause # Pause execution of the chained actions
/puppet <player> actions chain resume # Resume execution of the chained actions
/puppet <player> actions chain restart # Restart execution of the chained actions (from the first action)
/puppet <player> actions chain stop # Stops execution of the chained actions (and clears all actions)

For example, to make a player hold attack for 5 seconds, then let go for 2 seconds, then repeat we would run:

/puppet <player> actions chain add minecraft:attack hold
/puppet <player> actions chain add minecraft:delay 5s
/puppet <player> actions chain add minecraft:attack release
/puppet <player> actions chain add minecraft:delay 2s
/puppet <player> actions chain loop true

Config

The config is located in ./config/puppet-player-config.json and by default should look like this:

{
  "reload_puppet_players": true,
  "respawn_puppet_players": true,
  "puppet_player_death_delay": 0,
  "operator_required_for_puppets": true,
  "can_players_puppet_themselves": true,
  "can_spawn_puppets_anywhere": true,
  "can_spawn_whitelisted_players_as_puppets": true,
  "enable_puppeteering": false,
  "enabled_actions": "*"
}

• "reload_puppet_players" – Whether puppets will rejoin if the server stopped with them last online
• "respawn_puppet_players" – Whether to respawn puppets after they die, if disabled they will leave the game instead
• "puppet_player_death_delay" – The delay after the puppet dies to either respawn/leave (determined by respawn_puppet_players)
• "operator_required_for_puppets" – Whether players need operator permissions to run the /puppet command
• "can_players_puppet_themselves" – Whether non-op players are able to run the /puppet command on themselves
• "can_spawn_puppets_anywhere" – Whether you can run the /puppet <username> spawn <position?> to spawn puppets anywhere in the world (as opposed to join which spawns then where they last logged off)
• "can_spawn_whitelisted_players_as_puppets" – Whether you can spawn whitelisted players as puppets
• "enable_puppeteering" – Whether players are able to take over a puppet and play as it
• "enabled_actions" – The list of enabled actions that you can make puppets do, "*" for all actions, or list the enabled actions, e.g. ["attack", "use"]

For a survival server, a less “cheaty” version of the mod can be used with the following recommended config:

{
  "reload_puppet_players": true,
  "respawn_puppet_players": false,
  "puppet_player_death_delay": 20,
  "operator_required_for_puppets": true,
  "can_players_puppet_themselves": true,
  "can_spawn_puppets_anywhere": false,
  "can_spawn_whitelisted_players_as_puppets": false,
  "enable_puppeteering": false,
  "enabled_actions": ["use", "attack", "drop", "swap_slot"]
}