beta – Minecraft Beta

Protocols and factories for Minecraft Beta, the Mojang-authored Minecraft which everybody knows and loves.

Packets

bravo.beta.packets.IPacket(object)

Interface for packets.

class bravo.beta.packets.Metadata

Bases: tuple

Metadata(type, value)

type

Alias for field number 0

value

Alias for field number 1

bravo.beta.packets.Speed

alias of speed

bravo.beta.packets.make_error_packet(message)

Convenience method to generate an error packet bytestream.

bravo.beta.packets.make_packet(packet, *args, **kwargs)

Constructs a packet bytestream from a packet header and payload.

The payload should be passed as keyword arguments. Additional containers or dictionaries to be added to the payload may be passed positionally, as well.

bravo.beta.packets.parse_packets(bytestream)

Opportunistically parse out as many packets as possible from a raw bytestream.

Returns a tuple containing a list of unpacked packet containers, and any leftover unparseable bytes.

bravo.beta.packets.parse_packets_incrementally(bytestream)

Parse out packets one-by-one, yielding a tuple of packet header and packet payload.

This function returns a generator.

This function will yield all valid packets in the bytestream up to the first invalid packet.

Returns:a generator yielding tuples of headers and payloads

bravo.beta.packets.simple(name, fmt, *args)

Make a customized namedtuple representing a simple, primitive packet.

Protocols

class bravo.beta.protocol.BetaProxyProtocol

Bases: bravo.beta.protocol.BetaServerProtocol

A BetaServerProtocol that proxies for an InfiniCraft client.

add_node(address, port)

Add a new node to this client.

class bravo.beta.protocol.BetaServerProtocol

Bases: object, twisted.internet.protocol.Protocol, twisted.protocols.policies.TimeoutMixin

The Minecraft Alpha/Beta server protocol.

This class is mostly designed to be a skeleton for featureful clients. It tries hard to not step on the toes of potential subclasses.

action(container)

Hook for action packets.

animate(container)

Hook for animate packets.

ascend(count)

Ascend to the next XZ-plane.

count is the number of ascensions to perform, and may be zero in order to force this player to not be standing inside a block.

Returns:bool of whether the ascension was successful

This client must be located for this method to have any effect.

authenticated()

Called when the client has successfully authenticated with the server.

build(container)

Hook for build packets.

chat(container)

Hook for chat packets.

client_settings(container)

Hook for interaction setting packets.

complete(container)

Hook for tab-completion packets.

digging(container)

Hook for digging packets.

equip(container)

Hook for equip packets.

error(message)

Error out.

This method sends message to the client as a descriptive error message, then closes the connection.

grounded(container)

Hook for grounded packets.

handshake(container)

Hook for handshake packets.

Override this to customize how logins are handled. By default, this method will only confirm that the negotiated wire protocol is the correct version, copy data out of the packet and onto the protocol, and then run the authenticated callback.

This method will call the pre_handshake method hook prior to logging in the client.

location_packet(container)

Hook for location packets.

orientation(container)

Hook for orientation packets.

orientation_changed()

Called when the client moves.

This callback is only for orientation, not position.

pickup(container)

Hook for pickup packets.

ping(container)

Hook for ping packets.

By default, this hook will examine the timestamps on incoming pings, and use them to estimate the current latency of the connected client.

play_notes(notes)

Play some music.

Send a sequence of notes to the player. notes is a finite iterable of pairs of instruments and pitches.

There is no way to time notes; if staggered playback is desired (and it usually is!), then play_notes() should be called repeatedly at the appropriate times.

This method turns the block beneath the player into a note block, plays the requested notes through it, then turns it back into the original block, all without actually modifying the chunk.

poll(container)

Hook for poll packets.

By default, queries the parent factory for some data, and replays it in a specific format to the requester. The connection is then closed at both ends. This functionality is used by Beta 1.8 clients to poll servers for status.

position(container)

Hook for position packets.

position_changed()

Called when the client moves.

This callback is only for position, not orientation.

pre_handshake()

Whether this client should be logged in.

quit(container)

Hook for quit packets.

By default, merely logs the quit message and drops the connection.

Even if the connection is not dropped, it will be lost anyway since the client will close the connection. It’s better to explicitly let it go here than to have zombie protocols.

respawn(container)

Hook for respawn packets.

send_chat(message)

Send a chat message back to the client.

settings_packet(container)

Hook for presentation setting packets.

sign(container)

Hook for sign packets.

update_location()

Send this client’s location to the client.

Also let other clients know where this client is.

update_ping()

Send a keepalive to the client.

use(container)

Hook for use packets.

wacknowledge(container)

Hook for wacknowledge packets.

waction(container)

Hook for waction packets.

wclose(container)

Hook for wclose packets.

wcreative(container)

Hook for creative inventory action packets.

write_packet(header, **payload)

Send a packet to the client.

class bravo.beta.protocol.BravoProtocol(config, name)

Bases: bravo.beta.protocol.BetaServerProtocol

