Proxy Essentials

Supported software

Software	Plugin Support
Velocity	Yes
BungeeCord	Yes

Install the plugin

Install the proxy plugins

Download Proxy Essentials from GitHub and place it in the proxy template’s plugins/ folder. Standard SimpleCloud templates already include simplecloud-api; add it through the target’s Plugins setting or the CLI if you use a custom template.

Generate the configuration

Start a proxy once. Proxy Essentials creates its data directory in one of these locations:

Software	Directory
Velocity	`plugins/proxy-essentials-velocity/`
BungeeCord	`plugins/proxy-essentials-bungeecord/`

Keep the generated files in the template

For a group proxy, copy the generated plugin data directory from the running proxy back to the same path in its proxy template. Otherwise, changes made only in the temporary running directory disappear when that proxy stops.See Templates for how to move generated files into a template. Template changes apply the next time the proxy starts.

Apply and verify changes

Run /scproxy reload after editing files on a running proxy. If you edited its template instead, restart the proxy so it receives the changed files.

The proxy console should show Proxy Essentials starting without configuration or Cloud API errors.

/tab reload belongs to a different tablist plugin and does not reload Proxy Essentials. Use /scproxy reload on the proxy.

Generated files

File	Purpose
`config.yml`	Join states, domain MOTD routes, kick handling, player count, and tablist settings
`layout/*.yml`	Server list MOTD, icon, hover text, version, and slot layouts
`layout/server-icons/*`	Server list icons used by layouts
`placeholder.yml`	Ping color thresholds
`messages.yml`	Kick and command messages

Join states

A join state is a named access policy. The joinstates list in config.yml defines the available policies; the active state is stored on the selected SimpleCloud group or server instance. Join states can:

Require a permission to enter the proxy or a backend server
Require a separate permission to enter a full proxy network
Select a maintenance MOTD layout for the proxy
Apply to a complete group or one running server instance

Proxy groups and backend groups behave differently

Target	Effect
Proxy group	Controls entry to the network, checks the full-network permission, and can select a forced server list layout
Backend group, such as `Lobby`	Controls whether players may connect or switch to those backend server instances
One server instance, such as `Lobby-1`	Overrides access for only that running instance

Setting the Lobby group to maintenance does not change the public network MOTD. Set the proxy group to maintenance when you want to restrict the whole network and show its maintenance layout.

Define join states

config.yml

version: '2'

initial-state: public
initial-layout: public

joinstates:
  - name: public
    permission:
      join: ''
      full: 'simplecloud.proxy-essentials.join.full.public'
    forced-motd-layout: null

  - name: maintenance
    permission:
      join: 'simplecloud.proxy-essentials.join.maintenance'
      full: 'simplecloud.proxy-essentials.join.maintenance'
    forced-motd-layout: maintenance

Setting	Behavior
`name`	Name used in `/scproxy joinstate` commands
`permission.join`	Permission required to enter; an empty value allows everyone
`permission.full`	Permission required to enter when the proxy group has reached its player limit
`forced-motd-layout`	Fallback MOTD layout while this state is active on the proxy; `null` does not force one
`initial-state`	Fallback for groups or server instances without a stored state; changing it does not switch existing groups
`initial-layout`	Fallback MOTD layout when no stored or forced layout applies

Run /scproxy reload after adding or changing state definitions. Reloading a definition does not activate it.

Activate maintenance for the network

Assume the proxy group is named Proxy:

Configure the maintenance state

Set forced-motd-layout: maintenance on the state and make sure layout/maintenance.yml exists with motd.enabled: true.

Reload the files

Run /scproxy reload on the proxy.

Set the state on the proxy group

/scproxy joinstate set Proxy maintenance

The group command stores the state on the group and its currently running server instances. Instances without their own state fall back to the group state.

Verify the active state

/scproxy joinstate info Proxy

Players now need simplecloud.proxy-essentials.join.maintenance to enter. Refresh the Minecraft multiplayer list to see the maintenance MOTD.

Open the network again

/scproxy joinstate set Proxy public

To restrict only a backend group or one server instance, use for example:

/scproxy joinstate set Lobby maintenance
/scproxy joinstate set Lobby 1 maintenance

The first command changes the complete Lobby group and its running server instances. The second changes only Lobby-1.

MOTD layout priority

The proxy resolves its server list layout in this order:

A valid layout stored on the proxy instance or group by /scproxy layout set
The active join state’s forced-motd-layout
initial-layout

A layout stored with /scproxy layout set takes priority over forced-motd-layout. If maintenance activates but the MOTD stays public, check /scproxy layout info <proxy-group>. Either manage the layout explicitly with /scproxy layout set when changing states, or avoid pinning a layout when join states should switch it automatically. The whitelist block currently present in the generated config.yml is not evaluated by the join checks. Use permission.join for administrator or maintenance access.

Server list layouts

Each file in layout/ is one selectable server list layout. The file name is its layout name, so layout/maintenance.yml is referenced as maintenance.

layout/public.yml

config-version: '2'

motd:
  enabled: true
  update-type: RANDOM # RANDOM or QUEUE
  layouts:
    - name: public
      line1: '<color:#0ea5e9>A simplecloud.app network'
      line2: ' '

server-icon:
  enabled: true
  file: simplecloud.png

player-list:
  enabled: true
  player-list:
    - ''
    - 'simplecloud.app'
    - ''

version:
  name:
    enabled: false
    text: Example
  slots:
    enabled: true
    type: REAL # REAL, FAKE, or DYNAMIC
    fake-slots: 100
    dynamic-player-range: 5

RANDOM selects a random MOTD entry on each server list ping. QUEUE cycles through the configured entries. Place icon files in layout/server-icons/. Use /scproxy layout set <group> <layout> only when you want to pin a layout independently of join-state changes.

MOTD by domain

Show a different server list layout to players based on the hostname they connected with, for example when multiple domains point at the same proxy. Add routes to the domains list in config.yml:

config.yml

domains:
  - domain: play.example.com
    target: Lobby
    rules:
      - state: public
        layout: lobby-public
      - state: maintenance
        layout: lobby-maintenance

  - domain: citybuild.example.com
    target: Citybuild
    rules:
      - state: public
        layout: citybuild

Players connecting through play.example.com see the layout selected by the join state of the scalable Lobby group; players connecting through citybuild.example.com see the layout selected by the join state of the persistent Citybuild server.

Setting	Behavior
`domain`	Complete hostname a client must connect with, case-insensitive
`target`	Group or persistent server whose join state selects the layout for this domain
`rules`	List that maps a join state on `target` to a layout name in `layout/`

Exact matching: domain must be the complete hostname, such as play.example.com. Wildcards and subdomains, such as *.example.com, are not supported.
Target scope: target names a group or a persistent server, not a single server instance such as Lobby-1.
Layout resolution: for a matching domain, the proxy uses the rules entry whose state matches the current join state on target. If that rule’s layout does not exist, it falls back to that join state’s global forced-motd-layout, then to initial-layout.
Default target: a hostname without a matching domain, or a route where none of the above resolves, falls back to the standard MOTD layout priority described above.
Live updates: routes recompute automatically when target’s join state changes. Run /scproxy reload after adding or editing entries in domains so the new routes take effect.

This only changes the server list MOTD. To also send players who connect through a domain to a specific server, combine it with Server Connection’s subdomain routing.

Tablist

Tablist entries live in config.yml. Their name is matched against the backend server on which each player is currently connected. The first matching rule is used in this order:

Exact server name, case-insensitive
First configured prefix, such as Lobby for Lobby-1
*
global

config.yml

tablist:
  - name: Lobby
    layout:
      - header: '<green>Lobby'
        footer: '<gray>You are connected to <server_name>'
      - header: '<yellow>SimpleCloud'
        footer: '<gray><online_players> players online'
    update-time: 20

  - name: global
    layout:
      - header: '<color:#0ea5e9>SimpleCloud v3'
        footer: '<gray>Network'
    update-time: 20

Multiple layout entries under the same name rotate automatically. Currently, the lowest update-time from all tablist entries becomes one global interval for every entry. Use the same value for all entries and restart the proxy after changing it, because /scproxy reload does not recreate the scheduled task.

Player count

The displayed count includes all proxies in the current proxy group. You can add other groups and persistent servers.

config.yml

player-count:
  enabled: true
  additional-groups:
    - ExternalProxyGroup
  additional-persistent-servers:
    - EventProxy
  update-time: 20

The update interval is measured in ticks.

Backend kick handling

config.yml

show-kick-reason: false

false keeps the proxy’s normal fallback behavior after a backend kick.
true disconnects the player from the proxy with the backend’s kick reason instead of sending them to a fallback server.

