Voxel Telephone Server Configuration Reference

Complete reference for every option in config.json, grouped by purpose: server identity, database, gameplay, integrations, and more.

The server reads its configuration from config.json in the project root. Copy config-example.json to config.json and edit it before starting the server. The file must be valid JSON.

All keys are at the top level unless noted otherwise.

Server identity

Options that control how the server presents itself to players and to the ClassiCube network.

Key	Type	Description
serverName	string	The name displayed in the ClassiCube server list and shown to connecting players.
port	number	TCP port the server listens on. Defaults to 25565.
postToMainServer	boolean	When true, the server sends a heartbeat to the ClassiCube main server list so players can discover it publicly.
verifyUsernames	boolean	When true, the server verifies that connecting players are authenticated ClassiCube accounts. Set to false only in private or development environments.
maxIpConnections	number	Maximum simultaneous connections allowed from a single IP address.
texturePackUrl	string	URL to a custom texture pack served to connecting ClassiCube clients.
floorTextureUrl	string	URL to the texture used as the floor skin inside build levels.
taglines	array of strings	Localization string keys for the rotating taglines shown to players. Keys are resolved against the active language file.

{
  "serverName": "Voxel Telephone",
  "port": 25565,
  "postToMainServer": false,
  "verifyUsernames": true,
  "maxIpConnections": 3,
  "texturePackUrl": "https://bunnynabbit.com/classicube/palette-tex.png",
  "floorTextureUrl": "https://bunnynabbit.com/classicube/vt-floor.png",
  "taglines": [
    "announcements.taglines.0",
    "announcements.taglines.1"
  ]
}

Database

Options that control how the server connects to MongoDB.

Key	Type	Description
dbName	string	Name of the MongoDB database to use.
dbConnectionString	string	MongoDB connection URI. If omitted, the server defaults to mongodb://localhost:27017.

{
  "dbName": "voxeltelephone",
  "dbConnectionString": "mongodb://localhost:27017"
}

dbConnectionString is optional. Omitting it is equivalent to setting it to "mongodb://localhost:27017".

Hub level

Key	Type	Description
hubName	string	Filename (without extension) of the hub level loaded from the blockRecords directory. The hub is where players land when they log in or run out of available games.
hubEditors	array of strings	Usernames allowed to place and break blocks in the hub level. If the array is empty, any player can edit the hub. Add at least one placeholder entry to restrict editing to specific operators.

{
  "hubName": "hub",
  "hubEditors": [
    "YourUsername"
  ]
}

An empty hubEditors array grants hub editing permission to every connected player. Always list at least one trusted username unless you intentionally want an open hub.

Gameplay

Options that affect how the telephone game assigns turns to players.

Key	Type	Description
skipCompletedGames	boolean	When true, players are never assigned a turn in a game chain they have already completed (matched by root game ID).
skipCheckedCompletedTurns	number	When skipCompletedGames is false, this controls how many recent turns at the end of a game chain to inspect for prior player participation. Set to 1 to check only the current active turn; higher values check more history.
inspirationFeeds	array of strings	RSS or feed URLs shown to players when there are no available games for them to play. The server picks one at random and displays it as a suggestion.

{
  "skipCompletedGames": false,
  "skipCheckedCompletedTurns": 2,
  "inspirationFeeds": [
    "https://www.bing.com/images/feed",
    "https://mix.com/topic/for-you"
  ]
}

Staff and permissions

Key	Type	Description
moderators	array of strings	Usernames granted moderator permissions.
listOperators	array of strings	Usernames granted operator-level permissions in the server list context.

{
  "moderators": ["ModUsername"],
  "listOperators": ["OpUsername"]
}

Chat filter

Key	Type	Description
replacementMessages	array of strings	List of strings used as chat filter replacement messages. The default example contains a single "*" entry.

{
  "replacementMessages": ["*"]
}

Announcements

The server broadcasts periodic announcements to all connected players. Announcement messages are localization string keys resolved at runtime.

Key	Type	Description
announcements.interval	number	Time in milliseconds between announcement broadcasts. The example value 180000 equals three minutes.
announcements.categoryWeight	object	Map of category name to integer weight. Higher weights make a category more likely to be picked for each broadcast.
announcements.messages	object	Map of category name to an array of localization string keys. One key is chosen at random from the selected category.

{
  "announcements": {
    "interval": 180000,
    "categoryWeight": {
      "donation": 1,
      "openSource": 1,
      "buildingCommands": 8,
      "gameTips": 8,
      "safety": 1
    },
    "messages": {
      "donation": ["announcements.donation.0"],
      "buildingCommands": ["announcements.buildingCommands.0"]
    }
  }
}

Sounds

The sounds block enables an optional audio server that delivers sound effects to players through a ClassiCube extension (CEF).

Key	Type	Description
sounds.enabled	boolean	Set to true to start the sound server alongside the game server.
sounds.interfacePort	number	Port the sound server listens on internally.
sounds.audioPlayerBaseURL	string	Base URL used by clients to reach the audio player.

{
  "sounds": {
    "enabled": false,
    "interfacePort": 1333,
    "audioPlayerBaseURL": "http://127.0.0.1:1333/"
  }
}

The sounds feature requires a compatible ClassiCube extension on the client side. Most deployments leave this disabled.

Website

Key	Type	Description
website.baseURL	string	The public base URL of the companion website. Used when the server generates links for players (for example, links to finished games).

{
  "website": {
    "baseURL": "https://voxel-telephone.bunnynabbit.com/"
  }
}

Hatchday events

hatchday is an array of special event configurations. When the current date matches a hatchday entry, the server swaps in the event hub and announces a join message.

Key	Type	Description
month	number	Month number (1–12) when the event is active.
day	number	Day of the month when the event is active.
joinMessage	string	Message broadcast to players when they connect during the event. Supports ClassiCube color codes (e.g., &b for cyan).
hubName	string	Hub level file to use instead of the default hubName during the event.
hubTrack	string	Identifier for the music track played in the event hub.
userSignificance	string	Username associated with the event (for display purposes).

{
  "hatchday": [
    {
      "month": 12,
      "day": 1,
      "joinMessage": "&bHappy hatchday to BunnyNabbit!",
      "hubName": "hub-hatchday",
      "hubTrack": "hubTrackHatchday",
      "userSignificance": "BunnyNabbit"
    }
  ]
}

Integrations

integrations is an array of integration objects. Each object loads a class from class/integrations/ and registers it to receive push events from the server.

Key	Type	Description
class	string	Name of the integration class file (without .mjs). For example, "ServerAnnouncement" loads class/integrations/ServerAnnouncement.mjs.
interests	array of strings	Event types the integration subscribes to. Valid values include gameProgression, chatMessage, playerConnection, announcement, and startServer.
authData	object	Optional authentication data passed to the integration constructor (for example, API tokens).
language	string	Optional language code passed to the integration.

{
  "integrations": [
    {
      "class": "ServerAnnouncement",
      "interests": [
        "gameProgression",
        "chatMessage",
        "playerConnection"
      ]
    }
  ]
}