utilities – Helper functions

The utilities package is the standard home for shared functions which many modules may use. The spirit of utilities is also to isolate sections of critical code so that unit tests can be used to ensure a minimum of bugginess.

Automaton Helpers

bravo.utilities.automatic.column_scan(automaton, chunk)

Utility function which provides a chunk scanner which only examines the tallest blocks in the chunk. This can be useful for automatons which only care about sunlit or elevated areas.

This method can be used directly in automaton classes to provide scan().

bravo.utilities.automatic.naive_scan(automaton, chunk)

Utility function which can be used to implement a naive, slow, but thorough chunk scan for automatons.

This method is designed to be directly useable on automaton classes to provide the scan() interface.

This function depends on implementation details of Chunk.

Chat Formatting

Colorizers.

bravo.utilities.chat.complete(sentence, possibilities)

Perform completion on a string using a list of possible strings.

Returns a single string containing all possibilities.

bravo.utilities.chat.sanitize_chat(s)

Verify that the given chat string is safe to send to Notchian recepients.

bravo.utilities.chat.username_alternatives(n)

Permute a username through several common alternative-finding algorithms.

Coordinate Handling

Utilities for coordinate handling and munging.

bravo.utilities.coords.adjust_coords_for_face(coords, face)

Adjust a set of coords according to a face.

The face is a standard string descriptor, such as “+x”.

The “noop” face is supported.

bravo.utilities.coords.polar_round_vector(vector)

Rounds a vector towards zero

bravo.utilities.coords.split_coords(x, z)

Split a pair of coordinates into chunk and subchunk coordinates.

Parameters:

• x (int) – the X coordinate
• z (int) – the Z coordinate

Returns:

a tuple of the X chunk, X subchunk, Z chunk, and Z subchunk

bravo.utilities.coords.taxicab2(x1, y1, x2, y2)

Return the taxicab distance between two blocks.

bravo.utilities.coords.taxicab3(x1, y1, z1, x2, y2, z2)

Return the taxicab distance between two blocks, in three dimensions.

Data Packing

More affectionately known as “bit-twiddling.”

bravo.utilities.bits.grouper(n, iterable, fillvalue=None)

grouper(3, ‘ABCDEFG’, ‘x’) –> ABC DEF Gxx

bravo.utilities.bits.pack_nibbles(a)

Pack pairs of nibbles into bytes.

Bytes are returned as characters.

Parameters:a (array) – nibbles to pack Returns:packed nibbles as a string of bytes

bravo.utilities.bits.unpack_nibbles(l)

Unpack bytes into pairs of nibbles.

Nibbles are half-byte quantities. The nibbles unpacked by this function are returned as unsigned numeric values.

>>> unpack_nibbles("a")
[6, 1]
>>> unpack_nibbles("nibbles")
[6, 14, 6, 9, 6, 2, 6, 2, 6, 12, 6, 5, 7, 3]

Parameters:l (list) – bytes Returns:list of nibbles

Decorators

General decorators for a variety of purposes.

bravo.utilities.decos.timed(f)

Print out timing statistics on a given callable.

Intended largely for debugging; keep this in the tree for profiling even if it’s not currently wired up.

Geometry

Simple pixel graphics helpers.

bravo.utilities.geometry.gen_close_point(point1, point2)

Retrieve the first integer set of coordinates on the line from the first point to the second point.

The set of coordinates corresponding to the first point will not be retrieved.

bravo.utilities.geometry.gen_line_covered(point1, point2)

This is Bresenham’s algorithm with a little twist: all the blocks that intersect with the line are yielded.

bravo.utilities.geometry.gen_line_simple(point1, point2)

An adaptation of Bresenham’s line algorithm in three dimensions.

This function returns an iterable of integer coordinates along the line from the first point to the second point. No points are omitted.

Scheduling

class bravo.utilities.temporal.PendingEvent

Bases: object

An event which will happen at some point.

Structurally, this could be thought of as a poor man’s upside-down DeferredList; it turns a single callback/errback into a broadcast which fires many multiple Deferreds.

This code came from Epsilon and should go into Twisted at some point.

bravo.utilities.temporal.split_time(timestamp)

Turn an MC timestamp into hours and minutes.

The time is calculated by interpolating the MC clock over the standard 24-hour clock.

Parameters:timestamp (int) – MC timestamp, in the range 0-24000 Returns:a tuple of hours and minutes on the 24-hour clock

bravo.utilities.temporal.timestamp_from_clock(clock)

Craft an int-sized timestamp from a clock.

More precisely, the size of the timestamp is 4 bytes, and the clock must be an implementor of IReactorTime. twisted.internet.reactor and twisted.internet.task.Clock are the primary suspects.

This function’s timestamps are millisecond-accurate.

Spatial Hashes

class bravo.utilities.spatial.Block2DSpatialDict

Bases: bravo.utilities.spatial.SpatialDict

Class for tracking blocks in the XZ-plane.

key_for_bucket(key)

Partition keys into chunk-sized buckets.

keys_near(key, radius)

Get all bucket keys “near” this key.

This method may return a generator.

class bravo.utilities.spatial.Block3DSpatialDict

Bases: bravo.utilities.spatial.SpatialDict

Class for tracking blocks in the XZ-plane.

key_for_bucket(key)

Partition keys into chunk-sized buckets.

keys_near(key, radius)

Get all bucket keys “near” this key.

This method may return a generator.

class bravo.utilities.spatial.SpatialDict

Bases: object, UserDict.DictMixin

A spatial dictionary, for accelerating spatial lookups.

This particular class is a template for specific spatial dictionaries; in order to make it work, subclass it and add key_for_bucket().

iteritemsnear(key, radius)

A version of iteritems() that filters based on the distance from a given key.

The key does not need to actually be in the dictionary.

iterkeys()

Yield all the keys.

iterkeysnear(key, radius)

Yield all of the keys within a certain radius of this key.

itervaluesnear(key, radius)

Yield all of the values within a certain radius of this key.

keys()

Get a list of all keys in the dictionary.

Trigonometry

bravo.utilities.maths.circling(x, y, r)

Generate the points of the filled integral circle of the given radius around the given coordinates.

bravo.utilities.maths.clamp(x, low, high)

Clamp or saturate a number to be no lower than a minimum and no higher than a maximum.

Implemented as its own function simply because it’s so easy to mess up when open-coded.

bravo.utilities.maths.morton2(x, y)

Create a Morton number by interleaving the bits of two numbers.

This can be used to map 2D coordinates into the integers.

Inputs will be masked off to 16 bits, unsigned.

bravo.utilities.maths.rotated_cosine(x, y, theta, lambd)

Evaluate a rotated 3D sinusoidal wave at a given point, angle, and wavelength.

The function used is:

This function has a handful of useful properties; it has a local minimum at f(0, 0) and oscillates infinitely betwen 0 and 1.

Parameters:

• x (float) – X coordinate
• y (float) – Y coordinate
• theta (float) – angle of rotation
• lambda (float) – wavelength

Returns:

float of f(x, y)

bravo.utilities.maths.sorted_by_distance(iterable, x, y)

Like sorted(), but by distance to the given coordinates.