A Rust framework for building Minecraft: Java Edition servers. Like [feather](https://github.com/feather-rs/feather), Valence is an effort to build a Minecraft compatible server completely from scratch in Rust. The difference is that Valence has decided to organize the effort a little differently. All game logic is behind a trait. This approach has many advantages. Features such as a plugin system, dedicated executable, and vanilla game mechanics can be implemented _on top of_ Valence. Valence is a Rust library like any other. In the future we may decide to reimplement vanilla game mechanics as a separate project. If you're developing something like a minigame server without need for vanilla game mechanics, you can depend on Valence directly. # Goals Valence aims to be the following: * **Complete**. Abstractions for the full breadth of the Minecraft protocol. * **Flexible**. Your use case should be achievable without manually sending and receiving packets or other hacks. * **Minimal**. The API surface is small with only the necessities exposed. Opinionated features such as a standalone executable, plugin system, and reimplementation of vanilla mechanics should be built in a separate crate on top of the foundation that Valence provides. * **Intuitive**. An API that is easy to use and difficult to misuse. Extensive documentation is important. * **Efficient**. Optimal use of system resources with multiple CPU cores in mind. * **Up to date**. Targets the most recent stable version of Minecraft. Support for multiple versions at once is not planned (although you can use a proxy). ## Current Status Valence is still early in development with many features unimplemented or incomplete. However, the foundations are in place. Here are some noteworthy achievements: - [x] A new serde library for Minecraft's Named Binary Tag (NBT) format - [x] Authentication, encryption, and compression - [x] Block states - [x] Chunks - [x] Entities and tracked data - [x] Bounding volume hierarchy for fast spatial entity queries - [x] Player list and player skins - [x] Dimensions, biomes, and worlds - [x] JSON Text API - [x] A Fabric mod for extracting data from the game into JSON files. These files are processed by a build script to generate Rust code for the project. The JSON files can be used in other projects as well. - [ ] Block entities - [ ] Inventory and items - [ ] Proxy support - [ ] Sounds, particles, etc. - [ ] Utilities for continuous collision detection Here is a [short video](https://www.youtube.com/watch?v=6P072lKE01s) showing the examples and some of its current capabilities. # Getting Started ## Running the Examples You may want to try running one of the examples. After cloning the repository, run ```shell cargo r -r --example conway ``` Next, open your Minecraft client and connect to the address `localhost`. If all goes well you should be playing on the server. ## Adding Valence as a Dependency Valence is published to [crates.io](https://crates.io/crates/valence). Run `cargo add valence` to add it to your project. Documentation is available [here](https://docs.rs/valence/latest/valence/). However, the crates.io version is likely outdated. To use the most recent development version, clone the repo and add Valence as a [path dependency](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-path-dependencies). ```toml [dependencies] valence = { path = "the/path/to/valence" } ``` View the documentation by running `cargo d --open`. # Contributing Contributions are welcome! Take a look at the [issue tracker](https://github.com/rj00a/valence/issues) to see what needs to be done. You can also join [the Discord](https://discord.gg/8Fqqy9XrYb) to discuss the project and ask questions. # License Code is licensed under [MIT](https://opensource.org/licenses/MIT) while the Valence logo is under [CC BY-NC-ND 4.0](https://creativecommons.org/licenses/by-nc-nd/4.0/) # Funding If you would like to contribute financially consider sponsoring me (rj00a) on GitHub (soon?) or [Patreon](https://www.patreon.com/rj00a). I would love to continue working on Valence and your support would help me do that. Thanks!