diff --git a/docs/index.rst b/docs/index.rst index 72f41f4d..7700c007 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,6 +7,7 @@ Content :maxdepth: 1 :caption: Pages + pages/faq.rst pages/contributing.rst examples/examples.rst diff --git a/docs/pages/faq.rst b/docs/pages/faq.rst new file mode 100644 index 00000000..636cdff4 --- /dev/null +++ b/docs/pages/faq.rst @@ -0,0 +1,77 @@ +Frequently Asked Questions +========================== + + +Why doesn't :class:`~mcstatus.server.BedrockServer` have an async :meth:`~mcstatus.server.MCServer.lookup` method? +------------------------------------------------------------------------------------------------------------------ + +With Java servers, to find the server, we sometimes end up performing an SRV +DNS lookup. This means making a request to your DNS server and waiting for an +answer, making that lookup a blocking operation (during which other things can +be done). + +.. note:: + An SRV record allows the server to have an address like: ``hypixel.net``, + that points to a some specified IP/Host and port, depending on this record. + + That way, even if the server is hosted on a non-standard port (other than + 25565, say 8855), you won't need to use ``myserver.com:8855``, since the + port number will simply be stored in the SRV record, so people can still + connect simply with ``myserver.com``. + + On top of that, it also allows to specify a different IP/Host, which means + you don't need to use the same server to run both the website, and the + minecraft server. Instead, the SRV record can simply point to a different + IP/Host address (like ``mc.hypixel.net``, or ``209.222.114.112``). + +However with Bedrock servers, no such lookups are required (Bedrock doesn't +support SRV records), and so there is no blocking I/O operation being made, +that would justify having an async version. + +In fact, all that the bedrock lookup does is parsing the ``host:port`` address, +and obtaining the ``host`` and ``port`` parts out of it (with some error +handling, and support for default ports). + + +Incorrect encoding +------------------ + +In Query protocol, Minecraft uses ISO 8859-1 for encoding all text (like MOTD, +server name, etc.). This can cause problems with non-latin characters. To fix +such error, you can re-encode text into UTF-8. + +.. code-block:: python + + >>> query = JavaServer.lookup("my-server-ip.com").query() + >>> query.motd + 'Ð\x9fÑ\x80ивÑ\x96Ñ\x82!' + >>> query.motd.encode("iso-8859-1").decode("utf-8") + 'Привіт!' + +:attr:`query.motd ` here can be anything, +that contains incorrect encoding. + + +How to get server image? +------------------------ + +On Bedrock, only official servers have a server image. There is no way to get +or set an icon to a custom server. For Java servers, you can use +:attr:`status.icon ` +attribute. It will return `Base64 `_ +encoded PNG image, so you can decode it in that way: + +.. code-block:: python + + import base64 + + with open("server-icon.png", "wb") as server_icon_file: + server_favicon_file.write(base64.decodebytes(status.icon)) + +.. note:: + Most modern browsers support simply pasting the raw Base64 image into the + URL bar, which will open it as an image preview, allowing you to take a + quick look at it without having to use file saving from Python. + + See `How to display Base64 image `_ + and `Base64 Images: Support table `_. diff --git a/mcstatus/status_response.py b/mcstatus/status_response.py index a398646a..8bd98379 100644 --- a/mcstatus/status_response.py +++ b/mcstatus/status_response.py @@ -153,7 +153,10 @@ class JavaStatusResponse(BaseStatusResponse): players: JavaStatusPlayers version: JavaStatusVersion icon: str | None - """The icon of the server. In `Base64 `_ encoded PNG image format.""" + """The icon of the server. In `Base64 `_ encoded PNG image format. + + .. seealso:: :ref:`pages/faq:how to get server image?` + """ @classmethod def build(cls, raw: RawJavaResponse, latency: float = 0) -> Self: