valence/src/lib.rs

184 lines
5.7 KiB
Rust
Raw Normal View History

2022-07-15 16:18:20 +10:00
//! A Rust framework for building Minecraft servers.
2022-07-11 22:08:02 +10:00
//!
//! Valence is a Rust library which provides the necessary abstractions over
//! Minecraft's protocol to build servers. Very few assumptions about the
//! desired server are made, which allows for greater flexibility in its design.
//!
//! At a high level, a Valence [`Server`] is a collection of [`Clients`],
//! [`Entities`], and [`Worlds`]. When a client connects to the server, they are
//! added to the server's [`Clients`]. After connecting, clients are assigned to
//! a [`World`] where they are able to interact with the entities and
//! [`Chunks`] that are a part of it.
//!
//! The Valence documentation assumes some familiarity with Minecraft and its
//! mechanics. See the [Minecraft Wiki] for general information and [wiki.vg]
//! for protocol documentation.
//!
//! [Minecraft Wiki]: https://minecraft.fandom.com/wiki/Minecraft_Wiki
//! [wiki.vg]: https://wiki.vg/Main_Page
//!
//! # Logging
//!
//! Valence uses the [log] crate to report errors and other information. You may
//! want to use a logging implementation such as [env_logger] to see these
//! messages.
//!
//! [log]: https://docs.rs/log/latest/log/
//! [env_logger]: https://docs.rs/env_logger/latest/env_logger/
//!
//! # An Important Note on [`mem::swap`]
//!
//! In Valence, many types are owned by the library but given out as mutable
//! references for the user to modify. Examples of such types include [`World`],
//! [`Chunk`], [`Entity`], and [`Client`].
//!
//! **You must not call [`mem::swap`] on these references (or any other
//! function that would move their location in memory).** Doing so breaks
2022-07-15 16:18:20 +10:00
//! invariants within the library and the resulting behavior is safe but
//! unspecified. These types should be considered [pinned](std::pin).
2022-07-11 22:08:02 +10:00
//!
//! Preventing this illegal behavior using Rust's type system was considered too
//! cumbersome, so a note has been left here instead.
//!
//! [`mem::swap`]: std::mem::swap
//!
//! # Examples
//!
//! The following is a minimal server implementation. You should be able to
//! connect to the server at `localhost`.
//!
//! ```
//! use valence::config::Config;
//! use valence::server::{Server, ShutdownResult};
//!
//! pub fn main() -> ShutdownResult {
2022-07-16 13:40:39 +10:00
//! valence::start_server(Game, ())
2022-07-11 22:08:02 +10:00
//! }
//!
//! struct Game;
//!
//! impl Config for Game {
2022-07-28 12:21:11 +10:00
//! type ChunkState = ();
//! type ClientState = ();
//! type EntityState = ();
//! type ServerState = ();
//! type WorldState = ();
2022-07-16 13:40:39 +10:00
//!
2022-07-11 22:08:02 +10:00
//! fn max_connections(&self) -> usize {
//! 256
//! }
//!
2022-07-16 13:40:39 +10:00
//! fn update(&self, server: &mut Server<Self>) {
2022-07-11 22:08:02 +10:00
//! server.clients.retain(|_, client| {
//! if client.created_tick() == server.shared.current_tick() {
//! println!("{} joined!", client.username());
//! }
//!
//! if client.is_disconnected() {
//! println!("{} left!", client.username());
//! false
//! } else {
//! true
//! }
//! });
//! # server.shared.shutdown::<_, std::convert::Infallible>(Ok(()));
//! }
//! }
//! ```
//!
//! For more complete examples, see the [examples] in the source repository.
//!
//! [examples]: https://github.com/rj00a/valence/tree/main/examples
//!
//! # Feature Flags
//!
//! * `protocol`: Enables low-level access to the [`protocol`] module, which
//! could be used to build your own proxy or client. This feature is
//! considered experimental and is subject to change.
//!
//! [`Server`]: crate::server::Server
//! [`Clients`]: crate::client::Clients
//! [`Entities`]: crate::entity::Entities
//! [`Worlds`]: crate::world::Worlds
//! [`World`]: crate::world::World
//! [`Chunks`]: crate::chunk::Chunks
//! [`Chunk`]: crate::chunk::Chunk
//! [`Entity`]: crate::entity::Entity
//! [`Client`]: crate::client::Client
2022-04-15 07:55:45 +10:00
#![forbid(unsafe_code)]
2022-04-29 17:48:41 +10:00
#![warn(
trivial_casts,
trivial_numeric_casts,
unused_lifetimes,
2022-07-11 22:08:02 +10:00
unused_import_braces
2022-04-29 17:48:41 +10:00
)]
2022-07-15 16:18:20 +10:00
#![allow(
clippy::derive_partial_eq_without_eq,
clippy::unusual_byte_groupings,
clippy::comparison_chain
)]
2022-04-15 07:55:45 +10:00
/// Used on [`Config`](config::Config) to allow for async methods in traits.
///
/// For more information see the [async_trait] crate.
///
/// [async_trait]: https://docs.rs/async-trait/latest/async_trait/
pub use async_trait::async_trait;
#[doc(inline)]
pub use server::start_server;
#[doc(inline)]
pub use {nbt, uuid, vek};
2022-06-10 13:26:21 +10:00
pub mod biome;
2022-04-18 10:06:13 +10:00
pub mod block;
2022-04-15 07:55:45 +10:00
mod block_pos;
2022-06-13 19:34:03 +10:00
mod bvh;
2022-04-29 17:48:41 +10:00
pub mod chunk;
2022-06-28 10:52:23 +10:00
mod chunk_pos;
2022-04-29 17:48:41 +10:00
pub mod client;
2022-04-15 07:55:45 +10:00
pub mod config;
2022-06-10 13:26:21 +10:00
pub mod dimension;
2022-04-15 07:55:45 +10:00
pub mod entity;
2022-06-10 13:26:21 +10:00
pub mod ident;
2022-07-11 22:08:02 +10:00
pub mod player_list;
pub mod player_textures;
2022-07-11 22:08:02 +10:00
#[allow(dead_code)]
mod protocol_inner;
2022-04-29 17:48:41 +10:00
pub mod server;
mod slab;
mod slab_versioned;
2022-07-11 22:08:02 +10:00
pub mod spatial_index;
2022-04-15 07:55:45 +10:00
pub mod text;
pub mod util;
2022-04-29 17:48:41 +10:00
pub mod world;
2022-04-15 07:55:45 +10:00
2022-07-15 16:18:20 +10:00
/// Provides low-level access to the Minecraft protocol.
2022-07-11 22:08:02 +10:00
#[cfg(feature = "protocol")]
pub mod protocol {
pub use crate::protocol_inner::*;
}
/// The Minecraft protocol version this library currently targets.
pub const PROTOCOL_VERSION: i32 = 759;
2022-07-11 22:08:02 +10:00
/// The name of the Minecraft version this library currently targets, e.g.
/// "1.8.2"
pub const VERSION_NAME: &str = "1.19";
2022-04-15 07:55:45 +10:00
2022-07-11 22:08:02 +10:00
/// The namespace for this library used internally for
/// [identifiers](crate::ident::Ident).
///
/// You should avoid using this namespace in your own identifiers.
2022-07-18 14:29:44 +10:00
pub const LIBRARY_NAMESPACE: &str = "valence";
2022-04-15 07:55:45 +10:00
/// A discrete unit of time where 1 tick is the duration of a
/// single game update.
///
2022-07-18 14:29:44 +10:00
/// The duration of a game update on a Valence server depends on the current
/// configuration. In some contexts, "ticks" refer to the configured tick rate
/// while others refer to Minecraft's [standard TPS](STANDARD_TPS).
2022-04-15 07:55:45 +10:00
pub type Ticks = i64;
2022-07-18 14:29:44 +10:00
/// Minecraft's standard ticks per second (TPS).
pub const STANDARD_TPS: Ticks = 20;