Text formatting

Proxy Essentials uses MiniMessage for MOTDs, tablists, and messages. Use tags such as <red>, <color:#0ea5e9>, <bold>, and <br>. Legacy & and § color codes are not supported.

Commands

Command	Description
`/scproxy`	Show available Proxy Essentials commands
`/scproxy help`	Show command help
`/scproxy reload`	Reload `config.yml`, `placeholder.yml`, `messages.yml`, and all MOTD layouts
`/scproxy joinstate help`	Show join-state commands
`/scproxy joinstate info <group>`	Show the stored state for a group
`/scproxy joinstate info <group> <id>`	Show the effective state for one server instance
`/scproxy joinstate set <group> <joinstate>`	Set a state on a group and its running server instances
`/scproxy joinstate set <group> <id> <joinstate>`	Set a state on one server instance
`/scproxy layout help`	Show layout commands
`/scproxy layout info`	Show `initial-layout`
`/scproxy layout info <group>`	Show the layout stored or resolved for a group
`/scproxy layout set <group> <layout>`	Store a layout on a group and its running server instances

Placeholders

Placeholder	Context	Description
`<online_players>`	MOTD, tablist	Aggregated online player count
`<max_players>`	MOTD, tablist	Maximum player count from the selected slot mode
`<date:FORMAT>`	MOTD, tablist	Current date and time using a MiniMessage date pattern
`<env:NAME>`	MOTD, tablist	Environment variable value
`<env:NAME:default>`	MOTD, tablist	Environment variable value with a fallback
`<server_name>`	Tablist	Player’s current backend server
`<ping>`	Tablist	Player ping with the configured threshold color

Do not expose tokens, passwords, or other secrets through <env:NAME>. MOTDs are public, and tablist content is visible to connected players.

Configure <ping> colors in placeholder.yml:

placeholder.yml

pingColors:
  - ping: 0
    color: '<green>'
  - ping: 100
    color: '<gold>'
  - ping: 200
    color: '<dark_red>'

Permissions

Permission	Description
`simplecloud.proxy-essentials.command.help`	Use `/scproxy`, `/scproxy help`, and `/scproxy reload`
`simplecloud.proxy-essentials.command.joinstate.help`	View join-state help
`simplecloud.proxy-essentials.command.joinstate.info`	View join states
`simplecloud.proxy-essentials.command.joinstate.set`	Change join states
`simplecloud.proxy-essentials.command.layout.help`	View layout help
`simplecloud.proxy-essentials.command.layout.info`	View layout assignments
`simplecloud.proxy-essentials.command.layout.set`	Change a group’s MOTD layout
`simplecloud.proxy-essentials.join.maintenance`	Default permission to enter during maintenance
`simplecloud.proxy-essentials.join.full.public`	Default permission to enter a full public network

The last two permissions are defaults from config.yml; you can replace them with permissions from your own permission scheme.

Choose which features Proxy Essentials manages

Proxy Essentials does not have to manage every feature at once. For example, you can use its join states while another proxy plugin provides the MOTD or tablist. Configure one provider for each feature so plugins do not overwrite each other’s output.

Feature	How Proxy Essentials controls it
Join restrictions	Active Joinstate on each proxy or backend group
Server list response	`motd.enabled` in the selected `layout/*.yml` files
Tablist header and footer	The `tablist` list in `config.yml`
Aggregated player count	`player-count.enabled` in `config.yml`
Backend kick override	`show-kick-reason` in `config.yml`

Use another MOTD plugin

Set motd.enabled to false in every layout that the proxy can select:

layout/public.yml

motd:
  enabled: false

Repeat this setting in layouts such as maintenance.yml, then run /scproxy reload. Proxy Essentials now leaves the complete ping response unchanged, including its description, icon, hover list, displayed version, and slots. The replacement MOTD plugin must run on the proxy. A plugin installed only on a Lobby or another backend does not receive the network’s public server list ping.

Use another tablist plugin

Use an empty list in config.yml:

config.yml

tablist: []

Run /scproxy reload. Proxy Essentials then stops sending tablist headers and footers. Players may need to reconnect before content sent previously disappears or is replaced by the other plugin. update-time: 0 only disables scheduled tablist updates when the proxy starts; it does not reliably hand the feature to another plugin. Use tablist: [] instead.

