pyCraft Documentation

pyCraft is a Python project designed to handle networking between a Minecraft server and a client. It is divided into two primary functional areas:

1. Authentication: A package containing utilities to manage communication with Mojang's authentication servers. This allows you to log in with a Minecraft account, edit profiles, and more.
2. Networking: Centered around the Connection class, this package handles the core client-server interaction, including connecting to a server, sending packets, and listening for incoming packets.

Minecraft Versions

pyCraft supports a wide range of Minecraft releases, including:

• 1.8 through 1.8.9
• 1.9 through 1.9.4
• 1.10 through 1.10.2
• 1.11 through 1.11.2
• 1.12 through 1.12.2
• 1.13 through 1.13.2
• 1.14 through 1.14.4
• 1.15 through 1.15.2
• 1.16 through 1.16.5
• 1.17 through 1.17.1
• 1.18 through 1.18.1

Note: For a full list of supported versions and protocol numbers, refer to minecraft/__init__.py.

Python Versions

Compatible with:

• Python 3.5, 3.6, 3.7, 3.8, 3.9
• PyPy

The Connection class in minecraft.networking.connection is the primary interface for interacting with a Minecraft server. It handles the lifecycle of the connection and provides methods for writing packets and registering listeners.

from minecraft.networking.connection import Connection

connection = Connection(address, port, auth_token=auth_token)
connection.connect()

To authenticate a Minecraft account, create an instance of the AuthenticationToken class and call its authenticate method with the user's username and password.

If authentication is successful, the method returns True. If it fails (e.g., due to incorrect credentials or a network error), it raises a YggdrasilError.

from minecraft.authentication import AuthenticationToken

token = AuthenticationToken()
success = token.authenticate(username='your_username', password='your_password')
if success:
    print("Logged in successfully!")

To send data to a server, instantiate a specific packet class and use connection.write_packet(packet).

When setting values on a packet, ensure the attribute names you use match the names defined in the packet's definition attribute. For example, if a packet definition uses keep_alive_id, you must set packet.keep_alive_id.

from minecraft.networking.packets import serverbound
import random

# Create the packet instance
packet = serverbound.play.KeepAlivePacket()
# Set values based on the packet's definition
packet.keep_alive_id = random.randint(0, 5000)
# Send it via the connection
connection.write_packet(packet)

To install pyCraft and its necessary dependencies, use pip to install the requirements. The library requires cryptography, requests, and PyNBT.

pip install -r requirements.txt

When running the client, you can inspect the network traffic by using the --dump-packets flag.

• Standard Packets: Known packet types are printed to stderr with a prefix indicating direction (--> for incoming, <-- for outgoing).
• Unknown Packets: By default, packets that do not match a known type (instances of the base Packet class) are ignored. To see these, you must also include the --dump-unknown-packets flag. Unknown packets will be printed as --> [unknown packet] <packet_representation>.

All packet debugging output is sent to sys.stderr to avoid interfering with standard input/output.

The repository includes a file named start.py which serves as a basic example of a headless client using the pyCraft library. You can run this script to see the library in action. Use the --help flag to view available command-line options.

python start.py --help

If you cannot use decorators (e.g., the function is defined elsewhere), use the connection.register_packet_listener(callback, PacketClass) method to register a listener manually.

from minecraft.networking.packets.clientbound.play import ChatMessagePacket

def print_chat(chat_packet):
    print "Position: " + str(chat_packet.position)
    print "Data: " + chat_packet.json_data

connection.register_packet_listener(print_chat, ChatMessagePacket)

You can perform custom operations on Mojang's Yggdrasil authentication service by using the _make_request method. To target the authentication service specifically, pass authentication.AUTH_SERVER as the server parameter. This is useful for actions like signing out.

import minecraft.authentication as authentication

payload = {
    'username': 'your_username',
    'password': 'your_password'
}

# Example: making a signout request
authentication._make_request(authentication.AUTH_SERVER, "signout", payload)