Voxel Telephone Server Configuration Reference

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"
      ]
    }
  ]
}

Installation

Integrations

Administration

Voxel Telephone Server Configuration Reference

Build docs developers (and LLMs) love

Installation

Integrations

Administration

Documentation Index

Build docs developers (and LLMs) love