> For the complete documentation index, see [llms.txt](https://wiki.halosdev.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.halosdev.com/halos-player-spoofer/setup-guide/proxy-setup.md). # 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](https://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 {% hint style="info" %} 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. {% endhint %} *** ### 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](https://wiki.halosdev.com/halos-player-spoofer/setup-guide/first-install) 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: ```yaml plugins: - name: HalosPlayerSpoofer enabled: true license: XXXX-XXXX-XXXX version: STABLE ``` 4. 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: {% hint style="warning" %} 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. {% endhint %} **Option A — MySQL:** ```yaml database: type: SQL sql: host: localhost port: 3306 database: spoofer username: root password: yourpassword ``` **Option B — Redis:** ```yaml database: type: REDIS redis: host: localhost port: 6379 password: yourpassword ``` 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](https://wiki.halosdev.com/halos-player-spoofer/setup-guide/first-install).) 2. Open `plugins/HalosPlayerSpoofer/config.yml`. 3. Scroll to the `proxy` section and set it up like this: ```yaml proxy: proxy-mode: true server-name: lobby1 database: type: SQL sql: host: localhost port: 3306 database: spoofer username: root password: yourpassword ``` 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. {% hint style="warning" %} 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! {% endhint %} 4. 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. 5. 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. {% hint style="warning" %} 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. {% endhint %} {% hint style="success" %} 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. {% endhint %} *** ## 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. {% hint style="info" %} 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. 🙂 {% endhint %} #### `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. {% hint style="info" %} On a network, set the same command name on the proxy **and** every backend server, so everything responds to the same command. {% endhint %} #### `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. {% hint style="warning" %} Whatever you pick, it must be the **same value everywhere**: on the proxy and on every backend server. {% endhint %} #### `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. {% hint style="warning" %} 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. {% endhint %} #### `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: ```json [ "Notch", "7389929f-8656-4755-aa2a-eb92d2358097", "AnotherUsername" ] ``` {% hint style="info" %} 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. {% endhint %} #### `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: ```yaml fluctuation: fallback-server-ordering: - lobby1 - lobby2 ``` 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. {% hint style="warning" %} Only list servers that actually have HPS installed. A fallback server without HPS can't receive fake players. {% endhint %} #### `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) {% hint style="info" %} 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. {% endhint %} ### 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: ```yaml override-options: - day: SATURDAY start-hour: 18 end-hour: 23 options: active: true max-total-fake-players: 35 min-fixed-fake-players: 4 max-fixed-fake-players: 15 # ... and the rest of the options ``` 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:` {% hint style="warning" %} 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. {% endhint %} ### 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. {% hint style="info" %} 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. {% endhint %} ### 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). {% hint style="danger" %} 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. {% endhint %} *** ## 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](https://wiki.halosdev.com/halos-player-spoofer/setup-guide/first-install) 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](https://discord.gg/halosdev) and open a support ticket. We're happy to help you get it running!