FakePlayerPlugin

Advanced Fake Player Spoofer for Paper/Purpur/Folia 1.21+
Create realistic fake players — full tab-list entries, physical in-world bodies, skins, combat, pathfinding, automation, and multi-server proxy support with proxy-merged shared database.

✨ Features

Core (Ships with fpp.jar)

• 🎭 Realistic Fake Players — Full tab-list integration, join/leave messages, server count spoofing
• 🏃 Physical Bodies — NMS ServerPlayer entities with hitboxes, collision, damage, death & respawn
• 🎨 Skins — Auto-resolve from Mojang, per-bot skin commands, custom pool support
• 🧭 Pathfinding & Automation — A* navigation, follow, roam, find-and-mine, sleep, auto-eat, auto-place-bed
• ⛏️ Area Mining & Block Placing — Cuboid region mining (/fpp mine) and placement (/fpp place) with supply-container restocking
• ⚔️ PvE Combat — Per-bot attack settings, hunt mode, melee cooldowns
• ⚙️ Per-Bot Settings GUI — Shift+right-click any bot for inventories, pathfinding toggles, PvE settings, and automation overrides
• 💾 Persistence — Bot positions, tasks, and inventories survive restarts (YAML or database)
• 🗄️ Database — SQLite (local) or MySQL (network / multi-server with proxy-merged shared tables)
• 🌐 Proxy Support — Velocity & BungeeCord with companion plugins; proxy-merged database shares live bot registry and player counts across all backends
• 🔄 Config Sync — Push/pull config across backend servers via shared MySQL
• 📦 Extension API — Drop .jar files into plugins/FakePlayerPlugin/extensions/ to load third-party addons
• 🔤 Random Name Generator — bot-name.mode: random generates realistic Minecraft-style usernames on the fly
• 🚫 Badword Filter — Leet-speak normalization, auto-rename, remote word list
• 📊 PlaceholderAPI — 80+ placeholders for scoreboards, tab headers, cross-server counts, and more
• 🧱 WorldEdit & WorldGuard — --wesel selection flag for mine/place; region-aware PvP protection
• 📶 Simulated Ping — Tab-list latency display per bot
• 🌀 Folia Support — Full compatibility with Folia's region-threaded architecture

Extension (fpp-spoof.jar)

Some advanced subsystems require the fpp-spoof.jar extension:

• 🤖 AI conversations (/msg replies with personalities)
• 💬 Fake chat / broadcast messaging
• 🔄 Swap system / peak-hours scheduler
• 👥 Bot groups
• 📶 Ping command (/fpp ping)
• 💻 Stored right-click commands (/fpp cmd)

📥 Installation

1. Download fpp.jar from Modrinth or build from source.
2. Drop the JAR into your server's plugins/ folder.
3. Restart the server. The plugin will create plugins/FakePlayerPlugin/ with configs and data folders.
4. Configure permissions and plugins/FakePlayerPlugin/config.yml as needed.
5. Run /fpp reload to apply most config changes without restarting.

Optional Dependencies

• PlaceholderAPI — enables placeholder expansion (%fpp_count%, %fpp_total%, etc.)
• LuckPerms — prefix/suffix support and bot group assignment
• WorldGuard — bot PvP region protection
• WorldEdit — --wesel flag for area mining/placing

🚀 Quick Start

# Grant yourself admin access
/lp user <you> permission set fpp.admin true

# Spawn your first bot
/fpp spawn

# Open its settings
shift+right-click the bot entity

# Teleport it to you
/fpp tph <bot>

# Make it follow you
/fpp follow <bot> <player>

⌨️ Commands

All commands are prefixed with /fpp (aliases: fakeplayer, fp).

