Create an entity class with necessary information about that entity. Look on wiki.vg or here: https://wiki.vg/Protocol#Spawn_Entity to see what needs to be added.

• This should be located in src/types/entity.py or something similar.
• This should contain helpful classmethods such as creating the packet data for spawning, moving, and other interactions with the entity

• Must support all NBT types supported by Minecraft
• Must support loading NBT from bytes
• Must support dumping NBT to bytes

What do?

Pages

• A home/index page with a table of contents and something similar to the readme
• Installation instructions
• Installing plugins
• Developing plugins
• Project status (maybe)
• Development of PyMine guidelines (maybe)

Benefits

• Provides accessible information to users / developers
• Centralized place to store information on the project
• Makes project seem more official
• Less annoying kids asking questions with obvious answers (maybe)

There's missing buffer methods for packing and unpacking entity metadata. See here for information on entity metadata: https://wiki.vg/Entity_metadata#Entity_Metadata_Format

What Do?

• Update each plugin concurrently (at the same time)

Benefits / Reason?

• Updating each plugin takes about a second each, parallelized it would be wayyyyy faster.

What do?

• All code like b''.join(something for something in somethin) should be replaced with b''.join([something for something in somethin])

Why tho?

• It's over 2x faster using PyPy, and still significantly faster in regular Python.

There are some possibly unused functions used for packing/unpacking data in the Buffer class. However, they may be needed in the future as we haven't finished all of the packets yet. When 4-create-packets is finished, the following should be undertaken for every method in the Buffer object:

1. Check if method/function is used
2. If not, comment out the entire code for that function, and remove any dependencies that are needed solely for that method.

Again, this doesn't need to and can't be done till all of the packets have been finished.

Feature

• Make tests for everything that's testable, of course within reason.
• Tests should go under tests/
• We should use unittest or pytest (pytest looks better)
• Tests should be split up into different files by their category
• We should have tests for: (this a list of what I can think about rn, feel free to add more!)
  • Buffer methods
    • add a test for each type, unpack and repack each type
  • Packets
    • There should be an example data set, preferably bytes that is fed into the Packet.decode() and then back into packet.encode()
  • NBT lib
    • Load nbttest.nbt, parse it, pack/encode it back, and check to see if the uncompressed version is the same to the newly packed/encoded version.
  • World saving + loading
  • Chunk gen

Reason

• Allows us to test features/functions/classes/etc... reliably
• Gives examples of how to use the tested functions/classes/etc...

UPDATE

• Currently in progress under the tests branch
• We're using pytest
• GitHub workflows have been setup to utilize the tests

Cleanup plugin related code, and start on the basic plugin api.

What do?

• Currently the codebase is functional, based around functions calling each other. This is not really Pythonic and makes for very messy code.
• Convert to OOP (Object Oriented Programming)

Benefits

• Cleaner codebase
• Easier for plugin developers to understand + use
• Looks nicer

See here for immutable dicts and other types: https://github.com/MagicStack/immutables

What do?

• Move most of api/__init__.py to api/api.py and limit what parts of the API are exposed to the plugin developer
• Remember to update the example plugin if need be

Benefits

• Easier to understand + use for devs and plugin devs
• Less cluttering of names and scopes
• Looks nicer

Commands should be implemented via decorator, discord.py style. Decorators should contain the name of the command, any aliases, permission node of the command, namespace of the command, etc... Functions under decorators should only be async.

Rename the src folder to pymine for clarity in imports for plugin developers and because it looks better. This will also entail refactoring imports in almost all files.

What do?

• Start on packet handlers for play packets, world saving + loading code, etc...
• For packet handlers, you should go roughly "in order", basically do the ones most integral to being able to play on the server first.

See here for a normal login sequence: https://wiki.vg/Protocol_FAQ#What.27s_the_normal_login_sequence_for_a_client.3F

Finish Buffer.unpack_packet() now that PACKET_MAP has been finished

What Do?

• Plugins should come with their own file in the root folder of the plugin called something like plugin.yml
• This should replace plugins.yml

Benefits / Reason?

• Removes need for end user to have to config their own plugins.yml
• Makes it easier to use + install plugins

