📓 Composition

Composition is a new Minecraft server written from the ground-up in Rust.

Composition is targeting Minecraft version 1.21.5, protocol version 770. The main goal is to get a working server, then optimize for speed (multi-threading/kubernetes/etc).

Composition is my personal project to learn more about networking, game development, Rust, Docker, and CI/CD pipelines. Composition is not currently intended for production use. I want to use it as a platform to experiment with ideas about how a Minecraft server could work, such as a tickless design, one that could run across a distributed kubernetes cluster, or a world as a database that's accessed by multiple servers.

🚀 Getting Started

• The only prerequisite for running Composition is to have Docker installed.

• Pull the latest version of the Docker image: docker pull git.garen.dev/garentyler/composition:latest

• Make sure a folder exists for the it to store its data. The uid/gid of the process inside the container is 25565:25565, so make sure the folder is writable by that user.

  To get the right file permissions, you can run the following:

  mkdir -p composition-server
  sudo chown -R 25565:25565 composition-server
  sudo chmod -R 775 composition-server

🕹️ Running Composition as a Server

Standalone command:

docker run -it -v .:/app/data --network host git.garen.dev/garentyler/composition server

Example docker-compose.yml file:

services:
  # Composition running as a server.
  composition-server:
    image: git.garen.dev/garentyler/composition:latest
    container_name: composition-server
    restart: unless-stopped
    ports:
      - "25565:25565"
    volumes:
      - ./composition-server:/app/data
    command: server

🌐 Running Composition as a Proxy

Standalone command:

docker run -it -v .:/app/data --network host git.garen.dev/garentyler/composition proxy

Example docker-compose.yml file:

services:
  # Example Minecraft server to run as a reference.
  reference:
    image: itzg/minecraft-server
    container_name: reference
    restart: unless-stopped
    ports:
      - "25565:25565"
    environment:
      EULA: "TRUE"
      VERSION: "1.21.1"
  # Composition running as a proxy.
  composition-proxy:
    image: git.garen.dev/garentyler/composition:latest
    container_name: composition-proxy
    restart: unless-stopped
    depends_on:
      reference:
        condition: service_healthy
        restart: true
    ports:
      - "25566:25566"
    volumes:
      - ./composition-proxy:/app/data
    command: proxy -U reference

🛠️ Building From Source

To build Composition from source, you will need to have Rust and Cargo installed. The stable toolchain is recommended, but the nightly toolchain may be required for some features.

cargo build --release

To build the Docker image, you will need to have Docker configured with Bake.

# To build both linux/amd64 and linux/arm64 images, use the following command:
docker buildx bake -f docker-bake.hcl

# To build only the linux/amd64 image, use the following command:
docker buildx bake -f docker-bake.hcl --set default.platform=linux/amd64

🏗️ Project Structure

Composition is built using the async runtime and networking from Tokio. On startup, Composition sets up logging, reads the configuration, and parses command line arguments. From there, it decides which mode to start in (server, proxy, world, etc). The subcommand performs any startup tasks, such as loading the world, and then begins the main event loop.

🦀 Cargo Features

Composition has a non-optional core and multiple cargo features that can be enabled or disabled to configure functionality.

The server feature enables the composition server command, which runs a standalone Minecraft server.

The proxy feature enables the composition proxy command, which runs a proxy server that forwards packets to another server.

The world feature is not yet implemented. When finished, it will host a world server that can be accessed by multiple server cores.

📋 Useful Resources

• wiki.vg archive (now merged with the Minecraft wiki)
• Protocol Specification
• Normal Login Sequence
• Server Ping
• Map Format