Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Proxy Setup

So you're running a network with a Velocity or BungeeCord proxy and want HalosPlayerSpoofer (HPS) running across it? You're in the right place. This guide takes you through the whole thing step by step. No guesswork, no prior experience needed. By the end, your proxy and your backend servers will be working together as one.

Before You Start

Grab these things first, and the rest of the setup will be smooth sailing:

  • The HalosLoader .jar file (HPS installs through it, and it keeps the plugin up to date for you)

  • Your HPS license key. Don't have one yet? Join discord.gg/halosdev and open a ticket with your proof of purchase

  • Access to your proxy (Velocity or BungeeCord) and your backend servers (Spigot/Paper)

  • A MySQL database or a Redis server. Your proxy and servers use this to stay in sync, so it's a must-have

HPS needs to be installed on your proxy and on every backend server you want fake players on. You don't have to install it on all of your servers, just the ones you want spoofed. One license key covers your whole network. If you skip some servers, there's one small extra step later in Step 4, and we'll walk you through it.

Step 1 — Install HPS on Your Proxy (via HalosLoader)

Let's start at the top of your network. If you haven't already, follow the First Install guide on your proxy. In short:

  1. Drop HalosLoader.jar into your proxy's plugins folder.

  2. Start the proxy once so the loader generates its config, then open plugins/HalosLoader/config.yml.

  3. Find the HalosPlayerSpoofer entry, set it to enabled, and paste in your license key:

plugins:
- name: HalosPlayerSpoofer
  enabled: true
  license: XXXX-XXXX-XXXX
  version: STABLE

  1. Restart the proxy. The loader verifies your license, downloads the latest HPS build, and generates the plugin's config at plugins/HalosPlayerSpoofer/config.yml. Open that file up, we'll be working in here for the next step.

Step 2 — Connect Your Database (Proxy)

In the proxy's plugins/HalosPlayerSpoofer/config.yml, find the database section. This is how your proxy and servers talk to each other, so let's get it right.

Set type to either SQL or REDIS, then fill in your connection details:

On a network, type must not be left as NONE. Without a database, your proxy and servers have no way to sync, and nothing will work.

Option A — MySQL:

Option B — Redis:

Save the file and restart the proxy. If the console comes up clean with no database errors, you're ready for the next step.

Step 3 — Install HPS on Your Backend Servers

Now repeat this for each Spigot/Paper server you want fake players on. It only takes a couple of minutes per server:

  1. Install HPS through HalosLoader, exactly like you did on the proxy: drop HalosLoader.jar into the server's plugins folder, start the server once, enable HalosPlayerSpoofer and add your license key in plugins/HalosLoader/config.yml, then restart. (Full details in the First Install guide.)

  2. Open plugins/HalosPlayerSpoofer/config.yml.

  3. Scroll to the proxy section and set it up like this:

Here's what each part means:

  • proxy-mode sets this server up as part of a network. Flip it to true.

  • server-name is this server's unique ID. It must exactly match the name you gave this server in your proxy config (the [servers] section of velocity.toml, or the servers section of BungeeCord's config.yml).

  • database needs the exact same settings you used on the proxy in Step 2.

Every server needs its own unique server-name, and it has to match the proxy config exactly. If two servers share a name, or a name doesn't line up with the proxy, fake players won't sync. This is the single most common setup mistake, so double-check it!

  1. One more thing: check the account-fetcher setting. It must be the same value everywhere, on the proxy and all servers. The default (MINE_TOOLS) is fine for most networks.

  2. Save and restart the server. Then move on to the next one.

Step 4 — Restart and Verify

