From baa9fff16c21276014f0e3aa23fceeee385a77fe Mon Sep 17 00:00:00 2001 From: blackfur <64478051+theblackfurguy@users.noreply.github.com> Date: Mon, 5 Apr 2021 19:11:54 +0200 Subject: [PATCH] Added documentation and bumped the version to 0.1.1 --- Cargo.toml | 4 ++-- src/lib.rs | 54 ++++++++++++++++++++++++++++++++++-------------------- 2 files changed, 36 insertions(+), 22 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index b087a74..cfcf398 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,11 +1,11 @@ [package] name = "mcpi_api" -version = "0.1.0" +version = "0.1.1" authors = ["blackfur <64478051+theblackfurguy@users.noreply.github.com>"] edition = "2018" description = "Wrapper for the Minecraft Pi Edition API handling parsing and other aspects for you" license = "MIT OR Apache-2.0" -repository = "https://github.com/TheBlackfurGuy/mcpi-api-rust" +repository = "https://github.com/MCPI-Revival/mcpi-api-rust" readme = "README.md" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html diff --git a/src/lib.rs b/src/lib.rs index 691fa08..d8e487b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -44,6 +44,7 @@ pub struct Vec3 { } impl TileVec3 { + /// Function to generate a TileVec3 from 3 i32's pub fn from(x:i32, y:i32, z:i32) -> TileVec3 { TileVec3 { x, @@ -51,7 +52,9 @@ impl TileVec3 { z } } - + ///Function to generate a TileVec3 from a Vec + /// # Panics + /// This function panics if the vector contains less then 3 elements pub fn from_vector(vec:&Vec) -> TileVec3 { TileVec3 { x: vec[0], @@ -62,6 +65,7 @@ impl TileVec3 { } impl Vec3 { + ///Function to generate a Vec3 from 3 f32's pub fn from(x:f32, y:f32, z:f32) -> Vec3 { Vec3 { x, @@ -69,7 +73,9 @@ impl Vec3 { z } } - + ///Function to generate a Vec3 from a Vec + /// # Panics + /// This function panics if the vector contains less then 3 elements pub fn from_vector(vec:&Vec) -> Vec3 { Vec3{ x: vec[0], @@ -96,20 +102,23 @@ impl Connection { self.receive() } } - +///# Panics +/// All functions implemented on the Minecraft struct might panic if the API is not running anymore or packages fail to send. +/// This might change in a 0.2.0 version of this crate impl Minecraft { + ///Post a message to the chat pub fn post_to_chat(&mut self, msg:&str) { self.conn.send(&format!("chat.post({})", msg)); } - + ///Get the block at a specific position pub fn get_block(&mut self, pos:&TileVec3) -> u8 { self.conn.send_receive(&format!("world.getBlock({},{},{})", pos.x, pos.y, pos.z)).parse::().unwrap() } - + ///Get the block with data at a specific position pub fn get_block_with_data(&mut self, pos:&TileVec3) -> Vec { self.conn.send_receive(&format!("world.getBlockWithData({},{},{})", pos.x, pos.y, pos.z)).split(',').map(|s| s.parse()).collect::, _>>().unwrap() } - + ///Get a array of blocks contained in the specified area pub fn get_blocks(&mut self, pos1:&TileVec3, pos2:&TileVec3) -> Vec { let mut results:Vec = vec![]; for y in min(pos1.y, pos2.y)..max(pos1.y, pos2.y)+1 { @@ -121,7 +130,7 @@ impl Minecraft { } results } - + ///Get a array of blocks with their data contained in the specified area pub fn get_blocks_with_data(&mut self, pos1:&TileVec3, pos2:&TileVec3) -> Vec> { let mut results:Vec> = vec![]; for y in min(pos1.y, pos2.y)..max(pos1.y, pos2.y)+1 { @@ -133,61 +142,66 @@ impl Minecraft { } results } - + ///Set a block at a specific position pub fn set_block(&mut self, pos:&TileVec3, blocktype:u8, blockdata:u8) { self.conn.send(&format!("world.setBlock({},{},{},{},{})", pos.x, pos.y, pos.z, blocktype, blockdata)); } - + ///Fill the specified area with the a block pub fn set_blocks(&mut self, pos1:&TileVec3, pos2:&TileVec3, blocktype:u8, blockdata:u8) { self.conn.send(&format!("world.setBlocks({},{},{},{},{},{},{},{})", pos1.x,pos1.y,pos1.z,pos2.x,pos2.y,pos2.z,blocktype,blockdata)); } - + ///Get the highest point at the specified position pub fn get_height(&mut self, pos:&TileVec3) -> i8 { self.conn.send_receive(&format!("world.getHeight({},{})", pos.x,pos.z)).parse::().unwrap() } - + ///Save the current world state as a checkpoint pub fn save_checkpoint(&mut self) { self.conn.send("world.checkpoint.save()"); } - + ///Restore a previously saved world state pub fn restore_checkpoint(&mut self) { self.conn.send("world.checkpoint.restore()"); } - + ///Set a world setting to true or false. + /// Available settings: "world_immutable", "nametags_visible" pub fn setting(&mut self, setting:&str, status:bool) { self.conn.send(&format!("world.setting({},{})",setting,if status == true {1} else {0})); } - + ///Get a list of entity ids for all online players pub fn get_player_entity_ids(&mut self) -> Vec { self.conn.send_receive(&format!("world.getPlayerIds()")).split("|").map(|s| s.parse()).collect::, _>>().unwrap() } - + ///Get a instance of the Player struct containing player related functions pub fn player(&mut self) -> Player { Player { conn: &mut self.conn } } } - +///# Panics +/// All functions implemented on the Player struct might panic if the API is not running anymore or packages fail to send. +/// This might change in a 0.2.0 version of this crate impl Player<'_> { + ///Get the position of the main player pub fn get_pos(&mut self) -> Vec3 { let vec:Vec = self.conn.send_receive(&format!("player.getPos()")).split(',').map(|s| s.parse()).collect::, _>>().unwrap(); Vec3::from_vector(&vec) } - + ///Set the position of the main player pub fn set_pos(&mut self, pos:&Vec3) { self.conn.send(&format!("player.setPos({},{},{})", pos.x, pos.y, pos.z)); } - + ///Get the tile position of the main player pub fn get_tile_pos(&mut self) -> TileVec3 { let vec:Vec = self.conn.send_receive(&format!("player.getTile()")).split(',').map(|s| s.parse()).collect::, _>>().unwrap(); TileVec3::from_vector(&vec) } - + ///Set the tile position of the main player pub fn set_tile_pos(&mut self, pos:&TileVec3) { self.conn.send(&format!("player.setTile({},{},{})", pos.x, pos.y, pos.z)) } - + ///Set a setting for the main player + /// Available settings: "autojump" pub fn setting(&mut self, setting:&str, status:bool) { self.conn.send(&format!("player.setting({},{})",setting,if status {1} else {0})); }