Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/BunnyNabbit/voxel-telephone/llms.txt

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

This guide walks you through setting up a Voxel Telephone game server from a fresh clone to a running instance. The server targets the ClassiCube client and requires a handful of external tools before you start.
1

Install prerequisites

Make sure all required software is available on your system before proceeding.Required:
  • Node.js v20+ — the server runtime. Verify with node --version.
  • MongoDB — stores all game data (turns, players, interactions). A local instance on the default port (27017) works out of the box.
  • pnpm — the package manager used by this project. Install it via npm install -g pnpm or follow the official pnpm install guide.
  • Spotvox — a voxel renderer used to generate game previews. Download the .jar from github.com/tommyettinger/spotvox and place it at the project root (same directory as voxelTelephone.mjs). Java must be available on your PATH.
Optional:
  • ImageMagick — used by the renderer to convert PNG previews to WebP. Without it the renderer falls back to PNG. See dependencies for details.
See Dependencies for version notes and what each tool does in context.
2

Clone the repository

git clone https://github.com/BunnyNabbit/voxel-telephone.git
cd voxel-telephone
3

Install Node.js dependencies

pnpm install
pnpm reads pnpm-workspace.yaml and installs all workspace packages, including the website and renderer.
4

Create and edit config.json

Copy the example configuration and fill in values appropriate for your deployment:
cp config-example.json config.json
At minimum, review and adjust:
  • serverName — the name shown in the ClassiCube server list and in-game.
  • port — defaults to 25565.
  • dbName — the MongoDB database name.
  • verifyUsernames — set to true to authenticate ClassiCube accounts.
  • postToMainServer — set to true to list on the public ClassiCube server list.
See the Configuration page for a full reference of every option.
5

Start the game server

node voxelTelephone.mjs
The server loads config.json, connects to MongoDB, preloads the hub level, and begins accepting connections on the configured port.
For development, Voxel Telephone supports hot-module reloading via Dynohot. Run the server with Dynohot to reload changed modules (such as levelCommands.mjs) without restarting the process:
node --import dynohot voxelTelephone.mjs
6

Start the renderer (optional)

The renderer processes queued render jobs — it converts saved voxel builds to PNG or WebP preview images using Spotvox. It runs independently from the game server and polls for new jobs every five seconds.
node renderer/SpotvoxRenderer.mjs
The Spotvox .jar must be present at the project root for the renderer to work. ImageMagick’s convert command must be on your PATH to produce WebP output; otherwise previews are saved as PNG.
7

Connect and list the server

Once the server is running, players can connect in two ways:
  • Directly — open ClassiCube, choose Direct connect, and enter your server’s address and port.
  • Server list — set postToMainServer to true in config.json to have the server heartbeat to the ClassiCube main server list automatically.
Username verification (verifyUsernames: true) requires that connecting players have valid ClassiCube accounts. Disable this only in trusted private environments.

Build docs developers (and LLMs) love

Get started for freeTalk to us