Almost there! Time to bring it all online:

  1. Restart your proxy and your backend servers one more time.

  2. On its first proper startup, the proxy looks at your network and automatically creates a settings file for every server it knows about in plugins/HalosPlayerSpoofer/servers/ (for example lobby1.yml, survival.yml). Yes, that includes servers you didn't install HPS on.

  3. Did you skip HPS on some servers? Then open the matching file in the servers/ folder for each one and set active: false and primary-server: false. This tells HPS to leave those servers alone. Also make sure they're not listed in fallback-server-ordering in the proxy's config.yml, so fake players are never sent there. Then run /spoof reload.

  4. Check the proxy console. HPS prints a handy summary at startup showing each server and whether fluctuation is ACTIVE on it, along with any day/time overrides. It's the quickest way to confirm everything is wired up correctly.

  5. Give it a moment, and you should see fake players start to appear.

This part matters: any server that does not have HPS installed must be disabled in its file in the servers/ folder (active: false and primary-server: false). If you leave it enabled, HPS will try to send fake players to a server that can't handle them, and you'll run into errors.

Seeing fake players on your network? That's it, your setup is done! 🎉 Read on to learn what everything in the config does and how to fine-tune the behavior.

The Proxy Config, Explained

Here's a plain-English tour of everything you'll find in the proxy's config.yml, so you know exactly what each setting does and whether you should touch it.

debug

Turns on extra logging in the console. Handy if you're troubleshooting or our support team asks you for logs. Otherwise, feel free to set it to false to keep your console quiet.

database

Your MySQL or Redis connection, covered in Step 2 above. This is the backbone of the network setup.

If you're an advanced user, you can also provide a full connection url instead of the host/port fields (for example jdbc:mysql://localhost:3306/spoofer or redis://localhost:6379). When a url is set, the host/port fields are ignored. If you're not sure whether you need this, you don't. 🙂

plugin-disguise

Lets you rename the HPS command to whatever you like. By default the command is /spoof, but you can change spoof-command to anything. Nice for keeping things low-key.

On a network, set the same command name on the proxy and every backend server, so everything responds to the same command.

account-fetcher

Where HPS gets the usernames and skins for its fake players. Your options:

  • MINE_TOOLS is the default and works great for most networks

  • PLAYER_DB is an alternative source if you have trouble with the default

  • OFFLINE is for offline-mode (cracked) networks

If your network runs in online mode, you can't use OFFLINE. If your network runs in offline mode, you can still use an online fetcher. You'll just be limited to real online-mode accounts.

Whatever you pick, it must be the same value everywhere: on the proxy and on every backend server.

account-fetcher-timeout

How long HPS waits when fetching account data before giving up. The default (2s) is fine for almost everyone. Only bump it up if you start seeing time-out errors about account fetching in your console.

enable-fluctuation

The master switch for fluctuation (the automatic joining and leaving of fake players). On a network, fluctuation runs from the proxy, so you'll want this set to true here.

Running more than one proxy? Enable fluctuation on only one of them, or they'll both be adding players and your counts will double up.

kick-fake-players-on-real-player-join

If a real player tries to log in with an account that a fake player happens to be using, this kicks the fake player so the real one gets in without an "already online" error. Keep it on. There's really no reason to turn it off.

fluctuation → account-provider

Where HPS gets its pool of accounts to pick fake players from:

  • NAMEMC (default) pulls a list of accounts from a NameMC URL. You can point the url at any NameMC server-likes page. A popular server's likes page gives you a big, realistic pool of names.

  • LOCAL uses your own list of accounts from an accounts.json file in the proxy's plugins/HalosPlayerSpoofer/ folder. Perfect if you want full control over exactly which names show up. The file is just a list of usernames or UUIDs:

When using LOCAL, make sure your list has plenty of accounts in it. If your list is smaller than the number of fake players you're asking for, HPS will run out of accounts to use.

fluctuation → fallback-server-ordering

Your safety net. If one of your servers shuts down, the fake players on it get moved to the first available server on this list, checked from top to bottom:

Put your lobbies at the top since they're always a safe place to land. HPS fills this in automatically on first startup, but feel free to reorder it.

