Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/universeclouddev/Universe/llms.txt

Use this file to discover all available pages before exploring further.

Universe’s server plugins are placed in a game server’s plugins/ directory just like any other Bukkit plugin. On startup each plugin registers the server as an ONLINE instance with the Universe Master, begins a recurring heartbeat, and registers the /universe command set. On shutdown the plugin reports OFFLINE state before the process exits. Every flavor — Modern Paper, Legacy Spigot, and Folia — shares the same configuration file layout and command surface. The only differences are the platform APIs used internally and the chat formatting library (MiniMessage on modern platforms, legacy & codes on Spigot and BungeeCord).

​
What Server Plugins Do

When a server plugin loads it performs four actions:
  1. Resolves the Master URL from the system property, environment variable, config.yml, or the default http://localhost:6000 — in that order.
  2. Resolves the instance ID from universe.instance.id / UNIVERSE_INSTANCE_ID / instance-id in config.yml. Without an instance ID the plugin logs a warning and skips registration.
  3. Reports ONLINE state to the Master REST API at PUT /api/instances/{id}/state.
  4. Starts a heartbeat task on the configured interval (default 30 seconds) that sends current player count, max players, and TPS to the Master.
If no instance ID is configured the plugin will log No Universe instance ID configured and will not register with the Master. Universe typically injects UNIVERSE_INSTANCE_ID automatically when it starts the server process — manual configuration is only needed for servers you manage yourself.

​
Installation and Configuration

The minecraft-modern plugin targets Paper 1.21.11+ and uses the Incendo Cloud annotation parser for commands and MiniMessage for all chat output.
1

Build or download the JAR

./gradlew :minecraft:minecraft-modern:build
# Output: .built/minecraft-modern-<version>-all.jar
2

Place the JAR in plugins/

Copy minecraft-modern-<version>-all.jar into your Paper server’s plugins/ directory.
3

Configure the plugin

Start the server once to generate plugins/Universe/config.yml, then edit it:
# Universe Modern Plugin Configuration
# Instance ID and master URL can also be set via:
#   - System property: -Duniverse.instance.id=abc123 -Duniverse.master.url=http://localhost:6000
#   - Environment variable: UNIVERSE_INSTANCE_ID=abc123 UNIVERSE_MASTER_URL=http://localhost:6000

# Universe Master REST API URL
master-url: "http://localhost:6000"

# Instance ID (auto-detected from env/property if not set)
# instance-id: ""

# API Key for Bearer authentication (optional)
# api-key: ""

# Heartbeat interval in seconds
heartbeat-interval-seconds: 30
4

Restart the server

The plugin reports ONLINE state on startup and OFFLINE on shutdown automatically.

​
config.yml Reference

The following table describes every key in plugins/Universe/config.yml. All values can be overridden by the corresponding system property or environment variable listed alongside them.
KeyDefaultSystem PropertyEnv VarDescription
master-urlhttp://localhost:6000universe.master.urlUNIVERSE_MASTER_URLBase URL of the Universe Master REST API
instance-id(none)universe.instance.idUNIVERSE_INSTANCE_IDID of this server instance registered in Universe
api-key(none)universe.api.keyUNIVERSE_API_KEYOptional Bearer token for Master API authentication
heartbeat-interval-seconds30——How often (in seconds) to report player count and TPS

​
Heartbeat Reporting

Every interval the plugin sends a PUT /api/instances/{id}/state request to the Master containing:
  • Players — current online player count (server.onlinePlayers.size)
  • Max players — configured server max players
  • TPS — server ticks-per-second (reported in the /universe tps command and included in heartbeat data)
  • Last heartbeat — epoch milliseconds of the last successful report
The Master uses lastHeartbeat to detect stale instances. If a server crashes without a clean shutdown the Master will eventually mark it OFFLINE when the heartbeat stops arriving.

​
/universe Commands

All three server plugins register the same top-level /universe command. Each subcommand is available to operators by default.
SubcommandDescription
/universe infoDisplays the instance ID, Master URL, connection status, and current state
/universe playersShows the current player count and the configured maximum
/universe tpsReports the current server TPS (ticks per second)
The /universe info command is the fastest way to confirm that a server has successfully registered with the Master. A connected server shows the instance ID and ONLINE state; a misconfigured server shows not connected.

Build docs developers (and LLMs) love

Get started for freeTalk to us