mirror of
https://github.com/italicsjenga/valence.git
synced 2024-10-17 07:21:30 +11:00
cb9230ec34
This PR redesigns Valence's architecture around the Bevy Entity Component System framework (`bevy_ecs` and `bevy_app`). Along the way, a large number of changes and improvements have been made. - Valence is now a Bevy plugin. This allows Valence to integrate with the wider Bevy ecosystem. - The `Config` trait has been replaced with the plugin struct which is much easier to configure. Async callbacks are grouped into their own trait. - `World` has been renamed to `Instance` to avoid confusion with `bevy_ecs::world::World`. - Entities, clients, player list, and inventories are all just ECS components/resources. There is no need for us to have our own generational arena/slotmap/etc for each one. - Client events use Bevy's event system. Users can read events with the `EventReader` system parameter. This also means that events are dispatched at an earlier stage of the program where access to the full server is available. There is a special "event loop" stage which is used primarily to avoid the loss of ordering information between events. - Chunks have been completely overhauled to be simpler and faster. The distinction between loaded and unloaded chunks has been mostly eliminated. The per-section bitset that tracked changes has been removed, which should further reduce memory usage. More operations on chunks are available such as removal and cloning. - The full client's game profile is accessible rather than just the textures. - Replaced `vek` with `glam` for parity with Bevy. - Basic inventory support has been added. - Various small changes to `valence_protocol`. - New Examples - The terrain and anvil examples are now fully asynchronous and will not block the main tick loop while chunks are loading. # TODOs - [x] Implement and dispatch client events. - ~~[ ] Finish implementing the new entity/chunk update algorithm.~~ New approach ended up being slower. And also broken. - [x] [Update rust-mc-bot to 1.19.3](https://github.com/Eoghanmc22/rust-mc-bot/pull/3). - [x] Use rust-mc-bot to test for and fix any performance regressions. Revert to old entity/chunk update algorithm if the new one turns out to be slower for some reason. - [x] Make inventories an ECS component. - [x] Make player lists an ECS ~~component~~ resource. - [x] Expose all properties of the client's game profile. - [x] Update the examples. - [x] Update `valence_anvil`. - ~~[ ] Update `valence_spatial_index` to use `glam` instead of `vek`.~~ Maybe later - [x] Make entity events use a bitset. - [x] Update docs. Closes #69 Closes #179 Closes #53 --------- Co-authored-by: Carson McManus <dyc3@users.noreply.github.com> Co-authored-by: AviiNL <me@avii.nl> Co-authored-by: Danik Vitek <x3665107@gmail.com> Co-authored-by: Snowiiii <71594357+Snowiiii@users.noreply.github.com>
122 lines
5.3 KiB
Markdown
122 lines
5.3 KiB
Markdown
<p align="center">
|
|
<img src="assets/logo-full.svg" width="650" align="center">
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="https://github.com/valence-rs/valence/blob/main/LICENSE.txt">
|
|
<img src="https://img.shields.io/github/license/valence-rs/valence"
|
|
alt="license"></a>
|
|
<a href="https://crates.io/crates/valence">
|
|
<img src="https://img.shields.io/crates/d/valence?label=crates.io"></a>
|
|
<a href="https://discord.gg/8Fqqy9XrYb">
|
|
<img src="https://img.shields.io/discord/998132822239870997?logo=discord"
|
|
alt="chat on Discord"></a>
|
|
<a href="https://github.com/sponsors/rj00a">
|
|
<img src="https://img.shields.io/github/sponsors/rj00a"
|
|
alt="GitHub sponsors"></a>
|
|
</p>
|
|
|
|
A Rust framework for building Minecraft: Java Edition servers.
|
|
|
|
Built on top of [Bevy ECS](https://bevyengine.org/learn/book/getting-started/ecs/), Valence is an effort to create a
|
|
Minecraft compatible server completely from scratch in Rust. You can think of Valence as a _game engine for
|
|
Minecraft servers_. It doesn't do much by default, but by writing game logic yourself and leveraging Bevy's
|
|
powerful [plugin system](https://bevyengine.org/learn/book/getting-started/plugins/), you can make almost anything.
|
|
|
|
Opinionated features like dynamic scripting, dedicated executables, and vanilla game mechanics are all expected to be
|
|
built as optional plugins. This level of modularity is desirable for those looking to build highly custom experiences
|
|
in Minecraft such as minigame servers.
|
|
|
|
# Goals
|
|
|
|
Valence aims to be the following:
|
|
|
|
* **Complete**. Abstractions for the full breadth of the Minecraft protocol.
|
|
* **Flexible**. Valence provides direct access to the lowest levels of Minecraft's protocol when necessary.
|
|
* **Modular**. Pick and choose the features you actually need.
|
|
* **Intuitive**. An API that is easy to use and difficult to misuse. Extensive documentation and examples are important.
|
|
* **Efficient**. Optimal use of system resources with multiple CPU cores in mind. Valence uses very little memory and
|
|
can
|
|
support [thousands](https://cdn.discordapp.com/attachments/998132822864834613/1051100042519380028/2022-12-10_03.30.09.png)
|
|
of players at the same time without lag (assuming you have the bandwidth).
|
|
* **Up to date**. Targets the most recent stable version of Minecraft. Support for multiple versions at once is not
|
|
planned. However, you can use a proxy with [ViaBackwards](https://www.spigotmc.org/resources/viabackwards.27448/) to
|
|
achieve backwards compatibility with older clients.
|
|
|
|
## 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:
|
|
|
|
- `valence_nbt`: A speedy new library for Minecraft's Named Binary Tag (NBT) format.
|
|
- `valence_protocol`: A library for working with Minecraft's protocol. Does not depend on Valence and can be used in
|
|
other projects.
|
|
- Authentication, encryption, and compression
|
|
- Block states
|
|
- Chunks
|
|
- Entities and metadata
|
|
- Bounding volume hierarchy for fast spatial entity queries
|
|
- Player list and player skins
|
|
- Dimensions, biomes, and worlds
|
|
- JSON Text API
|
|
- 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.
|
|
- Inventories
|
|
- Items
|
|
- Particles
|
|
- Anvil file format (read only)
|
|
- Proxy support ([Velocity](https://velocitypowered.com/), [Bungeecord](https://www.spigotmc.org/wiki/bungeecord/)
|
|
and [Waterfall](https://docs.papermc.io/waterfall))
|
|
|
|
Here is a [short video](https://www.youtube.com/watch?v=6P072lKE01s) (outdated) showing the examples and some of
|
|
Valence's capabilities.
|
|
|
|
# Getting Started
|
|
|
|
## Running the Examples
|
|
|
|
After cloning the repository, run
|
|
|
|
```shell
|
|
cargo r -r --example
|
|
```
|
|
|
|
to view the list of examples. I recommend giving `parkour`, `conway`, `terrain`, and `cow_sphere` a try.
|
|
|
|
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, add Valence as a
|
|
[git dependency](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories)
|
|
|
|
```toml
|
|
[dependencies]
|
|
valence = { git = "https://github.com/valence-rs/valence" }
|
|
```
|
|
|
|
View the latest documentation by running `cargo d --open` in your project.
|
|
|
|
# Contributing
|
|
|
|
Contributions are welcome! Please
|
|
see [CONTRIBUTING.md](https://github.com/valence-rs/valence/blob/main/CONTRIBUTING.md). 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](https://github.com/sponsors/rj00a)
|
|
or [Patreon](https://www.patreon.com/rj00a).
|
|
|
|
I would love to continue working on Valence and your support would help me do that. Thanks!
|