List of optimizations (to maybe be implemented later) to make PyMine fast!

World pre-generation

• Each region or group of chunks to be generated handled by a separate process
• Easily parallelized via multiprocessing
• Benefits:
  • Faster world/chunk times for the pre-generated chunks
  • Less strain on the server later on
• Drawbacks:
  • Would probably render the server super laggy when active
  • Only works for a specified area
  • Could possibly waste disk space if that area isn't used

Groups of players handled each by a separate process

• Backend process which handles world gen, global events, etc...
• Every group of 3-5 players is handled by a separate process
• Benefits:
  • Faster server response times and packet handling
• Drawbacks:
  • Clunky + jank code to synchronize data between processes
  • Probably not worth it with groups so small or on crappier machines

Dynamic world generation

• Similar to world pre-generation
• When resources are free, pre-generate chunks around a player even if they're not attempting to load not-yet-generated chunks.
• Benefits:
  • Faster chunk/world load times for players in the area
  • Possible less strain on the server if the server were to need those chunks to be generated in the future
• Drawbacks:
  • Possible shortage of resources if resource usage suddenly spikes
  • Waste of disk space if chunks that are generated are never used

Unused chunk degenerator

• When ran, would delete chunks that were left completely unchanged
• Easily parallelized via multiprocessing
• Benefits:
  • Could reduce amount of used disk space
• Drawbacks:
  • Could increase server strain later on when those chunks are used again
  • Not worth it unless disk space is scarce

Separate processes for loading/dumping chunks/regions

• A full-ish region (from Xenon) takes about 6 seconds to load, and it'd probably take just as long to dump.
• Loading/unpacking a region file is also very CPU intensive, which would BLOCK the event loop
• Actually reading/writing the file from the disk also blocks the event loop
• Benefits:
  • Reduces server lag
  • Makes chunks faster to load (maybe)
• Drawbacks:
  • Hard to implement well

Custom Region Format

• Consists of 1024 chunks just like the normal format
• Has a location table, just like the normal format
• Each chunk has a header of a 4 byte int that says how long it is
• The entire file is zlib-compressed, rather than each chunk section
• Region file is named mostly the same, except the file extension is .mcpyr or something else idk
• Benefits:
  • Less space used to store a region (a 32x32 section of chunks)
  • Less calls to zlib.decompress()
• Drawbacks:
  • Not compatible with normal worlds / region files
  • We would need to support two region file formats

Once base packet class is done, start creating all the packets. These packets should go under src/types/packets and should be subclasses of src.types.packet.Packet. For a list of all the packets, look here: https://wiki.vg/Protocol (Important: this link displays the most recent versions protocol, to view a specific version go here)

Packet Making Guide v2

Naming

• Packets are named by their state and name on wiki.vg
  Examples: class PlayUpdateLight or class HandshakeHandshake or class PlayPlayerPosition

Creation

• Packets should have two class object attributes (id and to), a docstring describing them, an __init__, and the decode or encode method (or both)
• Packets should also subclass a Packet object, and initialize it.
  Example:

class TestExample(Packet):
  """This is an example packet, not used at all. (Client -> Server AND Server -> Client)

  :param str dummy_payload: The payload of the packet.
  :attr int id: Unique packet ID.
  :attr int to: Packet direction.
  :attr dummy_payload:
  """

  id = 0x00  # ID of the packet, found on wiki.vg in the section where there's info on the packet
  to = 2  # 0=serverbound, 1=clientbound, 2=both be careful when using 2 as many packets are both, but have different IDs

  def __init__(self, dummy_payload: str) -> None:
    super().__init__()

    self.dummy_payload = dummy_payload

  def encode(self) -> bytes:
    return Buffer.pack_string(self.dummy_payload)

  @classmethod
  def decode(cls, buf: Buffer) -> TestExample:
    return cls(buf.unpack_string())

Additional Info:

• Packet docstrings should be generated via the atom plugin docblock-python or another plugin for another editor. They should be in the sphinx format.
• Docstrings, on the first line, should contain the short summary, any additional links/info, and in parentheses the direction(s) of the packet.
• Remember to add the name of the packet to the file's __all__ (located near the top of the file, after imports)
• If you can't find the right file to place your packet, you can create a new one. Remember to import annotations from __future__ to allow for proper typehints, and to add an __all__.

