From 1493c06de597fc320b79212d133f08c678763a6b Mon Sep 17 00:00:00 2001 From: mat Date: Wed, 7 May 2025 08:24:46 -1300 Subject: [PATCH] better docs for disabling plugins --- azalea/README.md | 2 ++ azalea/src/lib.rs | 16 ++++++++++------ azalea/src/swarm/mod.rs | 20 +++++++++++++------- 3 files changed, 25 insertions(+), 13 deletions(-) diff --git a/azalea/README.md b/azalea/README.md index ec936b3b..83ff0d49 100644 --- a/azalea/README.md +++ b/azalea/README.md @@ -84,6 +84,8 @@ Azalea lets you create "swarms", which are a group of bots in the same world tha Azalea uses [Bevy ECS](https://docs.rs/bevy_ecs) internally to store information about the world and clients. Bevy plugins are more powerful than async handler functions, but more difficult to use. See [pathfinder](https://github.com/azalea-rs/azalea/blob/main/azalea/src/pathfinder/mod.rs) as an example of how to make a plugin. You can then enable a plugin by adding `.add_plugin(ExamplePlugin)` in your client/swarm builder. +Everything in Azalea is implemented as a Bevy plugin, which means you can disable default behaviors (like, physics or chat signing) by disabling built-in plugins. See [`SwarmBuilder::new_without_plugins`] to learn how to do that. + Also note that just because something is an entity in the ECS doesn't mean that it's a Minecraft entity. You can filter for that by having `With` as a filter. See the [Bevy Cheatbook](https://bevy-cheatbook.github.io/programming/ecs-intro.html) to learn more about Bevy ECS (and the ECS paradigm in general). diff --git a/azalea/src/lib.rs b/azalea/src/lib.rs index 3f388e42..26dde1fa 100644 --- a/azalea/src/lib.rs +++ b/azalea/src/lib.rs @@ -94,8 +94,10 @@ impl ClientBuilder { .add_plugins(DefaultBotPlugins) } - /// [`Self::new`] but without adding the plugins by default. This is useful - /// if you want to disable a default plugin. + /// [`Self::new`] but without adding the plugins by default. + /// + /// This is useful if you want to disable a default plugin. This also exists + /// for swarms, see [`SwarmBuilder::new_without_plugins`]. /// /// Note that you can also disable `LogPlugin` by disabling the `log` /// feature. @@ -104,12 +106,11 @@ impl ClientBuilder { /// /// ``` /// # use azalea::prelude::*; - /// use azalea::{app::PluginGroup, DefaultBotPlugins, DefaultPlugins}; - /// use bevy_log::LogPlugin; + /// use azalea::app::PluginGroup; /// /// let client_builder = ClientBuilder::new_without_plugins() - /// .add_plugins(DefaultPlugins.build().disable::()) - /// .add_plugins(DefaultBotPlugins); + /// .add_plugins(azalea::DefaultPlugins.build().disable::()) + /// .add_plugins(azalea::DefaultBotPlugins); /// # client_builder.set_handler(handle); /// # #[derive(Component, Clone, Default)] /// # pub struct State; @@ -171,6 +172,9 @@ where self } /// Add a group of plugins to the client. + /// + /// See [`Self::new_without_plugins`] to learn how to disable default + /// plugins. #[must_use] pub fn add_plugins(mut self, plugins: impl Plugins) -> Self { self.swarm = self.swarm.add_plugins(plugins); diff --git a/azalea/src/swarm/mod.rs b/azalea/src/swarm/mod.rs index 58742eaa..170effc8 100644 --- a/azalea/src/swarm/mod.rs +++ b/azalea/src/swarm/mod.rs @@ -112,21 +112,22 @@ impl SwarmBuilder { .add_plugins(DefaultSwarmPlugins) } - /// [`Self::new`] but without adding the plugins by default. This is useful - /// if you want to disable a default plugin. + /// [`Self::new`] but without adding the plugins by default. + /// + /// This is useful if you want to disable a default plugin. This also exists + /// for `ClientBuilder`, see [`ClientBuilder::new_without_plugins`]. /// /// You **must** add [`DefaultPlugins`], [`DefaultBotPlugins`], and /// [`DefaultSwarmPlugins`] to this. /// /// ``` /// # use azalea::{prelude::*, swarm::prelude::*}; - /// use azalea::{app::PluginGroup, DefaultBotPlugins, DefaultPlugins, swarm::{DefaultSwarmPlugins}}; - /// use bevy_log::LogPlugin; + /// use azalea::app::PluginGroup; /// /// let swarm_builder = SwarmBuilder::new_without_plugins() - /// .add_plugins(DefaultPlugins.build().disable::()) - /// .add_plugins(DefaultBotPlugins) - /// .add_plugins(DefaultSwarmPlugins); + /// .add_plugins(azalea::DefaultPlugins.build().disable::()) + /// .add_plugins(azalea::DefaultBotPlugins) + /// .add_plugins(azalea::swarm::DefaultSwarmPlugins); /// # swarm_builder.set_handler(handle).set_swarm_handler(swarm_handle); /// # #[derive(Component, Resource, Clone, Default)] /// # pub struct State; @@ -137,6 +138,8 @@ impl SwarmBuilder { /// # Ok(()) /// # } /// ``` + /// + /// [`ClientBuilder::new_without_plugins`]: crate::ClientBuilder::new_without_plugins #[must_use] pub fn new_without_plugins() -> Self { SwarmBuilder { @@ -355,6 +358,9 @@ where } /// Add one or more plugins to this swarm. + /// + /// See [`Self::new_without_plugins`] to learn how to disable default + /// plugins. #[must_use] pub fn add_plugins(mut self, plugins: impl Plugins) -> Self { self.app.add_plugins(plugins);