chunk – Chunk data structures

The chunk module holds the data structures required to track and update block data in chunks.

class bravo.chunk.Chunk(x, z)

Bases: object

A chunk of blocks.

Chunks are large pieces of world geometry (block data). The blocks, light maps, and associated metadata are stored in chunks. Chunks are always measured 16xCHUNK_HEIGHTx16 and are aligned on 16x16 boundaries in the xz-plane.

Variables:

• dirty (bool) – Whether this chunk needs to be flushed to disk.
• populated (bool) – Whether this chunk has had its initial block data filled out.
• heightmap (array.array) – Tracks the tallest block in each xz-column.
• all_damaged (bool) – Flag for forcing the entire chunk to be damaged. This is for efficiency; past a certain point, it is not efficient to batch block updates or track damage. Heavily damaged chunks have their damage represented as a complete resend of the entire chunk.

Parameters:

• x (int) – X coordinate in chunk coords
• z (int) – Z coordinate in chunk coords

clear_damage()

Clear this chunk’s damage.

damage(coords)

Record damage on this chunk.

destroy(chunk, coords, *args, **kwargs)

Destroy the block at the given coordinates.

This may or may not set the block to be full of air; it uses the block’s preferred replacement. For example, ice generally turns to water when destroyed.

This is safe as a no-op; for example, destroying a block of air with no metadata is not going to cause state changes.

Parameters:coords (tuple) – coordinate triplet

dirtied = None

Optional hook to be called when this chunk becomes dirty.

get_block(chunk, coords, *args, **kwargs)

Look up a block value.

Parameters:coords (tuple) – coordinate triplet Return type:int Returns:int representing block type

get_damage_packet()

Make a packet representing the current damage on this chunk.

This method is not private, but some care should be taken with it, since it wraps some fairly cryptic internal data structures.

If this chunk is currently undamaged, this method will return an empty string, which should be safe to treat as a packet. Please check with is_damaged() before doing this if you need to optimize this case.

To avoid extra overhead, this method should really be used in conjunction with Factory.broadcast_for_chunk().

Do not forget to clear this chunk’s damage! Callers are responsible for doing this.

>>> packet = chunk.get_damage_packet()
>>> factory.broadcast_for_chunk(packet, chunk.x, chunk.z)
>>> chunk.clear_damage()

Return type:str Returns:String representation of the packet.

get_metadata(chunk, coords, *args, **kwargs)

Look up metadata.

Parameters:coords (tuple) – coordinate triplet Return type:int

get_skylight(chunk, coords, *args, **kwargs)

Look up skylight value.

Parameters:coords (tuple) – coordinate triplet Return type:int

height_at(x, z)

Get the height of an xz-column of blocks.

Parameters:

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

Return type:

int

Returns:

The height of the given column of blocks.

is_damaged()

Determine whether any damage is pending on this chunk.

Return type:bool Returns:True if any damage is pending on this chunk, False if not.

regenerate()

Regenerate all auxiliary tables.

regenerate_heightmap()

Regenerate the height map array.

The height map is merely the position of the tallest block in any xz-column.

regenerate_skylight()

Regenerate the ambient light map.

Each block’s individual light comes from two sources. The ambient light comes from the sky.

The height map must be valid for this method to produce valid results.

save_to_packet()

Generate a chunk packet.

sed(search, replace)

Execute a search and replace on all blocks in this chunk.

Named after the ubiquitous Unix tool. Does a semantic s/search/replace/g on this chunk’s blocks.

Parameters:

• search (int) – block to find
• replace (int) – block to use as a replacement

set_block(chunk, coords, *args, **kwargs)

Update a block value.

Parameters:

• coords (tuple) – coordinate triplet
• block (int) – block type

set_metadata(chunk, coords, *args, **kwargs)

Update metadata.

Parameters:

• coords (tuple) – coordinate triplet
• metadata (int) –

set_skylight(chunk, coords, *args, **kwargs)

Update skylight value.

Parameters:

• coords (tuple) – coordinate triplet
• metadata (int) –

exception bravo.chunk.ChunkWarning

Bases: exceptions.Warning

Somebody did something inappropriate to this chunk, but it probably isn’t lethal, so the chunk is issuing a warning instead of an exception.

bravo.chunk.check_bounds(f)

Decorate a function or method to have its first positional argument be treated as an (x, y, z) tuple which must fit inside chunk boundaries of 16, CHUNK_HEIGHT, and 16, respectively.

A warning will be raised if the bounds check fails.

bravo.chunk.ci(x, y, z)

Turn an (x, y, z) tuple into a chunk index.

This is really a macro and not a function, but Python doesn’t know the difference. Hopefully this is faster on PyPy than on CPython.

bravo.chunk.composite_glow(target, strength, x, y, z)

Composite a light source onto a lightmap.

The exact operation is not quite unlike an add.

bravo.chunk.iter_neighbors(coords)

Iterate over the chunk-local coordinates surrounding the given coordinates.

All coordinates are chunk-local.

Coordinates which are not valid chunk-local coordinates will not be generated.

bravo.chunk.make_glows()

Set up glow tables.

These tables provide glow maps for illuminated points.

bravo.chunk.neighboring_light(glow, block)

Calculate the amount of light that should be shone on a block.

glow is the brighest neighboring light. block is the slot of the block being illuminated.

The return value is always a valid light value.

bravo.chunk.segment_array(a)

Chop up a chunk-sized array into sixteen components.

The chops are done in order to produce the smaller chunks preferred by modern clients.