Progress Checklist (By States)

• handshake packets
• status packets
• login packets
• play packets

What do?

• Merge the StreamReader and StreamWriter objects together in server.py's handle_con() function.
• By extension, the EncryptedStreamReader and EncryptedStreamWriter classes in util/encryption.py should be merged as well.

Benefits

• Easier for developers of PyMine
• Less function args, makes for cleaner function headers
• Easier to understand for plugin devs
• slightly faster? (unsure but seems like it)

Don't know where they went, but they include Buffer.pack_entity_metadata and Buffer.pack_particle and possibly others...

@all-contributors add @Iapetus-11 for contribution, design, data, example, ideas, mentoring, maintenance

Create the models for packets and data types sent and received by the server, as well as code to encode and decode them to make it easier to dev server

Feature

• Basic description of what this idea / new feature would entail
• List out all features of the idea / new feature

Reason

• Reasoning / benefits behind this feature / idea.

Add basic server connection handling and state changing logic. Should be able to deal with status packets, and login a player.

Console should have like two sections, horizontally split. The bottom-most one should be just one row/line and should contain a > and whatever the user is typing. The above section should contain output/logging information. If a user is typing, what they've typed should not be overwritten by any logging/output.

You can see any modern console, such as paper/bukkit/vanilla for how this looks/feels

Sort the methods in buffer.py by relevance and importance

Describe the bug

• Server address appears as None

To Reproduce

1. Download + run PyMine without a preexisting server.yml

Expected Behavior

• Server address should be automatically detected if not present.

What do?

• Add a query_enabled and query_port to the server.yml.
• If query is enabled, create a UDP server on the specified port, if the port isn't specified, use the one the server is on.
• Should support the query protocol in its entirety.
• Packets (which can be functions, nothing complex needed for only like 4 packets), should go under pymine/net/query.
• Actual server logic can go in pymine/logic/query.py.

Needed for PlayTradeList (0x26). See here for the format. Buffer.unpack_trade() is most likely not needed, and does not need to be completed for this issue to be closed.

Cleanup server.py code and files under src/logic

What do?

• Remove the need for a bool to be returned from packet handlers
• Replace it with a custom exception, something like StopHandlingStream

Reason

• Simpler code
• Probably slightly faster

Describe Bug

you get redirected to wrong page https://gyazo.com/cd77477b4128dba6919aba22c86ceefb ; instead you should be redirected to the invite which invites you to the discord

To Reproduce

1. Go to contribute md
2. Click on the discord link
3. See the issue

Expected Behavior

you should be invited to the discord

Screenshots / Proof

https://gyazo.com/cd77477b4128dba6919aba22c86ceefb

Additional Context

None

Feature

