Struct MinecraftConnection

pub struct MinecraftConnection { /* private fields */ }

A connection to Minecraft that can execute commands in Minecraft and listen for command output.

If you need to listen for command output, but don’t need to execute commands, consider using LogObserver directly.

The connection requires a building in Minecraft which continuously loads structure files that contain the commands passed to execute_commands. To create such a connection building you can call connect.

Minect supports operating multiple connection buildings in parallel, each with a unique identifier. A single connection building can be shared between any number of Rust programs, but it has a limited update frequency. For optimal performance every Rust program can use a different connection identifier.

The update frequency can be configured globally for all connections in a Minecraft world by changing the score of update_delay for the objective minect_config.

Implementations

impl MinecraftConnection

pub fn builder( identifier: impl Into<String>, world_dir: impl Into<PathBuf>, ) -> MinecraftConnectionBuilder

Creates a MinecraftConnectionBuilder.

identifier is a string that uniquely identifies a connection building in Minecraft. Because it is used with Minecraft’s tag command, it may only contain the following Characters: 0-9, A-Z, a-z, +, -, . & _.

world_dir is the directory containing the Minecraft world to connect to. For single player this is typically a directory within the saves directory:

• Windows: C:\Users\Herobrine\AppData\Roaming\.minecraft\saves\
• GNU/Linux: ~/.minecraft/saves/
• Mac: ~/Library/Application Support/minecraft/saves/

For servers it is specified in server.properties.

Panics

Panics if identifier contains an invalid character.

pub fn get_identifier(&self) -> &str

The connection identifier uniquely identifies a connection building in Minecraft.

pub fn get_datapack_dir(&self) -> &Path

The root directory of the datapack used to operate the connection in Minecraft.

pub async fn connect(&mut self) -> Result<(), ConnectError>

This function can be used to set up the connection building in Minecraft, which is required for execute_commands.

If the connection can be established, this function simply returns. Note that this still requires a running Minecraft instance. Otherwise this function blocks until a connection building is created. This function also creates an interactive installer that a player can start by executing /reload in Minecraft.

Because this function blocks indefinately if the connection can’t be established, it should be called with tokio::time::timeout or some other means of cancellation, such as futures::future::select.

Errors

This function will return an error if the player cancels the installation in the interactive installer (can be checked with ConnectError::is_cancelled) or if an io::Error occurs.

pub fn create_datapack(&self) -> Result<(), IoErrorAtPath>

Creates the Minect datapack.

pub fn remove_datapack(&self) -> Result<(), IoErrorAtPath>

Removes the Minect datapack.

pub fn execute_commands( &mut self, commands: impl IntoIterator<IntoIter = impl ExactSizeIterator<Item = Command>>, ) -> Result<(), ExecuteCommandsError>

Executes the given commands in Minecraft.

Errors

This function will return an error if an io::Error occurs.

pub fn add_listener(&mut self) -> impl Stream<Item = LogEvent>

Returns a Stream of all LogEvents. To remove the listener simply drop the stream.

Internally the stream is backed by an unbound channel. This means it should be polled regularly to avoid memory leaks.

pub fn add_named_listener( &mut self, name: impl Into<String>, ) -> impl Stream<Item = LogEvent>

Returns a Stream of LogEvents with executor equal to the given name. To remove the listener simply drop the stream.

This can be more memory efficient than add_listener, because only a small subset of LogEvents has to be buffered if not that many commands are executed with the given name.

Internally the stream is backed by an unbound channel. This means it should be polled regularly to avoid memory leaks.