Only list servers that actually have HPS installed. A fallback server without HPS can't receive fake players.

fluctuation → enable-account-blacklist

When a real player joins your network, HPS remembers their account and will never use it for a fake player again. This keeps things looking natural, so your regulars won't spot "themselves" online. Recommended to leave this on.

Fluctuation (Fake Player Behavior)

As of v3.0, fluctuation on a network is controlled entirely from the proxy. You no longer configure fluctuation on the backend servers. Everything lives in the proxy's servers/ folder.

Per-Server Settings

Each server on your network gets its own file in plugins/HalosPlayerSpoofer/servers/. HPS generates sensible defaults automatically based on each server's name (it recognizes lobbies, survival, creative, minigames, and so on), so things work well right out of the box. But tweaking these files is where you make the plugin truly yours.

The settings you'll care about most:

Setting
What it does

primary-server

Whether fake players can join the network through this server. Usually true for lobbies/hubs, false for gamemodes.

active

Turns fluctuation on or off for this server only. Set it to false (along with primary-server: false) on any server that doesn't have HPS installed.

min-fixed-fake-players / max-fixed-fake-players

The base number of fake players kept on this server.

min-real-multiplier / max-real-multiplier

Adds extra fake players based on your real player count (e.g. 1.5 means up to 1.5 fake players per real player). Your fake count grows naturally as your real count does.

max-total-fake-players

A hard cap on fake players for this server, no matter what the other settings add up to. If your counts feel stuck at a certain number, check this first.

min-real-players

How many real players need to be online before fluctuation kicks in. Set to -1 to always run.

min-lifespan / max-lifespan

How long each fake player sticks around on this server before leaving.

move-chance

The chance (0-100) that a leaving fake player hops to another server instead of logging off the network.

random-walk-chance

How often the player count drifts up or down. Higher means more joins and leaves, lower means a steadier count.

min-tick-interval / max-tick-interval

How often HPS re-evaluates the player count on this server. The defaults are fine for almost everyone.

override-options

Day and time based overrides, explained just below.

After editing any server file, run /spoof reload on the proxy (or restart it) to apply your changes.

Day and Time Overrides

Real networks are busier on weekends and evenings, and your fake counts should be too. That's what override-options is for. HPS even generates Saturday and Sunday boosts for you by default.

Each override picks a day, a time window, and a full set of options to use during that window:

A few things to know:

  • day is the day of the week in capital letters (MONDAY, TUESDAY, and so on).

  • start-hour and end-hour use 24-hour time and are both inclusive. 0 to 23 covers the full day.

  • The options block is a complete replacement, not a patch. Fill in every option, not just the ones you're changing.

  • Want quiet hours instead of a boost? Add an override with active: false for that window.

  • Don't want any overrides? Set the whole thing to nothing: override-options:

Overrides follow the clock and timezone of the machine your proxy runs on. If your host is in a different timezone than your players, shift your hours to match. If your weekend boost seems to fire at odd times, this is almost always why.

Adding, Renaming, or Removing Servers Later

This is the part that catches most people out, so give it a quick read.

HPS only auto-generates the servers/ files once, on the first startup when the folder is empty. It won't touch your files after that, so your tweaks are always safe. But that also means:

Adding a new server to your network? HPS won't create a file for it automatically. The proxy console will show yourserver -> Fluctuation DISABLED and no fake players will go there. To fix it, install HPS on the new server (see Step 3), then copy one of your existing files in plugins/HalosPlayerSpoofer/servers/, rename the copy to match the new server's name (in lowercase, e.g. skyblock.yml), adjust the settings, and run /spoof reload.

Renaming or removing a server? Rename or delete its matching file in the servers/ folder too. If a file points at a server your proxy no longer knows, HPS warns you about it in the console at startup.

