Rusty Bucket

A high-performance, modular Minecraft server implementation written in Rust.

Core Principles

• ECS-First Architecture: Game state is strictly separated from logic using a high-performance Entity Component System. This allows for seamless data queries and cache-friendly execution.
• Modularity by Design: The core engine is kept minimal. All features—from physics to chat—are implemented as modules that serve the broader plugin ecosystem.
• WASM Plugin System: Extensibility without compromise. Plugins are sandboxed for security, written in any language that targets WASM (Rust, Zig, C++, AssemblyScript), and cannot crash the main server.
• Parallel & Multi-threaded: Designed from the ground up to utilize modern multi-core processors. Systems run in parallel, and chunk processing is decoupled from the main tick loop.
• Hot-Reloadable Logic: Change game mechanics, update minigames, or fix bugs on the fly. WASM modules can be swapped at runtime without disconnecting players.
• 100% Vanilla Parity Goal: Through our dedicated vanilla-features plugin suite, we aim for bit-perfect replication of official Minecraft server behavior.

Architecture Overview

Rusty Bucket operates on a Host-Guest model:

1. The Host (Rust): Manages the ECS World, networking (Zero-copy), and the WASM runtime (Wasmtime). It handles the heavy lifting of IO and memory management.
2. The Guest (WASM Plugins): Contains the game logic. Plugins "subscribe" to ECS components and run logic in isolated sandboxes.
3. The Bridge: A high-speed memory interface that allows WASM plugins to read and write to the ECS state with minimal serialization overhead.

License

This project is "licensed" under the Unlicense.

Getting Started: The Core TCP Server

This project is set up with a basic asynchronous TCP server that listens for connections on the standard Minecraft port (25565). The server will accept incoming connections and echo back any data it receives.

Prerequisites

• Rust & Cargo
• netcat (pre-installed on most Linux/macOS systems)

Running the Server

1. Clone the repository (if you haven't already):

   git clone <repository-url>
   cd rusty-bucket
   

2. Run the server: Use Cargo to run the rb-server crate. By default, you will see INFO level logs.

   cargo run -p rb-server
   

   You should see output like: [... INFO rb_protocol] Server listening on 127.0.0.1:25565

Logging

The server uses env_logger, so you can control the log verbosity using the RUST_LOG environment variable.

For example, to see DEBUG level logs from all crates, you can run:

RUST_LOG=debug cargo run -p rb-server

To see TRACE logs only from rb-protocol, you would run:

RUST_LOG=rb_protocol=trace cargo run -p rb-server

Testing the Server

1. Open a new terminal window.

2. Connect to the server using netcat:

   nc localhost 25565
   

3. Send a message: Type any message (e.g., Hello, server!) and press Enter.

4. See the echo: The server will immediately send the same message back to your netcat session. You will see your message repeated on the next line.

5. Check the server logs: In the terminal where the server is running, you will see a message indicating a new connection: [... INFO rb_protocol] New connection from: 127.0.0.1:<some-port>

This confirms the core TCP server is up and running! From here, we can start implementing the Minecraft protocol handshake and packet handling.