> ## 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.

# Voxel Telephone Server Setup Quickstart Guide

> Step-by-step guide to get a Voxel Telephone game server running: install Node.js, MongoDB, and Spotvox, then configure and start the server.

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.

<Steps>
  <Step title="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](https://pnpm.io/installation).
    * **Spotvox** — a voxel renderer used to generate game previews. Download the `.jar` from [github.com/tommyettinger/spotvox](https://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](/server/dependencies) for details.

    <Note>
      See [Dependencies](/server/dependencies) for version notes and what each tool does in context.
    </Note>
  </Step>

  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/BunnyNabbit/voxel-telephone.git
    cd voxel-telephone
    ```
  </Step>

  <Step title="Install Node.js dependencies">
    <CodeGroup>
      ```bash pnpm theme={null}
      pnpm install
      ```
    </CodeGroup>

    pnpm reads `pnpm-workspace.yaml` and installs all workspace packages, including the website and renderer.
  </Step>

  <Step title="Create and edit config.json">
    Copy the example configuration and fill in values appropriate for your deployment:

    ```bash theme={null}
    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](/server/configuration) page for a full reference of every option.
  </Step>

  <Step title="Start the game server">
    ```bash theme={null}
    node voxelTelephone.mjs
    ```

    The server loads `config.json`, connects to MongoDB, preloads the hub level, and begins accepting connections on the configured port.

    <Tip>
      For development, Voxel Telephone supports hot-module reloading via [Dynohot](https://github.com/braidnetworks/dynohot). Run the server with Dynohot to reload changed modules (such as `levelCommands.mjs`) without restarting the process:

      ```bash theme={null}
      node --import dynohot voxelTelephone.mjs
      ```
    </Tip>
  </Step>

  <Step title="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.

    ```bash theme={null}
    node renderer/SpotvoxRenderer.mjs
    ```

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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.

    <Warning>
      Username verification (`verifyUsernames: true`) requires that connecting players have valid ClassiCube accounts. Disable this only in trusted private environments.
    </Warning>
  </Step>
</Steps>