Stop restricting joins

Join states have no global enabled setting. Set every affected proxy and backend group back to an unrestricted state such as public:

/scproxy joinstate set Proxy public
/scproxy joinstate set Lobby public

Make sure that state’s permission.join is empty:

config.yml

- name: public
  permission:
    join: ''
    full: 'simplecloud.proxy-essentials.join.full.public'
  forced-motd-layout: null

Stop aggregating player counts

config.yml

player-count:
  enabled: false
  additional-groups: []
  additional-persistent-servers: []
  update-time: 20

Run /scproxy reload. The local proxy count remains available, but Proxy Essentials no longer adds players from the rest of the proxy group or additional targets.

Keep standard fallback handling

config.yml

show-kick-reason: false

Run /scproxy reload. The proxy can then handle backend kicks with its normal fallback behavior.

Stop using Proxy Essentials

Remove the Proxy Essentials JAR from all matching proxy templates and restart the proxies. Keep simplecloud-api installed if another plugin depends on it.

Troubleshooting

The plugin or its configuration does not appear

Confirm that Proxy Essentials and simplecloud-api are in the proxy template, then restart a matching proxy. Check the proxy console and the platform-specific data directory listed under Install the plugin. Installing the JAR on a Lobby does not load the proxy plugin.

A reload command changes nothing

Use /scproxy reload, not /tab reload. Confirm that you edited the files belonging to the running proxy. Changes made only in a template require a proxy restart; changes made only in a temporary running group instance disappear when it stops.

Another plugin's tablist keeps being overwritten

Follow Use another tablist plugin above, then check for any other proxy or backend plugin that sends tablist headers and footers.

Maintenance is active, but the public MOTD does not change

Confirm that you changed the proxy group rather than only a backend group. Check that the state’s forced-motd-layout names an existing file with motd.enabled: true. Then check /scproxy layout info <proxy-group>: a layout stored with /scproxy layout set has higher priority than the join-state layout.

A domain always shows the default MOTD instead of its route

Confirm the DNS record for the domain points at this proxy and that the player connected with the exact hostname in domain; matching is case-insensitive but does not support wildcards or subdomains. Check that target is a group or persistent server name, not a single server instance. Confirm the current join state on target has a matching entry in rules, and that its layout names an existing file. Run /scproxy reload after editing domains.

The MOTD is still controlled by Proxy Essentials

Follow Use another MOTD plugin above and confirm that every selectable layout has been updated. A backend Lobby plugin cannot control the public proxy ping; use a compatible proxy MOTD plugin instead.

Colors appear as literal characters

Replace legacy & or § codes with MiniMessage tags such as <green> or <color:#22c55e>, then reload the configuration.

Proxy Essentials server list MOTD example

Introduction

Setup

Configuration

Plugins

Supported software

Install the plugin

Generated files

Join states

Proxy groups and backend groups behave differently

Define join states

Activate maintenance for the network

MOTD layout priority

Server list layouts

MOTD by domain

Tablist

Player count

Backend kick handling

Text formatting

Commands

Placeholders

Permissions

Choose which features Proxy Essentials manages

Use another MOTD plugin

Use another tablist plugin

Stop restricting joins

Stop aggregating player counts

Keep standard fallback handling

Stop using Proxy Essentials

Troubleshooting

​Supported software

​Install the plugin

​Generated files

​Join states

​Proxy groups and backend groups behave differently

​Define join states

​Activate maintenance for the network

​MOTD layout priority

​Server list layouts

​MOTD by domain

​Tablist

​Player count

​Backend kick handling

​Text formatting

​Commands

​Placeholders

​Permissions

​Choose which features Proxy Essentials manages

​Use another MOTD plugin

​Use another tablist plugin

​Stop restricting joins

​Stop aggregating player counts

​Keep standard fallback handling

​Stop using Proxy Essentials

​Troubleshooting

Supported software

Install the plugin

Generated files

Join states

Proxy groups and backend groups behave differently

Define join states

Activate maintenance for the network

MOTD layout priority

Server list layouts

MOTD by domain

Tablist

Player count

Backend kick handling

Text formatting

Commands

Placeholders

Permissions

Choose which features Proxy Essentials manages

Use another MOTD plugin

Use another tablist plugin

Stop restricting joins

Stop aggregating player counts

Keep standard fallback handling

Stop using Proxy Essentials

Troubleshooting