pyclassic package

Submodules

pyclassic.auth module

This module contains some classes useful in authentication.

class pyclassic.auth.ClassiCubeAuth(username, password)

Bases: pyclassic.auth.SimpleAuth

Authentication class to use with a ClassiCube account. It makes use of the API to log in and retrieve the sever list.

Warning

Don’t do like me, if you want to upload your bot somewhere, make sure to not expose your creds lol

Parameters

  • username (str) – Username of the ClassiCube account

  • password (str) – Password of the ClassiCube account

check_auth()

Function mostly used internally to check if the user is authenticated to ClassiCube.

Returns

True if the user is authenticated, otherwise False. However if the status code is not 200, it returns None.

Return type

bool or None

connect(**kargs)

Provides information for PyClassic.client.Client in order to connect to a server.

Parameters

kargs – Server list query, can be the server name, the IP or even the port. Can be multiple at once. Log in to your ClassiCube account and visit http://www.classicube.net/api/servers to know available parameters you can use.

Raises

pyclassic.PyClassicError – Server has not been found or it failed to retrieve the mppass (server salt).

Returns

ip, port, username and mppass (see pyclassic.auth.SimpleAuth.connect())

Return type

(str, int, str, str)

get_session(username, password)

Also mostly used internally, creates the session cookie and log in to ClassiCube servers using the API.

Parameters

  • username (str) – Username

  • password (str) – Password

Raises

  • AssertionError – The requests to /api/login did not returned 200 OK as status code.

  • pyclassic.PyClassicError – Authentication has failed.

Returns

Session

Return type

requests.Session

server_list()

Retrieves the server list.

Raises

pyclassic.PyClassicError – User is not authenticated.

Returns

JSON response from the ClassiCube API

Return type

dict

class pyclassic.auth.SimpleAuth(username, mppass)

Bases: object

Simple authentication by providing manually the username and the server salt. This is also the base class if other authentication classes has to be implemented.

Parameters

  • username (str) – Username to log in with.

  • mppass (str) – The server salt to log in with.

connect(**kargs)

Provides information for PyClassic.client.Client in order to connect to a server.

Parameters

  • ip (str) – IP Address of the server

  • port (int) – Port of the server

Raises

AssertionError – checks if an IP and a port has been given.

Returns

IP, port, username and server salt.

Return type

(str, int, str, str)

pyclassic.batch module

Queue batch system.

This is a very simple batch system to generate queues based on specific commands. Positions must be relative. documentation soon:tm:

class pyclassic.batch.Batch(fn: dict, filterfn: dict)

Bases: object

The Batch class can generate queues on a given script.

current_queue = []
execute_line(line)
filterfn: dict
fn: dict
generate_queue(script, ox=0, oy=0, oz=0)

Generates a queue from a script and a given offset.

Parameters

script (str) – The script

Returns

The generated queue

Return type

list[pyclassic.queue.Block]

exception pyclassic.batch.BatchError

Bases: Exception

class pyclassic.batch.DefaultBatchFunctions

Bases: object

This is a static class with all the default batch functions.

batch = Batch(fn={'cuboid': <function DefaultBatchFunctions.cuboid>, 'wall': <function DefaultBatchFunctions.wall>}, filterfn={'fblock': <function DefaultBatchFunctions.filter_block>})
cuboid(ay, az, bx, by, bz, bid)
filter_block()
filterfn_dict = {'fblock': <function DefaultBatchFunctions.filter_block>}
fn_dict = {'cuboid': <function DefaultBatchFunctions.cuboid>, 'wall': <function DefaultBatchFunctions.wall>}
wall(ay, az, bx, by, bz, bid)

pyclassic.client module

The client module contains… well… the Client class that is used to handle the protocol itself such as packet receiving and sending.

It can be used independently from pyclassic.PyClassic if you want to. However you won’t have the event system obviously.

This class allows the connection and packet handling as well as some additional methods to make programming easier.

class pyclassic.client.Client(auth: pyclassic.auth.SimpleAuth, client_name=None)

