Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Doxygen documentation #52

Merged
merged 6 commits into from
Jun 23, 2024
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
add/doxygen
johnathanchann committed Jun 23, 2024
commit ff406782d6713fc603b4a32dfd0ee70cb9d4ebca
30 changes: 30 additions & 0 deletions .github/workflows/doxygen.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
name: Deploy Doxygen Documentation

on:
push:
branches:
- main
pull_request:
branches:
- main

jobs:
build-and-deploy:
runs-on: ubuntu-latest

steps:
- name: Checkout code
uses: actions/checkout@v2

- name: Set up Doxygen
run: |
sudo apt-get update
sudo apt-get install -y doxygen graphviz

- name: Generate Documentation
run: doxygen ./Doxyfile

- name: Deploying to Gh-pages
uses: jinxto/doxygen-env-setup@v1
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -45,3 +45,6 @@ CMakeFiles
*.app
/cmake-build-debug-coverage/
/cmake-build-release-coverage/

#doxygen-folders
johnathanchann marked this conversation as resolved.
Show resolved Hide resolved
doc/
2,658 changes: 2,658 additions & 0 deletions Doxyfile
johnathanchann marked this conversation as resolved.
Show resolved Hide resolved

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -8,7 +8,7 @@
**mcpp** (Minecraft++) is a library built to interface with Minecraft through [Spigot server](https://www.spigotmc.org/)
running the [ELCI](https://github.com/rozukke/ELCI) plugin and using C++. It is currently limited to MacOS/Linux or Windows with WSL.

➡ For more details on the broad strokes of **mcpp**, refer to the [wiki](https://github.com/rozukke/mcpp/wiki/Index)!
➡ For more details on the broad strokes of **mcpp**, refer to the [wiki](https://github.com/rozukke/mcpp/wiki/Index) or to the [documentation](INSERT_YOUR_URL/classes.html)!
johnathanchann marked this conversation as resolved.
Show resolved Hide resolved

## History
This library is based on [mcpi](https://github.com/martinohanlon/mcpi), which is a Python library with similar functionality.
33 changes: 30 additions & 3 deletions include/mcpp/block.h
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
#pragma once

#include <ostream>

johnathanchann marked this conversation as resolved.
Show resolved Hide resolved
/**
* @file
* @brief BlockType class
*/
namespace mcpp {
class BlockType {
public:
@@ -10,19 +13,42 @@ class BlockType {

constexpr BlockType(int id = 0, int modifier = 0) : id(id), mod(modifier){};

/**
/**
* @brief Equality comparison operator.
*
* Watch out as this also compares the BlockType.mod element of the block,
* so some equalities may behave in unexpected ways e.g. rotated stairs
*
* @param other The BlockType to compare with the current instance.
*
* @return True if the two BlockType instances are not equal, false otherwise.
*/
bool operator==(const BlockType& other) const;

/**
* @brief Inequality comparison operator.
*
* Watch out as this also compares the BlockType.mod element of the block,
* so some equalities may behave in unexpected ways e.g. rotated stairs
*
* @param other The BlockType to compare with the current instance.
* @return True if the two BlockType instances are not equal, false otherwise.
*/
bool operator!=(const BlockType& other) const;


/**
* @brief Stream insertion operator for outputting the BlockType to an output stream.
*
* @param out The output stream to write to.
* @param block The BlockType instance to output.
* @return A reference to the output stream after the block information has been inserted.
*/
friend std::ostream& operator<<(std::ostream& out, const BlockType& block);

/**
* Returns a new BlockType with the same id and specified modifier, useful
* for rotations etc.
*
* @param modifier New modifier for the BlockType
* @return New BlockType object with the specified modifier
*/
@@ -32,6 +58,7 @@ class BlockType {
// Using script to extract ids from https://minecraft-ids.grahamedgecombe.com/

/**
* @struct Blocks
* Struct of static block objects that allows for a "search" of sorts, callable
* using Blocks::TYPE after importing <block.h>
*/
9 changes: 7 additions & 2 deletions include/mcpp/connection.h
Original file line number Diff line number Diff line change
@@ -4,7 +4,10 @@
#include <string>

#define FAIL_RESPONSE "Fail"

johnathanchann marked this conversation as resolved.
Show resolved Hide resolved
/** @file
* @brief SocketConnection class.
*
*/
namespace mcpp {
class SocketConnection {
private:
@@ -15,13 +18,14 @@ class SocketConnection {

public:
SocketConnection(const std::string& address_str, uint16_t port);

void send(const std::string& dataString);

/**
* Takes in parameters supporting std::stringstream conversion and a string
* prefix and transforms them into format "prefix(arg1,arg2,arg3)\n" (e.g.
* "chat.post(test)\n") and sends command to the server.
*
* @tparam Types
* @param prefix
* @param args
@@ -44,6 +48,7 @@ class SocketConnection {

/**
* Sends via sendCommand() and returns the result from endpoint
*
* @tparam T
* @tparam Types
* @param prefix
65 changes: 47 additions & 18 deletions include/mcpp/mcpp.h
Original file line number Diff line number Diff line change
@@ -6,23 +6,35 @@
#include <memory>
#include <string_view>
#include <vector>

johnathanchann marked this conversation as resolved.
Show resolved Hide resolved
/** @file
* @brief MinecraftConnection class.
*
*/

/**
* @brief Namespace containing all the the mcpp library classes.
*
* The mcpp namespace includes classes and functions designed to facilitate
* interaction with the Minecraft world through various server commands
* and data manipulations.
*/
namespace mcpp {
class MinecraftConnection {
private:
std::unique_ptr<SocketConnection> conn;
std::unique_ptr<SocketConnection> conn; ///< Handle to the socket connection.

static std::vector<std::vector<std::vector<BlockType>>>
unflattenBlocksArray(const Coordinate& loc1, const Coordinate& loc2,
const std::vector<BlockType>& inVector);
const std::vector<BlockType>& inVector); ///< Helper function to convert flat block array to 3D.

static std::vector<std::vector<int>>
unflattenHeightsArray(const Coordinate& loc1, const Coordinate& loc2,
const std::vector<int>& inVector);
const std::vector<int>& inVector); ///< Helper function to convert flat height array to 2D.

public:
/**
* Represents the main endpoint for interaction with the minecraft world.
* @brief Represents the main endpoint for interaction with the minecraft world.
*
* @param address String address in IPV4 format, defaults to "localhost"
* @param port Integer port to run on, defaults to 4711 as that is the port
* for ELCI
@@ -31,55 +43,63 @@ class MinecraftConnection {
int port = 4711);

/**
* Sends a message to the in-game chat, does not require a joined player
* @brief Sends a message to the in-game chat, does not require a joined player
*
* @param message
*/
void postToChat(const std::string& message);

/**
* Performs an in-game minecraft command. Players have to exist on the
* @brief Performs an in-game minecraft command. Players have to exist on the
* server and should be server operators (default with ELCI)
*
* @param command Command string in the in-game format (e.g. "time set day")
*/
void doCommand(const std::string& command);

/**
* Sets player pos (block pos of lower half of playermodel) to specified
* @brief Sets player pos (block pos of lower half of playermodel) to specified
* Coordinate
*
* @param pos Coordinate to set
*/
void setPlayerPosition(const Coordinate& pos);

/**
* Returns a coordinate representing player position (block pos of lower
* @brief Returns a coordinate representing player position (block pos of lower
* half of playermodel)
*
* @return Coordinate of location
*/
Coordinate getPlayerPosition();

/**
* Sets player position to be one above specified tile (i.e. tile = block
* @brief Sets player position to be one above specified tile (i.e. tile = block
* player is standing on)
*
* @param tile Coordinate to set
*/
void setPlayerTilePosition(const Coordinate& tile);

/**
* Returns the coordinate location of the block the player is standing on
* @brief Returns the coordinate location of the block the player is standing on
*
* @return Coordinate of location
*/
Coordinate getPlayerTilePosition();

/**
* Sets block at Coordinate loc to the BlockType specified by blockType
* @brief Sets block at Coordinate loc to the BlockType specified by blockType
*
* @param loc
* @param blockType
*/
void setBlock(const Coordinate& loc, const BlockType& blockType);

/**
* Sets a cuboid of blocks to the specified BlockType blockType, with the
* @brief Sets a cuboid of blocks to the specified BlockType blockType, with the
* corners of the cuboid provided by the Coordinate loc1 and loc2
*
* @param loc1
* @param loc2
* @param blockType
@@ -88,15 +108,17 @@ class MinecraftConnection {
const BlockType& blockType);

/**
* Returns BlockType object from the specified Coordinate loc with modifier
* @brief Returns BlockType object from the specified Coordinate loc with modifier
*
* @param loc
* @return BlockType of the requested block
*/
BlockType getBlock(const Coordinate& loc);

/**
* Returns a 3D vector of the BlockTypes of the requested cuboid with
* @brief Returns a 3D vector of the BlockTypes of the requested cuboid with
* modifiers
*
* @param loc1 1st corner of the cuboid
* @param loc2 2nd corner of the cuboid
* @return 3D vector of BlockType in the specified cuboid.
@@ -105,8 +127,12 @@ class MinecraftConnection {
getBlocks(const Coordinate& loc1, const Coordinate& loc2);

/**
* IMPORTANT: DO NOT USE FOR LARGE AREAS, IT WILL BE VERY SLOW
* @brief Returns the height of the specific provided x and y coordinate
*
* ***IMPORTANT:***
* DO NOT USE FOR LARGE AREAS, IT WILL BE VERY SLOW
* USE getHeights() INSTEAD
*
* Gets the y-value of the highest non-air block at the specified (x, z)
* coordinate.
* @param x
@@ -116,8 +142,11 @@ class MinecraftConnection {
int getHeight(int x, int z);

/**
* Provides a scaled option of the getHeight call to allow for considerable
* performance gains. USE THIS instead of getHeight in a for loop.
* @brief Provides a scaled option of the getHeight call to allow for considerable
* performance gains.
*
* \par USE THIS instead of getHeight in a for loop.
*
* @param loc1
* @param loc2
* @return Returns a vector of integers representing the 2D area of heights.
63 changes: 58 additions & 5 deletions include/mcpp/util.h
Original file line number Diff line number Diff line change
@@ -1,28 +1,81 @@
#pragma once

#include <ostream>

/** @file
* @brief Coordinate class.
*
*/
namespace mcpp {
/**
* Represented using integers since sub-unit coordinates are not of particular
* relevance. Allows for operations such as addition between coordinates.
*/
class Coordinate {
public:
/**
* @brief Constructs a Coordinate object with integer values.
*
* @param x The x-coordinate. Default is 0.
* @param y The y-coordinate. Default is 0.
* @param z The z-coordinate. Default is 0.
*/
explicit Coordinate(int x = 0, int y = 0, int z = 0);

/**
* @brief Constructs a Coordinate object with double values.
*
* @param x The x-coordinate as a double.
* @param y The y-coordinate as a double.
* @param z The z-coordinate as a double.
*/
Coordinate(double x, double y, double z);


/**
* @brief Adds two Coordinate objects.
*
* @param obj The Coordinate object to add.
* @return A new Coordinate object representing the sum of the two coordinates.
*/
Coordinate operator+(const Coordinate& obj) const;

/**
* @brief Checks if two Coordinate objects are equal.
*
* @param obj The Coordinate object to compare with.
* @return True if the coordinates are equal, false otherwise.
*/
bool operator==(const Coordinate& obj) const;


/**
* @brief Checks if two Coordinate objects are not equal.
*
* @param obj The Coordinate object to compare with.
* @return True if the coordinates are not equal, false otherwise.
*/
bool operator!=(const Coordinate& obj) const;


/**
* @brief Subtracts one Coordinate object from another.
*
* @param obj The Coordinate object to subtract.
* @return A new Coordinate object representing the difference between the two coordinates.
*/
Coordinate operator-(const Coordinate& obj) const;

/**
* @brief Creates a copy of the Coordinate object.
*
* @return A new Coordinate object that is a copy of the current object.
*/
[[nodiscard]] Coordinate clone() const;


/**
* @brief Outputs the Coordinate object to an ostream.
*
* @param out The output stream.
* @param coord The Coordinate object to output.
* @return The output stream with the Coordinate object's values.
*/
friend std::ostream& operator<<(std::ostream& out, const Coordinate& coord);

int x;