• NBT library with classes for all NBT types, and methods for dealing with NBT data.
• Should probably put it in under pymine/types/nbt/*

Reason

• All the other NBT libs I've seen either have unnecessary/extraneous features or are needlessly complex and slow.

• Remove nbt from the requirements.txt
• Update buffer methods which deal with nbt to use the new lib

• Add docstrings to classes and functions in the sphinx style (use docblock-python or a similar plugin)
• Create documentation on https://readthedocs.org using reStructured text
• This should be as detailed as possible
• Ask me on Discord if you want me to explain something or make a description / docs for it.

Is your feature request related to a problem? Please describe.
I don't like how there are flags for some states but not others.

Describe the solution you'd like
--dump-packets flags for all states, maybe some color in dumped packets, code cleanup

cause *** it is fugly (and not good for implementing api hooks)

Plugin ideas!

Feel free to make some of these! Ones which have been done reasonably well will be crossed out and linked to!

Utility

• permission manager
• bedrock server support (like Geyser)
• discord server link - is that not part of auto-message a bit lower down?
• core-protect clone (anti grief + logging + rollback capabilities)
• essentialsx knockoff (bunch of useful commands)
• warp points / teleportation plugin
• colored roles/chat
• anti-cheat / anti-xray
• realistic tree chopping
• multi-world support
• single player sleep
• auto messages (like send motd, customize player join messages, etc...)
• auto-backups
• command macros / aliases
• GUI for managing the server, maybe a web UI?
• password based login (good for offline servers)
• chat filter (anti-spam, anti-toxicity)
• large scale world editing (like world edit)
• java edition plugin APIs, like Bukkit (Bukkit git) or Sponge API
• punishments (banning/tempbanning/muting/kicking/reporting?/jail world?)
• a packet level vanish plugin that just removes all mentions of a player from outgoing packets, unless the reciever has permission to "see" them.

Fun(ish)

• trampolines
• towny
• minigames
• gameboy emulator
• death swap
• chairs (sit on stairs)
• particle trails
• custom armor + weapons
• mob/player head drop
• forge compatibility?

Misc

• markdown for the mc chat
• brainfuck interpreter + evaluation commands
• scratch but for PyMine
• fabric compatibility?
• a decent resource pack manager? maybe a gui for the client?
• two-factor authentication
  - Totp/hotp -> in-game, using maps + qr codes
  - Email -> external, click link sent in email enter code shown ingame, or enter code sent in email
  - Uf2/webauthn/fido2 -> external helper webserver + website, redirects
  - SMS API,
  - Discord, DM users

Put your ideas below, and they'll be added to the main comment!

The current buffer code is based off quarry's code for Minecraft 1.7. We need to update this to the latest available.

Methods were forgotten and need to be completed

Is your feature request related to a problem? Please describe.
Need me some hot docstrings.

Describe the solution you'd like
Add sphinx-styled descriptive docstrings to all classes/major functions.

Describe alternatives you've considered
no❤️
Additional info:
https://atom.io/packages/docblock-python

What Do?

• Move command API code under pymine/api/

Benefits / Reason?

• Cleaner and less confusing codebase

• This is to be used for optional packet fields, and will make life so much easier.
• Optional fields are ones which are marked by a boolean, if the boolean is True, then that field will actually be present, otherwise there will be no following field.
• Buffer.pack_optional() should take two arguments, the packer method (like Buffer.pack_varint) and the data.
• Buffer.unpack_optional() should take two arguments as well, the unpacker method (like Buffer.unpack_varint) and the data.

When attempting to follow each step written in the Installing from source section in the README with either pypy3 or python3, it leads to a ModuleNotFoundError when running the last step, python3 pymine/server.py.

Pypy3:

$ pypy3 --version
Python 3.7.9 (7e6e2bb30ac5fbdbd443619cae28c51d5c162a02, Nov 24 2020, 10:03:59)
[PyPy 7.3.3-beta0 with GCC 10.2.0]
$ pypy3 pymine/server.py 
Traceback (most recent call last):
  File "pymine/server.py", line 7, in <module>
    from pymine.types.buffer import Buffer
ModuleNotFoundError: No module named 'pymine'

Python3:

$ python3 --version
Python 3.9.1
$ python3 pymine/server.py 
Traceback (most recent call last):
  File "/mnt/pool/sofi/Downloads/PyMine/pymine/server.py", line 7, in <module>
    from pymine.types.buffer import Buffer
ModuleNotFoundError: No module named 'pymine'

What do?

• Add an rcon_enabled, rcon_port, and rcon_password to the server.yml.
• If rcon_enabled is true, start a tcp server on the specified port (or if not present 25575).
• This should support the entirety of the rcon spec.
• The RCON protocol / packets should probably go under pymine/net/rcon.
• Actual server logic should probably go in pymine/logic/rcon.py.

Use the os module to check if the os is linux. If so, and if uvloop is available, use it.

What do?

• Add a classmethod to the Buffer class which packs modifier data. (Should be called pack_modifier)
• See here for examples on modifier data:
  • https://minecraft.gamepedia.com/Attribute#Modifiers
  • https://wiki.vg/Protocol#Entity_Properties

Why tho?

• Required for the PlayEntityProperties packet.

Implement all needed packets, chunk/world gen, saving, etc...

Add uvloop to requirements.txt and use it in server.py