diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/about/contact.rst b/about/contact.rst new file mode 100644 index 0000000..4c4f6e1 --- /dev/null +++ b/about/contact.rst @@ -0,0 +1,4 @@ +Contact Us +=========== + +You can reach us on our `Discord `_. \ No newline at end of file diff --git a/about/faq.rst b/about/faq.rst new file mode 100644 index 0000000..5961e80 --- /dev/null +++ b/about/faq.rst @@ -0,0 +1,20 @@ +Frequently Asked Questions +=========================== + +General +******** + +What is Podrum? +---------------- + +Podrum is a Minecraft Bedrock Edition server software written in Python. + +What do I need to run it? +-------------------------- + +Podrum requires python 3.6+, however, we recommend you use the latest version. + +Where do I get it? +------------------- + +You can view a tutorial on downloading Podrum :ref:`here`. diff --git a/about/index.rst b/about/index.rst new file mode 100644 index 0000000..abcafb2 --- /dev/null +++ b/about/index.rst @@ -0,0 +1,12 @@ +About Podrum +============= + +This section provides basic information about the project. + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + introduction + faq + contact \ No newline at end of file diff --git a/about/introduction.rst b/about/introduction.rst new file mode 100644 index 0000000..1878376 --- /dev/null +++ b/about/introduction.rst @@ -0,0 +1,13 @@ +Introduction +============= + +Podrum is a Minecraft Bedrock Edition server software written in Python. + +It was made to provide an easy way for Python developers to +create a server for the Minecraft: Bedrock Edition. + +Where can I download Podrum? +***************************** + +You can view a tutorial on downloading Podrum :ref:`here`. + diff --git a/conf.py b/conf.py new file mode 100644 index 0000000..efa7584 --- /dev/null +++ b/conf.py @@ -0,0 +1,60 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) +import sphinx_rtd_theme + + +# -- Project information ----------------------------------------------------- + +project = 'Podrum' +copyright = '2021, Podrum Team' +author = 'Podrum Team' + +# The full version, including alpha/beta/rc tags +release = '0.0.6' + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx_rtd_theme", + "sphinx.ext.intersphinx" +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# -- Template Options -------------------------------------------------------- + +intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/index.rst b/index.rst new file mode 100644 index 0000000..8179fd1 --- /dev/null +++ b/index.rst @@ -0,0 +1,67 @@ +.. Podrum documentation master file, created by + sphinx-quickstart on Tue Jul 6 11:42:36 2021. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Podrum +================================== + +A Minecraft Bedrock Edition server software written in Python. +It's still under active development, yet it has a few advantages: + +1. Easy to use, + +2. Written in Python which makes plugins easier to write. + +.. warning:: + This software and documentation is in active development, + many things will be subject to change. + +Features +********* + +- World Generation +- Networking +- Commands +- MOTD +- Joinable +- Plugin API +- Mobs (coming soon) + +Running a Podrum Server +************************ + +Running a Podrum server is simple. +This section will cover common tasks such as configuring it, +maintaining plugins, amongst other things. + +.. toctree:: + :maxdepth: 3 + :titlesonly: + + server/index + +Creating Plugins +***************** + +Creating plugins is fairly straighforward. +This section will explain the process of creating a plugin. + +.. toctree:: + :maxdepth: 3 + :titlesonly: + + plugins/index + +About Podrum +************* + +Podrum is a Minecraft Bedrock Edition server software written in Python. +The following links will explain more about this project. + +.. toctree:: + :maxdepth: 3 + :titlesonly: + + about/index + diff --git a/make.bat b/make.bat new file mode 100644 index 0000000..2119f51 --- /dev/null +++ b/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/plugins/api.rst b/plugins/api.rst new file mode 100644 index 0000000..f9e3e5a --- /dev/null +++ b/plugins/api.rst @@ -0,0 +1,371 @@ +Plugin API Reference +===================== + +The following section outlines the Podrum plugin API. + + +.. py:class:: server() + + The Podrum server. + + .. py:attribute:: managers + + An instance of :class:`managers`. + + .. py:attribute:: rak_net_interface + + The server's raknet interface. Shouldn't be messed with. + + .. py:attribute:: logger + + The server's :class:`logger`. + + .. py:attribute:: players + + A :class:`dict` of all the players connected to the server. + + .. py:attribute:: current_entity_id + + An :class:`int`. Currently does nothing. + + .. py:attribute:: is_ticking + + A :class:`bool` that indicates whether or not the server is ticking. + + .. py:attribute:: world + + The server's default :class:`world`. + Only available when the server is running. + + .. py:method:: get_plugin_main(name) + + Returns a plugin's main class. + + :param name: The plugin's name. + :type name: str + + :returns: The plugin's main class, or ``None`` if not found. + + .. py:method:: get_root_path() + + Gets the path of the Podrum source. + + :returns: The path of the Podrum source. + :rtype: :class:`str` + + .. py:method:: setup_config() + + Loads the server's configuration. + + .. py:method:: start() + + Starts the server. + + .. py:method:: dispatch_command(user_input, sender) + + Dispatches a command. + + :param user_input: The input from the user. + :type user_input: :class:`str` + + :param sender: The person that sent the command. Can be either a player or the server. + :type sender: Union[:class:`server`, :class:`mcbe_player`] + + .. py:method:: stop() + + Unloads all plugins, saves the world, and stops the server. + + .. py:method:: send_message(message) + + Sends a message to the console. + + :param message: The message to send. + :type message: :class:`str` + + .. py:method:: broadcast_message(message) + + Sends a message to all online players. + + :param message: The message to broadcast. + :type message: :class:`str` + + .. py:method:: send_chat_message(message) + + Broadcasts a message with the format ``[Server] ``. + + :param message: The message to send. + :type message: :class:`str` + + .. py:method:: console_input() + + Takes input from the console and then + dispatches a command with :func:`dispatch_command`. + + .. py:method:: find_player(username) + + Finds a player with the specified username. + + :param username: The username to search for. + :type username: :class:`str` + + :returns: A player with the specified username, or ``None`` if not found. + :rtype: Optional[:class:`mcbe_player`] + + +.. py:class:: mcbe_player(connection, server, entity_id) + + Represents a Minecraft: Bedrock Edition player. + + .. py:attribute:: connection + + The player's connection to the server. + + .. py:attribute:: server + + The :class:`server` the player is associated with. + + .. py:attribute:: world + + The :class:`world` the player is in. + + .. py:attribute:: metadata_storage + + Stores the player's metadata. + + .. py:attribute:: attributes + + A :class:`list` of the player's attributes. + + .. py:attribute:: message_format + + The format the player's messages should be sent in. Defaults to ``<%username> %message`` + + .. py:attribute:: chunk_send_queue + + A :class:`Queue` for sending chunks. + + .. py:method:: chunk_send_worker() + + A worker for sending chunks. + + .. py:method:: start_chunk_send_workers(count) + + Starts a set amount of :func:`chunk_send_worker`. + + :param count: The number of workers to start. + :type count: :class:`int` + + .. py:method:: send_start_game() + + Sends a ``start_game`` packet to the player. + + .. py:method:: send_item_component_packet() + + Sends an ``item_component`` packet to the player. + + .. py:method:: send_creative_content_packet() + + Sends a ``creative_content`` packet to the player. + + .. py:method:: send_biome_definition_list_packet() + + Sends a ``biome_definition_list`` packet to the player. + + .. py:method:: send_available_entity_identifiers_packet() + + Sends an ``available_entity_identifiers`` packet to the player. + + .. py:method:: handle_login_packet(data) + + Handles a ``login`` packet. + + :param data: The packet's data. + :type data: :class:`bytes` + + .. py:method:: disconnect(message, *, hide_disconnect_screen) + + Disconnects the player from the server. + + :param message: The message to be displayed to the player. + Defaults to ``Disconnected from server.`` + :type message: :class:`str` + + :param hide_disconnect_screen: Whether or not to hide the disconnect screen. + Defaults to ``False``. + :type hide_disconnect_screen: :class:`bool` + + .. py:method:: transfer(address, port) + + Transfers the player to another server. + + This disconnects the player, brings them to the main menu, + connects them to the server. + + :param address: The address of the server to transfer the player to. + :type address: :class:`str` + + :param port: The port of the server to transfer the player to. + Defaults to ``19132``. + :type port: :class:`int` + + .. py:method:: send_form(form_id, form) + + Sends a form to the player. + + :param form_id: The ID of the form. + :type form_id: :class:`int` + + :param form: The form to send to the player. + :type form: :class:`form` + + .. py:method:: handle_modal_form_response_packet(data) + + Handles a ``modal_form_response`` packet. + + :param data: The packet's data. + :type data: :class:`bytes` + + .. py:method:: handle_resource_pack_client_response_packet(data) + + Handles a ``resource_pack_client_response`` packet. + + :param data: The packet's data. + :type data: :class:`bytes` + + .. py:method:: handle_packet_violation_warning_packet(data) + + Handles a ``packet_violation_warning`` packet. + + :param data: The packet's data. + :type data: :class:`bytes` + + .. py:method:: handle_request_chunk_radius_packet(data) + + Handles a ``request_chunk_radius`` packet. + + :param data: The packet's data. + :type data: :class:`bytes` + + .. py:method:: handle_move_player_packet(data) + + Handles a ``move_player`` packet. + + :param data: The packet's data. + :type data: :class:`bytes` + + .. py:method:: handle_player_action_packet(data) + + Handles a ``player_action`` packet. + + :param data: The packet's data. + :type data: :class:`bytes` + + .. py:method:: send_message(message, xuid, needs_translation) + + Sends a message to the player. + + :param message: The message to send. + :type message: :class:`str` + + :param xuid: The XUID of the player who sent the message. + Defaults to an empty string. + :type xuid: :class:`str` + + :param needs_translation: Whether or not the message needs translation. + Defaults to ``False``. + :type needs_translation: :class:`bool` + + .. py:method:: broadcast_message(message, xuid, needs_translation) + + Sends a message to all online players. + + :param message: The message to send. + :type message: :class:`str` + + :param xuid: The XUID of the player who sent the message. + Defaults to an empty string. + :type xuid: :class:`str` + + :param needs_translation: Whether or not the message needs translation. + Defaults to ``False``. + :type needs_translation: :class:`bool` + + .. py:method:: send_chat_message(message) + + Sends a message as the player. + + :param message: The message to send. + :type message: :class:`str` + + .. py:method:: handle_text_packet(data) + + Handles a ``text`` packet. + + :param data: The packet's data. + :type data: :class:`bytes` + + .. py:method:: handle_interact_packet(data) + + Handles a ``interact`` packet. + + :param data: The packet's data. + :type data: :class:`bytes` + + .. py:method:: handle_command_request_packet(data) + + Handles a ``command_request`` packet. + + :param data: The packet's data. + :type data: :class:`bytes` + + .. py:method:: handle_packet(data) + + Handles an incoming packet. + + :param data: The packet's data. + :type data: :class:`bytes` + + .. py:method:: send_chunks() + + Sends chunks to the player. + + .. py:method:: send_available_commands() + + Sends available commands to the player. + + .. py:method:: send_network_chunk_publisher_update() + + Sends a ``network_chunk_publisher_update`` packet to the player. + + .. py:method:: send_chunk(send_chunk) + + Sends a chunk to the player. + + :param send_chunk: The chunk to send. + :type send_chunk: :class:`chunk` + + .. py:method:: send_play_status(status) + + Sends a ``play_status`` packet to the player. + + :param status: The status to send. + :type status: :class:`int` + + .. py:method:: send_metadata() + + Sends a ``set_entity_data`` packet to the player. + + .. py:method:: send_attributes() + + Sends an ``update_attributes`` packet to the player. + + .. py:method:: send_packet(data) + + Sends a packet to the player. + + :param data: The packet's data. + :type data: :class:`bytes` + + + + diff --git a/plugins/creating.rst b/plugins/creating.rst new file mode 100644 index 0000000..fa1d4f1 --- /dev/null +++ b/plugins/creating.rst @@ -0,0 +1,39 @@ +Creating a Plugin +=================== + +A plugin has two main components: + +* An ``info.json`` file that tells the server about the plugin, +* A main class inside a main file. + +To start, create an ``info.json`` file. It should look something like this: + +.. code:: js + + { + "name": "Plugin Name", // The name of your plugin. + "api_version": "0.0.1", // The API version of your plugin. + "main": "main.Main", // Your plugin's main class. + "version": "0.0.1", // Your plugin's version. + "description": "Plugin Description", // Your plugin's description. + "author": "Plugin Author" // The plugin's author. + } + +Now, it's time to start coding. + +Create a new Python file. For the purpose of this tutorial, +we're going to name it ``main.py``. + +Inside that file, create a new class, let's call it ``Main``. + +This class should have an ``__init__`` method that takes no arguments (other than ``self``), +and gives the class a ``server`` attribute. + +When your plugin is loaded, the ``server`` attribute will be the server the plugin is loaded into. + +Your plugin's ``Main`` class can have 2 methods that are used by the server, +``on_load`` and ``on_unload``. + +Each method is called when the plugin is loaded/unloaded respectively. + + diff --git a/plugins/index.rst b/plugins/index.rst new file mode 100644 index 0000000..a490e22 --- /dev/null +++ b/plugins/index.rst @@ -0,0 +1,12 @@ +Plugins +======== + +This section details how to create plugins using Podrum's plugin API. + + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + creating + api \ No newline at end of file diff --git a/server/configuration.rst b/server/configuration.rst new file mode 100644 index 0000000..330a86e --- /dev/null +++ b/server/configuration.rst @@ -0,0 +1,52 @@ +Configuration +============== + +This page details the various settings you can +configure to modify the behavior of Podrum. + +The server's configuration is stored in a json format, in ``server.json``. + +ip_address +*********** + +hostname +--------- + +* **default**: ``0.0.0.0`` +* **description**: Sets the IP the server should be listening for connections on. + +port +----- + +* **default**: ``19132`` +* **description**: Sets the port the server should be listening for connections on. + +motd +***** + +* **default**: Podrum Server +* **description**: Sets the server's MOTD (message of the day). + +max_players +************ + +* **default**: ``20`` +* **description**: Sets the server's maximum player count. + +max_view_distance +****************** + +* **default**: ``8`` +* **description**: Sets a player's maximum view distance, in chunks. + +world_provider +****************** + +* **default**: anvil +* **description**: Sets the default world provider. + +world_name +****************** + +* **default**: world +* **description**: Sets the default world name. diff --git a/server/getting-started.rst b/server/getting-started.rst new file mode 100644 index 0000000..762c9a3 --- /dev/null +++ b/server/getting-started.rst @@ -0,0 +1,76 @@ +Getting Started +================ + +- :ref:`Downloading the Server` +- :ref:`Requirements` +- :ref:`Running The Server` +- :ref:`Updating The Server` + + +.. _download: + +Downloading the Server +*********************** + +To obtain a copy of the server, +simply clone our `GitHub Repository `_, +or download it as a zip and extract it to a location on your system. + + +.. _requirements: + +Requirements +************* + +Podrum should function with Python 3.6+, however, +it is recommended that you use the latest version. + +You can download a version of Python at https://python.org/downloads. + +Once you have Python installed, you can install the rest of the requirements +by running one of the the following commands in your server's root directory: + +.. code:: sh + + # Linux/macOS + python3 -m pip install -U -r requirements.txt + + # Windows + py -3 -m pip install -U -r requirements.txt + + +.. _running: + +Running the Server +******************* + +To run the server, run one of the the following +commands in your server's root directory: + +.. code:: sh + + # Linux/macOS + python3 __main__.py + + # Windows + py -3 __main__.py + +.. _updating: + +Updating the Server +******************* + +To update your server, simply re-clone our `GitHub Repository `_, +or download it as a zip and extract it to a location on your system. + +You can then update your requirements by running one of the the +following commands in your server's root directory: + +.. code:: sh + + # Linux/macOS + python3 -m pip install -U -r requirements.txt + + # Windows + py -3 -m pip install -U -r requirements.txt + diff --git a/server/index.rst b/server/index.rst new file mode 100644 index 0000000..c2bedcd --- /dev/null +++ b/server/index.rst @@ -0,0 +1,15 @@ +.. _server_index: + +Running a Podrum Server +======================== + +Running a Podrum server is easy. + +Click a link below to get started. + +.. toctree:: + :maxdepth: 2 + :titlesonly: + + getting-started + configuration