diff options
| author | mat <git@matdoes.dev> | 2025-10-12 23:01:54 +0300 |
|---|---|---|
| committer | mat <git@matdoes.dev> | 2025-10-12 23:01:54 +0300 |
| commit | ee2575794e91b9457a74a95daf1dcc707058cd58 (patch) | |
| tree | df725850ef18ded5ce3f6552e17095d0f704ae84 | |
| parent | 1a1402954b07cd77615d0afc026c73b008787f51 (diff) | |
| download | azalea-drasl-ee2575794e91b9457a74a95daf1dcc707058cd58.tar.xz | |
upgrade deps and clean up lots of doc comments
78 files changed, 784 insertions, 627 deletions
@@ -898,9 +898,9 @@ dependencies = [ [[package]] name = "cc" -version = "1.2.40" +version = "1.2.41" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e1d05d92f4b1fd76aad469d46cdd858ca761576082cd37df81416691e50199fb" +checksum = "ac9fe6cdbb24b6ade63616c0a0688e45bb56732262c158df3c0c4bea4ca47cb7" dependencies = [ "find-msvc-tools", "shlex", @@ -1212,7 +1212,7 @@ checksum = "881c5d0a13b2f1498e2306e82cbada78390e152d4b1378fb28a84f4dcd0dc4f3" dependencies = [ "dispatch", "nix", - "windows-sys 0.61.1", + "windows-sys 0.61.2", ] [[package]] @@ -1390,9 +1390,9 @@ checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be" [[package]] name = "find-msvc-tools" -version = "0.1.3" +version = "0.1.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0399f9d26e5191ce32c498bebd31e7a3ceabc2745f0ac54af3f335126c3f24b3" +checksum = "52051878f80a721bb68ebfbc930e07b65ba72f2da88968ea5c06fd6ca3d3a127" [[package]] name = "fixedbitset" @@ -1408,9 +1408,9 @@ checksum = "1d674e81391d1e1ab681a28d99df07927c6d4aa5b027d7da16ba32d1d21ecd99" [[package]] name = "flate2" -version = "1.1.2" +version = "1.1.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4a3d7db9596fecd151c5f638c0ee5d5bd487b6e0ea232e5dc96d5250f6f94b1d" +checksum = "dc5a4e564e38c699f2880d3fda590bedc2e69f3f84cd48b457bd892ce61d0aa9" dependencies = [ "crc32fast", "libz-rs-sys", @@ -1594,12 +1594,13 @@ dependencies = [ [[package]] name = "half" -version = "2.6.0" +version = "2.7.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "459196ed295495a68f7d7fe1d84f6c4b7ff0e21fe3017b2f283c6fac3ad803c9" +checksum = "e54c115d4f30f52c67202f079c5f9d8b49db4691f460fdb0b4c2e838261b2ba5" dependencies = [ "cfg-if", "crunchy", + "zerocopy", ] [[package]] @@ -2023,9 +2024,9 @@ checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe" [[package]] name = "libc" -version = "0.2.176" +version = "0.2.177" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "58f929b4d672ea937a23a1ab494143d968337a5f47e56d0815df1e0890ddf174" +checksum = "2874a2af47a2325c2001a6e6fad9b16a53b802102b528163885171cf92b15976" [[package]] name = "libm" @@ -2107,6 +2108,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316" dependencies = [ "adler2", + "simd-adler32", ] [[package]] @@ -2164,11 +2166,11 @@ checksum = "610a5acd306ec67f907abe5567859a3c693fb9886eb1f012ab8f2a47bef3db51" [[package]] name = "nu-ansi-term" -version = "0.50.1" +version = "0.50.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d4a28e057d01f97e61255210fcff094d74ed0466038633e95017f5beb68e4399" +checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5" dependencies = [ - "windows-sys 0.52.0", + "windows-sys 0.61.2", ] [[package]] @@ -2629,9 +2631,9 @@ dependencies = [ [[package]] name = "regex" -version = "1.11.3" +version = "1.12.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8b5288124840bee7b386bc413c487869b360b2b4ec421ea56425128692f2a82c" +checksum = "4a52d8d02cacdb176ef4678de6c052efb4b3da14b78e4db683a4252762be5433" dependencies = [ "aho-corasick", "memchr", @@ -2641,9 +2643,9 @@ dependencies = [ [[package]] name = "regex-automata" -version = "0.4.11" +version = "0.4.12" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "833eb9ce86d40ef33cb1306d8accf7bc8ec2bfea4355cbdebb3df68b40925cad" +checksum = "722166aa0d7438abbaa4d5cc2c649dac844e8c56d82fb3d33e9c34b5cd268fc6" dependencies = [ "aho-corasick", "memchr", @@ -2652,9 +2654,9 @@ dependencies = [ [[package]] name = "regex-syntax" -version = "0.8.6" +version = "0.8.7" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "caf4aa5b0f434c91fe5c7f1ecb6a5ece2130b02ad2a590589dda5146df959001" +checksum = "c3160422bbd54dd5ecfdca71e5fd59b7b8fe2b1697ab2baf64f6d05dcc66d298" [[package]] name = "reqwest" @@ -2956,6 +2958,12 @@ dependencies = [ ] [[package]] +name = "simd-adler32" +version = "0.3.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d66dc143e6b11c1eddc06d5c423cfc97062865baf299914ab64caa38182078fe" + +[[package]] name = "simd_cesu8" version = "1.1.0" source = "registry+https://github.com/rust-lang/crates.io-index" @@ -2968,8 +2976,7 @@ dependencies = [ [[package]] name = "simdnbt" version = "0.8.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "247f969f6e48456ca7b7073832a4ab3d9ad10a90c0af13c3fed96be5c92e7971" +source = "git+https://github.com/azalea-rs/simdnbt#3473e8e1f4bfc7f9cd6409430a37d006ca7b723d" dependencies = [ "byteorder", "flate2", @@ -2982,8 +2989,7 @@ dependencies = [ [[package]] name = "simdnbt-derive" version = "0.8.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ec7721700b09b47f6b3f34a0c612899139469f6446b7e1902642186b84316455" +source = "git+https://github.com/azalea-rs/simdnbt#3473e8e1f4bfc7f9cd6409430a37d006ca7b723d" dependencies = [ "proc-macro2", "quote", @@ -3092,9 +3098,9 @@ dependencies = [ [[package]] name = "stable_deref_trait" -version = "1.2.0" +version = "1.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a8f112729512f8e442d81f95a8a7ddf2b7c6b8a1a6f509a95864142b30cab2d3" +checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596" [[package]] name = "static_assertions" @@ -3285,18 +3291,18 @@ dependencies = [ [[package]] name = "toml_datetime" -version = "0.7.2" +version = "0.7.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "32f1085dec27c2b6632b04c80b3bb1b4300d6495d1e129693bdda7d91e72eec1" +checksum = "f2cdb639ebbc97961c51720f858597f7f24c4fc295327923af55b74c3c724533" dependencies = [ "serde_core", ] [[package]] name = "toml_edit" -version = "0.23.6" +version = "0.23.7" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f3effe7c0e86fdff4f69cdd2ccc1b96f933e24811c5441d44904e8683e27184b" +checksum = "6485ef6d0d9b5d0ec17244ff7eb05310113c3f316f2d14200d4de56b3cb98f8d" dependencies = [ "indexmap", "toml_datetime", @@ -3306,9 +3312,9 @@ dependencies = [ [[package]] name = "toml_parser" -version = "1.0.3" +version = "1.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4cf893c33be71572e0e9aa6dd15e6677937abd686b066eac3f8cd3531688a627" +checksum = "c0cbe268d35bdb4bb5a56a2de88d0ad0eb70af5384a99d648cd4b3d04039800e" dependencies = [ "winnow", ] @@ -3675,9 +3681,9 @@ dependencies = [ [[package]] name = "webpki-roots" -version = "1.0.2" +version = "1.0.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7e8983c3ab33d6fb807cfcdad2491c4ea8cbc8ed839181c7dfd9c67c83e261b2" +checksum = "32b130c0d2d49f8b6889abc456e795e82525204f27c42cf767cf0d7734e089b8" dependencies = [ "rustls-pki-types", ] @@ -3699,9 +3705,9 @@ dependencies = [ [[package]] name = "widestring" -version = "1.2.0" +version = "1.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "dd7cf3379ca1aac9eea11fba24fd7e315d621f8dfe35c8d7d2be8b793726e07d" +checksum = "72069c3113ab32ab29e5584db3c6ec55d416895e60715417b5b883a357c3e471" [[package]] name = "winapi-util" @@ -3709,14 +3715,14 @@ version = "0.1.11" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22" dependencies = [ - "windows-sys 0.48.0", + "windows-sys 0.61.2", ] [[package]] name = "windows-link" -version = "0.2.0" +version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "45e46c0661abb7180e7b9c281db115305d49ca1709ab8242adf09666d2173c65" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" [[package]] name = "windows-sys" @@ -3751,14 +3757,14 @@ version = "0.60.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f2f500e4d28234f72040990ec9d39e3a6b950f9f22d3dba18416c35882612bcb" dependencies = [ - "windows-targets 0.53.4", + "windows-targets 0.53.5", ] [[package]] name = "windows-sys" -version = "0.61.1" +version = "0.61.2" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6f109e41dd4a3c848907eb83d5a42ea98b3769495597450cf6d153507b166f0f" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" dependencies = [ "windows-link", ] @@ -3796,19 +3802,19 @@ dependencies = [ [[package]] name = "windows-targets" -version = "0.53.4" +version = "0.53.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2d42b7b7f66d2a06854650af09cfdf8713e427a439c97ad65a6375318033ac4b" +checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3" dependencies = [ "windows-link", - "windows_aarch64_gnullvm 0.53.0", - "windows_aarch64_msvc 0.53.0", - "windows_i686_gnu 0.53.0", - "windows_i686_gnullvm 0.53.0", - "windows_i686_msvc 0.53.0", - "windows_x86_64_gnu 0.53.0", - "windows_x86_64_gnullvm 0.53.0", - "windows_x86_64_msvc 0.53.0", + "windows_aarch64_gnullvm 0.53.1", + "windows_aarch64_msvc 0.53.1", + "windows_i686_gnu 0.53.1", + "windows_i686_gnullvm 0.53.1", + "windows_i686_msvc 0.53.1", + "windows_x86_64_gnu 0.53.1", + "windows_x86_64_gnullvm 0.53.1", + "windows_x86_64_msvc 0.53.1", ] [[package]] @@ -3825,9 +3831,9 @@ checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" [[package]] name = "windows_aarch64_gnullvm" -version = "0.53.0" +version = "0.53.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "86b8d5f90ddd19cb4a147a5fa63ca848db3df085e25fee3cc10b39b6eebae764" +checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53" [[package]] name = "windows_aarch64_msvc" @@ -3843,9 +3849,9 @@ checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" [[package]] name = "windows_aarch64_msvc" -version = "0.53.0" +version = "0.53.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c7651a1f62a11b8cbd5e0d42526e55f2c99886c77e007179efff86c2b137e66c" +checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006" [[package]] name = "windows_i686_gnu" @@ -3861,9 +3867,9 @@ checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" [[package]] name = "windows_i686_gnu" -version = "0.53.0" +version = "0.53.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c1dc67659d35f387f5f6c479dc4e28f1d4bb90ddd1a5d3da2e5d97b42d6272c3" +checksum = "960e6da069d81e09becb0ca57a65220ddff016ff2d6af6a223cf372a506593a3" [[package]] name = "windows_i686_gnullvm" @@ -3873,9 +3879,9 @@ checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" [[package]] name = "windows_i686_gnullvm" -version = "0.53.0" +version = "0.53.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9ce6ccbdedbf6d6354471319e781c0dfef054c81fbc7cf83f338a4296c0cae11" +checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c" [[package]] name = "windows_i686_msvc" @@ -3891,9 +3897,9 @@ checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" [[package]] name = "windows_i686_msvc" -version = "0.53.0" +version = "0.53.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "581fee95406bb13382d2f65cd4a908ca7b1e4c2f1917f143ba16efe98a589b5d" +checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2" [[package]] name = "windows_x86_64_gnu" @@ -3909,9 +3915,9 @@ checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" [[package]] name = "windows_x86_64_gnu" -version = "0.53.0" +version = "0.53.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "2e55b5ac9ea33f2fc1716d1742db15574fd6fc8dadc51caab1c16a3d3b4190ba" +checksum = "9c3842cdd74a865a8066ab39c8a7a473c0778a3f29370b5fd6b4b9aa7df4a499" [[package]] name = "windows_x86_64_gnullvm" @@ -3927,9 +3933,9 @@ checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" [[package]] name = "windows_x86_64_gnullvm" -version = "0.53.0" +version = "0.53.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0a6e035dd0599267ce1ee132e51c27dd29437f63325753051e71dd9e42406c57" +checksum = "0ffa179e2d07eee8ad8f57493436566c7cc30ac536a3379fdf008f47f6bb7ae1" [[package]] name = "windows_x86_64_msvc" @@ -3945,9 +3951,9 @@ checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" [[package]] name = "windows_x86_64_msvc" -version = "0.53.0" +version = "0.53.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "271414315aff87387382ec3d271b52d7ae78726f5d44ac98b4f4030c91880486" +checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650" [[package]] name = "winnow" @@ -67,14 +67,14 @@ rand = "0.9" regex = "1" reqwest = { version = "0.12", default-features = false } rsa = "0.10.0-rc.9" -signature = "=3.0.0-rc.4" # TODO: Remove when rsa is fixed. +signature = "=3.0.0-rc.4" # TODO: Remove when rsa is fixed. rsa_public_encrypt_pkcs1 = "0.4" rustc-hash = "2" serde = "1" serde_json = "1" sha1 = "0.11.0-rc.2" sha2 = "0.11.0-rc.2" -simdnbt = "0.8" +simdnbt = { version = "0.8", git = "https://github.com/azalea-rs/simdnbt" } socks5-impl = "0.7" syn = "2" thiserror = "2" diff --git a/azalea-auth/src/auth.rs b/azalea-auth/src/auth.rs index d54194c9..d45547bc 100644 --- a/azalea-auth/src/auth.rs +++ b/azalea-auth/src/auth.rs @@ -18,21 +18,24 @@ use crate::cache::{self, CachedAccount, ExpiringValue}; #[derive(Default)] pub struct AuthOpts<'a> { - /// Whether we should check if the user actually owns the game. This will - /// fail if the user has Xbox Game Pass! Note that this isn't really - /// necessary, since getting the user profile will check this anyways. + /// Whether we should check if the user actually owns the game. + /// + /// This will fail if the user has Xbox Game Pass. Note that this isn't + /// really necessary, since getting the user profile will check this + /// anyways. pub check_ownership: bool, - // /// Whether we should get the Minecraft profile data (i.e. username, uuid, - // /// skin, etc) for the player. - // pub get_profile: bool, - /// The directory to store the cache in. If this is not set, caching is not - /// done. + /// The directory to store the cache in. + /// + /// If this is `None`, azalea-auth will not keep its own cache. pub cache_file: Option<PathBuf>, - /// If you choose to use your own Microsoft authentication instead of using - /// Nintendo Switch, just put your client_id here. + /// An override for the Microsoft Client ID to authenticate with. + /// + /// The default client ID is for Nintendo Switch, but you can replace this + /// if you'd like authentication to have your own branding. + /// + /// For more information about this, see <https://minecraft.wiki/w/Microsoft_authentication#Microsoft_OAuth2_flow>. pub client_id: Option<&'a str>, - /// If you want to use custom scope instead of default one, just put your - /// scope here. + /// An override for the OAuth2 scope to authenticate with. pub scope: Option<&'a str>, } @@ -59,12 +62,11 @@ pub enum AuthError { GetXboxLiveAuth(#[from] XboxLiveAuthError), } -/// Authenticate with Microsoft. If the data isn't cached, -/// they'll be asked to go to log into Microsoft in a web page. +/// Authenticate with Microsoft. If the data isn't cached, the user will be +/// asked to go to log into Microsoft in a web page. /// /// The cache key is an arbitrary string that's used to identify the account in -/// the future. As a convention, we usually prefer to put the account email -/// here. +/// the future. The account email is often used for this. /// /// If you want to use your own code to cache or show the auth code to the user /// in a different way, use [`get_ms_link_code`], [`get_ms_auth_token`], @@ -344,8 +346,10 @@ pub async fn get_ms_link_code( .await?) } -/// Wait until the user logged into Microsoft with the given code. You get the -/// device code response needed for this function from [`get_ms_link_code`]. +/// Wait until the user logged into Microsoft with the given code. +/// +/// You get the device code response needed for this function from +/// [`get_ms_link_code`]. /// /// You should pass the response from this to [`get_minecraft_token`]. pub async fn get_ms_auth_token( diff --git a/azalea-auth/src/sessionserver.rs b/azalea-auth/src/sessionserver.rs index 87d0e32c..317d09fa 100644 --- a/azalea-auth/src/sessionserver.rs +++ b/azalea-auth/src/sessionserver.rs @@ -53,8 +53,9 @@ pub struct ForbiddenError { static REQWEST_CLIENT: LazyLock<reqwest::Client> = LazyLock::new(reqwest::Client::new); /// Tell Mojang's servers that you are going to join a multiplayer server, -/// which is required to join online-mode servers. The server ID is an empty -/// string. +/// which is required to join online-mode servers. +/// +/// The server ID should typically be an empty string. pub async fn join( access_token: &str, public_key: &[u8], diff --git a/azalea-block/azalea-block-macros/src/lib.rs b/azalea-block/azalea-block-macros/src/lib.rs index 3e8ccf7d..843ea2ca 100644 --- a/azalea-block/azalea-block-macros/src/lib.rs +++ b/azalea-block/azalea-block-macros/src/lib.rs @@ -532,7 +532,7 @@ pub fn make_block_states(input: TokenStream) -> TokenStream { /// The highest possible block state ID. pub const MAX_STATE: BlockStateIntegerRepr = #last_state_id; - /// Get a property from this block state. Will be `None` if the block can't have the property. + /// Get a property from this block state, or `None` if the block can't have the property. /// /// ``` /// fn is_waterlogged(block_state: azalea_block::BlockState) -> bool { diff --git a/azalea-block/src/block_state.rs b/azalea-block/src/block_state.rs index a954c333..e3f894bf 100644 --- a/azalea-block/src/block_state.rs +++ b/azalea-block/src/block_state.rs @@ -25,14 +25,14 @@ pub type BlockStateIntegerRepr = u16; /// [`BlockStateIntegerRepr`]. #[derive(Copy, Clone, PartialEq, Eq, Default, Hash)] pub struct BlockState { - /// The protocol ID for the block state. IDs may change every - /// version, so you shouldn't hard-code them or store them in databases. id: BlockStateIntegerRepr, } impl BlockState { /// A shortcut for getting the air block state, since it always has an ID of /// 0. + /// + /// This does not include the other types of air like cave air. pub const AIR: BlockState = BlockState { id: 0 }; /// Create a new BlockState and panic if the block is not a valid state. @@ -53,15 +53,18 @@ impl BlockState { state_id <= Self::MAX_STATE } - /// Returns true if the block is air. This only checks for normal air, not - /// other types like cave air. + /// Returns true if the block is air. + /// + /// This only checks for normal air, not other types like cave air. #[inline] pub fn is_air(&self) -> bool { self == &Self::AIR } - /// Returns the protocol ID for the block state. IDs may change every - /// version, so you shouldn't hard-code them or store them in databases. + /// Returns the protocol ID for the block state. + /// + /// These IDs may change across Minecraft versions, so you shouldn't + /// hard-code them or store them in databases. #[inline] pub const fn id(&self) -> BlockStateIntegerRepr { self.id @@ -71,7 +74,7 @@ impl BlockState { impl TryFrom<u32> for BlockState { type Error = (); - /// Safely converts a u32 state id to a block state. + /// Safely converts a u32 state ID to a block state. fn try_from(state_id: u32) -> Result<Self, Self::Error> { let state_id = state_id as BlockStateIntegerRepr; if Self::is_valid_state(state_id) { @@ -84,7 +87,7 @@ impl TryFrom<u32> for BlockState { impl TryFrom<u16> for BlockState { type Error = (); - /// Safely converts a u16 state id to a block state. + /// Safely converts a u16 state ID to a block state. fn try_from(state_id: u16) -> Result<Self, Self::Error> { let state_id = state_id as BlockStateIntegerRepr; if Self::is_valid_state(state_id) { diff --git a/azalea-block/src/fluid_state.rs b/azalea-block/src/fluid_state.rs index cfddcc7f..80d0953b 100644 --- a/azalea-block/src/fluid_state.rs +++ b/azalea-block/src/fluid_state.rs @@ -112,9 +112,10 @@ impl From<BlockState> for FluidState { } } -/// Sometimes Minecraft represents fluids with 0 being empty and 8 being full, -/// and sometimes it's the opposite. You can use this function to convert -/// in between those two representations. +/// Convert between Minecraft's two fluid level representations. +/// +/// This exists because sometimes Minecraft represents fluids with 0 being empty +/// and 8 being full, and sometimes it's the opposite. /// /// You usually don't need to call this yourself, see [`FluidState`]. pub fn to_or_from_legacy_fluid_level(level: u8) -> u8 { diff --git a/azalea-brigadier/src/builder/argument_builder.rs b/azalea-brigadier/src/builder/argument_builder.rs index 945f7fcb..27320eba 100644 --- a/azalea-brigadier/src/builder/argument_builder.rs +++ b/azalea-brigadier/src/builder/argument_builder.rs @@ -77,8 +77,9 @@ impl<S> ArgumentBuilder<S> { self } - /// Set the command to be executed when this node is reached. If this is not - /// present on a node, it is not a valid command. + /// Set the command to be executed when this node is reached. + /// + /// If this is not present on a node, it is not a valid command. /// /// ``` /// # use azalea_brigadier::prelude::*; @@ -105,8 +106,9 @@ impl<S> ArgumentBuilder<S> { self } - /// Set the requirement for this node to be considered. If this is not - /// present on a node, it is considered to always pass. + /// Set the requirement for this node to be considered. + /// + /// If this is not present on a node, it is considered to always pass. /// /// ``` /// # use azalea_brigadier::prelude::*; diff --git a/azalea-brigadier/src/builder/required_argument_builder.rs b/azalea-brigadier/src/builder/required_argument_builder.rs index 3fc33143..5aca8617 100644 --- a/azalea-brigadier/src/builder/required_argument_builder.rs +++ b/azalea-brigadier/src/builder/required_argument_builder.rs @@ -13,8 +13,9 @@ use crate::{ suggestion::{SuggestionProvider, Suggestions, SuggestionsBuilder}, }; -/// An argument node type. The `T` type parameter is the type of the argument, -/// which can be anything. +/// An argument node type. +/// +/// The `T` type parameter is the type of the argument, which can be anything. pub struct Argument<S> { pub name: String, parser: Arc<dyn ArgumentType + Send + Sync>, diff --git a/azalea-brigadier/src/command_dispatcher.rs b/azalea-brigadier/src/command_dispatcher.rs index d9a45132..a2024139 100644 --- a/azalea-brigadier/src/command_dispatcher.rs +++ b/azalea-brigadier/src/command_dispatcher.rs @@ -173,8 +173,10 @@ impl<S> CommandDispatcher<S> { }) } - /// Parse and execute the command using the given input and context. The - /// number returned depends on the command, and may not be of significance. + /// Parse and execute the command using the given input and context. + /// + /// The number returned depends on the command, and may not be of + /// significance. /// /// This is a shortcut for `Self::parse` and `Self::execute_parsed`. pub fn execute( diff --git a/azalea-brigadier/src/tree/mod.rs b/azalea-brigadier/src/tree/mod.rs index 993b0698..12a5a50c 100644 --- a/azalea-brigadier/src/tree/mod.rs +++ b/azalea-brigadier/src/tree/mod.rs @@ -57,16 +57,26 @@ impl<S> Clone for CommandNode<S> { } impl<S> CommandNode<S> { - /// Gets the literal, or panics. You should use match if you're not certain - /// about the type. + /// Returns the value as a literal from this command node, assuming it's + /// already been checked. + /// + /// # Panics + /// + /// Will panic if this node is not a literal. Consider using a match + /// statement instead. pub fn literal(&self) -> &Literal { match self.value { ArgumentBuilderType::Literal(ref literal) => literal, _ => panic!("CommandNode::literal() called on non-literal node"), } } - /// Gets the argument, or panics. You should use match if you're not certain - /// about the type. + /// Returns the value as an argument from this command node, assuming it's + /// already been checked. + /// + /// # Panics + /// + /// Will panic if this node is not an argument. Consider using a match + /// statement instead. pub fn argument(&self) -> &Argument<S> { match self.value { ArgumentBuilderType::Argument(ref argument) => argument, diff --git a/azalea-chat/src/component.rs b/azalea-chat/src/component.rs index 87886e96..30b0ed9d 100644 --- a/azalea-chat/src/component.rs +++ b/azalea-chat/src/component.rs @@ -76,19 +76,22 @@ impl FormattedText { /// Render all components into a single `String`, using your custom /// closures to drive styling, text transformation, and final cleanup. /// - /// # Type params + /// # Type parameters + /// /// - `F`: `(running, component, default) -> (prefix, suffix)` for /// per-component styling /// - `S`: `&str -> String` for text tweaks (escaping, mapping, etc.) /// - `C`: `&final_running_style -> String` for any trailing cleanup /// - /// # Args - /// - `style_formatter`: how to open/close each component’s style - /// - `text_formatter`: how to turn raw text into output text + /// # Arguments + /// + /// - `style_formatter`: how to open/close each component's style + /// - `text_formatter`: how to turn raw text into output text /// - `cleanup_formatter`: emit after all components (e.g. reset codes) - /// - `default_style`: where to reset when a component’s `reset` is true + /// - `default_style`: where to reset when a component's `reset` is true /// /// # Example + /// /// ```rust /// use azalea_chat::{FormattedText, DEFAULT_STYLE}; /// use serde::de::Deserialize; diff --git a/azalea-chat/src/style.rs b/azalea-chat/src/style.rs index c43b7791..514944f1 100644 --- a/azalea-chat/src/style.rs +++ b/azalea-chat/src/style.rs @@ -497,7 +497,7 @@ impl Style { } /// Returns a new style that is a merge of self and other. - /// For any field that `other` does not specify (is None), self’s value is + /// For any field that `other` does not specify (is None), self's value is /// used. pub fn merged_with(&self, other: &Style) -> Style { Style { diff --git a/azalea-chat/src/translatable_component.rs b/azalea-chat/src/translatable_component.rs index 13afe6b7..ae1d80bc 100644 --- a/azalea-chat/src/translatable_component.rs +++ b/azalea-chat/src/translatable_component.rs @@ -2,7 +2,10 @@ use std::fmt::{self, Display}; use serde::{Deserialize, Serialize}; #[cfg(feature = "simdnbt")] -use simdnbt::ToNbtTag; +use simdnbt::{ + ToNbtTag, + owned::{NbtList, NbtTag}, +}; use crate::{FormattedText, base_component::BaseComponent, text_component::TextComponent}; @@ -49,93 +52,12 @@ pub struct TranslatableComponent { } #[cfg(feature = "simdnbt")] -fn serialize_args_as_nbt(args: Vec<PrimitiveOrComponent>) -> simdnbt::owned::NbtList { - let tags: Vec<simdnbt::owned::NbtTag> = args.into_iter().map(|arg| arg.to_nbt_tag()).collect(); - - if let Some(first_element) = tags.first() { - let tags = tags.clone(); - let homogenous_list = match first_element { - simdnbt::owned::NbtTag::Byte(_) => tags - .into_iter() - .map(|tag| tag.into_byte()) - .collect::<Option<Vec<i8>>>() - .map(simdnbt::owned::NbtList::from), - simdnbt::owned::NbtTag::Short(_) => tags - .into_iter() - .map(|tag| tag.into_short()) - .collect::<Option<Vec<i16>>>() - .map(simdnbt::owned::NbtList::from), - simdnbt::owned::NbtTag::Int(_) => tags - .into_iter() - .map(|tag| tag.into_int()) - .collect::<Option<Vec<i32>>>() - .map(simdnbt::owned::NbtList::from), - simdnbt::owned::NbtTag::Long(_) => tags - .into_iter() - .map(|tag| tag.into_long()) - .collect::<Option<Vec<i64>>>() - .map(simdnbt::owned::NbtList::from), - simdnbt::owned::NbtTag::Float(_) => tags - .into_iter() - .map(|tag| tag.into_float()) - .collect::<Option<Vec<f32>>>() - .map(simdnbt::owned::NbtList::from), - simdnbt::owned::NbtTag::Double(_) => tags - .into_iter() - .map(|tag| tag.into_double()) - .collect::<Option<Vec<f64>>>() - .map(simdnbt::owned::NbtList::from), - simdnbt::owned::NbtTag::ByteArray(_) => tags - .into_iter() - .map(|tag| tag.into_byte_array()) - .collect::<Option<Vec<Vec<u8>>>>() - .map(simdnbt::owned::NbtList::from), - simdnbt::owned::NbtTag::String(_) => tags - .into_iter() - .map(|tag| tag.into_string()) - .collect::<Option<Vec<simdnbt::Mutf8String>>>() - .map(simdnbt::owned::NbtList::from), - simdnbt::owned::NbtTag::List(_) => tags - .into_iter() - .map(|tag| tag.into_list()) - .collect::<Option<Vec<simdnbt::owned::NbtList>>>() - .map(simdnbt::owned::NbtList::from), - simdnbt::owned::NbtTag::Compound(_) => tags - .into_iter() - .map(|tag| tag.into_compound()) - .collect::<Option<Vec<simdnbt::owned::NbtCompound>>>() - .map(simdnbt::owned::NbtList::from), - simdnbt::owned::NbtTag::IntArray(_) => tags - .into_iter() - .map(|tag| tag.into_int_array()) - .collect::<Option<Vec<Vec<i32>>>>() - .map(simdnbt::owned::NbtList::from), - simdnbt::owned::NbtTag::LongArray(_) => tags - .into_iter() - .map(|tag| tag.into_long_array()) - .collect::<Option<Vec<Vec<i64>>>>() - .map(simdnbt::owned::NbtList::from), - }; - - if let Some(homogenous_list) = homogenous_list { - return homogenous_list; - } - } - - let mut compounds = Vec::with_capacity(tags.len()); - for tag in tags { - let compound = if let simdnbt::owned::NbtTag::Compound(compound) = tag { - compound - } else { - let mut compound = simdnbt::owned::NbtCompound::new(); - compound.insert("", tag); - compound - }; - - compounds.push(compound); - } - - compounds.into() +fn serialize_args_as_nbt(args: Vec<PrimitiveOrComponent>) -> NbtList { + let tags = args + .into_iter() + .map(|arg| arg.to_nbt_tag()) + .collect::<Vec<NbtTag>>(); + NbtList::from(tags) } #[cfg(feature = "simdnbt")] diff --git a/azalea-client/src/account.rs b/azalea-client/src/account.rs index bda69558..ab8e8e65 100644 --- a/azalea-client/src/account.rs +++ b/azalea-client/src/account.rs @@ -37,8 +37,9 @@ use uuid::Uuid; pub struct Account { /// The Minecraft username of the account. pub username: String, - /// The access token for authentication. You can obtain one of these - /// manually from azalea-auth. + /// The access token for authentication. + /// + /// You can obtain one of these manually from azalea-auth. /// /// This is an `Arc<Mutex>` so it can be modified by [`Self::refresh`]. pub access_token: Option<Arc<Mutex<String>>>, @@ -46,8 +47,10 @@ pub struct Account { pub uuid: Option<Uuid>, /// The parameters (i.e. email) that were passed for creating this - /// [`Account`]. This is used for automatic reauthentication when we get - /// "Invalid Session" errors. If you don't need that feature (like in + /// [`Account`]. + /// + /// This is used for automatic reauthentication when we get "Invalid + /// Session" errors. If you don't need that feature (like in /// offline mode), then you can set this to `AuthOpts::default()`. pub account_opts: AccountOpts, @@ -74,8 +77,9 @@ pub enum AccountOpts { impl Account { /// An offline account does not authenticate with Microsoft's servers, and - /// as such can only join offline mode servers. This is useful for testing - /// in LAN worlds. + /// as such can only join offline mode servers. + /// + /// This is useful for testing in LAN worlds. pub fn offline(username: &str) -> Self { Self { username: username.to_string(), @@ -89,19 +93,20 @@ impl Account { } /// This will create an online-mode account by authenticating with - /// Microsoft's servers. Note that the email given is actually only used as - /// a key for the cache, but it's recommended to use the real email to - /// avoid confusion. - pub async fn microsoft(email: &str) -> Result<Self, azalea_auth::AuthError> { - Self::microsoft_with_custom_client_id_and_scope(email, None, None).await + /// Microsoft's servers. + /// + /// The cache key is used for avoiding having to log in every time. This is + /// typically set to the account email, but it can be any string. + pub async fn microsoft(cache_key: &str) -> Result<Self, azalea_auth::AuthError> { + Self::microsoft_with_custom_client_id_and_scope(cache_key, None, None).await } - /// Similar to [`Account::microsoft`] but you can use your - /// own `client_id` and `scope`. + /// Similar to [`Account::microsoft`] but you can use your own `client_id` + /// and `scope`. /// /// Pass `None` if you want to use default ones. pub async fn microsoft_with_custom_client_id_and_scope( - email: &str, + cache_key: &str, client_id: Option<&str>, scope: Option<&str>, ) -> Result<Self, azalea_auth::AuthError> { @@ -112,7 +117,7 @@ impl Account { ) }); let auth_result = azalea_auth::auth( - email, + cache_key, azalea_auth::AuthOpts { cache_file: Some(minecraft_dir.join("azalea-auth.json")), client_id, @@ -126,7 +131,7 @@ impl Account { access_token: Some(Arc::new(Mutex::new(auth_result.access_token))), uuid: Some(auth_result.profile.id), account_opts: AccountOpts::Microsoft { - email: email.to_string(), + email: cache_key.to_string(), }, // we don't do chat signing by default unless the user asks for it certs: Arc::new(Mutex::new(None)), @@ -235,8 +240,10 @@ impl Account { } } - /// Get the UUID of this account. This will generate an offline-mode UUID - /// by making a hash with the username if the `uuid` field is None. + /// Get the UUID of this account. + /// + /// If the `uuid` field is None, the UUID will be determined by using + /// Minecraft's offline-mode UUIDv3 algorithm. pub fn uuid_or_offline(&self) -> Uuid { self.uuid .unwrap_or_else(|| azalea_auth::offline::generate_uuid(&self.username)) diff --git a/azalea-client/src/client.rs b/azalea-client/src/client.rs index cf07f8b2..6957619e 100644 --- a/azalea-client/src/client.rs +++ b/azalea-client/src/client.rs @@ -78,9 +78,11 @@ pub struct Client { /// The entity for this client in the ECS. pub entity: Entity, - /// The entity component system. You probably don't need to access this - /// directly. Note that if you're using a shared world (i.e. a swarm), this - /// will contain all entities in all worlds. + /// A mutually exclusive reference to the entity component system (ECS). + /// + /// You probably don't need to access this directly. Note that if you're + /// using a shared world (i.e. a swarm), the ECS will contain all entities + /// in all instances/dimensions. pub ecs: Arc<Mutex<World>>, } @@ -524,8 +526,9 @@ pub struct LocalPlayerBundle { } /// A bundle for the components that are present on a local player that is -/// currently in the `game` protocol state. If you want to filter for this, use -/// [`InGameState`]. +/// currently in the `game` protocol state. +/// +/// If you want to filter for this, use [`InGameState`]. #[derive(Bundle, Default)] pub struct JoinedClientBundle { // note that InstanceHolder isn't here because it's set slightly before we fully join the world diff --git a/azalea-client/src/entity_query.rs b/azalea-client/src/entity_query.rs index a1d761e3..6945549d 100644 --- a/azalea-client/src/entity_query.rs +++ b/azalea-client/src/entity_query.rs @@ -175,8 +175,10 @@ impl Client { predicate.find_all_sorted(self.ecs.clone(), &instance_name, (&position).into()) } - /// Get a component from an entity. Note that this will return an owned type - /// (i.e. not a reference) so it may be expensive for larger types. + /// Get a component from an entity. + /// + /// Note that this will return an owned type (i.e. not a reference) so it + /// may be expensive for larger types. /// /// If you're trying to get a component for this client, use /// [`Self::component`]. @@ -192,9 +194,10 @@ impl Client { components.clone() } - /// Get a component from an entity, if it exists. This is similar to - /// [`Self::entity_component`] but returns an `Option` instead of panicking - /// if the component isn't present. + /// Get a component from an entity, if it exists. + /// + /// This is similar to [`Self::entity_component`] but returns an `Option` + /// instead of panicking if the component isn't present. pub fn get_entity_component<Q: Component + Clone>(&self, entity: Entity) -> Option<Q> { let mut ecs = self.ecs.lock(); let mut q = ecs.query::<&Q>(); diff --git a/azalea-client/src/local_player.rs b/azalea-client/src/local_player.rs index 20da4c80..4bc69995 100644 --- a/azalea-client/src/local_player.rs +++ b/azalea-client/src/local_player.rs @@ -26,11 +26,12 @@ use crate::{ClientInformation, events::Event as AzaleaEvent, player::PlayerInfo} /// [`InstanceName`]: azalea_world::InstanceName #[derive(Component, Clone)] pub struct InstanceHolder { - /// The partial instance is the world this client currently has loaded. It - /// has a limited render distance. + /// The partial instance is the world this client currently has loaded. + /// + /// It has a limited render distance. pub partial_instance: Arc<RwLock<PartialInstance>>, - /// The world is the combined [`PartialInstance`]s of all clients in the - /// same world. + /// The combined [`PartialInstance`]s of all clients in the same instance + /// (aka world/dimension). /// /// This is only relevant if you're using a shared world (i.e. a /// swarm). @@ -81,11 +82,13 @@ pub struct TabList(HashMap<Uuid, PlayerInfo>); #[derive(Component, Clone)] pub struct Hunger { - /// The main hunger bar. Goes from 0 to 20. + /// The main hunger bar. This is typically in the range `0..=20`. pub food: u32, - /// The amount of saturation the player has. This isn't shown in normal - /// vanilla clients but it's a separate counter that makes it so your hunger - /// only starts decreasing when this is 0. + /// The amount of saturation the player has. + /// + /// This isn't displayed in the vanilla Minecraft GUI, but it's used + /// internally by the game. It's a decrementing counter, and the player's + /// [`Hunger::food`] only starts decreasing when this reaches 0. pub saturation: f32, } diff --git a/azalea-client/src/player.rs b/azalea-client/src/player.rs index 46596e48..9a2e7a1c 100644 --- a/azalea-client/src/player.rs +++ b/azalea-client/src/player.rs @@ -22,12 +22,14 @@ pub struct PlayerInfo { pub uuid: Uuid, /// The current gamemode of the player, like survival or creative. pub gamemode: GameMode, - /// The player's latency in milliseconds. The bars in the tab screen depend - /// on this. + /// The player's latency in milliseconds. + /// + /// The bars in the tab screen depend on this. pub latency: i32, /// The player's display name in the tab list, but only if it's different - /// from the player's normal username. Use `player_info.profile.name` to get - /// the player's actual username. + /// from the player's normal username. + /// + /// Use [`GameProfile::name`] to get the player's actual username. pub display_name: Option<Box<FormattedText>>, } diff --git a/azalea-client/src/plugins/attack.rs b/azalea-client/src/plugins/attack.rs index 0e7cfeb8..7550ed19 100644 --- a/azalea-client/src/plugins/attack.rs +++ b/azalea-client/src/plugins/attack.rs @@ -43,7 +43,10 @@ impl Plugin for AttackPlugin { } impl Client { - /// Attack the entity with the given id. + /// Attack an entity in the world. + /// + /// This doesn't automatically look at the entity or perform any + /// range/visibility checks, so it might trigger anticheats. pub fn attack(&self, entity: Entity) { self.ecs.lock().write_message(AttackEvent { entity: self.entity, diff --git a/azalea-client/src/plugins/auto_reconnect.rs b/azalea-client/src/plugins/auto_reconnect.rs index bff72e5a..fd24f12c 100644 --- a/azalea-client/src/plugins/auto_reconnect.rs +++ b/azalea-client/src/plugins/auto_reconnect.rs @@ -14,14 +14,17 @@ use super::{ }; use crate::Account; -/// The default delay that Azalea will use for reconnecting our clients. See -/// [`AutoReconnectPlugin`] for more information. +/// The default delay that Azalea will use for reconnecting our clients. +/// +/// See [`AutoReconnectPlugin`] for more information. pub const DEFAULT_RECONNECT_DELAY: Duration = Duration::from_secs(5); /// A default plugin that makes clients automatically rejoin the server when -/// they're disconnected. The reconnect delay is configurable globally or -/// per-client with the [`AutoReconnectDelay`] resource/component. Auto -/// reconnecting can be disabled by removing the resource from the ECS. +/// they're disconnected. +/// +/// The reconnect delay is configurable globally or per-client with the +/// [`AutoReconnectDelay`] resource/component. Auto reconnecting can be disabled +/// by removing the resource from the ECS. /// /// The delay defaults to [`DEFAULT_RECONNECT_DELAY`]. pub struct AutoReconnectPlugin; diff --git a/azalea-client/src/plugins/chat/mod.rs b/azalea-client/src/plugins/chat/mod.rs index 098b6543..e0a41d49 100644 --- a/azalea-client/src/plugins/chat/mod.rs +++ b/azalea-client/src/plugins/chat/mod.rs @@ -131,9 +131,11 @@ impl ChatPacket { self.split_sender_and_content().0 } - /// Get the UUID of the sender of the message. If it's not a - /// player-sent chat message, this will be None (this is sometimes the case - /// when a server uses a plugin to modify chat messages). + /// Get the UUID of the sender of the message. + /// + /// If it's not a player-sent chat message, this will be None (this is + /// sometimes the case when a server uses a plugin to modify chat + /// messages). pub fn sender_uuid(&self) -> Option<Uuid> { match self { ChatPacket::System(_) => None, @@ -142,14 +144,16 @@ impl ChatPacket { } } - /// Get the content part of the message as a string. This does not preserve - /// formatting codes. If it's not a player-sent chat message or the sender - /// couldn't be determined, this will contain the entire message. + /// Get the content part of the message as a string. + /// + /// This does not preserve formatting codes. If it's not a player-sent chat + /// message or the sender couldn't be determined, this will contain the + /// entire message. pub fn content(&self) -> String { self.split_sender_and_content().1 } - /// Create a new Chat from a string. This is meant to be used as a + /// Create a new `ChatPacket` from a string. This is meant to be used as a /// convenience function for testing. pub fn new(message: &str) -> Self { ChatPacket::System(Arc::new(ClientboundSystemChat { @@ -159,8 +163,9 @@ impl ChatPacket { } /// Whether this message is an incoming whisper message (i.e. someone else - /// dm'd the bot with /msg). It works by checking the translation key, so it - /// won't work on servers that use their own whisper system. + /// messaged the bot with /msg). + /// + /// This is not guaranteed to work correctly on custom servers. pub fn is_whisper(&self) -> bool { match self { ChatPacket::System(p) => { @@ -183,11 +188,13 @@ impl ChatPacket { } impl Client { - /// Send a chat message to the server. This only sends the chat packet and - /// not the command packet, which means on some servers you can use this to - /// send chat messages that start with a `/`. The [`Client::chat`] function - /// handles checking whether the message is a command and using the - /// proper packet for you, so you should use that instead. + /// Send a chat message to the server. + /// + /// This only sends the chat packet and not the command packet, which means + /// on some servers you can use this to send chat messages that start + /// with a `/`. The [`Client::chat`] function handles checking whether + /// the message is a command and using the proper packet for you, so you + /// should use that instead. pub fn write_chat_packet(&self, message: &str) { self.ecs.lock().write_message(SendChatKindEvent { entity: self.entity, diff --git a/azalea-client/src/plugins/client_information.rs b/azalea-client/src/plugins/client_information.rs index 499b8ab5..98f69a2d 100644 --- a/azalea-client/src/plugins/client_information.rs +++ b/azalea-client/src/plugins/client_information.rs @@ -45,8 +45,9 @@ pub fn send_client_information( impl Client { /// Tell the server we changed our game options (i.e. render distance, main - /// hand). If this is not set before the login packet, the default will - /// be sent. + /// hand). + /// + /// If this is not set before the login packet, the default will be sent. /// /// ```rust,no_run /// # use azalea_client::{Client, ClientInformation}; @@ -54,12 +55,11 @@ impl Client { /// bot.set_client_information(ClientInformation { /// view_distance: 2, /// ..Default::default() - /// }) - /// .await; + /// }); /// # Ok(()) /// # } /// ``` - pub async fn set_client_information(&self, client_information: ClientInformation) { + pub fn set_client_information(&self, client_information: ClientInformation) { self.query_self::<&mut ClientInformation, _>(|mut ci| { *ci = client_information.clone(); }); diff --git a/azalea-client/src/plugins/connection.rs b/azalea-client/src/plugins/connection.rs index 5d9cde18..dc14545a 100644 --- a/azalea-client/src/plugins/connection.rs +++ b/azalea-client/src/plugins/connection.rs @@ -182,9 +182,10 @@ pub struct RawConnection { pub(crate) is_alive: bool, /// This exists for internal testing purposes and probably shouldn't be used - /// for normal bots. It's basically a way to make our client think it - /// received a packet from the server without needing to interact with the - /// network. + /// for normal bots. + /// + /// It's basically a way to make our client think it received a packet from + /// the server without needing to interact with the network. pub injected_clientbound_packets: Vec<Box<[u8]>>, } impl RawConnection { @@ -305,9 +306,10 @@ pub struct NetworkConnection { pub enc_cipher: Option<Aes128CfbEnc>, pub writer_task: bevy_tasks::Task<()>, - /// A queue of raw TCP packets to send. These will not be modified further, - /// they should already be serialized and encrypted and everything before - /// being added here. + /// A queue of raw TCP packets to send. + /// + /// These will not be modified further, they should already be serialized + /// and compressed and encrypted before being added here. network_packet_writer_tx: mpsc::UnboundedSender<Box<[u8]>>, } impl NetworkConnection { @@ -344,8 +346,9 @@ impl NetworkConnection { trace!("Set compression threshold to {threshold:?}"); self.reader.compression_threshold = threshold; } - /// Set the encryption key that is used to encrypt and decrypt packets. It's - /// the same for both reading and writing. + /// Set the encryption key that is used to encrypt and decrypt packets. + /// + /// The same key is used for both reading and writing. pub fn set_encryption_key(&mut self, key: [u8; 16]) { trace!("Enabled protocol encryption"); let (enc_cipher, dec_cipher) = azalea_crypto::create_cipher(&key); diff --git a/azalea-client/src/plugins/events.rs b/azalea-client/src/plugins/events.rs index bc8a7a98..e8d99e7c 100644 --- a/azalea-client/src/plugins/events.rs +++ b/azalea-client/src/plugins/events.rs @@ -54,12 +54,16 @@ use crate::{ #[non_exhaustive] pub enum Event { /// Happens right after the bot switches into the Game state, but before - /// it's actually spawned. This can be useful for setting the client - /// information with `Client::set_client_information`, so the packet - /// doesn't have to be sent twice. + /// it's actually spawned. + /// + /// This can be useful for setting the client information with + /// [`Client::set_client_information`], so the packet doesn't have to be + /// sent twice. /// /// You may want to use [`Event::Spawn`] instead to wait for the bot to be /// in the world. + /// + /// [`Client::set_client_information`]: crate::Client::set_client_information Init, /// Fired when we receive a login packet, which is after [`Event::Init`] but /// before [`Event::Spawn`]. You usually want [`Event::Spawn`] instead. @@ -123,8 +127,9 @@ pub enum Event { } /// A component that contains an event sender for events that are only -/// received by local players. The receiver for this is returned by -/// [`Client::start_client`]. +/// received by local players. +/// +/// The receiver for this is returned by [`Client::start_client`]. /// /// [`Client::start_client`]: crate::Client::start_client #[derive(Component, Deref, DerefMut)] diff --git a/azalea-client/src/plugins/interact/mod.rs b/azalea-client/src/plugins/interact/mod.rs index 52862a38..09a8afc9 100644 --- a/azalea-client/src/plugins/interact/mod.rs +++ b/azalea-client/src/plugins/interact/mod.rs @@ -363,8 +363,9 @@ pub fn handle_start_use_item_queued( } } -/// Whether we can't interact with the block, based on your gamemode. If -/// this is false, then we can interact with the block. +/// Whether we can't interact with the block, based on your gamemode. +/// +/// If this is false, then we can interact with the block. /// /// Passing the inventory, block position, and instance is necessary for the /// adventure mode check. @@ -427,8 +428,10 @@ pub fn can_use_game_master_blocks( abilities.instant_break && **permission_level >= 2 } -/// Swing your arm. This is purely a visual effect and won't interact with -/// anything in the world. +/// Swing your arm. +/// +/// This is purely a visual effect and won't interact with anything in the +/// world. #[derive(EntityEvent, Clone, Debug)] pub struct SwingArmEvent { pub entity: Entity, diff --git a/azalea-client/src/plugins/inventory.rs b/azalea-client/src/plugins/inventory.rs index a805ae9b..c167917b 100644 --- a/azalea-client/src/plugins/inventory.rs +++ b/azalea-client/src/plugins/inventory.rs @@ -47,8 +47,8 @@ impl Plugin for InventoryPlugin { pub struct InventorySystems; impl Client { - /// Return the menu that is currently open. If no menu is open, this will - /// have the player's inventory. + /// Return the menu that is currently open, or the player's inventory if no + /// menu is open. pub fn menu(&self) -> Menu { self.query_self::<&Inventory, _>(|inv| inv.menu().clone()) } @@ -95,26 +95,29 @@ pub struct Inventory { /// bare [`azalea_inventory::Player`] doesn't have. pub inventory_menu: azalea_inventory::Menu, - /// The ID of the container that's currently open. Its value is not - /// guaranteed to be anything specific, and may change every time you open a - /// container (unless it's 0, in which case it means that no container is - /// open). + /// The ID of the container that's currently open. + /// + /// Its value is not guaranteed to be anything specific, and it may change + /// every time you open a container (unless it's 0, in which case it + /// means that no container is open). pub id: i32, - /// The current container menu that the player has open. If no container is - /// open, this will be `None`. + /// The current container menu that the player has open, or `None` if no + /// container is open. pub container_menu: Option<azalea_inventory::Menu>, - /// The custom name of the menu that's currently open. This is Some when - /// `container_menu` is Some. + /// The custom name of the menu that's currently open. + /// + /// This can only be `Some` when `container_menu` is `Some`. pub container_menu_title: Option<FormattedText>, - /// The item that is currently held by the cursor. `Slot::Empty` if nothing - /// is currently being held. + /// The item that is currently held by the cursor, or `Slot::Empty` if + /// nothing is currently being held. /// /// This is different from [`Self::selected_hotbar_slot`], which is the /// item that's selected in the hotbar. pub carried: ItemStack, - /// An identifier used by the server to track client inventory desyncs. This - /// is sent on every container click, and it's only ever updated when the - /// server sends a new container update. + /// An identifier used by the server to track client inventory desyncs. + /// + /// This is sent on every container click, and it's only ever updated when + /// the server sends a new container update. pub state_id: u32, pub quick_craft_status: QuickCraftStatusKind, @@ -124,7 +127,7 @@ pub struct Inventory { pub quick_craft_slots: HashSet<u16>, /// The index of the item in the hotbar that's currently being held by the - /// player. This MUST be in the range 0..9 (not including 9). + /// player. This must be in the range 0..=8. /// /// In a vanilla client this is changed by pressing the number keys or using /// the scroll wheel. @@ -132,9 +135,10 @@ pub struct Inventory { } impl Inventory { - /// Returns a reference to the currently active menu. If a container is open - /// it'll return [`Self::container_menu`], otherwise - /// [`Self::inventory_menu`]. + /// Returns a reference to the currently active menu. + /// + /// If a container is open then it'll return [`Self::container_menu`], + /// otherwise [`Self::inventory_menu`]. /// /// Use [`Self::menu_mut`] if you need a mutable reference. pub fn menu(&self) -> &azalea_inventory::Menu { @@ -144,9 +148,10 @@ impl Inventory { } } - /// Returns a mutable reference to the currently active menu. If a container - /// is open it'll return [`Self::container_menu`], otherwise - /// [`Self::inventory_menu`]. + /// Returns a mutable reference to the currently active menu. + /// + /// If a container is open then it'll return [`Self::container_menu`], + /// otherwise [`Self::inventory_menu`]. /// /// Use [`Self::menu`] if you don't need a mutable reference. pub fn menu_mut(&mut self) -> &mut azalea_inventory::Menu { @@ -743,8 +748,10 @@ fn handle_menu_opened_trigger(event: On<MenuOpenedEvent>, mut query: Query<&mut #[derive(EntityEvent)] pub struct CloseContainerEvent { pub entity: Entity, - /// The ID of the container to close. 0 for the player's inventory. If this - /// is not the same as the currently open inventory, nothing will happen. + /// The ID of the container to close. 0 for the player's inventory. + /// + /// If this is not the same as the currently open inventory, nothing will + /// happen. pub id: i32, } fn handle_container_close_event( @@ -772,7 +779,7 @@ fn handle_container_close_event( }); } -/// A Bevy trigger that's fired when our client closed a container. +/// A Bevy event that's fired when our client closed a container. /// /// This can also be triggered directly to close a container silently without /// sending any packets to the server. You probably don't want that though, and diff --git a/azalea-client/src/plugins/join.rs b/azalea-client/src/plugins/join.rs index b9878370..a8f6e3c5 100644 --- a/azalea-client/src/plugins/join.rs +++ b/azalea-client/src/plugins/join.rs @@ -57,8 +57,9 @@ pub struct StartJoinServerEvent { pub start_join_callback_tx: Option<mpsc::UnboundedSender<Entity>>, } -/// Options for how the connection to the server will be made. These are -/// persisted on reconnects. +/// Options for how the connection to the server will be made. +/// +/// These are persisted on reconnects. /// /// This is inserted as a component on clients to make auto-reconnecting work. #[derive(Debug, Clone, Component)] diff --git a/azalea-client/src/plugins/mining.rs b/azalea-client/src/plugins/mining.rs index fda54521..101cd4df 100644 --- a/azalea-client/src/plugins/mining.rs +++ b/azalea-client/src/plugins/mining.rs @@ -147,8 +147,9 @@ fn handle_auto_mine( } } -/// Information about the block we're currently mining. This is only present if -/// we're currently mining a block. +/// Information about the block we're currently mining. +/// +/// This is only present if we're currently mining a block. #[derive(Component, Debug, Clone)] pub struct Mining { pub pos: BlockPos, @@ -441,8 +442,9 @@ pub struct MineBundle { #[derive(Component, Debug, Default, Deref, DerefMut, Clone)] pub struct MineDelay(pub u32); -/// A component that stores the progress of the current mining operation. This -/// is a value between 0 and 1. +/// A component that stores the progress of the current mining operation. +/// +/// This is a value between 0 and 1. #[derive(Component, Debug, Default, Deref, DerefMut, Clone)] pub struct MineProgress(pub f32); @@ -457,8 +459,9 @@ impl MineProgress { } /// A component that stores the number of ticks that we've been mining the same -/// block for. This is a float even though it should only ever be a round -/// number. +/// block for. +/// +/// This is a float despite the fact that it should only ever be a round number. #[derive(Component, Clone, Debug, Default, Deref, DerefMut)] pub struct MineTicks(pub f32); @@ -466,8 +469,8 @@ pub struct MineTicks(pub f32); #[derive(Component, Clone, Debug, Default, Deref, DerefMut)] pub struct MineBlockPos(pub Option<BlockPos>); -/// A component that contains the item we're currently using to mine. If we're -/// not mining anything, it'll be [`ItemStack::Empty`]. +/// A component that contains the item we're currently using to mine, or +/// [`ItemStack::Empty`] if nothing is being mined. #[derive(Component, Clone, Debug, Default, Deref, DerefMut)] pub struct MineItem(pub ItemStack); diff --git a/azalea-client/src/plugins/movement.rs b/azalea-client/src/plugins/movement.rs index 2ee5c379..adbaa01d 100644 --- a/azalea-client/src/plugins/movement.rs +++ b/azalea-client/src/plugins/movement.rs @@ -100,7 +100,9 @@ pub struct MoveEventsSystems; impl Client { /// Set whether we're jumping. This acts as if you held space in - /// vanilla. If you want to jump once, use the `jump` function. + /// vanilla. + /// + /// If you want to jump once, use the `jump` function in `azalea`. /// /// If you're making a realistic client, calling this function every tick is /// recommended. @@ -124,19 +126,21 @@ impl Client { self.query_self::<&PhysicsState, _>(|p| p.trying_to_crouch) } - /// Sets the direction the client is looking. `y_rot` is yaw (looking to the - /// side), `x_rot` is pitch (looking up and down). You can get these - /// numbers from the vanilla f3 screen. - /// `y_rot` goes from -180 to 180, and `x_rot` goes from -90 to 90. + /// Sets the direction the client is looking. + /// + /// `y_rot` is yaw (looking to the side, between -180 to 180), and `x_rot` + /// is pitch (looking up and down, between -90 to 90). + /// + /// You can get these numbers from the vanilla f3 screen. pub fn set_direction(&self, y_rot: f32, x_rot: f32) { self.query_self::<&mut LookDirection, _>(|mut ld| { ld.update(LookDirection::new(y_rot, x_rot)); }); } - /// Returns the direction the client is looking. The first value is the y - /// rotation (ie. yaw, looking to the side) and the second value is the x - /// rotation (ie. pitch, looking up and down). + /// Returns the direction the client is looking. + /// + /// See [`Self::set_direction`] for more details. pub fn direction(&self) -> (f32, f32) { let look_direction: LookDirection = self.component::<LookDirection>(); (look_direction.y_rot(), look_direction.x_rot()) @@ -350,8 +354,9 @@ pub(crate) fn tick_controls(mut query: Query<&mut PhysicsState>) { } } -/// Makes the bot do one physics tick. Note that this is already handled -/// automatically by the client. +/// Makes the bot do one physics tick. +/// +/// This is handled automatically by the client. #[allow(clippy::type_complexity)] pub fn local_player_ai_step( mut query: Query< @@ -532,17 +537,18 @@ fn distance_to_unit_square(v: Vec2) -> f32 { } impl Client { - /// Start walking in the given direction. To sprint, use - /// [`Client::sprint`]. To stop walking, call walk with - /// `WalkDirection::None`. + /// Start walking in the given direction. /// - /// # Examples + /// To sprint, use [`Client::sprint`]. To stop walking, call walk with + /// [`WalkDirection::None`]. + /// + /// # Example /// - /// Walk for 1 second /// ```rust,no_run /// # use azalea_client::{Client, WalkDirection}; /// # use std::time::Duration; /// # async fn example(mut bot: Client) { + /// // walk for one second /// bot.walk(WalkDirection::Forward); /// tokio::time::sleep(Duration::from_secs(1)).await; /// bot.walk(WalkDirection::None); @@ -556,16 +562,17 @@ impl Client { }); } - /// Start sprinting in the given direction. To stop moving, call - /// [`bot.walk(WalkDirection::None)`](Self::walk) + /// Start sprinting in the given direction. + /// + /// o stop moving, call [`bot.walk(WalkDirection::None)`](Self::walk) /// - /// # Examples + /// # Example /// - /// Sprint for 1 second /// ```rust,no_run /// # use azalea_client::{Client, WalkDirection, SprintDirection}; /// # use std::time::Duration; /// # async fn example(mut bot: Client) { + /// // sprint for one second /// bot.sprint(SprintDirection::Forward); /// tokio::time::sleep(Duration::from_secs(1)).await; /// bot.walk(WalkDirection::None); @@ -580,8 +587,9 @@ impl Client { } } -/// An event sent when the client starts walking. This does not get sent for -/// non-local entities. +/// An event sent when the client starts walking. +/// +/// This does not get sent for non-local entities. /// /// To stop walking or sprinting, send this event with `WalkDirection::None`. #[derive(Message, Debug)] @@ -606,8 +614,9 @@ pub fn handle_walk( } } -/// An event sent when the client starts sprinting. This does not get sent for -/// non-local entities. +/// An event sent when the client starts sprinting. +/// +/// This does not get sent for non-local entities. #[derive(Message)] pub struct StartSprintEvent { pub entity: Entity, @@ -662,10 +671,11 @@ fn has_enough_impulse_to_start_sprinting(physics_state: &PhysicsState) -> bool { // } } -/// An event sent by the server that sets or adds to our velocity. Usually -/// `KnockbackKind::Set` is used for normal knockback and `KnockbackKind::Add` -/// is used for explosions, but some servers (notably Hypixel) use explosions -/// for knockback. +/// An event sent by the server that sets or adds to our velocity. +/// +/// Usually `KnockbackKind::Set` is used for normal knockback and +/// `KnockbackKind::Add` is used for explosions, but some servers (notably +/// Hypixel) use explosions for knockback. #[derive(Message)] pub struct KnockbackEvent { pub entity: Entity, diff --git a/azalea-client/src/plugins/packet/game/events.rs b/azalea-client/src/plugins/packet/game/events.rs index cb9a5e07..7c773b44 100644 --- a/azalea-client/src/plugins/packet/game/events.rs +++ b/azalea-client/src/plugins/packet/game/events.rs @@ -102,9 +102,10 @@ pub struct UpdatePlayerEvent { pub info: PlayerInfo, } -/// Event for when an entity dies. dies. If it's a local player and there's a -/// reason in the death screen, the [`ClientboundPlayerCombatKill`] will -/// be included. +/// Event for when an entity dies. +/// +/// If it's a local player and there's a reason in the death screen, the +/// [`ClientboundPlayerCombatKill`] will be included. #[derive(Message, Debug, Clone)] pub struct DeathEvent { pub entity: Entity, @@ -116,16 +117,20 @@ pub struct DeathEvent { #[derive(Message, Debug, Clone)] pub struct KeepAliveEvent { pub entity: Entity, - /// The ID of the keepalive. This is an arbitrary number, but vanilla - /// servers use the time to generate this. + /// The ID of the keepalive. + /// + /// This is an arbitrary number, but vanilla servers use the current time to + /// generate this. pub id: u64, } #[derive(Message, Debug, Clone)] pub struct ResourcePackEvent { pub entity: Entity, - /// The random ID for this request to download the resource pack. The packet - /// for replying to a resource pack push must contain the same ID. + /// The random ID for this request to download the resource pack. + /// + /// The packet for replying to a resource pack push must contain the same + /// ID. pub id: Uuid, pub url: String, pub hash: String, diff --git a/azalea-client/src/plugins/task_pool.rs b/azalea-client/src/plugins/task_pool.rs index 56ebc7cf..5e9031d7 100644 --- a/azalea-client/src/plugins/task_pool.rs +++ b/azalea-client/src/plugins/task_pool.rs @@ -34,8 +34,9 @@ fn tick_global_task_pools(_main_thread_marker: Option<NonSend<NonSendMarker>>) { tick_global_task_pools_on_main_thread(); } -/// Helper for configuring and creating the default task pools. For end-users -/// who want full control, set up [`TaskPoolPlugin`] +/// Helper for configuring and creating the default task pools. +/// +/// For end-users who want full control, set up [`TaskPoolPlugin`] #[derive(Clone, Resource)] pub struct TaskPoolOptions { /// If the number of physical cores is less than min_total_threads, force @@ -85,15 +86,6 @@ impl Default for TaskPoolOptions { } impl TaskPoolOptions { - // /// Create a configuration that forces using the given number of threads. - // pub fn with_num_threads(thread_count: usize) -> Self { - // TaskPoolOptions { - // min_total_threads: thread_count, - // max_total_threads: thread_count, - // ..Default::default() - // } - // } - /// Inserts the default thread pools into the given resource map based on /// the configured values pub fn create_default_pools(&self) { @@ -160,7 +152,9 @@ pub struct TaskPoolThreadAssignmentPolicy { /// Under no circumstance use more than this many threads for this pool pub max_threads: usize, /// Target using this percentage of total cores, clamped by min_threads and - /// max_threads. It is permitted to use 1.0 to try to use all remaining + /// max_threads. + /// + /// It is permitted to use 1.0 to try to use all remaining /// threads pub percent: f32, } diff --git a/azalea-core/src/game_type.rs b/azalea-core/src/game_type.rs index 0b249246..db1d6bc5 100644 --- a/azalea-core/src/game_type.rs +++ b/azalea-core/src/game_type.rs @@ -24,7 +24,7 @@ impl GameMode { } } - /// Get the id of the game type, but return -1 if the game type is invalid. + /// Get the ID of the game mode, but return -1 if the game type is invalid. pub fn to_optional_id<T: Into<Option<GameMode>>>(game_type: T) -> i8 { match game_type.into() { Some(game_type) => game_type.to_id() as i8, diff --git a/azalea-core/src/position.rs b/azalea-core/src/position.rs index 9aebd80b..7feb24d2 100644 --- a/azalea-core/src/position.rs +++ b/azalea-core/src/position.rs @@ -484,8 +484,9 @@ pub struct Vec3i { pub z: i32, } -/// Chunk coordinates are used to represent where a chunk is in the world. You -/// can convert the x and z to block coordinates by multiplying them by 16. +/// Chunk coordinates are used to represent where a chunk is in the world. +/// +/// You can convert the x and z to block coordinates by multiplying them by 16. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] pub struct ChunkPos { pub x: i32, @@ -556,8 +557,8 @@ impl Hash for ChunkPos { u64::from(*self).hash(state); } } -/// nohash_hasher lets us have IntMap<ChunkPos, _> which is significantly faster -/// than a normal HashMap +/// `nohash_hasher` lets us have IntMap<ChunkPos, _> which is significantly +/// faster than a normal HashMap impl nohash_hasher::IsEnabled for ChunkPos {} /// The coordinates of a chunk section in the world. @@ -612,8 +613,9 @@ impl From<ChunkBlockPos> for u64 { } impl nohash_hasher::IsEnabled for ChunkBlockPos {} -/// The coordinates of a block inside a chunk section. Each coordinate should be -/// in the range 0..=15. +/// The coordinates of a block inside of a chunk section. +/// +/// Each coordinate should be in the range 0..=15. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] pub struct ChunkSectionBlockPos { pub x: u8, @@ -622,8 +624,9 @@ pub struct ChunkSectionBlockPos { } vec3_impl!(ChunkSectionBlockPos, u8); -/// The coordinates of a chunk inside a chunk section. Each coordinate should be -/// in the range 0..=3. +/// The coordinates of a biome inside of a chunk section. +/// +/// Each coordinate should be in the range 0..=3. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] pub struct ChunkSectionBiomePos { pub x: u8, @@ -648,7 +651,9 @@ impl From<ChunkBiomePos> for ChunkSectionBiomePos { } vec3_impl!(ChunkSectionBiomePos, u8); -/// The coordinates of a biome inside a chunk. Biomes are 4x4 blocks. +/// The coordinates of a biome inside a chunk. +/// +/// Biomes are 4x4 blocks. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] pub struct ChunkBiomePos { pub x: u8, diff --git a/azalea-core/src/registry_holder.rs b/azalea-core/src/registry_holder.rs index f5657dc6..7c5bfede 100644 --- a/azalea-core/src/registry_holder.rs +++ b/azalea-core/src/registry_holder.rs @@ -45,8 +45,9 @@ impl RegistryHolder { } } - /// Get the dimension type registry, or `None` if it doesn't exist. You - /// should do some type of error handling if this returns `None`. + /// Get the dimension type registry, or `None` if it doesn't exist. + /// + /// You should do some type of error handling if this returns `None`. pub fn dimension_type(&self) -> Option<RegistryType<DimensionTypeElement>> { let name = ResourceLocation::new("minecraft:dimension_type"); match self.get(&name) { diff --git a/azalea-entity/src/lib.rs b/azalea-entity/src/lib.rs index 1ffce394..4645e4ba 100644 --- a/azalea-entity/src/lib.rs +++ b/azalea-entity/src/lib.rs @@ -125,8 +125,10 @@ pub fn on_pos(offset: f32, chunk_storage: &ChunkStorage, pos: Position) -> Block pos } -/// The Minecraft UUID of the entity. For players, this is their actual player -/// UUID, and for other entities it's just random. +/// The Minecraft UUID of the entity. +/// +/// For players, this is their actual player UUID, and for other entities it's +/// just random. #[derive(Component, Deref, DerefMut, Clone, Copy, Default, PartialEq)] pub struct EntityUuid(Uuid); impl EntityUuid { @@ -181,7 +183,9 @@ impl From<&Position> for BlockPos { } /// The second most recent position of the entity that was sent over the -/// network. This is currently only updated for our own local player entities. +/// network. +/// +/// This is currently only updated for our own local player entities. #[derive(Component, Clone, Copy, Debug, Default, PartialEq, Deref, DerefMut)] pub struct LastSentPosition(Vec3); impl From<&LastSentPosition> for Vec3 { @@ -248,9 +252,10 @@ impl LookDirection { self.x_rot } - /// Update this look direction to the new value, while handling relative - /// rotations correctly and with the default Minecraft sensitivity to avoid - /// triggering anticheats. + /// Update this look direction to the new value. + /// + /// This handles relative rotations correctly and with the default Minecraft + /// sensitivity to avoid triggering anticheats. pub fn update(&mut self, new: LookDirection) { self.update_with_sensitivity(new, 1.); } @@ -353,8 +358,9 @@ pub struct Physics { /// and sets to 0 if we're not trying to jump. pub no_jump_delay: u32, - /// The bounding box of the entity. This is more than just width and height, - /// unlike dimensions. + /// The bounding box of the entity. + /// + /// This is more than just width and height, unlike dimensions. pub bounding_box: Aabb, pub has_impulse: bool, @@ -460,8 +466,9 @@ pub struct Dead; #[derive(Component, Clone, Copy, Debug, PartialEq, Deref)] pub struct EntityKindComponent(pub azalea_registry::EntityKind); -/// A bundle of components that every entity has. This doesn't contain metadata, -/// that has to be added separately. +/// A bundle of components that every entity has. +/// +/// This doesn't contain metadata; that has to be added separately. #[derive(Bundle)] pub struct EntityBundle { pub kind: EntityKindComponent, @@ -559,7 +566,9 @@ pub struct OnClimbable(bool); pub struct Crouching(bool); /// A component that contains the abilities the player has, like flying -/// or instantly breaking blocks. This is only present on local players. +/// or instantly breaking blocks. +/// +/// This is only present on local players. #[derive(Clone, Debug, Component, Default)] pub struct PlayerAbilities { pub invulnerable: bool, diff --git a/azalea-entity/src/mining.rs b/azalea-entity/src/mining.rs index ea521a9a..cd526799 100644 --- a/azalea-entity/src/mining.rs +++ b/azalea-entity/src/mining.rs @@ -5,7 +5,9 @@ use azalea_registry as registry; use crate::{FluidOnEyes, Physics, effects}; /// How much progress is made towards mining the block per tick, as a -/// percentage. If this is 1 then the block gets broken instantly. +/// percentage. +/// +/// If this is 1, then the block gets broken instantly. /// /// You can divide 1 by this and then round up to get the number of ticks it /// takes to mine the block. @@ -71,8 +73,9 @@ fn has_correct_tool_for_drops(block: &dyn BlockTrait, tool: registry::Item) -> b } /// Returns the destroy speed of the given block with the given tool, taking -/// into account enchantments and effects. If the player is not holding anything -/// then `tool` should be `Item::Air`. +/// enchantments and effects into account. +/// +/// If the player is not holding anything, then `tool` should be `Item::Air`. fn destroy_speed( block: registry::Block, tool: registry::Item, diff --git a/azalea-entity/src/particle.rs b/azalea-entity/src/particle.rs index ce5f5350..5b7bb6af 100644 --- a/azalea-entity/src/particle.rs +++ b/azalea-entity/src/particle.rs @@ -130,8 +130,10 @@ pub enum Particle { } impl From<ParticleKind> for Particle { - /// Convert a particle kind into particle data. If the particle has data - /// attached (like block particles), then it's set to the default. + /// Convert a particle kind into particle data. + /// + /// If the particle has data attached (like block particles), then it's set + /// to the default. fn from(kind: ParticleKind) -> Self { // this is mostly just here so it fails to compile when a new particle is added // to ParticleKind, since `Particle` has to be updated manually diff --git a/azalea-entity/src/plugin/indexing.rs b/azalea-entity/src/plugin/indexing.rs index f1926286..6f170dc6 100644 --- a/azalea-entity/src/plugin/indexing.rs +++ b/azalea-entity/src/plugin/indexing.rs @@ -45,9 +45,10 @@ impl EntityUuidIndex { } } -/// An index of Minecraft entity IDs to Azalea ECS entities. This is a -/// `Component` so local players can keep track of entity IDs independently from -/// the instance. +/// An index of Minecraft entity IDs to Azalea ECS entities. +/// +/// This is a `Component` so local players can keep track of entity IDs +/// independently from the instance. /// /// If you need a per-instance instead of per-client version of this, you can /// use [`Instance::entity_by_id`]. diff --git a/azalea-entity/src/plugin/mod.rs b/azalea-entity/src/plugin/mod.rs index e20ed860..a3ea11d0 100644 --- a/azalea-entity/src/plugin/mod.rs +++ b/azalea-entity/src/plugin/mod.rs @@ -80,8 +80,9 @@ fn debug_new_entity(query: Query<(Entity, Option<&LocalEntity>), Added<Minecraft } /// System that adds the [`Dead`] marker component if an entity's health is set -/// to 0 (or less than 0). This will be present if an entity is doing the death -/// animation. +/// to 0 (or less than 0). +/// +/// This will be present if an entity is doing the death animation. /// /// Entities that are dead cannot be revived. pub fn add_dead(mut commands: Commands, query: Query<(Entity, &Health), Changed<Health>>) { @@ -188,7 +189,9 @@ fn is_trapdoor_useable_as_ladder( } /// A component that lists all the local player entities that have this entity -/// loaded. If this is empty, the entity will be removed from the ECS. +/// loaded. +/// +/// If this is empty, the entity will be removed from the ECS. #[derive(Component, Clone, Deref, DerefMut)] pub struct LoadedBy(pub HashSet<Entity>); @@ -203,10 +206,13 @@ pub fn apply_clamp_look_direction(mut look_direction: LookDirection) -> LookDire look_direction } -/// Sets the position of the entity. This doesn't update the cache in -/// azalea-world, and should only be used within azalea-world! +/// Sets the position of the entity. +/// +/// This doesn't update the cache in azalea-world, and should only be used +/// within azalea-world. /// /// # Safety +/// /// Cached position in the world must be updated. #[allow(clippy::type_complexity)] pub fn update_bounding_box( diff --git a/azalea-entity/src/plugin/relative_updates.rs b/azalea-entity/src/plugin/relative_updates.rs index 1c0a899f..3917c946 100644 --- a/azalea-entity/src/plugin/relative_updates.rs +++ b/azalea-entity/src/plugin/relative_updates.rs @@ -54,6 +54,7 @@ impl RelativeEntityUpdate { } /// A component that counts the number of times this entity has been modified. +/// /// This is used for making sure two clients don't do the same relative update /// on an entity. /// @@ -102,15 +103,12 @@ impl EntityCommand for RelativeEntityUpdate { } } -/// The [`UpdatesReceived`] component should never be on [`LocalEntity`] -/// entities. This warns if an entity has both components. +/// A system that logs a warning if an entity has both [`UpdatesReceived`] +/// and [`LocalEntity`]. pub fn debug_detect_updates_received_on_local_entities( query: Query<Entity, (With<LocalEntity>, With<UpdatesReceived>)>, ) { for entity in &query { - warn!( - "Entity {:?} has both LocalEntity and UpdatesReceived", - entity - ); + warn!("Entity {entity:?} has both LocalEntity and UpdatesReceived"); } } diff --git a/azalea-inventory/azalea-inventory-macros/src/menu_impl.rs b/azalea-inventory/azalea-inventory-macros/src/menu_impl.rs index 4840f84c..1540fdff 100644 --- a/azalea-inventory/azalea-inventory-macros/src/menu_impl.rs +++ b/azalea-inventory/azalea-inventory-macros/src/menu_impl.rs @@ -174,14 +174,18 @@ pub fn generate(input: &DeclareMenus) -> TokenStream { }) } - /// Get the range of slot indexes that contain the player's inventory. This may be different for each menu. + /// Get the range of slot indexes that contain the player's inventory. + /// + /// This may be different for each menu. pub fn player_slots_range(&self) -> RangeInclusive<usize> { match self { #player_slots_range_match_variants } } - /// Get the range of slot indexes that contain the player's hotbar. This may be different for each menu. + /// Get the range of slot indexes that contain the player's hotbar. + /// + /// This may be different for each menu. /// /// ``` /// # let inventory = azalea_inventory::Menu::Player(azalea_inventory::Player::default()); @@ -192,7 +196,9 @@ pub fn generate(input: &DeclareMenus) -> TokenStream { ((*self.player_slots_range().end() - 8)..=*self.player_slots_range().end()) } - /// Get the range of slot indexes that contain the player's inventory, not including the hotbar. This may be different for each menu. + /// Get the range of slot indexes that contain the player's inventory, not including the hotbar. + /// + /// This may be different for each menu. pub fn player_slots_without_hotbar_range(&self) -> RangeInclusive<usize> { (*self.player_slots_range().start()..=*self.player_slots_range().end() - 9) } diff --git a/azalea-inventory/src/operations.rs b/azalea-inventory/src/operations.rs index 97ae1e60..fc42e498 100644 --- a/azalea-inventory/src/operations.rs +++ b/azalea-inventory/src/operations.rs @@ -27,11 +27,13 @@ pub enum ClickOperation { #[derive(Debug, Clone)] pub enum PickupClick { - /// Left mouse click. Note that in the protocol, None is represented as - /// -999. + /// Left mouse click. + /// + /// Note that in the protocol, None is represented as -999. Left { slot: Option<u16> }, - /// Right mouse click. Note that in the protocol, None is represented as - /// -999. + /// Right mouse click. + /// + /// Note that in the protocol, None is represented as -999. Right { slot: Option<u16> }, /// Drop cursor stack. LeftOutside, @@ -134,11 +136,13 @@ impl From<QuickCraftStatus> for QuickCraftStatusKind { } } -/// Double click +/// Double click. #[derive(Debug, Clone)] pub struct PickupAllClick { - /// The slot that we're double clicking on. It should be empty or at least - /// not pickup-able (since the carried item is used as the filter). + /// The slot that we're double clicking on. + /// + /// It should be empty or at least not pickup-able (since the carried item + /// is used as the filter). pub slot: u16, /// Impossible in vanilla clients. pub reversed: bool, diff --git a/azalea-inventory/src/slot.rs b/azalea-inventory/src/slot.rs index 2d4202e8..d19ab177 100644 --- a/azalea-inventory/src/slot.rs +++ b/azalea-inventory/src/slot.rs @@ -146,8 +146,9 @@ impl Serialize for ItemStack { } } -/// An item in an inventory, with a count and NBT. Usually you want -/// [`ItemStack`] or [`azalea_registry::Item`] instead. +/// An item in an inventory, with a count and a set of data components. +/// +/// Usually you want [`ItemStack`] or [`azalea_registry::Item`] instead. #[derive(Debug, Clone, PartialEq, Serialize)] pub struct ItemStackData { #[serde(rename = "id")] diff --git a/azalea-physics/src/collision/entity_collisions.rs b/azalea-physics/src/collision/entity_collisions.rs index af2db1f0..de70b2b9 100644 --- a/azalea-physics/src/collision/entity_collisions.rs +++ b/azalea-physics/src/collision/entity_collisions.rs @@ -14,8 +14,8 @@ use tracing::error; use super::VoxelShape; -/// This query matches on entities that we can collide with. That is, boats and -/// shulkers. +/// This query matches on entities that we can collide with (boats and +/// shulkers). /// /// If you want to use this in a more complex query, use /// [`CollidableEntityFilter`] as a filter instead. diff --git a/azalea-physics/src/local_player.rs b/azalea-physics/src/local_player.rs index f36e7ede..f2f213d8 100644 --- a/azalea-physics/src/local_player.rs +++ b/azalea-physics/src/local_player.rs @@ -1,8 +1,9 @@ use azalea_core::position::Vec2; use bevy_ecs::component::Component; -/// Component for entities that can move and sprint. Usually only in -/// [`LocalEntity`]s. +/// Component for entities that can move and sprint. +/// +/// Usually only present for [`LocalEntity`]s. /// /// [`LocalEntity`]: azalea_entity::LocalEntity #[derive(Default, Component, Clone)] diff --git a/azalea-protocol/azalea-protocol-macros/src/lib.rs b/azalea-protocol/azalea-protocol-macros/src/lib.rs index feff2ded..bba35762 100644 --- a/azalea-protocol/azalea-protocol-macros/src/lib.rs +++ b/azalea-protocol/azalea-protocol-macros/src/lib.rs @@ -367,7 +367,7 @@ pub fn declare_state_packets(input: TokenStream) -> TokenStream { } } - /// Read a packet by its id, ConnectionProtocol, and flow. + /// Read a packet by its ID, `ConnectionProtocol`, and flow. fn read( id: u32, buf: &mut std::io::Cursor<&[u8]>, @@ -411,7 +411,7 @@ pub fn declare_state_packets(input: TokenStream) -> TokenStream { } } - /// Read a packet by its id, ConnectionProtocol, and flow. + /// Read a packet by its ID, `ConnectionProtocol`, and flow. fn read( id: u32, buf: &mut std::io::Cursor<&[u8]>, diff --git a/azalea-protocol/src/common/client_information.rs b/azalea-protocol/src/common/client_information.rs index 690d052a..5dedd1a8 100644 --- a/azalea-protocol/src/common/client_information.rs +++ b/azalea-protocol/src/common/client_information.rs @@ -5,8 +5,9 @@ use azalea_core::bitset::FixedBitSet; use bevy_ecs::component::Component; /// A component that contains some of the "settings" for this client that are -/// sent to the server, such as render distance. This is only present on local -/// players. +/// sent to the server, such as render distance. +/// +/// This is only present on local players. #[derive(Clone, Debug, AzBuf, PartialEq, Eq, Component)] pub struct ClientInformation { /// The locale of the client. @@ -14,11 +15,13 @@ pub struct ClientInformation { /// The view distance of the client in chunks, same as the render distance /// in-game. pub view_distance: u8, - /// The types of chat messages the client wants to receive. Note that many - /// servers ignore this. + /// The types of chat messages the client wants to receive. + /// + /// Note that this is enforced by the server, and many servers ignore this. pub chat_visibility: ChatVisibility, - /// Whether the messages sent from the server should have colors. Note that - /// many servers ignore this and always send colored messages. + /// Whether the messages sent from the server should have colors. + /// + /// Note that many servers ignore this and always send colored messages. pub chat_colors: bool, pub model_customization: ModelCustomization, pub main_hand: HumanoidArm, diff --git a/azalea-protocol/src/connect.rs b/azalea-protocol/src/connect.rs index 78ad6d81..febb2337 100644 --- a/azalea-protocol/src/connect.rs +++ b/azalea-protocol/src/connect.rs @@ -247,7 +247,9 @@ where self.writer.write(packet).await } - /// Split the reader and writer into two objects. This doesn't allocate. + /// Split the reader and writer into two objects. + /// + /// This doesn't allocate. #[must_use] pub fn into_split(self) -> (ReadConnection<R>, WriteConnection<W>) { (self.reader, self.writer) @@ -304,8 +306,9 @@ impl Connection<ClientboundHandshakePacket, ServerboundHandshakePacket> { Self::new_from_stream(stream).await } - /// Create a new connection to the given address and Socks5 proxy. If you're - /// not using a proxy, use [`Self::new`] instead. + /// Create a new connection to the given address and Socks5 proxy. + /// + /// If you're not using a proxy, use [`Self::new`] instead. pub async fn new_with_proxy( address: &SocketAddr, proxy: Proxy, @@ -320,8 +323,10 @@ impl Connection<ClientboundHandshakePacket, ServerboundHandshakePacket> { Self::new_from_stream(stream.into_inner()).await } - /// Create a new connection from an existing stream. Useful if you want to - /// set custom options on the stream. Otherwise, just use [`Self::new`]. + /// Create a new connection from an existing stream. + /// + /// Useful if you want to set custom options on the stream. Otherwise, just + /// use [`Self::new`]. pub async fn new_from_stream(stream: TcpStream) -> Result<Self, ConnectionError> { let (read_stream, write_stream) = stream.into_split(); @@ -346,15 +351,17 @@ impl Connection<ClientboundHandshakePacket, ServerboundHandshakePacket> { }) } - /// Change our state from handshake to login. This is the state that is used - /// for logging in. + /// Change our state from handshake to login. + /// + /// This is the state that is used for logging in. #[must_use] pub fn login(self) -> Connection<ClientboundLoginPacket, ServerboundLoginPacket> { Connection::from(self) } - /// Change our state from handshake to status. This is the state that is - /// used for pinging the server. + /// Change our state from handshake to status. + /// + /// This is the state that is used for pinging the server. #[must_use] pub fn status(self) -> Connection<ClientboundStatusPacket, ServerboundStatusPacket> { Connection::from(self) @@ -363,9 +370,10 @@ impl Connection<ClientboundHandshakePacket, ServerboundHandshakePacket> { impl Connection<ClientboundLoginPacket, ServerboundLoginPacket> { /// Set our compression threshold, i.e. the maximum size that a packet is - /// allowed to be without getting compressed. Setting it to 0 means every - /// packet will be compressed. If you set it to less than 0, - /// then compression is disabled. + /// allowed to be without getting compressed. + /// + /// Setting it to 0 means every packet will be compressed. If you set it to + /// less than 0 then compression is disabled. pub fn set_compression_threshold(&mut self, threshold: i32) { // if you pass a threshold of less than 0, compression is disabled if threshold >= 0 { @@ -377,24 +385,28 @@ impl Connection<ClientboundLoginPacket, ServerboundLoginPacket> { } } - /// Set the encryption key that is used to encrypt and decrypt packets. It's - /// the same for both reading and writing. + /// Set the encryption key that is used to encrypt and decrypt packets. + /// + /// It's the same for both reading and writing. pub fn set_encryption_key(&mut self, key: [u8; 16]) { let (enc_cipher, dec_cipher) = azalea_crypto::create_cipher(&key); self.reader.raw.dec_cipher = Some(dec_cipher); self.writer.raw.enc_cipher = Some(enc_cipher); } - /// Change our state from login to configuration. This is the state where - /// the server sends us the registries and resource pack and stuff. + /// Change our state from login to configuration. + /// + /// This is the state where the server sends us the registries and the + /// resource pack. #[must_use] pub fn config(self) -> Connection<ClientboundConfigPacket, ServerboundConfigPacket> { Connection::from(self) } /// Authenticate with Minecraft's servers, which is required to join - /// online-mode servers. This must happen when you get a - /// `ClientboundLoginPacket::Hello` packet. + /// online-mode servers. + /// + /// This must happen when you get a `ClientboundLoginPacket::Hello` packet. /// /// # Examples /// @@ -460,15 +472,18 @@ impl Connection<ClientboundLoginPacket, ServerboundLoginPacket> { } impl Connection<ServerboundHandshakePacket, ClientboundHandshakePacket> { - /// Change our state from handshake to login. This is the state that is used - /// for logging in. + /// Change our state from handshake to login. + /// + /// This is the state that is used while negotiating encryption and + /// authenticating with Mojang. #[must_use] pub fn login(self) -> Connection<ServerboundLoginPacket, ClientboundLoginPacket> { Connection::from(self) } - /// Change our state from handshake to status. This is the state that is - /// used for pinging the server. + /// Change our state from handshake to status. + /// + /// This is the state that is used for pinging the server. #[must_use] pub fn status(self) -> Connection<ServerboundStatusPacket, ClientboundStatusPacket> { Connection::from(self) @@ -477,8 +492,9 @@ impl Connection<ServerboundHandshakePacket, ClientboundHandshakePacket> { impl Connection<ServerboundLoginPacket, ClientboundLoginPacket> { /// Set our compression threshold, i.e. the maximum size that a packet is - /// allowed to be without getting compressed. If you set it to less than 0 - /// then compression gets disabled. + /// allowed to be without getting compressed. + /// + /// If you set it to less than 0 then compression gets disabled. pub fn set_compression_threshold(&mut self, threshold: i32) { // if you pass a threshold of less than 0, compression is disabled if threshold >= 0 { @@ -490,16 +506,18 @@ impl Connection<ServerboundLoginPacket, ClientboundLoginPacket> { } } - /// Set the encryption key that is used to encrypt and decrypt packets. It's - /// the same for both reading and writing. + /// Set the encryption key that is used to encrypt and decrypt packets. + /// + /// It's the same for both reading and writing. pub fn set_encryption_key(&mut self, key: [u8; 16]) { let (enc_cipher, dec_cipher) = azalea_crypto::create_cipher(&key); self.reader.raw.dec_cipher = Some(dec_cipher); self.writer.raw.enc_cipher = Some(enc_cipher); } - /// Change our state from login to game. This is the state that's used when - /// the client is actually in the game. + /// Change our state from login to game. + /// + /// This is the state that's used when the client is actually in the game. #[must_use] pub fn game(self) -> Connection<ServerboundGamePacket, ClientboundGamePacket> { Connection::from(self) @@ -526,8 +544,9 @@ impl Connection<ServerboundLoginPacket, ClientboundLoginPacket> { } impl Connection<ServerboundConfigPacket, ClientboundConfigPacket> { - /// Change our state from configuration to game. This is the state that's - /// used when the client is actually in the world. + /// Change our state from configuration to game. + /// + /// This is the state that's used when the client is actually in the world. #[must_use] pub fn game(self) -> Connection<ServerboundGamePacket, ClientboundGamePacket> { Connection::from(self) @@ -535,8 +554,9 @@ impl Connection<ServerboundConfigPacket, ClientboundConfigPacket> { } impl Connection<ClientboundConfigPacket, ServerboundConfigPacket> { - /// Change our state from configuration to game. This is the state that's - /// used when the client is actually in the world. + /// Change our state from configuration to game. + /// + /// This is the state that's used when the client is actually in the world. #[must_use] pub fn game(self) -> Connection<ClientboundGamePacket, ServerboundGamePacket> { Connection::from(self) diff --git a/azalea-protocol/src/lib.rs b/azalea-protocol/src/lib.rs index fd092293..fdba34bc 100644 --- a/azalea-protocol/src/lib.rs +++ b/azalea-protocol/src/lib.rs @@ -71,9 +71,11 @@ impl TryFrom<String> for ServerAddress { } impl From<SocketAddr> for ServerAddress { - /// Convert an existing `SocketAddr` into a `ServerAddress`. This just - /// converts the ip to a string and passes along the port. The resolver - /// will realize it's already an IP address and not do any DNS requests. + /// Convert an existing `SocketAddr` into a `ServerAddress`. + /// + /// This just converts the IP to a string and passes along the port. The + /// resolver will realize it's already an IP address and not do any DNS + /// requests. fn from(addr: SocketAddr) -> Self { ServerAddress { host: addr.ip().to_string(), @@ -88,8 +90,9 @@ impl Display for ServerAddress { } } -/// Serde deserialization for ServerAddress. This is useful for config file -/// usage. +/// Serde deserialization for ServerAddress. +/// +/// This is useful if you're storing the server address in a config file. impl<'de> serde::Deserialize<'de> for ServerAddress { fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where @@ -100,8 +103,9 @@ impl<'de> serde::Deserialize<'de> for ServerAddress { } } -/// Serde serialization for ServerAddress. This uses the Display impl, so it -/// will serialize to a string. +/// Serde serialization for ServerAddress. +/// +/// This uses the Display impl, so it will serialize to a string. impl serde::Serialize for ServerAddress { fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where diff --git a/azalea-protocol/src/packets/game/c_add_entity.rs b/azalea-protocol/src/packets/game/c_add_entity.rs index 7fb680a1..fe473289 100644 --- a/azalea-protocol/src/packets/game/c_add_entity.rs +++ b/azalea-protocol/src/packets/game/c_add_entity.rs @@ -30,8 +30,9 @@ pub struct ClientboundAddEntity { } impl ClientboundAddEntity { - /// Make the entity into a bundle that can be inserted into the ECS. You - /// must apply the metadata after inserting the bundle with + /// Make the entity into a bundle that can be inserted into the ECS. + /// + /// You must apply the metadata after inserting the bundle with /// [`Self::apply_metadata`]. pub fn as_entity_bundle(&self, world_name: ResourceLocation) -> EntityBundle { EntityBundle::new(self.uuid, self.position, self.entity_type, world_name) diff --git a/azalea-protocol/src/packets/game/c_map_item_data.rs b/azalea-protocol/src/packets/game/c_map_item_data.rs index 4bd2b21d..eaf5dc9f 100644 --- a/azalea-protocol/src/packets/game/c_map_item_data.rs +++ b/azalea-protocol/src/packets/game/c_map_item_data.rs @@ -19,7 +19,7 @@ pub struct MapDecoration { pub decoration_type: DecorationType, pub x: i8, pub y: i8, - /// Minecraft does & 15 on this value, azalea-protocol doesn't. I don't + /// Minecraft does `& 15` on this value and azalea-protocol doesn't. I don't /// think it matters. pub rot: i8, pub name: Option<FormattedText>, diff --git a/azalea-protocol/src/packets/game/c_player_chat.rs b/azalea-protocol/src/packets/game/c_player_chat.rs index 1e65864c..75683c21 100644 --- a/azalea-protocol/src/packets/game/c_player_chat.rs +++ b/azalea-protocol/src/packets/game/c_player_chat.rs @@ -41,7 +41,7 @@ pub struct PackedLastSeenMessages { pub entries: Vec<PackedMessageSignature>, } -/// Messages can be deleted by either their signature or message id. +/// Messages can be deleted by either their signature or message ID. #[derive(Clone, Debug, PartialEq)] pub enum PackedMessageSignature { Signature(Box<MessageSignature>), @@ -88,9 +88,10 @@ pub struct MessageSignatureCache { } impl ClientboundPlayerChat { - /// Returns the content of the message. If you want to get the FormattedText - /// for the whole message including the sender part, use - /// [`ClientboundPlayerChat::message`]. + /// Returns the content of the message. + /// + /// If you want to get the [`FormattedText`] for the whole message including + /// the sender part, use [`ClientboundPlayerChat::message`]. #[must_use] pub fn content(&self) -> FormattedText { self.unsigned_content diff --git a/azalea-protocol/src/packets/game/s_use_item_on.rs b/azalea-protocol/src/packets/game/s_use_item_on.rs index e97d8aaf..61d7fc78 100644 --- a/azalea-protocol/src/packets/game/s_use_item_on.rs +++ b/azalea-protocol/src/packets/game/s_use_item_on.rs @@ -24,9 +24,10 @@ pub struct BlockHit { pub block_pos: BlockPos, /// The face of the block that was clicked. pub direction: Direction, - /// The exact coordinates of the world where the block was clicked. In the - /// network, this is transmitted as the difference between the location and - /// block position. + /// The exact coordinates of the world where the block was clicked. + /// + /// In the network, this is transmitted as the difference between the + /// location and block position. pub location: Vec3, /// Whether the player's head is inside a block. pub inside: bool, diff --git a/azalea-protocol/src/packets/mod.rs b/azalea-protocol/src/packets/mod.rs index e532ebcd..cbcf4d6d 100644 --- a/azalea-protocol/src/packets/mod.rs +++ b/azalea-protocol/src/packets/mod.rs @@ -50,7 +50,7 @@ where /// like `pong`. fn name(&self) -> &'static str; - /// Read a packet by its id, `ConnectionProtocol`, and flow + /// Read a packet by its ID, `ConnectionProtocol`, and flow. fn read(id: u32, buf: &mut Cursor<&[u8]>) -> Result<Self, Box<ReadPacketError>>; fn write(&self, buf: &mut impl Write) -> io::Result<()>; diff --git a/azalea-protocol/src/read.rs b/azalea-protocol/src/read.rs index 433a2718..d4357c9f 100644 --- a/azalea-protocol/src/read.rs +++ b/azalea-protocol/src/read.rs @@ -83,7 +83,7 @@ pub enum FrameSplitterError { } /// Read a length, then read that amount of bytes from the `Cursor<Vec<u8>>`. If -/// there's not enough data, return None +/// there's not enough data, `None` is returned. fn parse_frame(buffer: &mut Cursor<Vec<u8>>) -> Result<Box<[u8]>, FrameSplitterError> { // copy the buffer first and read from the copy, then once we make sure // the packet is all good we read it fully @@ -183,8 +183,10 @@ pub enum DecompressionError { AboveCompressionThreshold { size: u32, maximum: u32 }, } -/// Get the decompressed bytes from a packet. It must have been decrypted -/// first. +/// Get the decompressed bytes from a packet. +/// +/// The stream must have already been decrypted before passing it to this +/// function. pub fn compression_decoder( stream: &mut Cursor<&[u8]>, compression_threshold: u32, diff --git a/azalea-registry/README.md b/azalea-registry/README.md index d70dd971..a0121972 100644 --- a/azalea-registry/README.md +++ b/azalea-registry/README.md @@ -1,3 +1,5 @@ # Azalea Registry -Minecraft has a concept called "registries", which are primarily used to determine ids in the protocol. The contents of this crate are automatically generated using Minecraft's built-in data generator. +Minecraft has a concept called "registries", which are primarily used to determine IDs in the protocol. + +The contents of this crate are automatically generated using Minecraft's built-in data generator. diff --git a/azalea-registry/src/lib.rs b/azalea-registry/src/lib.rs index 6c1bf7af..88b154a2 100644 --- a/azalea-registry/src/lib.rs +++ b/azalea-registry/src/lib.rs @@ -29,8 +29,9 @@ where fn to_u32(&self) -> u32; } -/// A registry that might not be present. This is transmitted as a single -/// varint in the protocol. +/// A registry that might not be present. +/// +/// This is transmitted as a single varint in the protocol. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub struct OptionalRegistry<T: Registry>(pub Option<T>); @@ -337,8 +338,10 @@ enum Attribute { } registry! { -/// An enum of every type of block in the game. To represent a block *state*, -/// use [`azalea_block::BlockState`] or [`azalea_block::BlockTrait`]. +/// An enum of every type of block in the game. +/// +/// To represent a block *state*, use [`azalea_block::BlockState`] or +/// [`azalea_block::BlockTrait`]. /// /// [`azalea_block::BlockState`]: https://docs.rs/azalea-block/latest/azalea_block/struct.BlockState.html /// [`azalea_block::BlockTrait`]: https://docs.rs/azalea-block/latest/azalea_block/trait.BlockTrait.html @@ -1513,9 +1516,10 @@ enum Block { } registry! { -/// An enum that contains every type of block entity. A block entity is a block -/// that contains data that can't be represented as just a block state, like -/// how chests store items. +/// An enum that contains every type of block entity. +/// +/// A block entity is a block that contains data that can't be represented as +/// just a block state, like how chests store items. enum BlockEntityKind { Furnace => "minecraft:furnace", Chest => "minecraft:chest", diff --git a/azalea-world/src/chunk_storage.rs b/azalea-world/src/chunk_storage.rs index d38c5ef9..35d8cac3 100644 --- a/azalea-world/src/chunk_storage.rs +++ b/azalea-world/src/chunk_storage.rs @@ -28,7 +28,9 @@ use crate::{ const SECTION_HEIGHT: u32 = 16; /// An efficient storage of chunks for a client that has a limited render -/// distance. This has support for using a shared [`ChunkStorage`]. +/// distance. +/// +/// This has support for using a shared [`ChunkStorage`]. pub struct PartialChunkStorage { /// The center of the view, i.e. the chunk the player is currently in. view_center: ChunkPos, @@ -39,8 +41,9 @@ pub struct PartialChunkStorage { } /// A storage for chunks where they're only stored weakly, so if they're not -/// actively being used somewhere else they'll be forgotten. This is used for -/// shared worlds. +/// actively being used somewhere else they'll be forgotten. +/// +/// This is used for shared worlds. /// /// This is relatively cheap to clone since it's just an `IntMap` with `Weak` /// pointers. @@ -51,10 +54,11 @@ pub struct ChunkStorage { pub map: IntMap<ChunkPos, Weak<RwLock<Chunk>>>, } -/// A single chunk in a world (16*?*16 blocks). This only contains the blocks -/// and biomes. You can derive the height of the chunk from the number of -/// sections, but you need a [`ChunkStorage`] to get the minimum Y -/// coordinate. +/// A single chunk in a world (16*?*16 blocks). +/// +/// This only contains blocks and biomes. You can derive the height of the chunk +/// from the number of sections, but you need a [`ChunkStorage`] to get the +/// minimum Y coordinate. #[derive(Debug)] pub struct Chunk { pub sections: Box<[Section]>, @@ -72,8 +76,9 @@ pub struct Section { pub biomes: PalettedContainer<Biome>, } -/// Get the actual stored view distance for the selected view distance. For some -/// reason Minecraft actually stores an extra 3 chunks. +/// Get the actual stored view distance for the selected view distance. +/// +/// For some reason, Minecraft stores an extra 3 chunks. pub fn calculate_chunk_storage_range(view_distance: u32) -> u32 { u32::max(view_distance, 2) + 3 } @@ -98,8 +103,10 @@ impl PartialChunkStorage { } } - /// Update the chunk to center the view on. This should be called when the - /// client receives a `SetChunkCacheCenter` packet. + /// Update the chunk to center the view on. + /// + /// This should be called when the client receives a `SetChunkCacheCenter` + /// packet. pub fn update_view_center(&mut self, view_center: ChunkPos) { // this code block makes it force unload the chunks that are out of range after // updating the view center. it's usually fine without it but the commented code @@ -211,8 +218,9 @@ impl PartialChunkStorage { self.chunks[index].as_ref() } /// Get a mutable reference to a [`Chunk`] within render distance, or - /// `None` if it's not loaded. Use [`ChunkStorage::get`] to get - /// a chunk from the shared storage. + /// `None` if it's not loaded. + /// + /// Use [`ChunkStorage::get`] to get a chunk from the shared storage. pub fn limited_get_mut(&mut self, pos: &ChunkPos) -> Option<&mut Option<Arc<RwLock<Chunk>>>> { if !self.in_range(pos) { return None; @@ -224,8 +232,9 @@ impl PartialChunkStorage { } /// Set a chunk in the shared storage and reference it from the limited - /// storage. Use [`Self::limited_set`] if you already have an - /// `Arc<RwLock<Chunk>>`. + /// storage. + /// + /// Use [`Self::limited_set`] if you already have an `Arc<RwLock<Chunk>>`. /// /// # Panics /// If the chunk is not in the render distance. diff --git a/azalea-world/src/container.rs b/azalea-world/src/container.rs index bb8ade70..279f3061 100644 --- a/azalea-world/src/container.rs +++ b/azalea-world/src/container.rs @@ -13,8 +13,10 @@ use tracing::{debug, error}; use crate::{ChunkStorage, Instance}; -/// A container of [`Instance`]s (aka worlds). Instances are stored as a Weak -/// pointer here, so if no clients are using an instance it will be forgotten. +/// A container of [`Instance`]s (aka worlds). +/// +/// Instances are stored as a Weak pointer here, so if no clients are using an +/// instance it will be forgotten. #[derive(Default, Resource)] pub struct InstanceContainer { // We just refer to the chunks here and don't include entities because there's not that many @@ -85,8 +87,9 @@ impl InstanceContainer { } } -/// The name of the [`Instance`](crate::Instance) (world) the entity is -/// in. If two entities share the same instance name, we assume they're in the +/// The name of the [`Instance`] (aka world/dimension) that the entity is in. +/// +/// If two entities share the same instance name, we assume they're in the /// same instance. #[derive(Component, Clone, Debug, PartialEq, Deref, DerefMut)] #[doc(alias("worldname", "world name"))] diff --git a/azalea-world/src/find_blocks.rs b/azalea-world/src/find_blocks.rs index 4086358f..17e66754 100644 --- a/azalea-world/src/find_blocks.rs +++ b/azalea-world/src/find_blocks.rs @@ -224,7 +224,7 @@ pub fn find_blocks_in_chunk( let block_state = section.states.get_at_index(i); if block_states.contains(&block_state) { - let section_pos = section.states.coords_from_index(i); + let section_pos = section.states.pos_from_index(i); let (x, y, z) = ( chunk_pos.x * 16 + (section_pos.x as i32), min_y + (section_index * 16) as i32 + section_pos.y as i32, diff --git a/azalea-world/src/iterators.rs b/azalea-world/src/iterators.rs index 3362487b..eb6b2052 100644 --- a/azalea-world/src/iterators.rs +++ b/azalea-world/src/iterators.rs @@ -77,8 +77,9 @@ impl Iterator for BlockIterator { } } -/// A spiral iterator, useful for iterating over chunks in a world. Use -/// `ChunkIterator` to sort by x+y+z (Manhattan) distance. +/// A spiral iterator, useful for iterating over chunks in a world. +/// +/// You can use [`ChunkIterator`] instead to sort by x+y+z (Manhattan) distance. /// /// ``` /// # use azalea_core::position::ChunkPos; diff --git a/azalea-world/src/palette/container.rs b/azalea-world/src/palette/container.rs index 0ddac6c2..4aae64de 100644 --- a/azalea-world/src/palette/container.rs +++ b/azalea-world/src/palette/container.rs @@ -151,14 +151,14 @@ impl<S: PalletedContainerKind> PalettedContainer<S> { }) } - /// Calculates the index of the given coordinates. - pub fn index_from_coords(&self, pos: S::SectionPos) -> usize { + /// Calculates the index of the given position. + pub fn index_from_pos(&self, pos: S::SectionPos) -> usize { let size_bits = S::size_bits(); let (x, y, z) = pos.coords(); (((y << size_bits) | z) << size_bits) | x } - pub fn coords_from_index(&self, index: usize) -> S::SectionPos { + pub fn pos_from_index(&self, index: usize) -> S::SectionPos { let size_bits = S::size_bits(); let mask = (1 << size_bits) - 1; S::SectionPos::new( @@ -173,8 +173,8 @@ impl<S: PalletedContainerKind> PalettedContainer<S> { /// # Panics /// /// This function panics if the index is greater than or equal to the number - /// of things in the storage. (So for block states, it must be less than - /// 4096). + /// of things in the storage. For example, for block states, it must be less + /// than 4096. pub fn get_at_index(&self, index: usize) -> S { // first get the palette id let paletted_value = self.storage.get(index); @@ -182,32 +182,30 @@ impl<S: PalletedContainerKind> PalettedContainer<S> { self.palette.value_for(paletted_value as usize) } - /// Returns the value at the given coordinates. + /// Returns the value at the given position. pub fn get(&self, pos: S::SectionPos) -> S { - // let paletted_value = self.storage.get(self.get_index(x, y, z)); - // self.palette.value_for(paletted_value as usize) - self.get_at_index(self.index_from_coords(pos)) + self.get_at_index(self.index_from_pos(pos)) } - /// Sets the id at the given coordinates and return the previous id + /// Sets the ID at the given position and return the previous ID. pub fn get_and_set(&mut self, pos: S::SectionPos, value: S) -> S { let paletted_value = self.id_for(value); let old_paletted_value = self .storage - .get_and_set(self.index_from_coords(pos), paletted_value as u64); + .get_and_set(self.index_from_pos(pos), paletted_value as u64); self.palette.value_for(old_paletted_value as usize) } - /// Sets the id at the given index and return the previous id. You probably + /// Sets the ID at the given index and return the previous ID. You probably /// want `.set` instead. pub fn set_at_index(&mut self, index: usize, value: S) { let paletted_value = self.id_for(value); self.storage.set(index, paletted_value as u64); } - /// Sets the id at the given coordinates and return the previous id + /// Sets the ID at the given position and return the previous ID. pub fn set(&mut self, pos: S::SectionPos, value: S) { - self.set_at_index(self.index_from_coords(pos), value); + self.set_at_index(self.index_from_pos(pos), value); } fn create_or_reuse_data(&self, bits_per_entry: u8) -> PalettedContainer<S> { diff --git a/azalea-world/src/palette/tests.rs b/azalea-world/src/palette/tests.rs index d1423306..39031a38 100644 --- a/azalea-world/src/palette/tests.rs +++ b/azalea-world/src/palette/tests.rs @@ -69,8 +69,8 @@ fn test_coords_from_index() { for y in 0..15 { for z in 0..15 { assert_eq!( - palette_container.coords_from_index( - palette_container.index_from_coords(ChunkSectionBlockPos::new(x, y, z)) + palette_container.pos_from_index( + palette_container.index_from_pos(ChunkSectionBlockPos::new(x, y, z)) ), ChunkSectionBlockPos::new(x, y, z) ); diff --git a/azalea-world/src/world.rs b/azalea-world/src/world.rs index 082ba7bc..969b7d36 100644 --- a/azalea-world/src/world.rs +++ b/azalea-world/src/world.rs @@ -119,11 +119,10 @@ impl From<u32> for MinecraftEntityId { /// world. #[derive(Debug, Default)] pub struct PartialEntityInfos { - // note: using MinecraftEntityId for entity ids is acceptable here since - // there's no chance of collisions here - /// The entity id of the player that owns this partial world. This will - /// make `RelativeEntityUpdate` pretend this entity doesn't exist so - /// it doesn't get modified from outside sources. + /// The entity ID of the player that owns this partial world. + /// + /// This will make `RelativeEntityUpdate` pretend this entity doesn't exist + /// so it doesn't get modified from outside sources. pub owner_entity: Option<Entity>, /// A counter for each entity that tracks how many updates we've observed /// for it. @@ -131,6 +130,8 @@ pub struct PartialEntityInfos { /// This is used for shared worlds (i.e. swarms), to make sure we don't /// update entities twice on accident. pub updates_received: IntMap<MinecraftEntityId, u32>, + // ^ note: using MinecraftEntityId for entity ids is acceptable here since + // there's no chance of collisions } impl PartialEntityInfos { diff --git a/azalea/README.md b/azalea/README.md index 5d0b6d5f..7860741a 100644 --- a/azalea/README.md +++ b/azalea/README.md @@ -57,9 +57,11 @@ async fn main() { #[derive(Default, Clone, Component)] pub struct State { /// An example field that stores the number of messages that've been - /// received by the client so far. The state gets cloned whenever the - /// handler is called, so to have all the clones point to the same data and - /// have it be mutable, we use an Arc<Mutex<T>>. + /// received by the client so far. + /// + /// The state gets cloned whenever the handler is called, so to have all + /// the clones point to the same data and have it be mutable, we use an + /// Arc<Mutex<T>>. pub messages_received: Arc<Mutex<usize>> } diff --git a/azalea/examples/testbot/commands/debug.rs b/azalea/examples/testbot/commands/debug.rs index b98d737f..d80ee3be 100644 --- a/azalea/examples/testbot/commands/debug.rs +++ b/azalea/examples/testbot/commands/debug.rs @@ -58,7 +58,7 @@ pub fn register(commands: &mut CommandDispatcher<Mutex<CommandSource>>) { }; let entity_id = source.bot.entity_component::<MinecraftEntityId>(entity); source.reply(format!( - "Your Minecraft ID is {} and your ECS id is {entity:?}", + "Your Minecraft ID is {} and your ECS ID is {entity:?}", *entity_id )); 1 diff --git a/azalea/examples/testbot/main.rs b/azalea/examples/testbot/main.rs index 249f7b92..b4ef20ba 100644 --- a/azalea/examples/testbot/main.rs +++ b/azalea/examples/testbot/main.rs @@ -127,8 +127,7 @@ async fn handle(bot: Client, event: azalea::Event, state: State) -> anyhow::Resu bot.set_client_information(ClientInformation { view_distance: 32, ..Default::default() - }) - .await; + }); if swarm.args.pathfinder_debug_particles { bot.ecs .lock() diff --git a/azalea/src/bot.rs b/azalea/src/bot.rs index 1897f510..6d7dc774 100644 --- a/azalea/src/bot.rs +++ b/azalea/src/bot.rs @@ -57,8 +57,10 @@ impl Plugin for BotPlugin { } } -/// A component that clients with [`BotPlugin`] will have. If you just want to -/// check if an entity is one of our bots, you should use [`LocalEntity`]. +/// A component that clients with [`BotPlugin`] will have. +/// +/// If you just want to check if an entity is one of our bots, you should use +/// [`LocalEntity`]. #[derive(Default, Component)] pub struct Bot { jumping_once: bool, @@ -97,8 +99,10 @@ pub trait BotClientExt { fn wait_ticks(&self, n: usize) -> impl Future<Output = ()> + Send; /// Wait for the specified number of ECS `Update`s. fn wait_updates(&self, n: usize) -> impl Future<Output = ()> + Send; - /// Mine a block. This won't turn the bot's head towards the block, so if - /// that's necessary you'll have to do that yourself with [`look_at`]. + /// Mine a block. + /// + /// This won't turn the bot's head towards the block, so if that's necessary + /// you'll have to do that yourself with [`look_at`]. /// /// [`look_at`]: crate::prelude::BotClientExt::look_at fn mine(&self, position: BlockPos) -> impl Future<Output = ()> + Send; diff --git a/azalea/src/container.rs b/azalea/src/container.rs index cd11b7c2..57753cc3 100644 --- a/azalea/src/container.rs +++ b/azalea/src/container.rs @@ -27,8 +27,9 @@ impl Plugin for ContainerPlugin { } pub trait ContainerClientExt { - /// Open a container in the world, like a chest. Use - /// [`Client::open_inventory`] to open your own inventory. + /// Open a container in the world, like a chest. + /// + /// Use [`Client::open_inventory`] to open your own inventory. /// /// ``` /// # use azalea::prelude::*; @@ -48,8 +49,9 @@ pub trait ContainerClientExt { &self, pos: BlockPos, ) -> impl Future<Output = Option<ContainerHandle>> + Send; - /// Open the player's inventory. This will return None if another - /// container is open. + /// Open the player's inventory. + /// + /// This will return None if another container is open. /// /// Note that this will send a packet to the server once it's dropped. Also, /// due to how it's implemented, you could call this function multiple times @@ -134,8 +136,10 @@ impl ContainerClientExt for Client { } } -/// A handle to a container that may be open. This does not close the container -/// when it's dropped. See [`ContainerHandle`] if that behavior is desired. +/// A handle to a container that may be open. +/// +/// This does not close the container when it's dropped. See [`ContainerHandle`] +/// if that behavior is desired. pub struct ContainerHandleRef { id: i32, client: Client, @@ -159,15 +163,18 @@ impl ContainerHandleRef { }); } - /// Get the id of the container. If this is 0, that means it's the player's - /// inventory. Otherwise, the number isn't really meaningful since only one - /// container can be open at a time. + /// Get the ID of the container. + /// + /// If this is 0, that means it's the player's inventory. Otherwise, the + /// number isn't really meaningful since only one container can be open + /// at a time. pub fn id(&self) -> i32 { self.id } - /// Returns the menu of the container. If the container is closed, this - /// will return `None`. + /// Returns the menu of the container. + /// + /// If the container is closed, this will return `None`. /// /// Note that any modifications you make to the `Menu` you're given will not /// actually cause any packets to be sent. If you're trying to modify your @@ -191,13 +198,16 @@ impl ContainerHandleRef { } /// Returns the item slots in the container, not including the player's - /// inventory. If the container is closed, this will return `None`. + /// inventory. + /// + /// If the container is closed, this will return `None`. pub fn contents(&self) -> Option<Vec<ItemStack>> { self.menu().map(|menu| menu.contents()) } - /// Return the contents of the menu, including the player's inventory. If - /// the container is closed, this will return `None`. + /// Return the contents of the menu, including the player's inventory. + /// + /// If the container is closed, this will return `None`. pub fn slots(&self) -> Option<Vec<ItemStack>> { self.menu().map(|menu| menu.slots()) } @@ -233,8 +243,9 @@ impl ContainerHandleRef { } } -/// A handle to the open container. The container will be closed once this is -/// dropped. +/// A handle to the open container. +/// +/// The container will be closed once this is dropped. #[derive(Deref)] pub struct ContainerHandle(ContainerHandleRef); diff --git a/azalea/src/lib.rs b/azalea/src/lib.rs index e3e92170..069837b3 100644 --- a/azalea/src/lib.rs +++ b/azalea/src/lib.rs @@ -56,7 +56,7 @@ pub enum StartError { } /// A builder for creating new [`Client`]s. This is the recommended way of -/// making Azalea bots. +/// making a bot. /// /// ```no_run /// # use azalea::prelude::*; @@ -201,8 +201,9 @@ where } /// Build this `ClientBuilder` into an actual [`Client`] and join the given - /// server. If the client can't join, it'll keep retrying forever until it - /// can. + /// server. + /// + /// If the client can't join, it'll keep retrying forever until it can. /// /// The `address` argument can be a `&str`, [`ServerAddress`], or anything /// that implements `TryInto<ServerAddress>`. @@ -247,8 +248,10 @@ impl Default for ClientBuilder<NoState, ()> { } /// A marker that can be used in place of a State in [`ClientBuilder`] or -/// [`SwarmBuilder`]. You probably don't need to use this manually since the -/// compiler will infer it for you. +/// [`SwarmBuilder`]. +/// +/// You probably don't need to use this manually since the compiler will infer +/// it for you. /// /// [`SwarmBuilder`]: swarm::SwarmBuilder #[derive(Component, Clone, Default)] diff --git a/azalea/src/nearest_entity.rs b/azalea/src/nearest_entity.rs index 2c01e5df..6e94e331 100644 --- a/azalea/src/nearest_entity.rs +++ b/azalea/src/nearest_entity.rs @@ -65,6 +65,7 @@ where F: QueryFilter + 'static, { /// Gets the nearest entity to the given position and world instance name. + /// /// This method will return `None` if there are no entities within range. If /// multiple entities are within range, only the closest one is returned. pub fn nearest_to_position( @@ -91,9 +92,11 @@ where nearest_entity } - /// Gets the nearest entity to the given entity. This method will return - /// `None` if there are no entities within range. If multiple entities are - /// within range, only the closest one is returned. + /// Gets the nearest entity to the given entity. + /// + /// This method will return `None` if there are no entities within range. If + /// multiple entities are within range, only the closest one is + /// returned. pub fn nearest_to_entity(&'a self, entity: Entity, max_distance: f64) -> Option<Entity> { let Ok((position, instance_name)) = self.all_entities.get(entity) else { return None; @@ -122,8 +125,9 @@ where } /// This function get an iterator over all nearby entities to the given - /// position within the given maximum distance. The entities in this - /// iterator are not returned in any specific order. + /// position within the given maximum distance. + /// + /// The entities in this iterator are not returned in any specific order. /// /// This function returns the Entity ID of nearby entities and their /// distance away. @@ -150,8 +154,9 @@ where } /// This function get an iterator over all nearby entities to the given - /// entity within the given maximum distance. The entities in this iterator - /// are not returned in any specific order. + /// entity within the given maximum distance. + /// + /// The entities in this iterator are not returned in any specific order. /// /// This function returns the Entity ID of nearby entities and their /// distance away. diff --git a/azalea/src/pathfinder/astar.rs b/azalea/src/pathfinder/astar.rs index b2559c1f..d2a57b38 100644 --- a/azalea/src/pathfinder/astar.rs +++ b/azalea/src/pathfinder/astar.rs @@ -312,9 +312,10 @@ impl PartialOrd for WeightedNode { /// [`PathfinderOpts::max_timeout`]: super::goto_event::PathfinderOpts::max_timeout #[derive(Debug, Clone, Copy, PartialEq)] pub enum PathfinderTimeout { - /// Time out after a certain duration has passed. This is a good default so - /// you don't waste too much time calculating a path if you're on a slow - /// computer. + /// Time out after a certain duration has passed. + /// + /// This is a good default so you don't waste too much time calculating a + /// path if you're on a slow computer. Time(Duration), /// Time out after this many nodes have been considered. /// diff --git a/azalea/src/pathfinder/goto_event.rs b/azalea/src/pathfinder/goto_event.rs index 379c61d0..e4f934f2 100644 --- a/azalea/src/pathfinder/goto_event.rs +++ b/azalea/src/pathfinder/goto_event.rs @@ -106,8 +106,10 @@ impl PathfinderOpts { self } /// The absolute maximum amount of time that the pathfinder function can - /// take to find a path. If it takes this long, it means no usable path was - /// found (so it might be impossible). + /// take to find a path. + /// + /// If it takes this long, it means no usable path was found (so it might be + /// impossible). /// /// Defaults to `PathfinderTimeout::Time(Duration::from_secs(5))`. pub fn max_timeout(mut self, max_timeout: PathfinderTimeout) -> Self { diff --git a/azalea/src/pathfinder/mod.rs b/azalea/src/pathfinder/mod.rs index 6d78b043..c001f838 100644 --- a/azalea/src/pathfinder/mod.rs +++ b/azalea/src/pathfinder/mod.rs @@ -917,7 +917,7 @@ pub fn check_for_path_obstruction( } } -/// update the given [`ExecutingPath`] to recalculate the path of the nodes in +/// Update the given [`ExecutingPath`] to recalculate the path of the nodes in /// the given index range. /// /// You should avoid making the range too large, since the timeout for the A* @@ -1153,9 +1153,11 @@ pub fn recalculate_if_has_goal_but_no_path( #[derive(Message)] pub struct StopPathfindingEvent { pub entity: Entity, - /// If false, then let the current movement finish before stopping. If true, - /// then stop moving immediately. This might cause the bot to fall if it was - /// in the middle of parkouring. + /// Whether we should stop moving immediately without waiting for the + /// current movement to finish. + /// + /// This is usually set to false, since it might cause the bot to fall if it + /// was in the middle of parkouring. pub force: bool, } @@ -1210,7 +1212,9 @@ pub fn stop_pathfinding_on_instance_change( } /// Checks whether the path has been obstructed, and returns Some(index) if it -/// has been. The index is of the first obstructed node. +/// has been. +/// +/// The index is of the first obstructed node. pub fn check_path_obstructed<SuccessorsFn>( origin: BlockPos, mut current_position: RelBlockPos, diff --git a/azalea/src/pathfinder/moves/mod.rs b/azalea/src/pathfinder/moves/mod.rs index 39ef786b..bb2354bf 100644 --- a/azalea/src/pathfinder/moves/mod.rs +++ b/azalea/src/pathfinder/moves/mod.rs @@ -137,8 +137,9 @@ impl ExecuteCtx<'_, '_, '_, '_, '_, '_, '_, '_> { true } - /// Mine the block at the given position. Returns whether the block is being - /// mined. + /// Mine the block at the given position. + /// + /// Returns whether the block is being mined. pub fn mine(&mut self, block: BlockPos) -> bool { let block_state = self .instance diff --git a/azalea/src/pathfinder/world.rs b/azalea/src/pathfinder/world.rs index 318ed55e..0f1a8305 100644 --- a/azalea/src/pathfinder/world.rs +++ b/azalea/src/pathfinder/world.rs @@ -17,8 +17,9 @@ use super::{mining::MiningCache, rel_block_pos::RelBlockPos}; /// An efficient representation of the world used for the pathfinder. pub struct CachedWorld { - /// The origin that the [`RelBlockPos`] types will be relative to. This is - /// for an optimization that reduces the size of the block positions + /// The origin that the [`RelBlockPos`] types will be relative to. + /// + /// This is for an optimization that reduces the size of the block positions /// that are used by the pathfinder. origin: BlockPos, @@ -247,8 +248,9 @@ impl CachedWorld { passable } - /// Get the block state at the given position. This is relatively slow, so - /// you should avoid it whenever possible. + /// Get the block state at the given position. + /// + /// This is relatively slow, so you should avoid it whenever possible. pub fn get_block_state(&self, pos: RelBlockPos) -> BlockState { self.get_block_state_at_pos(pos.apply(self.origin)) } @@ -304,8 +306,9 @@ impl CachedWorld { solid } - /// Returns how much it costs to break this block. Returns 0 if the block is - /// already passable. + /// Returns how much it costs to break this block. + /// + /// Returns 0 if the block is already passable. pub fn cost_for_breaking_block(&self, pos: RelBlockPos, mining_cache: &MiningCache) -> f32 { // SAFETY: pathfinding is single-threaded let cached_mining_costs = unsafe { &mut *self.cached_mining_costs.get() }; @@ -478,8 +481,10 @@ impl CachedWorld { + self.cost_for_breaking_block(pos.up(1), mining_cache) } - /// Whether we can stand in this position. Checks if the block below is - /// solid, and that the two blocks above that are passable. + /// Whether we can stand in this position. + /// + /// Checks if the block below is solid, and that the two blocks above that + /// are passable. pub fn is_standable(&self, pos: RelBlockPos) -> bool { self.is_standable_at_block_pos(pos.apply(self.origin)) } diff --git a/azalea/src/swarm/mod.rs b/azalea/src/swarm/mod.rs index f2e65715..59bad419 100644 --- a/azalea/src/swarm/mod.rs +++ b/azalea/src/swarm/mod.rs @@ -81,8 +81,10 @@ where pub(crate) app: SubApp, /// The accounts and proxies that are going to join the server. pub(crate) accounts: Vec<(Account, JoinOpts)>, - /// The individual bot states. This must be the same length as `accounts`, - /// since each bot gets one state. + /// The individual bot states. + /// + /// This must be the same length as `accounts`, since each bot gets one + /// state. pub(crate) states: Vec<S>, /// The state for the overall swarm. pub(crate) swarm_state: SS, @@ -92,14 +94,16 @@ where /// [`SwarmEvent`]. pub(crate) swarm_handler: Option<BoxSwarmHandleFn<SS, SR>>, - /// How long we should wait between each bot joining the server. Set to - /// None to have every bot connect at the same time. None is different than - /// a duration of 0, since if a duration is present the bots will wait for - /// the previous one to be ready. + /// How long we should wait between each bot joining the server. + /// + /// If this is None, every bot will connect at the same time. None is + /// different than a duration of 0, since if a duration is present the + /// bots will wait for the previous one to be ready. pub(crate) join_delay: Option<Duration>, - /// The default reconnection delay for our bots. This will change the value - /// of the `AutoReconnectDelay` resource. + /// The default reconnection delay for our bots. + /// + /// This will change the value of the [`AutoReconnectDelay`] resource. pub(crate) reconnect_after: Option<Duration>, } impl SwarmBuilder<NoState, NoSwarmState, (), ()> { @@ -165,7 +169,8 @@ where SS: Default + Send + Sync + Clone + Resource + 'static, { /// Set the function that's called every time a bot receives an - /// [`enum@Event`]. This is the way to handle normal per-bot events. + /// [`enum@Event`]. This is the intended way to handle normal per-bot + /// events. /// /// Currently you can have up to one handler. /// @@ -221,7 +226,7 @@ where S: Send + Sync + Clone + Component + 'static, { /// Set the function that's called every time the swarm receives a - /// [`SwarmEvent`]. This is the way to handle global swarm events. + /// [`SwarmEvent`]. This is the intended way to handle global swarm events. /// /// Currently you can have up to one swarm handler. /// @@ -306,8 +311,9 @@ where self } - /// Add a single new [`Account`] to the swarm. Use [`Self::add_accounts`] to - /// add multiple accounts at a time. + /// Add a single new [`Account`] to the swarm. + /// + /// Use [`Self::add_accounts`] to add multiple accounts at a time. /// /// This will make the state for this client be the default, use /// [`Self::add_account_with_state`] to avoid that. @@ -319,15 +325,19 @@ where self.add_account_with_state_and_opts(account, S::default(), JoinOpts::default()) } - /// Add an account with a custom initial state. Use just - /// [`Self::add_account`] to use the Default implementation for the state. + /// Add an account with a custom initial state. + /// + /// Use just [`Self::add_account`] to use the `Default` implementation for + /// the state. #[must_use] pub fn add_account_with_state(self, account: Account, state: S) -> Self { self.add_account_with_state_and_opts(account, state, JoinOpts::default()) } - /// Add an account with a custom initial state. Use just - /// [`Self::add_account`] to use the Default implementation for the state. + /// Add an account with a custom initial state. + /// + /// Use just [`Self::add_account`] to use the `Default` implementation for + /// the state. #[must_use] pub fn add_account_with_opts(self, account: Account, opts: JoinOpts) -> Self where @@ -612,8 +622,10 @@ impl Default for SwarmBuilder<NoState, NoSwarmState, (), ()> { pub enum SwarmEvent { /// All the bots in the swarm have successfully joined the server. Login, - /// The swarm was created. This is only fired once, and it's guaranteed to - /// be the first event to fire. + /// The swarm was created. + /// + /// This is only fired once, and it's guaranteed to be the first event to + /// fire. Init, /// A bot got disconnected from the server. /// @@ -688,8 +700,9 @@ pub type BoxSwarmHandleFn<SS, R> = /// Ok(()) /// } impl Swarm { - /// Add a new account to the swarm. You can remove it later by calling - /// [`Client::disconnect`]. + /// Add a new account to the swarm. + /// + /// You can remove it later by calling [`Client::disconnect`]. /// /// # Errors /// @@ -702,9 +715,10 @@ impl Swarm { self.add_with_opts(account, state, &JoinOpts::default()) .await } - /// Add a new account to the swarm, using custom options. This is useful if - /// you want bots in the same swarm to connect to different addresses. - /// Usually you'll just want [`Self::add`] though. + /// Add a new account to the swarm, using custom options. + /// + /// This is useful if you want bots in the same swarm to connect to + /// different addresses. Usually you'll just want [`Self::add`] though. /// /// # Errors /// @@ -831,8 +845,9 @@ impl Swarm { ); } - /// Add a new account to the swarm, retrying if it couldn't join. This will - /// run forever until the bot joins or the task is aborted. + /// Add a new account to the swarm, retrying if it couldn't join. + /// + /// This will run forever until the bot joins or the task is aborted. /// /// This does exponential backoff (though very limited), starting at 5 /// seconds and doubling up to 15 seconds. @@ -928,8 +943,9 @@ impl PluginGroup for DefaultSwarmPlugins { } } -/// A marker that can be used in place of a SwarmState in [`SwarmBuilder`]. You -/// probably don't need to use this manually since the compiler will infer it -/// for you. +/// A marker that can be used in place of a SwarmState in [`SwarmBuilder`]. +/// +/// You probably don't need to use this manually since the compiler will infer +/// it for you. #[derive(Resource, Clone, Default)] pub struct NoSwarmState; |