A BetaServerProtocol suitable for serving MC worlds to clients.

This protocol really does need to be hooked up with a BravoFactory or something very much like it.

build(*args, **kwargs)

Handle a build packet.

Several things must happen. First, the packet’s contents need to be examined to ensure that the packet is valid. A check is done to see if the packet is opening a windowed object. If not, then a build is run.

complete(container)

Attempt to tab-complete user names.

connectionLost(reason=<twisted.python.failure.Failure <class 'twisted.internet.error.ConnectionDone'>>)

Cleanup after a lost connection.

Most of the time, these connections are lost cleanly; we don’t have any cleanup to do in the unclean case since clients don’t have any kind of pending state which must be recovered.

Remember, the connection can be lost before identification and authentication, so self.username and self.player can be None.

enable_chunk(x, z)

Request a chunk.

This function will asynchronously obtain the chunk, and send it on the wire.

Returns:Deferred that will be fired when the chunk is obtained, with no arguments

entities_near(radius)

Obtain the entities within a radius of this player.

Radius is measured in blocks.

pre_handshake()

Set up username and get going.

run_dig_hooks(chunk, coords, block)

Destroy a block and run the post-destroy dig hooks.

send_initial_chunk_and_location()

Send the initial chunks and location.

This method sends more than one chunk; since Beta 1.2, it must send nearly fifty chunks before the location can be safely sent.

settings_packet(container)

Acknowledge a change of settings and update chunk distance.

use(container)

For each entity in proximity (4 blocks), check if it is the target of this packet and call all hooks that stated interested in this type.

wcreative(container)

A slot was altered in creative mode.

class bravo.beta.protocol.KickedProtocol(reason=None)

Bases: bravo.beta.protocol.BetaServerProtocol

A very simple Beta protocol that helps enforce IP bans, Max Connections, and Max Connections Per IP.

This protocol disconnects people as soon as they connect, with a helpful message.

Factories

class bravo.beta.factory.BravoFactory(config, name)

Bases: twisted.internet.protocol.Factory

A Factory that creates BravoProtocol objects when connected to.

Create a factory and world.

name is the string used to look up factory-specific settings from the configuration.

Parameters:name (str) – internal name of this factory

broadcast(packet)

Broadcast a packet to all connected players.

broadcast_for_chunk(packet, x, z)

Broadcast a packet to all players that have a certain chunk loaded.

x and z are chunk coordinates, not block coordinates.

broadcast_for_others(packet, protocol)

Broadcast a packet to all players except the originating player.

Useful for certain packets like player entity spawns which should never be reflexive.

buildProtocol(addr)

Create a protocol.

This overriden method provides early player entity registration, as a solution to the username/entity race that occurs on login.

chat(message)

Relay chat messages.

Chat messages are sent to all connected clients, as well as to anybody consuming this factory.

create_entity(x, y, z, name, **kwargs)

Spawn an entirely new entity at the specified block coordinates.

Handles entity registration as well as instantiation.

destroy_entity(entity)

Destroy an entity.

The factory doesn’t have to know about entities, but it is a good place to put this logic.

flush_all_chunks()

Flush any damage anywhere in this world to all players.

This is a sledgehammer which should be used sparingly at best, and is only well-suited to plugins which touch multiple chunks at once.

In other words, if I catch you using this in your plugin needlessly, I’m gonna have a chat with you.

flush_chunk(chunk)

Flush a damaged chunk to all players that have it loaded.

give(coords, block, quantity)

Spawn a pickup at the specified coordinates.

The coordinates need to be in pixels, not blocks.

If the size of the stack is too big, multiple stacks will be dropped.

Parameters:

• coords (tuple) – coordinates, in pixels
• block (tuple) – key of block or item to drop
• quantity (int) – number of blocks to drop in the stack

players_near(player, radius)

Obtain other players within a radius of a given player.

Radius is measured in blocks.

protocol

alias of BravoProtocol

register_entity(entity)

Registers an entity with this factory.

Registration is perhaps too fancy of a name; this method merely makes sure that the entity has a unique and usable entity ID. In particular, this method does not make the entity attached to the world, or advertise its existence.

register_plugins()

Setup plugin hooks.

scan_chunk(chunk)

Tell automatons about this chunk.

set_username(protocol, username)

Attempt to set a new username for a protocol.

Returns:whether the username was changed

stopFactory()

Called before factory stops listening on ports. Used to perform shutdown tasks.

teardown_protocol(protocol)

Do internal bookkeeping on behalf of a protocol which has been disconnected.

Did you know that “bookkeeping” is one of the few words in English which has three pairs of double letters in a row?

update_season()

Update the world’s season.

update_time()

Update the in-game timer.

The timer goes from 0 to 24000, both of which are high noon. The clock increments by 20 every second. Days are 20 minutes long.

The day clock is incremented every in-game day, which is every 20 minutes. The day clock goes from 0 to 360, which works out to a reset once every 5 days. This is a Babylonian in-game year.