Simple Setup (Hub + Gateway)

Every network requires at least one server running in HUB mode for network logic and coordination, and a Redis server to enable cross-server communication.

Refer to the Redis Cloud Setup (Free) guide to set one up for free.

Let's begin with setting up the hub.

Important Hub Note

If the hub crashes, the network is effectively dead. If you expect high throughput on your network's landing server(s), use gateway servers as your landing and keep all player activity off the hub to reduce crash risk.

Step 1: Generate the Hub Config

Drop the plugin jar into the mods folder of an existing server.

On first launch, you will see an expected error while Network Manager loads, because it cannot connect to the default Redis host and port (127.0.0.1:6379).

Stop the server, then open:

mods/HeroTweaks_NetworkPlugin/network-manager-config.json

At the top, you will find Mode.

A plugin can launch in four modes:

HUB
GATEWAY
WORKER
GATEWAY_WORKER

By default, Mode is HUB, and since we are setting up the hub, leave this unchanged.

Step 2: Fill Redis Connection Fields

Set the following fields to your Redis server's host, port, and password:

network-manager-config.json (Redis excerpt)
{
  ...
  "Mode": "HUB",
  "Redis": {
    ...
    "Host": "your-redis-endpoint",
    "Port": 6379,
    "Password": "your-redis-password"
    ...
  }
  ...
}

Queue Behavior

Redis fields will be the same for all network servers.

Step 3: Set Server Identity

Additionally, set ServerName, ServerGroup, Server.Host, and Server.Port.

As a default, you can set ServerName to Hub-01 and ServerGroup to HUB (case-insensitive).

network-manager-config.json (Server excerpt)
{
  ...
  "Server": {
    ...
    "ServerName": "Hub-01",
    "ServerGroup": "HUB",
    "Host": "127.0.0.1",
    "Port": 5520
    ...
  }
  ...
}

The hub server is now set up.

Step 4: Prepare Your Second Server (Gateway)

To make this into a network, set up another server.

Repeat the same setup process for your second server: first launch (expected Redis connection error), stop the server, and edit its generated network-manager-config.json.

Required for Server #2

Set Mode to GATEWAY on the second server. If you leave it as HUB, your second server will not behave as a gateway destination.

Make sure to set the Redis fields in this config the same as the Hub server config.

network-manager-config.json (Second server excerpt)
{
  ...
  "Mode": "GATEWAY",
  "Server": {
    ...
    "ServerName": "Lobby-01",
    "ServerGroup": "LOBBY"
    ...
  }
  ...
}

Give it a unique ServerName and ServerGroup, for example Lobby-01 and LOBBY.

You can think of a gateway as a simple server node or destination. It does not come packaged with any special functionality, but simply identifies that server as a network connection point. Many network setups can rely solely on a HUB + GATEWAY setup without needing to rely on WORKER or GATEWAY_WORKER.

Step 5: Launch and Verify Redis Connectivity

Launch both servers.

At this point, both servers should connect to Redis successfully.

Test each server from its console:

netdebug ping

Confirm that a PONG response appears on each server.

Step 6: Bootstrap Staff Access on the Hub

Connect to the HUB server and run the following in the hub console:

op add <username>

You should see a burst of info logs as the network bootstraps the Admin role and assigns it to your player.

You should now have access to /netpanel, which opens the Staff Network Panel.

The Staff Network Panel provides deep access to your network, including:

Player Manager
Role Manager
Announcements
Configs
Permissions

Step 7: Learn the Core Routing Commands

Use these commands to connect players to destinations in your network:

/queuegroup <ServerGroup>
Find the best available destination in a server group.

/queue <ServerGroup>
Alias of /queuegroup.

/queueserver <ServerName>
Find the best available destination in a specified server.

/queueplayer <username> <ServerGroup>
Queue a specified player for a server group.

Queue Behavior

If all destinations are full, the player is entered into queue and is automatically sent when a slot opens. This behavior can be adjusted in the Queue section of config.

Step 8: Quick Live Test

Since we defined Lobby-01 as group LOBBY, run:

/queue LOBBY

This sends you to an available server in the LOBBY group, which in this setup is Lobby-01.

You now have a simple functioning network.

If your network does not need the advanced support of WORKER and GATEWAY_WORKER, you can build a complete network with only HUB and GATEWAY.

Step 9: Example Network Layout

Server	Group	Mode	Purpose
`Hub-01`	`HUB`	`HUB`	Central coordination and network logic
`Survival-01`	`SURVIVAL`	`GATEWAY`	Survival gameplay destination
`KitPVP-01`	`KITPVP`	`GATEWAY`	KitPVP shard
`KitPVP-02`	`KITPVP`	`GATEWAY`	KitPVP shard
`Skywars-01`	`SKYWARS`	`GATEWAY`	Skywars shard
`Skywars-02`	`SKYWARS`	`GATEWAY`	Skywars shard

Recommended Per-Group Settings

Most important fields to tune per group are:

Server.ForceLobbySpawnOnJoin
Server.AllowDirectJoin
Server.UseReservation
Server.MaxPlayers

Example profile for each group type:

HUB profile (coordination-first)
{
  "Mode": "HUB",
  "Server": {
    "ServerName": "Hub-01",
    "ServerGroup": "HUB",
    "AllowDirectJoin": false, // ignored for hub
    "ForceLobbySpawnOnJoin": true,
    "UseReservation": true,
    "MaxPlayers": 50
  }
}

SURVIVAL profile (persistent-world style gateway)
{
  "Mode": "GATEWAY",
  "Server": {
    "ServerName": "Survival-01",
    "ServerGroup": "SURVIVAL",
    "AllowDirectJoin": true,
    "ForceLobbySpawnOnJoin": false, // players join back where they last logged out
    "UseReservation": false,
    "MaxPlayers": 120
  }
}

KITPVP/SKYWARS profile (lobby-like gateway shards)
{
  "Mode": "GATEWAY",
  "Server": {
    "ServerName": "KitPVP-01",
    "ServerGroup": "KITPVP",
    "AllowDirectJoin": false, // force routing through hub to join minigames.
    "ForceLobbySpawnOnJoin": true,
    "UseReservation": true, // minigames may use reservation logic
    "MaxPlayers": 100
  }
}