Bases: object

Client class

Parameters

  • auth (pyclassic.auth.SimpleAuth) – Authentication class to connect the client to a server.

  • client_name (str or None, optional) – Client name, can be changed as you wish but defaults to “pyclassic <VERSION>”. Can be useful sometimes :troll:

connect(**kargs)

Connects to a server. Will use the specified pyclassic.auth.SimpleAuth-based class to retrieve the IP, port, username and server salt. See pyclassic.auth.SimpleAuth.connect()

If a socket is already active, it will disconnect it first then reconnect.

Parameters

kargs – Arguments to pass to the auth object to retrieve the server and the credentials to connect.

Raises
Returns

Server information or None

Return type

(str, str) or None

disconnect()

Disconnects the client if it’s connected to a server, otherwise does a great amount of nothing.

message(message)

Sends a message to the server.

Parameters

message (str) – Message to send

move(x, y, z, pitch=0, yaw=0)

Teleports the player at the specified position and direction. This functions relies on block position. See pyclassic.client.Client.move_precise() for more precise teleportation.

Note

Pitch and yaw angles are between 0 and 255 and not 0 and 359 since these fits in a byte.

move_precise(x, y, z, pitch=0, yaw=0)

Teleports the player at the specified position and direction.

Note

Pitch and yaw angles are between 0 and 255 and not 0 and 359 since these fits in a byte.

recv()

Receives a packet and decodes it appropriately.

Raises

pyclassic.utils.PyClassicError – no more data is received.

Returns

packet information and the decoded packet (without the packet ID as there is packet info)

Return type

(pyclassic.utils.PacketFormat, list)

send(pid, *args)

Sends a packet to the server.

Parameters

  • pid (int) – Packet ID

  • args – arguments

Raises

pyclassic.utils.PyClassicError – Invalid packet.

set_block(x, y, z, block_id)

Make the client place a block at a specified position.

Note

Abuse this and you’ll get kicked lmao.

pyclassic.extra module

pyclassic.extra.cuboid(x1, y1, z1, x2, y2, z2, blockid)
pyclassic.extra.download_map(bot)

Hacky function to download the map from a server. I would not recommend using it unless you’re doing hacky automated shit like I do.

Parameters

bot (pyclassic.client.Client) – The client to receive data with

Returns

The downloaded, decompressed and parsed map.

Return type

pyclassic.map.ClassicMap

pyclassic.extra.hollow(y, x1, z1, x2, z2, bid)
pyclassic.extra.pyramid(size, ox, oy, oz, bid)
pyclassic.extra.throwaway(username, clientname=None, **kargs)

Makes a “throw-away” account. This can only be used on servers that does not check user authentication. It uses pyclassic.auth.SimpleAuth as auth object.

Parameters

  • username (str) – Username of the throwaway, will also be the specified salt

  • clientname (str or None, optional) – The name of the client :troll:

  • kargs – Arguments to pass to the auth object on connection

Returns

The freshly new client that has been created just for you

Return type

pyclassic.client.Client

pyclassic.map module

This module take care of doing all the map stuff for you. It features map data decoding (including gzip decompression), and can also be edited which has been useful for the event system.

We are also considering supporting other formats such as schematic or ClassicWorld (.cw) files

Note

Concerning map loading and saving, the format it uses is essentially just the same as the data downloaded on a regular Classic server with 6 shorts (12 bytes) prepended. The 3 first being the offset of the map and the 3 last being the size of the map. All of it gzipped. It is quite trivial to parse.

class pyclassic.map.ClassicMap(data: bytes, width, height, length, compressed=True)

Bases: object

This ClassicMap class is used to store map data which can also be modified and saved in a file with the format mentionned at the beginning of the module documentation. It can also be sliced into a region.

Getting and setting blocks can be done like on an array. For example, map[3, 1, 2] = 1 sets a stone block at the position (3, 1, 2) of the stored map.

