3 releases

0.1.2 Jun 24, 2024
0.1.1 Jun 11, 2024
0.1.0 Jun 2, 2024

#427 in Network programming

MIT license

150KB
3.5K SLoC

sandstone

Crates.io Docs.rs

sandstone is a Minecraft: Java Edition networking library. It is not a server implementation, but rather a library that can be used to create your own server-sided software. The ultimate goal is to use this library in a future implementation of a Minecraft: Java Edition server in Rust.

This project will be a continuous work in progress, and may see months of no activity.

This library is provided as a structured baseline and as an open source software solution for anyone looking to create specialized Minecraft: Java Edition servers. It is built with convenient optimizations and abstractions in mind.

The library currently has a fully custom packet serializer and deserializer, as well as a client connection handler.

Here is a current example of handling the server list status.

#[tokio::main]
async fn main() {
    SimpleLogger::new().init().unwrap();
	debug!("Starting server");

	let server = TcpListener::bind("127.0.0.1:25565").await.unwrap();

	loop {
		let (socket, _) = server.accept().await.unwrap();
		
		let mut client = CraftClient::from_connection(socket).unwrap();
		
		let mut response = StatusResponseSpec::new(ProtocolVerison::V1_20, "&a&lThis is a test description &b§kttt");
		response.set_player_info(1, 0, vec![PlayerSample::new_random("&6&lTest")]);
		
		let image = image::open("src/server-icon.png").unwrap();
		response.set_favicon_image(image);
		
		DefaultHandshakeHandler::handle_handshake(&mut client).await.unwrap();
		DefaultStatusHandler::handle_status(&mut client, StatusResponseBody::new(response), DefaultPingHandler).await.unwrap();
	}
}

Which produces this...
Image from Gyazo

More examples can be found in the examples/ folder.

TODO

The actual TODO list is massive, but here are the current priorities for the project.

  • Figure out what to do with packets and begin implementing a full version
    • Deserialize given standard info tests
    • How to handle optional fields ... See Packet::LoginPluginResponse
    • Implement Java's bitset for bit fields
    • Maybe implement an Identifier struct? - See minecraft api types
  • Utilities
    • Thread pool for new connections
    • Auto generate serialization/deserialization tests for all packets?
      • Macro
      • Default field trait? Derive?
  • Begin basic login procedure handler?
  • Compression support
  • Encryption support
  • Begin server structure
  • Documentation
    • Give explainer line for every file
    • Document all public functions
      • Better examples and documentation for packet reading
    • Copyright notices

Disclaimer

Please note that this project is under heavy development and functions might not be heavily optimized yet.
Please also note that encryption has not been rigorously tested for security, so please use online features with caution.

References

  • wiki.vg = The main resource for implementing new functions for the library. This wiki has extensive documentation on everything relating to the Minecraft protocol, both Bedrock and Java Edition. It also has a lot of articles relating to encryption, the Mojang protocol, and other hidden details about the game.

Some other projects were consulted for general design and handling for the minecraft protocol.

The following projects were significantly useful for understanding some quirks with the Minecraft protocol. It also guided me on early version of McSerializer and McDeserializer (instead of using serde).

Dependencies

~15–31MB
~413K SLoC