FakePlayer-CE

FakePlayer CE (Community Edition)

English | 简体中文 | 繁體中文 | 日本語

FakePlayer CE is a community-maintained fork of FakePlayer: a server-side plugin inspired by Carpet-Mod that spawns fake players indistinguishable from real ones, rebuilt with Gradle multi-module architecture for single-jar compatibility from Minecraft 1.20.1 to 26.3.

⭐ If you like FakePlayer CE, please give it a star — it really helps the project grow.

⚠️ Community Edition Statement

• This repository is an independent community fork — not released, maintained or endorsed by the original author.
• Report all bugs and feature requests only to this repository, never upstream.

Quick Start

1. Install CommandAPI into plugins/
2. Put fakeplayer-fp.buildX.jar into plugins/
3. Start the server once, then rename config.tmpl.yml to config.yml
4. Run /fp spawn

Features

• Spawn fake players that appear fully real to the server — ideal for chunk loading
• Fully compatible with vanilla and plugin commands (teleport, ban, inventory editing, ...)
• Complete action control: movement, jumping, attacking, mining, with periodic automation
• Per-player personalized default configuration profiles
• Single jar, many versions: one jar covers 1.20.1 ~ 26.3, with NMS code isolated per version
• HTTP Admin API: query state, spawn / remove fake players and drive actions, rotation, inventory and commands remotely
• Login plugin compatibility: AuthMe / CatSeedLogin / LibreLogin need no configuration

Requirements

• Paper or Purpur server
• CommandAPI (any version except 10.0.0; MC 26.3 requires 12.1.0 or newer)

Download

FakePlayer CE ships as a single fakeplayer-fp.buildX.jar. Drop it into your server's plugins/ folder and restart (CommandAPI must be installed first).

• Stable: GitHub Releases (recommended)
• Hangar: hangar.papermc.io/EndlessPixel/FakePlayer-CE — download and update from the web panel
• Latest build: GitHub Actions → any successful run → Artifacts → fakeplayer-dist

Config File

On first launch only a template config.tmpl.yml is generated; rename it to config.yml to activate it. The template lets you preview new options when upgrading without overwriting existing settings. See the sample config.

AI Chat

/fp aichat lets fake players generate chat lines through an OpenAI-compatible endpoint. Fill in api and api-key (or the environment variable named by api-key-env) in plugins/FakePlayer-CE/ai-chat.yml, set enabled: true, then run /fp reload.

auto-reply is the recommended mode: the fake player answers only when a player says something worth answering (short, symbol-only and spam messages are filtered), paced by chance and cooldown-seconds. continuous talks on a timer, is off by default and needs allow-continuous: true. Persona, prompts, retained context and pacing live in system-prompt, turn-prompt, max-context, recent-chat-lines and interval-ticks.

Commands

HTTP Admin API

Optional lightweight HTTP API (disabled by default, no extra dependencies) for web panels and automation.

http-admin:
  enabled: true
  host: 127.0.0.1        # Prefer loopback or an internal address
  port: 3253
  token: ""              # Empty generates a random token at startup and prints it to the console
  allow-get: true        # false accepts POST only
  allowed-hosts: []      # Host / Origin allowlist; empty disables the check
  rate-limit:
    requests-per-minute: 120   # Per source IP
    auth-failures: 10          # Consecutive auth failures before lockout (0 disables)
    lockout-seconds: 60
  interface:
    list: true           # Every endpoint has a switch of the same name; disabled returns 403

• The token goes in the Authorization: Bearer <token> header only; ?token= is not supported.
• Parameters always travel in the query string; GET and POST are both accepted.

/action parameters:

Success returns {"status":"success"} (bulk endpoints add count); failures return {"status":"failure","msg":"..."} describing the problem. HTTP status: 401 bad token, 403 endpoint disabled or Host not allowed, 404 unknown path, 405 wrong method, 414 URI too long, 429 rate limited or locked out.

TOKEN="YOUR_TOKEN"; API="http://localhost:3253"

