Crate chunkedge 

❗ NOTE: This documentation is sourced from the main branch. Guides and general project documentation can be found in docs.

---

ChunkEdge

A Rust framework for building Minecraft: Java Edition servers.

Built on top of Bevy ECS, ChunkEdge is an effort to create a Minecraft-compatible server completely from scratch in Rust. You can think of ChunkEdge as a game engine for Minecraft servers similar to the Minestom project. It doesn’t do much by default, but by writing game logic yourself and leveraging Bevy’s powerful plugin system, 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.

[!WARNING]
ChunkEdge is still early in development with many features unimplemented or incomplete. Expect to encounter bugs, limitations, and breaking changes. At the moment, ChunkEdge is only compatible with Minecraft 1.21.5. The aim is to support the latest stable version of Minecraft. For now, you can use a proxy (for example ViaProxy combined with Velocity) to allow players on both older and newer clients to connect to your server.

Goals

ChunkEdge aims to be the following:

• Complete. Abstractions for the full breadth of the Minecraft protocol.
• Flexible. ChunkEdge can be easily extended from within user code. Direct access to the Minecraft protocol is provided.
• Modular. Pick and choose the components you need. Some crates can also be reused in projects that don’t use the full ChunkEdge framework.
• 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.
• Up-to-date. Tries to be up-to-date with the most recent stable version of Minecraft. Currently Minecraft 1.21.5 is supported. Support for multiple versions at once is not planned. However, you can use a proxy (for example ViaProxy combined with Velocity) to allow players on both older and newer clients to connect to your server.

Current Status

Here are some noteworthy achievements:

• chunkedge_nbt: A speedy new library for Minecraft’s Named Binary Tag (NBT) format.
• 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)

Getting Started

Creating a New Project

To create your own server project using ChunkEdge, please see the Getting Started guide.

Other usefull resources from the documentation include:

• Full API Documentation (rustdoc)
• General docs page with links to guides and the FAQ

Running the Examples

After cloning the repository, run this command to try an example.

cargo r -r --example parkour

List all available examples with:

cargo run --example

Recommended examples to try are parkour, game_of_life, terrain, and cow_sphere.

Open your Minecraft client and connect to the address localhost. If all goes well, you should be able to play the example.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md. You can use GitHub Discussions to discuss the project and ask questions.

License

The source code in this repository is licensed under the MIT License, except where otherwise noted.

The project name, logo, icons, and other branding assets are not licensed under the MIT License. They are reserved by the repository owner Job Paardekooper and may not be used in a way that suggests endorsement, affiliation, or official status without prior written permission.

History

This project is a fork of valence-rs/valence, combined with code from the then-open Minecraft protocol update PR / branch.

Star History

General Project Documentation

The guides, FAQ, and other pages are available in docs.

Re-exports

pub use bevy_log as log;

pub use chunkedge_advancement as advancement;

pub use chunkedge_anvil as anvil;

pub use chunkedge_boss_bar as boss_bar;

pub use chunkedge_command as command;

pub use chunkedge_command_macros as command_macros;

pub use chunkedge_equipment as equipment;

pub use chunkedge_inventory as inventory;

pub use chunkedge_network as network;

pub use chunkedge_player_list as player_list;

pub use chunkedge_scoreboard as scoreboard;

pub use chunkedge_weather as weather;

pub use chunkedge_world_border as world_border;

pub use chunkedge_item as item;

pub use chunkedge_lang as lang;

Modules

abilities

action

app

This crate is about everything concerning the highest-level, application layer of a Bevy app.

block

brand

client

client_command

client_settings

custom_payload

docs

General Project Documentation

ecs

Bevy ECS

entity

chunkedge_entity

event_loop

hand_swing

ident

chunkedge_ident

interact_block

interact_entity

interact_item

keepalive

layer

Defines chunk layers and entity layers. Chunk layers contain the chunks and dimension data of a world, while entity layers contain all the Minecraft entities.

math

chunkedge_math

message

movement

nbt

chunkedge_nbt

op_level

prelude

Contains the most frequently used items in ChunkEdge projects.

protocol

chunkedge_protocol

rand

Utilities for random number generation

registry

chunkedge_registry

resource_pack

spawn

Handles spawning and respawning the client.

status

status_effect

status_effects

teleport

testing

text

chunkedge_text

title

uuid

Generate and parse universally unique identifiers (UUIDs).

Macros

ident

Creates a new Ident at compile time from a string literal. A compile error is raised if the string is not a valid resource identifier.

Structs

BiomePos

BlockPos

Represents an absolute block position in world space.

BlockState

Represents the state of a block. This does not include block entity data such as the text on a sign, the design on a banner, or the content of a spawner.

ChunkLayer

A Component containing the chunks and dimension information of a Minecraft world.

ChunkPos

The X and Z position of a chunk.

ChunkView

Represents the set of all chunk positions that a client can see, defined by a center chunk position pos and view distance dist.

CompressionThreshold

How large a packet should be before it is compressed by the packet encoder.

DefaultPlugins

This plugin group will add all the default plugins for a ChunkEdge application.

Despawned

A marker Component for entities that should be despawned at the end of the tick.

EntityLayer

A Component containing Minecraft entities.

EventLoopPostUpdate

EventLoopPreUpdate

EventLoopUpdate

Ident

A wrapper around a string type S which guarantees the wrapped string is a valid resource identifier.

ItemStack

A stack of items in an inventory.

LayerBundle

Convenience Bundle for spawning a layer entity with both ChunkLayer and EntityLayer components.

Server

Contains global server state accessible as a Resource.

ServerPlugin

ServerSettings

Text

Represents formatted text in Minecraft’s JSON text format.

UniqueId

The universally unique identifier of an entity. Component wrapper for a Uuid.

Enums

Difficulty

Direction

GameMode

Hand

ItemKind

Represents an item from the game

Constants

DEFAULT_TPS

Minecraft’s standard ticks per second (TPS).

MINECRAFT_VERSION

The stringified name of the Minecraft version this library currently targets.

PROTOCOL_VERSION

The Minecraft protocol version this library currently targets.

Traits

Layer

Common functionality for layers. Notable implementors are ChunkLayer and EntityLayer.