| Command | Usage | Description | Permission |
|---------|-------|-------------|------------|
| spawn | [amount] [world [x y z]] [--name <name>] [--random-name] [--notp] [<bottype>] | Spawn fake player bots | fpp.spawn (admin) / fpp.spawn.user (user) |
| despawn | <name> \| all \| --count <n> \| --random [--count <n>] | Remove bot(s) | fpp.despawn |
| list | [page] | List active bots | fpp.list |
| tph | [botname\|all] | Teleport bot(s) to you | fpp.tph |
| tp | [botname] | Teleport to a bot | fpp.tp |
| xp | <bot> | Collect XP from a bot | fpp.xp |
| move | <bot\|all> --to <player> \| --coords <x> <y> <z> \| --roam [x,y,z] [radius \| infinite \| forever \| unbounded] \| --stop | Navigate bot | fpp.move |
| mine | <bot> [--once\|--stop\|--pos1\|--pos2\|--start\|--wesel] \| --stop | Mine blocks | fpp.mine |
| place | <bot> [--once\|--stop\|--wesel] \| --stop | Place blocks | fpp.place |
| use | <bot> [--once\|--stop] \| --stop | Right-click automation | fpp.use.cmd |
| attack | <bot\|all> [--mob [type]] [--range <n>] [--type <mob>] [--priority nearest\|lowest-health] [--move] [--stop] \| --hunt [<mob>] [--range <n>] [--priority <mode>] [--stop] | PvE attack / hunt | fpp.attack |
| follow | <bot\|all> <player\|--start> \| <bot\|all> --stop | Follow a player | fpp.follow |
| find | <bot> <block> [-r <n> \| --radius <n>] [-c <n> \| --count <n>] [--prefer-visible] \| <bot> --stop \| --stop | Find and mine blocks | fpp.find |
| sleep | <bot\|all> <x y z> <radius> \| <bot\|all> --stop | Auto-sleep at night | fpp.sleep |
| stop | [<bot>\|all] | Cancel active tasks | fpp.stop |
| freeze | <bot\|all> [on\|off] | Freeze/unfreeze | fpp.freeze |
| inventory | <bot> (alias: inv) | Open bot inventory | fpp.inventory |
| storage | <bot> [storage_name\|--list\|--remove <name>\|--clear] | Manage supply containers | fpp.storage |
| extension | (bare) \| --list | Open marketplace link or list extensions | (implied admin) |
| save | — | Force-save all bots | fpp.save |
| setowner | <bot> <player> | Transfer ownership | fpp.setowner |
| rename | <oldname> <newname> | Rename a bot | fpp.rename |
| info | [bot\|spawner] <name> | Bot info / session history | fpp.info |
| stats | — | Plugin statistics | fpp.stats |
| badword | <check\|update\|status> | Manage badword filter | fpp.badword |
| migrate | <backup\|status\|config\|lang\|names\|db> | Backup / migrate data | fpp.migrate |
| reload | [all\|config\|lang\|extensions] | Hot-reload config | fpp.reload |
| settings | [bot] | Open settings GUI | fpp.settings |
| help | [page] | Show help menu | fpp.help |

Quick Examples

/fpp spawn 5                          # Spawn 5 bots
/fpp spawn --name Steve               # Spawn a bot named "Steve"
/fpp spawn --notp                     # Spawn at last known location (if persisted)
/fpp spawn world_nether 100 64 -200   # Spawn in another world
/fpp spawn 3 afk                      # Spawn 3 bots with "afk" bot-type preset
/fpp despawn all                      # Remove all bots
/fpp despawn --random --count 3       # Remove 3 random bots
/fpp move bot1 --to Notch             # Navigate to player
/fpp move bot1 --roam 500,64,200 25   # Roam in 25-block radius
/fpp mine bot1 diamond_ore --wesel    # Mine using WorldEdit selection
/fpp place bot1 --once                # Place one block
/fpp attack bot1 --hunt --range 16    # Hunt mobs
/fpp follow bot1 Notch                # Follow a player
/fpp find bot1 diamond_ore --radius 64 --count 20
/fpp sleep bot1 100 64 200 50         # Set sleep origin
/fpp stop bot1                        # Stop all tasks
/fpp freeze bot1 on                   # Freeze bot
/fpp inv bot1                         # Open inventory
/fpp storage bot1 chest1              # Register container
/fpp rename bot1 builder_01           # Rename bot
/fpp info bot1                        # Show session history

🔐 Permissions

FPP uses a two-tier permission system.

Wildcards

| Node | Default | Description |
|------|---------|-------------|
| fpp.admin | op | Full admin access (same as fpp.op) |
| fpp.op | op | Full access to all commands |
| fpp.use | true | User-tier: spawn (1 bot), tph, xp, info (own bots) |

Key Nodes