Parameters

  • data (bytes) – Raw data downloaded from the server, compressed or not

  • compressed (bool, optional) – If true, it will decompress the data using gzip

get_queue(ox=0, oy=0, oz=0)

Turns a map into a queue, a list of pyclassic.queue.Block to be used with pyclassic.queue.ThreadedQueue

Parameters

  • ox (int, optional) – X offset

  • oy (int, optional) – Y offset

  • oz (int, optional) – Z offset

Returns

The queue converted from the map.

Return type

list[pyclassic.queue.ThreadedQueue]

get_queue_from_region(x1, y1, z1, x2, y2, z2, ox=0, oy=0, oz=0)
getpos(idx)

Calculate the x, y, z position of a specified index.

Parameters

idx (int) – Index in the map

Returns

Calculated position

Return type

(int, int, int)

save(filename, compresslevel=9, ox=0, oy=0, oz=0)

Saves the map in a file.

Parameters

  • filename (str) – Name of the file to save.

  • compresslevel (int, optional) – Level of gzip compression.

  • ox (int, optional) – X offset

  • oy (int, optional) – Y offset

  • oz (int, optional) – Z offset

slice_down(vectors)
exception pyclassic.map.ClassicMapError

Bases: Exception

pyclassic.map.load(filename)

Loads a map.

Parameters

filename (str) – File name

Returns

The offset and the generate map object.

Return type

(int, int, int), pyclassic.map.ClassicMap

pyclassic.queue module

This is a queue system which can be used to build stuff. It uses a job queue and threading to optimize the building speed as it is slow using the asynchronous system of the event system.

It is designed to be used by an array of clients but can also be used with only one client. If you want to build fast on a server with anti-grief policies, this module is for you.

Warning

Some servers may IP-ban you :) Make sure to only use it on unmoderated servers. Or maybe you can do a little trolling while no one is connected :troll:

class pyclassic.queue.Block(x: int, y: int, z: int, bid: int)

Bases: object

A single block.

bid: int
x: int
y: int
z: int
exception pyclassic.queue.QueueError

Bases: Exception

class pyclassic.queue.ThreadedQueue(player: pyclassic.PyClassic, map=None, delay=0.03)

Bases: object

The class that does all the queue job.

Warning

To prevent Python from eventually doing a funny because threading while editing the job queue, please use the functions as they ensure the queue is not locked before modifying it.

Parameters
Raises

pyclassic.queue.QueueError – The list is empty or the PyClassic instance has no bot array.

add_queue(queue)

Adds a queue to the job queue.

Parameters

queue (list[pyclassic.queue.Block]) – Block queue

check_lock()

Checks if the block queue has been locked (it locks when the thread is running). It will raise an exception if it is. This is an helper function used in functions that edits the queue.

Raises

pyclassic.queue.QueueError – The queue is locked.

clear_current_queue()

Clears only the current queue.

clear_queues()

Clear the whole job queue along with the current queue.

do_all_blockqueues()

Do all queues from the job queue until there is nothing left.

Warning

I do not recommend manually running as it breaks the whole point of this class but do as you wish. See pyclassic.queue.ThreadedQueue.start_all().

do_blockqueue(threaded=True)

Pops a queue from the job queue and make the multibot run it. If there is already an unfinished current queue, continue it. Otherwise if it is empty, do nothing.

Warning

I do not recommend manually running as it breaks the whole point of this class but do as you wish. See pyclassic.queue.ThreadedQueue.start().

Parameters

threaded (bool, optional) – is it running in a thread?

is_active()

Checks if there is a running thread.

Returns

Thread running?

Return type

bool

make_thread(**kargs)

Helper function used internally to make and start a thread.

remove_queue(i)

Removes a queue from the job queue.

Parameters

i (int) – Index

start()

Starts a thread to execute one job in the queue. Does nothing if the thread is already running.

start_all()

Starts a thread to execute all jobs in the queue. Does nothing if the thread is already running.

stop()

Send a termination signal to the running thread if there is one and wait for it to stop.

