Factories and Protocols

Factories

Factories represent your minecraft server or client as a whole. Normally only one factory is created.

Client factories require a Profile object to be supplied to the initializer. Use the ClientFactory.connect() method to connect. If force_protocol_version is not defined, this method will make two connections to the server; the first is used to establish the server’s protocol version.

class quarry.net.client.ClientFactory(profile=None)

protocol

alias of ClientProtocol

__init__(profile=None)

connect(host, port=25565)

force_protocol_version = None

get_buff_type(protocol_version)

Gets a buffer type for the given protocol version.

Server factories are used to customize server-wide behaviour. Use listen() to listen for connections. A set of all associated ServerProtocol objects is available as players().

class quarry.net.server.ServerFactory

protocol

alias of ServerProtocol

motd = 'A Minecraft Server'

max_players = 20

icon_path = None

online_mode = True

prevent_proxy_connections = True

compression_threshold = 256

auth_timeout = 30

__init__()

players = None

listen(host, port=25565)

force_protocol_version = None

get_buff_type(protocol_version)

Gets a buffer type for the given protocol version.

Protocols

Protocols represent a connection to a remote minecraft server or client. For most common usages, clients have only one protocol active at any given time. In protocols you can define packet handlers or override methods in order to respond to events.

class quarry.net.protocol.Protocol

Minecraft protocol implementation common to both clients and servers. You should not subclass from this class, but rather subclass from one of the three classes below.

The methods/attributes given below relate specifically to quarry; the rest are given in the Connection, Authentication and Packets sections further on.

factory = None

A reference to the factory

logger = None

The logger for this protocol.

ticker = None

A reference to a Ticker instance.

class quarry.net.server.ServerProtocol(factory, remote_addr)

This class represents a connection with a client

class quarry.net.client.ClientProtocol(factory, remote_addr)

This class represents a connection to a server

class quarry.net.client.SpawningClientProtocol(factory, remote_addr)

Connection

Override the connection_made(), connection_lost() and connection_timed_out() methods to handle connection events. The remote’s IP address is available as the remote_addr attribute.

In servers, connect_host stores the hostname the client reported that it connected to; this can be used to implement virtual hosting.

Protocol.connection_made()

Called when the connection is established

Protocol.connection_lost(reason=None)

Called when the connection is lost

Protocol.connection_timed_out()

Called when the connection has been idle too long

Protocol.remote_addr = None

The IP address of the remote.

ServerProtocol.connect_host = None

ServerProtocol.connect_port = None

Protocol.close(reason=None)

Closes the connection

Protocol.closed = False

Authentication

Override the auth_ok() and auth_failed() methods to handle an authentication outcome. In servers, the player’s display name can be obtained as display_name, with display_name_confirmed being set to True when authentication is successful. In clients, the in-use profile is available as self.factory.profile.

Override the player_joined() and player_left() methods to respond to a player entering “play” mode (via the authentication process) or quitting the game from “play” mode. You can check the player’s current status via in_game

Protocol.auth_ok(data)

Called when auth with mojang succeeded (online mode only)

Protocol.auth_failed(err)

Called when auth with mojang failed (online mode only)

ServerProtocol.display_name = None

ServerProtocol.display_name_confirmed = False

Protocol.player_joined()

Called when the player joins the game

Protocol.player_left()

Called when the player leaves the game

Protocol.in_game = False

Packets

Call send_packet() to send a packet:

# Add a diamond sword to the first hotbar slot
window_id = 0
slot_id = 36
item_id = 276

self.send_packet("set_slot",
    self.buff_type.pack('bh', window_id, slot_id) +
    self.buff_type.pack_slot(item_id))

To construct the payload, call static methods on Buffer. A reference to this class is available as self.buff_type.

To receive a packet, implement a method in your subclass of ClientProtocol or ServerProtocol with a name like packet_<packet name>:

def packet_update_health(self, buff):
    health = buff.unpack('f')
    food = buff.unpack_varint()
    saturation = buff.unpack('f')

See also

Packet Names.

You are passed a Buffer instance, which contains the payload of the packet. If you hook a packet, you should ensure you read the entire payload.

Packet dispatching can be customized. If you override packet_unhandled() you can handle any packets without a matching packet_<packet name> handler. If you override packet_received(), you can replace the entire packet_<packet name> dispatching.

Protocol.send_packet(name, *data)

Sends a packet to the remote.

Protocol.buff_type = None

Usually a reference to a Buffer class. This is useful when constructing a packet payload for use in send_packet()

Protocol.packet_received(buff, name)

Called when a packet is received from the remote. Usually this method dispatches the packet to a method named packet_<packet name>, or calls packet_unhandled() if no such methods exists. You might want to override this to implement your own dispatch logic or logging.

Protocol.packet_unhandled(buff, name)

Called when a packet is received that is not hooked. The default implementation silently discards the packet.

Protocol.log_packet(prefix, name)

Logs a packet at debug level

Protocol.get_packet_name(ident)

Protocol.get_packet_ident(name)

Ticking

To register delayed or repeating callbacks, call methods on the Ticker object available as self.ticker.

class quarry.net.ticker.Ticker(logger)

tick = 0

The current tick

interval = 0.05

Interval between ticks, in seconds

max_lag = 40

Maximum number of delayed ticks before they’re all skipped

start()

Start running the tick loop.

stop()

Stop running the tick loop.

add_loop(interval, callback)

Repeatedly run a callback.

Parameters:

• interval – The interval in ticks
• callback – The callback to run

Returns:

An instance providing a stop() method

add_delay(delay, callback)

Run a callback after a delay.

Parameters:

• delay – The delay in ticks
• callback – The callback to run

Returns:

An instance providing stop() and restart() methods

remove(task)

Removes a task, effectively cancelling it.

Parameters:task – The task to remove

remove_all()

Removes all registered tasks, effectively cancelling them.