• Spawn: fpp.spawn, fpp.spawn.user, fpp.spawn.limit.1 through fpp.spawn.limit.100
• Despawn: fpp.despawn, fpp.despawn.bulk, fpp.despawn.own
• Movement: fpp.move, fpp.move.to, fpp.move.stop
• Automation: fpp.mine, fpp.place, fpp.use.cmd, fpp.attack, fpp.attack.hunt, fpp.find, fpp.follow, fpp.sleep, fpp.stop
  • fpp.mine.wesel — WorldEdit selection for mining area
  • fpp.place.wesel — WorldEdit selection for placement area
• Management: fpp.freeze, fpp.rename, fpp.rename.own, fpp.inventory, fpp.storage, fpp.setowner, fpp.save, fpp.settings
• System: fpp.reload, fpp.migrate, fpp.badword
• Bypass: fpp.bypass.max, fpp.bypass.cooldown
• Notify: fpp.notify — update notifications on join

Quick Setup

# Admin
/lp group admin permission set fpp.admin true

# User
/lp group member permission set fpp.use true

# Custom bot limit (5)
/lp user Alice permission set fpp.spawn.limit.5 true

# Bypass cooldown for VIPs
/lp group vip permission set fpp.bypass.cooldown true

# Hide /fpp from guests
/lp group guest permission set fpp.command false

📊 Placeholders

Requires PlaceholderAPI. 80+ placeholders — all prefixed with %fpp_.

Server-Wide (16 placeholders)

| Placeholder | Description |
|-------------|-------------|
| %fpp_count% | Total bots (local + remote) |
| %fpp_local_count% | Bots on this server |
| %fpp_network_count% | Bots on other proxy servers |
| %fpp_max% | Global bot cap (∞ if unlimited) |
| %fpp_real% | Real players online |
| %fpp_total% / %fpp_online% | Total players (real + bots) on this server |
| %fpp_network_total% | Total players + bots across ALL backends (NETWORK mode) |
| %fpp_network_real% | Total real players across ALL backends (NETWORK mode) |
| %fpp_network_bots% | Total bots across ALL backends (NETWORK mode) |
| %fpp_frozen% | Frozen bot count |
| %fpp_names% | Comma-separated bot names (includes remote in NETWORK mode) |
| %fpp_network_names% | Remote bot names |
| %fpp_version% | Plugin version |
| %fpp_config_version% | Config version number |
| %fpp_uptime% | Plugin uptime (e.g. 4h 12m) |

Server Performance (2 placeholders)

| Placeholder | Description |
|-------------|-------------|
| %fpp_server_tps% | Server TPS |
| %fpp_server_uptime% | Server uptime |

Extensions (2 placeholders)

| Placeholder | Description |
|-------------|-------------|
| %fpp_extensions% | Number of loaded extensions |
| %fpp_extensions_names% | Comma-separated extension names |

Settings / Toggles (28 placeholders)

| Placeholder | Returns |
|-------------|---------|
| %fpp_chat% | on / off |
| %fpp_skin% | Skin mode |
| %fpp_body% | Always on |
| %fpp_pushable% / %fpp_damageable% / %fpp_tab% / %fpp_ping% | on / off |
| %fpp_max_health% | Max HP |
| %fpp_network% / %fpp_network_mode% | on / off (NETWORK mode) |
| %fpp_server_id% | Server ID |
| %fpp_persistence% | on / off |
| %fpp_spawn_cooldown% | Cooldown seconds |
| %fpp_chunk_loading% / %fpp_chunk_loading_radius% | on / off or radius value |
| %fpp_head_ai% / %fpp_swim_ai% | on / off |
| %fpp_auto_eat% / %fpp_auto_place_bed% / %fpp_auto_milk% | on / off |
| %fpp_prevent_bad_omen% / %fpp_fall_damage% / %fpp_respawn_on_death% | on / off |
| %fpp_hurt_sound% / %fpp_join_message% / %fpp_leave_message% / %fpp_death_message% | on / off |
| %fpp_peak_hours% / %fpp_swap% / %fpp_metrics% / %fpp_update_checker% | on / off |
| %fpp_badword_filter% / %fpp_database% | on / off |
| %fpp_database_mode% | Database mode |

Per-World

| Placeholder | Description |
|-------------|-------------|
| %fpp_count_<world>% | Bots in world |
| %fpp_real_<world>% | Real players in world |
| %fpp_total_<world>% | Total in world |