pyclassic.utils module

This module contains a bunch of useful functions. I am not going to document this because those are mostly helpers for other modules. I will only document the functions that can be useful for the developer.

class pyclassic.utils.PacketFormat(pid: int, name: str, content: list)

Bases: object

content: list
name: str
pid: int
exception pyclassic.utils.PyClassicError

Bases: Exception

pyclassic.utils.api_url(n)
pyclassic.utils.contains_all(needle, haystack)
pyclassic.utils.decint(n, s=True)
pyclassic.utils.decode_packet(fmt, packet: bytes)
pyclassic.utils.decstr(n)
pyclassic.utils.enc(n)
pyclassic.utils.encint(n, l=2)
pyclassic.utils.encode_packet(fmt, *args)
pyclassic.utils.encstr(n)
pyclassic.utils.find_packet_id(t)
pyclassic.utils.sanitize(msg)

Sanitizes message input (removes the &x stuff from a message).

Parameters

msg (str) – Message to sanitize

Returns

Sanitized message

Return type

str

Module contents

PyClassic - Minecraft Classic Protocol implementation in Python.

This is the main classes of the module.

class pyclassic.Player(name: str, x: int, y: int, z: int, pitch: int, yaw: int)

Bases: object

This is a simple class to store player data such as their position, their username and their head direction.

name: str
pitch: int
x: int
y: int
yaw: int
z: int
class pyclassic.PyClassic(client, multibot=[], client_name=None, build_delay=0.03)

Bases: object

The PyClassic class is the “main” class. It handles the event system which the core design of this library. However you do not have to use this class. See pyclassic.client.Client.

It supports event handling of course but also multibot which can be useful for building stuff using pyclassic.queue.ThreadedQueue.

Parameters
Raises

pyclassic.PyClassicError – if the client parameter is invalid.

async asend(pid, *args)

Actually not very useful, sends stuff but asynchronously.

see pyclassic.PyClassic.send()

connect(**kargs)

Connects the main client to a server.

see pyclassic.client.Client.connect()

connect_multibot(delay=4, **kargs)

Connects the multibot army to a server.

see pyclassic.client.Client.connect()

die(*msg)

Logs stuff but more dramatically

disconnect()

Disconnects the main client.

see pyclassic.client.Client.disconnect()

disconnect_multibot()

Disconnects the whole bot army.

see pyclassic.client.Client.disconnect()

event(fn)

Decorator to define an event.

Parameters

fn (function) – Event function. The function must be named as the wanted event.

async event_loop()

Runs the asynchronous event loop.

Warning

This function SHOULD NOT be run manually unless you are doing cursed shit. See pyclassic.PyClassic.run()

get_block(x, y, z)

Retrieve a block from self.map

Parameters

  • x (int) – X position

  • y (int) – Y position

  • z (int) – Z position

Raises

pyclassic.PyClassicError – The map has not been loaded.

Returns

The ID of the wanted block.

Return type

int

log(*msg)

Logs stuff

map: pyclassic.map.ClassicMap

Map object that stores the downloaded map.

async message(*args)

Send a message from the main client.

See pyclassic.client.Client.message()

async move(*args)

Moves the main client. see pyclassic.client.Client.move()

players: dict

List of players, dynamically updated with the event system.

queue: pyclassic.queue.ThreadedQueue

Queue object for multibot, None if there are no multibot.

recv()

see pyclassic.client.Client.recv()

run(delay=4, **kargs)

Connects all clients and run the event loop.

Parameters

  • delay – Delay of connection between each multibot connection.

  • kargs – Arguments such as the IP address, port, etc. It depends of the pyclassic.auth class.

send(pid, *args)

see pyclassic.client.Client.send()

async set_block(x, y, z, bid)

Makes the main client place a block and updates the map if there is one.

See pyclassic.client.Client.set_block()

Parameters

bid (int) – Block ID to place

update_player(playerid, name=None, x=None, y=None, z=None, pitch=None, yaw=None, relative=False)