PhantomPlayers

PhantomPlayers

PhantomPlayers is a configuration-driven fake-player population plugin for Paper and Folia. It provides packet-based virtual players, global TAB entries, simulated conversations, skin profiles, and configurable server-browser player counts.

Note: Fake players are virtual profiles, not genuine connected Minecraft clients. They do not count as real Bukkit players or trigger genuine player connection events.

Compatibility

Platform| Version| Status Paper| 1.21.11| Compile-verified Folia| 1.21.11| Compile-verified Paper| 26.3| Compile-verified; runtime unverified Folia| 26.3| Compile-verified; runtime unverified

• Minimum target: Minecraft 1.21.11.
• Java 21 bytecode; Minecraft 26.3 requires Java 25 at runtime.
• Client-visible behavior and Folia runtime compatibility have not been fully verified.

Installation

1. Download "PhantomPlayers-1.0.0.jar".
2. Place it in your server's "plugins/" directory.
3. Start the server.
4. Edit the generated configuration files.
5. Run "/fp spawnall".

The plugin starts with zero active fake players after a restart.

Commands

Command| Description| Permission "/fp spawn <name>"| Spawn one fake player| "phantomplayers.spawn" "/fp spawnall"| Spawn fake players up to the configured limit| "phantomplayers.spawn" "/fp despawn <name>"| Despawn one fake player| "phantomplayers.despawn" "/fp despawnall"| Despawn all active fake players| "phantomplayers.despawnall" "/fp list [page]"| View fake-player and population statistics| "phantomplayers.list" "/fp reload"| Reload configuration, names, and chat templates| "phantomplayers.reload"

"phantomplayers.admin" grants all listed permissions. Permissions default to operators.

Configuration Files

All files are located in "plugins/PhantomPlayers/".

File| Purpose "config.yml"| Population limits, spawning, TAB, ping, skins, server-list settings, compatibility "names.txt"| Username pool; one name per line "chat.yml"| Shared conversation templates and timing "players.yml"| Optional disabled identities and UUID overrides "cache/profiles.yml"| Persistent skin-profile cache

Important settings

In "config.yml":

• "population.max-active" — maximum active fake players; default "100".
• "population.spawn-batch-size" — players spawned per batch.
• "population.spawn-batch-delay-ticks" — delay between batches.
• "presentation.tab-list" — enable fake TAB entries.
• "presentation.entity-view-distance" — same-world entity visibility distance.
• "profiles.enabled" — enable username-based Mojang profile and skin lookups.
• "ping.enabled" — enable randomized fake-player ping values.
• "ping.minimum-ms" / "ping.maximum-ms" — ping range.
• "server-list.count-mode" — "active", "configured", or "disabled".
• "server-list.include-fake-count" — include fake players in the displayed online count.
• "server-list.include-fake-sample-names" — include fake names in the server-browser sample.

See the generated "config.yml" for all supported settings and defaults.

"names.txt"

The bundled file contains 600 fictional usernames. Add one username per line. Blank lines and lines beginning with "#" are ignored. Invalid and duplicate names are skipped with a warning.

"chat.yml"

Configure shared multi-line conversations using weighted templates and speaker placeholders:

• "{player1}", "{player2}", "{player3}", etc.
• "min-delay-seconds" / "max-delay-seconds"
• "conversation-cooldown-seconds"
• "max-concurrent-conversations"
• "max-lines-per-conversation"

Chat is broadcast globally to connected players in all worlds. Conversations pause when no real audience is online.

"players.yml"

Optional overrides:

disabled:

• SomeName

uuids: SomeName: 00000000-0000-0000-0000-000000000000

Disabled identities are excluded from "/fp spawnall". UUID overrides allow custom stable identities.

PlaceholderAPI

PlaceholderAPI is optional. If installed, PhantomPlayers automatically registers its expansion.

Placeholder| Description "%phantomplayers_fake_online%"| Active fake players "%phantomplayers_real_online%"| Real online players "%phantomplayers_total_online%"| Real + active fake players "%phantomplayers_fake_max%"| Configured maximum "%phantomplayers_configured%"| Enabled saved identities "%phantomplayers_spawned%"| Fully spawned fake players "%phantomplayers_unspawned%"| Configured identities not currently active

Example:

Online: %phantomplayers_total_online% Fake: %phantomplayers_fake_online%

Important Behavior

• Packet-only players: Fake players are not real connections and do not appear in "/list" or trigger genuine join/quit events.
• TAB visibility: Fake entries are sent globally; physical entity visibility is limited to nearby viewers in the same world.
• Join/quit messages: PhantomPlayers does not generate separate join/quit announcements. Existing server plugins cannot automatically treat virtual profiles as genuine connections.
• Skins: Username lookups use Mojang's public APIs when enabled. Results are cached; unavailable profiles use the configured fallback.
• Ping: Fake latency is cosmetic. Server-browser samples do not support per-player ping values.
• Server status: Fake counts and sample names are handled separately from the in-game TAB list.
• Restart behavior: Active fake players are not restored automatically. Run "/fp spawnall" after restarting.
• Folia: Runtime behavior has not been fully verified on all listed versions.

Network Access

When "profiles.enabled: true", PhantomPlayers contacts Mojang's public APIs to resolve usernames and skin profiles. Disable this setting to prevent those outbound requests.

Support and Compatibility

Report issues with the Minecraft version, server platform, relevant configuration, and error logs. See "DELIVERY.md" for detailed build verification and known limitations.