Player-Relative (13 placeholders)

| Placeholder | Description |
|-------------|-------------|
| %fpp_user_count% | Player's bot count |
| %fpp_user_max% | Player's bot limit (respects permission overrides) |
| %fpp_user_names% | Player's bot names |
| %fpp_user_ping% | First bot's ping |
| %fpp_user_ping_avg% | Average ping of player's bots |
| %fpp_user_frozen% | Number of player's frozen bots |
| %fpp_user_oldest% / %fpp_user_newest% | Name of oldest/newest bot |
| %fpp_user_uptime% / %fpp_user_total_uptime% | Combined uptime of player's bots |
| %fpp_user_total_damage% | Total damage taken by player's bots |
| %fpp_user_deaths% | Total deaths of player's bots |
| %fpp_user_count_<world>% | Player's bot count in specific world |

Per-Bot (22 placeholders)

| Placeholder | Description |
|-------------|-------------|
| %fpp_ping_<bot_name>% | Specific bot's ping |
| %fpp_health_<bot_name>% | Bot's current health |
| %fpp_health_max_<bot_name>% | Bot's max health |
| %fpp_world_<bot_name>% | Bot's current world |
| %fpp_loc_x_<bot_name>% / %fpp_loc_y_<bot_name>% / %fpp_loc_z_<bot_name>% | Bot's coordinates |
| %fpp_frozen_<bot_name>% / %fpp_sleeping_<bot_name>% | yes / no |
| %fpp_owner_<bot_name>% / %fpp_spawned_by_<bot_name>% | Who spawned the bot |
| %fpp_pve_<bot_name>% | yes / no |
| %fpp_displayname_<bot_name>% | Bot's display name |
| %fpp_uuid_<bot_name>% | Bot's UUID |
| %fpp_spawn_time_<bot_name>% | When bot was spawned (ISO format) |
| %fpp_task_<bot_name>% | Current active task (mining, moving, etc.) or idle |
| %fpp_following_<bot_name>% | Who the bot is following (if any) |
| %fpp_damage_<bot_name>% | Total damage taken by bot |
| %fpp_deaths_<bot_name>% | Bot's death count |
| %fpp_type_<bot_name>% | Bot's type (AFK, MINER, BUILDER, etc.) |
| %fpp_chat_<bot_name>% | yes / no (bot chat enabled) |
| %fpp_skin_<bot_name>% | Bot's skin name |

Ping

| Placeholder | Description |
|-------------|-------------|
| %fpp_ping_all% | Bot ping if sender is bot, else real player ping |
| %fpp_avg_ping% | Average across all local bots |
| %fpp_player_ping% | Sender's real ping |

🗂️ Configuration

Main file: plugins/FakePlayerPlugin/config.yml

Key sections:

• limits — max bots, user limits, spawn cooldowns
• persistence — save/restore bots on restart
• bot-name — name sources and formatting
• badword-filter — profanity filtering
• body — entity settings (pushable, damageable, item pickup)
• combat — health, fall damage, hurt sounds
• death — respawn behavior
• chunk-loading — keep chunks loaded around bots
• automation — auto-eat, auto-place-bed, auto-milk, bad-omen prevention
• head-ai — smooth head rotation
• swim-ai — automatic upward swimming
• collision — push radius, strength, separation
• database — SQLite / MySQL settings
• config-sync — cross-server config push/pull
• performance — position-sync distance tuning
• heartbeat — network liveness publishing
• attack-mob — default targeting range and priority
• logging.debug — per-subsystem debug flags
• metrics — FastStats usage statistics
• pathfinding — A* tuning (gap walking, block break/place, node limits, stuck thresholds)
• skin — mode, pool, overrides, mineskin integration
• ping — random fake ping (requires fpp-spoof.jar)

The plugin includes an automatic config migrator (current version: 73). Do not edit config-version manually.

📚 Documentation

• Wiki — Full documentation
• Commands — Command reference
• Permissions — Permission setup
• Configuration — Config tuning
• Extensions — Extension API guide
• Changelog — Version history

💬 Support

• Discord: Join our server
• Modrinth: Download updates
• GitHub Issues: Report bugs & request features
• GitHub Sponsors: Sponsor development
• Patreon: Support FPP

⚖️ License

MIT License. See LICENSE.

Made with ❤️ by Bill_Hub