Servarium

Adds a customisable server list to Minecraft and enables you to configure every aspect of your servers.

Cover image

Features

[x] Configurable name, motd and player count with colour and formatting support (Markdown & QuickText)
[x] Custom server icon
[x] Modifiable ping icon and player count
[x] Custom text alignment and spacing options
[ ] In-game config editor
[ ] Using vanilla server motd, ping and/or player count instead of a forced one available as an option
[ ] Templated player count to enable formats such as "15 of 100" using actual player count data

Note: Unchecked features are not yet available but are planned for a later release.

Requirements

Servarium is a client-side mod and requires the following dependencies:

Minecraft: >=26.3
Fabric Loader: >=0.20.1
Fabric API: >=0.165.0+26.3
Fabric Language Kotlin: >=1.14.2+kotlin.2.4.21

Placeholder API is bundled directly into the mod and does not need to be installed separately.

Configuration Structure

The configuration file is written in YAML and is located at config/servarium/config.yml in your Minecraft directory. It has two top-level sections:

Key	Type	Default	Description
`settings`	Settings	see below	General mod settings.
`servers`	list of Server entries	`[]`	The servers shown in the custom server list.

Note: Some values are listed in the configuration but are not yet implemented. They are marked with "⚠️ Not yet implemented." below and should not be used for now.

Example

Example server

---
settings:
  list_header: "Servarium"
  button_label: "Servarium"
  button_placement: NEXT_TO_MULTIPLAYER

servers:
  - name: "Minecraft Server"
    address: "play.example.com"
    icon:
      type: DEFAULT
    motd: |-
      Example MOTD
      for the example server
    player_count:
      type: FORCED
      value: "12/100"
    ping_icon: LEVEL_5
    text_alignment: CENTER
    text_spacing: BALANCED

All options are optional. Any option you leave out falls back to its default value.

Settings

General options that control how the mod appears in the main menu.

Key	Type	Default	Description
`list_header`	string	`"Servarium"`	The text displayed at the top of the server list.
`button_label`	string	`"Servarium"`	The text displayed on the button that opens the server list.
`button_placement`	enum	`NEXT_TO_MULTIPLAYER`	Where the button is placed on the title screen.

`button_placement`

Value	Behavior
`NEXT_TO_MULTIPLAYER`	Adds the button next to the Multiplayer button. (default)
`REPLACE_MULTIPLAYER`	Replaces the Multiplayer button with the Servarium button.
`NEXT_TO_REALMS`	Adds the button next to the Realms button.
`REPLACE_REALMS`	Replaces the Realms button with the Servarium button.

Server entries

Each item in the servers list describes one server.

Key	Type	Default	Description
`name`	string	`"Minecraft Server"`	The name displayed for the server.
`address`	string	`""`	The address of the server (for example `play.example.com` or `play.example.com:25566`).
`icon`	Icon	see below	The icon shown for the server. See `icon`.
`motd`	string	`""`	The message of the day, up to 2 lines. See `motd`.
`player_count`	Player count	see below	Controls how the player count is displayed.
`ping_icon`	enum	`LEVEL_5`	Controls the connection/ping icon.
`text_alignment`	enum	`LEFT`	Alignment of the server text.
`text_spacing`	enum	`VANILLA`	Line spacing of the server text.

Icon

An object controlling how the server icon is rendered:

Key	Type	Default	Description
`type`	enum	`DEFAULT`	The icon source type.
`value`	string	omitted	The file name, atlas and sprite, username, or base64 string.

`type`

Value	Behavior	`value`
`NONE`	Draws no icon in the GUI.	Ignored
`DEFAULT`	Displays the default server icon. (default)	Ignored
`FILE`	Loads an image from the `icons/` directory.	Required
`ATLAS`	Renders a texture from a game atlas.	Required
`PLAYER`	Shows a player's face from their skin.	Required
`BASE64`	Renders a Base64-encoded image.	Required

Using a file

Place the file in config/servarium/icons/:

config/servarium/
├── config.yml
└── icons/
    └── my_server.png

Set value to the file's name:

icon:
  type: FILE
  value: "my_server.png"

Subfolders and other paths are not supported. The file must be placed directly in the icons folder.

Using an atlas texture

Specify the atlas and the sprite from it, separated by a space:

icon: 
  type: ATLAS
  value: "blocks block/bedrock"

Here blocks is the atlas and block/bedrock is the sprite from that atlas.

Using a player's face

icon: 
  type: PLAYER
  value: "TMShader"

Using base64

icon:
  type: BASE64
  value: "iVBORw0KGgoAAAANSUhEUg..."

Using the default image or hiding the icon

icon:
  type: DEFAULT

icon:
  type: NONE

Image size

A 64x64 image is recommended. Images of any other size are resized automatically.

`motd`