curl -H "Authorization: Bearer $TOKEN" "$API/list"
curl -H "Authorization: Bearer $TOKEN" "$API/spawn?name=klmgun"
curl -H "Authorization: Bearer $TOKEN" "$API/action?name=klmgun&action=attack&interval=10"
curl -G -H "Authorization: Bearer $TOKEN" "$API/cmd" --data-urlencode "name=klmgun" --data-urlencode "command=say hello"
curl -G -H "Authorization: Bearer $TOKEN" "$API/say" --data-urlencode "name=klmgun" --data-urlencode "message=hello world"

Security

Built in, no configuration needed: authentication before the endpoint switch, so 401/403 cannot be used to probe which endpoints are enabled; token redaction and control-character replacement in logs; per-IP rate limiting with lockout after repeated failures; optional allowed-hosts Host / Origin checks; Cache-Control: no-store on responses.

Still up to the administrator:

• The API has no TLS — use a long random token and expose it only on a trusted network or behind a reverse proxy.
• /cmd runs commands as the fake player, with that fake player's permissions; never OP a fake player.
• Prefer host: 127.0.0.1 and restrict access at the firewall.

Personal Configuration

Each player can save their own defaults; changes apply on the next spawn. Use /fp config list to view and /fp config set <key> <value> to change.

• replace_tools: GCA-style — broken non-Mending tools, and Mending tools worn below tool-replacement.remaining-durability-threshold (default 10), are swapped for an identical item from the inventory; enchantments are ignored.
• replenish: /fp drop and /fp dropstack refill the main hand; food and drink containers come back when they fit. /fp dropinv never refills.
• simulation_distance: chunk radius ticking around the fake player; set the default under default-features, override with /fp config set or /fp set.

Permissions

Placeholder Variables

Custom Translation

Built-in locales: en, zh, zh_tw, zh_hk, ja. Switch with i18n.locale in config.yml (then /fp reload).

Custom: drop message_<language>_<region>.properties (copy the template) into plugins/fakeplayer/message/, set i18n.locale to the matching suffix (e.g. en_us), and run /fp reload-translation. Files must be UTF-8 encoded.

Login plugin compatibility & chat events

With a login plugin installed, fake players would be kicked or frozen for not logging in. FakePlayer CE marks them as logged in on join, and /fp say triggers the chat events so formatter plugins work normally.

• Automatic: no configuration needed — each plugin is only used when it is installed.

Auto-login (two independent mechanisms)

The first never shows a login screen; the second runs commands as the fake player and works with plugins that have no API compatibility here:

auto-login:
  command:
    enabled: true
    register: "/reg %password% %password%"
    login: "/login %password%"
    change-password: "/changepassword %oldpassword% %newpassword% %newpassword%"
  random-password:
    charset: "abcdefghijklmnopqrstuvwxyz0123456789"   # empty disables generation
    length: 12

Both can be active at once; when the API exemption already works, the command templates are usually unnecessary.

Chat event compatibility (/fp say)

/fp say fully triggers AsyncPlayerChatEvent and AsyncChatEvent, so EssentialsX Chat, Vane and similar plugins can rewrite format and content; the message is broadcast unless the event is cancelled. Works the same on every supported version (1.20.1 ~ 26.3).

FAQ

Player disconnected: "PacketEvents 2.0 failed to inject"

Some plugins modify the fake player's network connection; set this in your config:

prevent-kicking: ALWAYS

Fake players are not attacked by mobs

Fake players spawn with invincible mode enabled. Run /fp config set invulnerable false to let them take damage; consider regeneration beacons or potions to keep them alive.

Fake players get kicked after a while

Usually a login plugin kicking players that never logged in. The three plugins above are handled automatically; if yours is not covered, fall back to command-template login:

auto-login:
  command:
    enabled: true
    register: "/reg %password% %password%"
    login: "/login %password%"

Use a strong password so AuthMe's security policy does not reject it.

Build

See BUILD.md. It applies to this project's Gradle multi-module workflow only, not to the upstream Maven build.