Display System

The display system controls how server groups appear on signs and NPCs in your lobby. Each non-proxy group gets an auto-generated display config in the config/modules/display/ directory that you can customize.

Overview

• Display configs are stored as TOML files in config/modules/display/ (e.g., config/modules/display/BedWars.toml)
• Configs are auto-generated for new groups (proxy groups are excluded)
• Placeholders like {name}, {players}, and {state} are replaced at runtime
• State labels map internal states (e.g., READY) to display-friendly names (e.g., ONLINE)

Configuration File

Each display config has three sections: sign layout, NPC appearance, and state labels.

Complete Example

[display]
name = "BedWars"

[display.sign]
line1 = "&1&l★ BedWars ★"
line2 = "&8{players}/{max_players} online"
line3 = "&7{state}"
line4_online = "&2▶ Click to join!"
line4_offline = "&4✖ Offline"

[display.npc]
display_name = "&b&lBedWars"
subtitle = "&7{players}/{max_players} online &8| &7{state}"
subtitle_offline = "&c✖ Offline"
floating_item = "RED_BED"

[display.npc.status_items]
ONLINE = "LIME_WOOL"
STARTING = "YELLOW_WOOL"
INGAME = "ORANGE_WOOL"
WAITING = "LIGHT_BLUE_WOOL"
OFFLINE = "GRAY_WOOL"
FULL = "RED_WOOL"
ENDING = "ORANGE_WOOL"
STOPPING = "RED_WOOL"

[display.npc.inventory]
title = "&8» &b&lBedWars Servers"
size = 27
item_name = "&b{name}"
item_lore = ["&7Players: &f{players}/{max_players}", "&7State: &f{state}", "", "&aClick to join!"]

[display.states]
PREPARING = "STARTING"
STARTING = "STARTING"
READY = "ONLINE"
STOPPING = "STOPPING"
STOPPED = "OFFLINE"
CRASHED = "OFFLINE"
WAITING = "WAITING"
INGAME = "INGAME"
ENDING = "ENDING"

[display.sign]

Controls the four lines of a Minecraft sign.

[display.npc]

Controls NPC appearance in the lobby.

[display.npc.status_items]

Maps resolved state labels to Minecraft material names. The item is shown in the NPC's hand and reused as the per-server item in the selector inventory.

[display.npc.inventory]

The server-selector inventory opened when a player interacts with the NPC (INVENTORY action).

Auto-Detected Floating Items

When Nimbus generates a display config, it guesses a fitting floating_item based on the group name:

Placeholders

The following placeholders can be used in any sign or NPC text field:

[display.states]

Maps internal service states to display-friendly labels. You can customize these to match your network's branding.

Default State Labels

Custom States

Plugins on your backend servers can set custom states via the Nimbus SDK (e.g., WAITING, INGAME, ENDING). These are also resolved through the state label map:

You can add your own custom states:

[display.states]
READY = "ONLINE"
WAITING = "Waiting for players..."
INGAME = "In Progress"
ENDING = "Finishing Up"
RESTARTING = "Restarting Soon"
MAINTENANCE = "Under Maintenance"

Auto-Generation

When groups are loaded, Nimbus checks the config/modules/display/ directory and creates a default display config for any group that doesn't have one. Proxy groups (Velocity) are skipped since they don't appear on signs or NPCs.

The auto-generated config uses:

• The group name for all display text
• max_players from the group's resource config
• An auto-detected NPC item based on the group name
• Default state labels

To regenerate a display config, delete its file from config/modules/display/ and run the reload command.

API Endpoints

Display configs are accessible via the REST API. All endpoints require bearer token authentication.

Example Response

GET /api/displays/BedWars

{
  "name": "BedWars",
  "sign": {
    "line1": "&1&l★ BedWars ★",
    "line2": "&8{players}/16 online",
    "line3": "&7{state}",
    "line4Online": "&2▶ Click to join!",
    "line4Offline": "&4✖ Offline"
  },
  "npc": {
    "displayName": "&b&lBedWars",
    "item": "RED_BED",
    "subtitle": "&7{players}/16 online &8| &7{state}",
    "subtitleOffline": "&c✖ Offline"
  },
  "states": {
    "PREPARING": "STARTING",
    "STARTING": "STARTING",
    "READY": "ONLINE",
    "STOPPING": "STOPPING",
    "STOPPED": "OFFLINE",
    "CRASHED": "OFFLINE",
    "WAITING": "WAITING",
    "INGAME": "INGAME",
    "ENDING": "ENDING"
  }
}

Display Plugin

The nimbus-display plugin provides server-selector signs and NPCs on your lobby servers. It is auto-deployed along with FancyNpcs. The plugin:

1. Connects to the Nimbus API to fetch display configs and live service data
2. Updates signs and NPC holograms with current player counts and states
3. Handles player clicks to send them to the appropriate server group
4. Supports FancyNpcs-powered NPCs with player skins, entity types, equipment, floating items, look-at-player, poses, and a server selector inventory