Minecraft Server

A Minecraft 1.21.8 protocol server implementation written in Go.

⚠️ Note: This project is in very early development and is not a functional server. Currently only the initial handshake, login, and configuration phases are partially implemented. The Play state (actual gameplay) is not yet implemented.

Overview

This project implements a Minecraft server that handles the protocol handshake, login, and configuration phases. It can accept client connections and respond to Minecraft protocol requests, making it useful for testing and protocol development.

Prerequisites

• Go 1.25.1 or later
• Just (optional, for convenient command running)
• Node.js (optional, for testing with included client scripts)

Building

go build -o ./out/ .

Or using just:

just build

Running

Start the server listening on port 44444:

go run .

Or using just:

just run

Testing

Run all tests:

just test

For verbose output:

just test-v

The test suite covers:

• Protocol reading/writing (VarInt, strings, UUIDs, struct serialization)
• NBT (Named Binary Tag) format parsing
• Type utilities (MCString, VarInt, PrefixedArray)

Testing with Clients

Included are Node.js-based client scripts for testing the server:

just echo <PORT>              # Simple echo client
just echo-bot <PORT>          # Bot that connects and plays
just server                   # Start a reference server

Project Structure

• main.go - Server entry point and connection handling
• internal/protocol/ - Minecraft protocol I/O (reading/writing data types)
• internal/packet/ - Packet definitions for different protocol states
• internal/parsers/ - Protocol state management
• internal/response/ - Server response packet definitions
• internal/types/ - Minecraft data types (VarInt, MCString, Position, etc.)
• internal/nbt/ - NBT format support
• test/ - Testing utilities and client scripts

License

See LICENSE file for details.