The message of the day can have a maximum of 2 lines. To configure both lines, write the text as a multi-line string using YAML's literal block style (|):

motd: |
  First line
  Second line

For a single line, a regular string is enough:

motd: "Welcome!"

Player count

An object with two properties:

Key	Type	Default	Description
`type`	enum	`FORCED`	How the player count is determined.
`value`	string	`""`	The text used by the `FORCED` type.

`type`

Value	Behavior	`value`
`NONE`	Hides the player count.	Ignored
`FORCED`	Always displays the text in `value` exactly as written. (default)	Required
`VANILLA`	⚠️ Not yet implemented.	Ignored
`TEMPLATED`	⚠️ Not yet implemented.	Required

Examples

# Hide the player count
player_count:
  type: NONE

# Always show a fixed text
player_count:
  type: FORCED
  value: "12/100"

`ping_icon`

Controls the icon shown on the right side of the server entry.

Value	Behavior
`NONE`	No ping icon is shown.
`VANILLA`	⚠️ Not yet implemented.
`LEVEL_1`	Always shows the ping level 1 icon
`LEVEL_2`	Always shows the ping level 2 icon
`LEVEL_3`	Always shows the ping level 3 icon
`LEVEL_4`	Always shows the ping level 4 icon
`LEVEL_5`	Always shows the ping level 5 icon (default)
`UNREACHABLE`	Always shows the "unreachable" icon

`text_alignment`

Value	Behavior
`LEFT`	Aligns the motd and server name to the left. (default)
`CENTER`	Centers the motd and server name.

`text_spacing`

Controls the vertical spacing between the server name and the MOTD lines. In vanilla, the gap between the server name and the first line of the MOTD is larger than the gap between the two MOTD lines. All other options apply equal spacing across all three lines.

Value	Behavior
`VANILLA`	Uses the vanilla spacing. (default)
`RELAXED`	Slightly larger spacing than `BALANCED`.
`BALANCED`	Equal spacing between all lines, closest to vanilla.
`COMPACT`	Tighter spacing.
`TIGHT`	The tightest spacing available.

Positioning the server name

When text_spacing is not VANILLA, the server text can be thought of as having three lines: name is line 1, and motd provides lines 2 and 3.

This lets you place the server name on line 2 (the first line of the motd), which centers it vertically. To do this, set name to an empty string and write the actual name as the first line of the motd:

servers:
  - name: ""
    motd: "My Server"
    text_spacing: BALANCED

Text Formatting & Placeholders

Servarium parses text using Placeholder API's built-in QuickText and Markdown formatters. Formatting tags and styles can be used in:

settings.list_header
settings.button_label
servers[].name
servers[].motd
servers[].player_count.value (when type is FORCED or TEMPLATED)

For the full list of tags, colours, gradients, and syntax rules, see the QuickText Documentation.

Quick reference

Key	Allowed values	Default
`settings.list_header`	Any string	`"Servarium"`
`settings.button_label`	Any string	`"Servarium"`
`settings.button_placement`	`NEXT_TO_MULTIPLAYER`, `REPLACE_MULTIPLAYER`, `NEXT_TO_REALMS`, `REPLACE_REALMS`	`NEXT_TO_MULTIPLAYER`
`servers[].name`	Any string	`"Minecraft Server"`
`servers[].address`	Any string	`""`
`servers[].icon.type`	`NONE`, `DEFAULT`, `FILE`, `ATLAS`, `PLAYER`, `BASE64`	`DEFAULT`
`servers[].icon.value`	File name, atlas and sprite, username, or base64 string	omitted
`servers[].motd`	Any string, up to 2 lines	`""`
`servers[].player_count.type`	`NONE`, `FORCED` (`VANILLA` and `TEMPLATED` are not yet implemented)	`FORCED`
`servers[].player_count.value`	Any string (required only for `FORCED` and `TEMPLATED`)	`""`
`servers[].ping_icon`	`NONE`, `LEVEL_1`, `LEVEL_2`, `LEVEL_3`, `LEVEL_4`, `LEVEL_5`, `UNREACHABLE` (`VANILLA` is not yet implemented)	`LEVEL_5`
`servers[].text_alignment`	`LEFT`, `CENTER`	`LEFT`
`servers[].text_spacing`	`VANILLA`, `RELAXED`, `BALANCED`, `COMPACT`, `TIGHT`	`VANILLA`

Servarium

Compatibility

Minecraft: Java Edition

Platforms

Supported environments

Links

Tags

Creators

Details

Servarium

Features

Requirements

Configuration Structure

Example

Settings

`button_placement`

Server entries

Icon

`type`

Using a file

Using an atlas texture

Using a player's face

Using base64

Using the default image or hiding the icon

Image size

`motd`

Player count

`type`

Examples

`ping_icon`

`text_alignment`

`text_spacing`

Positioning the server name

Text Formatting & Placeholders

Quick reference