TruePlayer

TruePlayer is a Paper plugin that provides server-side fake players for testing, automation and survival utility tasks.

The project currently targets modern Paper/Paperweight mappings and uses NMS, so it is version-sensitive. If you upgrade Minecraft/Paper, rebuild and test fake-player spawning and interactions first.

Features

• Spawn and remove fake players from in-game commands.
• Fake players are registered in the server player list and keep nearby chunks active like online players.
• Left-click attack support.
• Right-click/use support for blocks, entities and held items.
• Repeating attack/use actions with configurable tick interval.
• Stop command to cancel all repeating actions and reset transient movement/action state.
• Open and edit fake-player inventories.
• Persist fake-player inventory data across despawn/restart:
  • storage contents
  • armor contents
  • offhand item
  • selected hotbar slot
• Select fake-player hotbar slot from the inventory UI with number keys or mouse wheel.
• Swap main hand/offhand from the inventory UI.
• Chunk/debug command for checking whether the fake player is present in Bukkit and the server player list.

Requirements

• Java 21 or newer.
• Paper server matching the version used by the build configuration.
• Operator/permission access for administration commands.

Build

./gradlew build

The plugin jar is generated under:

build/libs/

Upload the built jar to your server's plugins/ directory and restart the server.

Commands

All commands use /player <name> <action>.

Command	Description
/player <name> spawn	Spawn a fake player at your current location.
/player <name> kill	Remove the fake player and save its inventory.
/player <name> stop	Stop repeating use/attack actions and reset transient action state.
/player <name> use	Right-click/use once.
/player <name> use <ticks>	Repeatedly right-click/use every <ticks> ticks.
/player <name> attack	Left-click/attack once.
/player <name> attack <ticks>	Repeatedly attack every <ticks> ticks.
/player <name> inventory	Open the fake player's inventory.
/player <name> chunkinfo	Print fake-player chunk/list/debug information.

Examples:

/player Bot spawn
/player Bot use
/player Bot use 20
/player Bot attack 10
/player Bot stop
/player Bot inventory
/player Bot kill

Permissions

The command is available to senders with:

trueplayer.admin

Players can also be allowed through the config whitelist by player name or UUID.

Inventory usage

Open a fake player's inventory with:

/player <name> inventory

You can also sneak-right-click the fake player to open it.

While viewing the inventory:

• The top hotbar row represents the fake player's hotbar.
• Use number keys or mouse wheel hotbar changes to select the fake player's held slot.
• Press F, or double-click the selected hand/offhand slot, to swap main hand and offhand.
• Closing or editing the inventory schedules a save.

Inventory files are stored in:

plugins/TruePlayer/fake-player-inventories/<name>.yml

Interaction notes

Right-click/use tries to mimic vanilla/Carpet ordering:

1. Ray trace from the fake player's eyes.
2. If a block is hit, call server game-mode useItemOn.
3. If an entity is hit, first try exact hit-position entity interaction, then the player's interactOn path.
4. If no target interaction succeeds, use the item in hand.

This means the fake player must face the target and be within normal reach. Some entity or block interactions may still differ from a real client because the fake player has no real network client.

Configuration notes

Common config keys used by the plugin include:

fake-player:
  max-name-length: 16
  allow-duplicate-name: false
  default-game-mode: survival
  spawn-message: true

player-command-whitelist: []

Troubleshooting

• 生成失败：名称不合法 Use 1-16 characters: letters, numbers or underscores.

• NMS 运行时不兼容 The plugin was likely built for a different Paper/Minecraft version. Rebuild against the target server version.

• Right-click does nothing Check the fake player's direction, reach distance, held item and game mode. Use /player <name> chunkinfo to verify that the fake player is still registered and loaded.

• Inventory changes are missing Remove the fake player with /player <name> kill or close the inventory UI to trigger a save.

Development references

The fake-player action logic borrows the practical ordering used by Carpet's EntityPlayerActionPack: block use first for block hits, entity hit-position interaction before player fallback for entity hits, then item use fallback.