Want HPS to regenerate everything from scratch? Stop the proxy, delete the entire servers/ folder, and start it again. Fresh files will be created for every server currently on your proxy. Just know this wipes any custom tweaks you made, including the files you disabled for servers without HPS, so remember to disable those again.

Handy Commands

A few commands you'll actually use day to day (all run from the proxy, and all need the /spoof permission):

Command
What it does

/spoof reload

Reloads the proxy's config and server files. Run this after editing anything.

/spoof reload backend

Tells all your backend servers to reload their configs too, without restarting them.

/spoof fluctuation status

Shows what fluctuation is currently doing on each server.

/spoof fluctuation suspend

Pauses fluctuation without touching your config. Great during maintenance.

/spoof fluctuation resume

Picks fluctuation back up after a suspend.

/spoof players list

Lists the fake players currently online.

Routing Styles

There are two common ways to route your fake players around the network. Pick whichever matches how real players move through yours.

Style 1 — Lobby Funnel (Recommended)

Fake players join a lobby first, then spread out to your gamemodes, exactly like real players do. This is the most natural-looking option.

  • Lobby servers: set primary-server: true, a short lifespan (e.g. 2s to 45s), and a high move-chance (e.g. 80). Players pass through quickly instead of piling up in the lobby.

  • Gamemode servers: set primary-server: false and a longer lifespan (e.g. 5m to 60m), so players settle in and actually "play."

Style 2 — Direct Joining

Fake players join your gamemodes directly, skipping the lobby entirely.

  • Set primary-server: true on each gamemode server you want fake players joining directly.

  • Set primary-server: false on the lobby (or leave it true if you'd like some lobby traffic too).

At least one server with HPS installed must have primary-server: true. If none do, fake players have no way to enter your network and nothing will join at all.

Troubleshooting

Something not working? Run through these. Nine times out of ten, it's one of the first two.

HPS didn't download or start at all

  • Head back to the First Install guide and double-check your HalosLoader config: enabled: true is set, and the license key has no typos or extra spaces.

  • Make sure the server has internet access so the loader can verify your license.

Fake players aren't showing up on my servers

  • Check that server-name on each backend server exactly matches the name in your proxy config.

  • Make sure every server has a unique server-name, no duplicates.

  • Confirm the proxy and all servers point to the same database, and that type isn't NONE.

  • Confirm account-fetcher is the same value on the proxy and all servers.

  • Check the proxy console at startup. The per-server summary tells you exactly which servers fluctuation is running on.

Fake players show up everywhere except one server

  • First things first: is HPS actually installed on that server? Fake players only appear on servers running the plugin.

  • If it's a server you added after the initial setup, it has no file in the servers/ folder yet. See Adding, Renaming, or Removing Servers Later.

  • Check that server's file for active: false or a min-real-players value higher than your current real player count.

  • If that server has its whitelist turned on, either add the accounts to the whitelist or set respect-whitelist: false in that server's HPS config. By default HPS respects your whitelist and won't force players past it.

I'm getting errors about a server I didn't install HPS on

  • Open that server's file in the servers/ folder on the proxy and set active: false and primary-server: false.

  • Remove it from fallback-server-ordering in the proxy's config.yml too, then run /spoof reload.

Fake players join but never move between servers

  • Check that move-chance is above 0 in the server files on the proxy.

  • Make sure at least one server has primary-server: true.

My player counts feel too low

  • Check max-total-fake-players in each server file. It's a hard cap that overrides everything else.

  • Remember the account blacklist: accounts that real players have used are never reused, so a small LOCAL account list can shrink over time. Add more accounts or use NAMEMC.

My weekend boost fires at the wrong time

  • Overrides use the clock and timezone of the machine the proxy runs on. Adjust start-hour and end-hour to match, or change your host machine's timezone.

Still stuck?

No worries. Join our Discord at discord.gg/halosdev and open a support ticket. We're happy to help you get it running!

PreviousSpigot Plugin Configurations
NextOffline Fake Player Accounts

Last updated