chunk

Block ¶

Python

Block(
    block_id: int,
    metadata: int = 0,
    position: Optional[Vector3D[int]] = None,
)

Represents a block state in the Minecraft world.

A Block encapsulates the fundamental properties of a single block position, including its type, metadata, world position, and any associated block entity.

ATTRIBUTE	DESCRIPTION
`id`	Block type identifier TYPE: `int`
`metadata`	Block metadata value TYPE: `int`
`entity`	Associated block entity (e.g., chest, furnace) TYPE: `Optional[BaseEntity]`
`position`	World position coordinates TYPE: `Optional[Vector3D[int]]`

is_valid ¶

Python

is_valid() -> bool

Check if block state has valid ID and metadata values.

RETURNS	DESCRIPTION
`bool`	True if block ID is in [0, 255] and metadata is in [0, 15]

is_solid ¶

Python

is_solid() -> bool

Check if block is solid for collision and pathfinding purposes.

RETURNS	DESCRIPTION
`bool`	True if block is not air (ID != 0), False for air blocks

Notes

This method considers any non-air block as solid. For more complex collision detection, additional logic may be needed based on block type.

Chunk ¶

Python

Chunk(
    chunk_pos: Vector2D[int],
    full: bool,
    mask: int,
    data: bytes,
)

Complete chunk in the world, optimized for pathfinding and storage.

A chunk represents a 16x16x256 column of blocks divided into 16x16x16 sections. Provides efficient access to block data and manages chunk loading/unloading.

ATTRIBUTE	DESCRIPTION
`position`	Chunk position in world coordinates TYPE: `Vector2D[int]`
`sections`	Array of chunk sections, None for empty sections TYPE: `List[Optional[ChunkSection]]`
`biomes`	Biome data for the chunk surface (16x16 array) TYPE: `array.array`

Notes

Chunks are loaded from network data and automatically parsed into sections. Empty sections are represented as None to save memory.

get_section ¶

Python

get_section(section_y: int) -> Optional[ChunkSection]

Get chunk section at the specified Y level.

PARAMETER	DESCRIPTION
`section_y`	Section Y coordinate [0, 15] TYPE: `int`

RETURNS	DESCRIPTION
`Optional[ChunkSection]`	Chunk section at the Y level, or None if invalid Y or empty section

set_block_state ¶

Python

set_block_state(
    position: Vector3D[int],
    section_y: int,
    block_id: int,
    metadata: int = 0,
) -> None

Set block state at the specified position.

PARAMETER	DESCRIPTION
`position`	Local position within section [0, 15] TYPE: `Vector3D[int]`
`section_y`	Section Y coordinate [0, 15] TYPE: `int`
`block_id`	Block type identifier [0, 255] TYPE: `int`
`metadata`	Block metadata [0, 15] TYPE: `int` DEFAULT: `0`

set_block_entity ¶

Python

set_block_entity(
    position: Vector3D[int],
    section_y: int,
    block_entity: BaseEntity,
) -> None

Set block entity at the specified position.

PARAMETER	DESCRIPTION
`position`	Local position within section [0, 15] TYPE: `Vector3D[int]`
`section_y`	Section Y coordinate [0, 15] TYPE: `int`
`block_entity`	Block entity to place TYPE: `BaseEntity`

Notes

Automatically creates a new section if one doesn't exist at the Y level.

set_section ¶

Python

set_section(section_y: int, section: ChunkSection) -> None

Set chunk section at the specified Y level.

PARAMETER	DESCRIPTION
`section_y`	Section Y coordinate [0, 15] TYPE: `int`
`section`	Chunk section to set TYPE: `ChunkSection`

Notes

Ignores requests to set sections at invalid Y coordinates.

ChunkSection ¶

Python

ChunkSection(chunk_pos: Vector2D[int], section_y: int = 0)

16x16x16 chunk section optimized for pathfinding and world storage.

Represents a cubic section of the world containing blocks and block entities. Provides efficient storage and access patterns for block data.

ATTRIBUTE	DESCRIPTION
`chunk_pos`	Parent chunk position TYPE: `Vector2D[int]`
`section_y`	Vertical section index TYPE: `int`
`block_data`	Packed block data array (block_id << 4 \| metadata) TYPE: `array.array`
`palette`	Palette used for block state mapping TYPE: `Optional[Union[IndirectPalette, DirectPalette]]`
`block_entities`	Maps block indices to their associated entities TYPE: `Dict[int, BaseEntity]`

Notes

Block data is stored as packed integers where each value contains both block ID and metadata: (block_id << 4) | metadata

get_block_id ¶

Python

get_block_id(pos: Vector3D[int]) -> int

Get block ID at the specified position.

PARAMETER	DESCRIPTION
`pos`	Local coordinates within section [0, 15] TYPE: `Vector3D[int]`

RETURNS	DESCRIPTION
`int`	Block ID at the position

Notes

Extracts only the block ID from packed data, ignoring metadata.

get_block ¶

Python

get_block(pos: Vector3D[int]) -> Tuple[int, int]

Get block ID and metadata at the specified position.

PARAMETER	DESCRIPTION
`pos`	Local coordinates within section [0, 15] TYPE: `Vector3D[int]`

RETURNS	DESCRIPTION
`Tuple[int, int]`	Block ID and metadata (block_id, metadata)

get_block_entity ¶

Python

get_block_entity(
    pos: Vector3D[int],
) -> Optional[BaseEntity]

Get block entity at the specified position.

PARAMETER	DESCRIPTION
`pos`	Local coordinates within section [0, 15] TYPE: `Vector3D[int]`

RETURNS	DESCRIPTION
`Optional[BaseEntity]`	Block entity at position, or None if no entity exists

set_block ¶

Python

set_block(
    pos: Vector3D[int], block_id: int, metadata: int = 0
) -> None

Set block state at the specified position.

PARAMETER	DESCRIPTION
`pos`	Local coordinates within section [0, 15] TYPE: `Vector3D[int]`
`block_id`	Block type identifier [0, 255] TYPE: `int`
`metadata`	Block metadata [0, 15] TYPE: `int` DEFAULT: `0`

Notes

Automatically removes any existing block entity at the position.

set_entity ¶

Python

set_entity(
    pos: Vector3D[int], block_entity: BaseEntity
) -> None

Set block entity at the specified position.

PARAMETER	DESCRIPTION
`pos`	Local coordinates within section [0, 15] TYPE: `Vector3D[int]`
`block_entity`	Block entity to place at the position TYPE: `BaseEntity`

is_empty ¶

Python

is_empty() -> bool

Check if section contains only air blocks.

RETURNS	DESCRIPTION
`bool`	True if all blocks are air (ID = 0), False otherwise

Notes

Useful for optimization - empty sections can be skipped during rendering and collision detection.

choose_palette `staticmethod` ¶

Python

choose_palette(
    bits_per_block: int,
) -> Union[IndirectPalette, DirectPalette]

Choose appropriate palette type based on bits per block.

PARAMETER	DESCRIPTION
`bits_per_block`	Number of bits required per block TYPE: `int`

RETURNS	DESCRIPTION
`Union[IndirectPalette, DirectPalette]`	IndirectPalette for <= 8 bits, DirectPalette otherwise

Notes

Indirect palettes are more efficient for sections with few unique block types, while direct palettes are better for diverse sections.

IndirectPalette ¶

Python

IndirectPalette(bits_per_block: int)

Indirect palette mapping local indices to global palette IDs.

Used for chunk sections with limited unique block types to compress storage by mapping small local IDs to full block state IDs.

ATTRIBUTE	DESCRIPTION
`bits_per_block`	Actual bits per block used (>= 4) TYPE: `int`
`id_to_state`	Maps palette ID to packed block state TYPE: `Dict[int, int]`
`state_to_id`	Maps packed block state to palette ID TYPE: `Dict[int, int]`

Notes

Block states are packed as: (block_id << 4) | metadata This allows efficient storage of both block type and metadata in a single integer.

add_state ¶

Python

add_state(state: Block) -> int

Add block state to palette and return its local ID.

PARAMETER	DESCRIPTION
`state`	State to add to the palette TYPE: `Block`

RETURNS	DESCRIPTION
`int`	Local palette ID for the state (0-based index)

Notes

If the state already exists in the palette, returns the existing ID. Otherwise, assigns a new sequential ID starting from 0.

state_for_id ¶

Python

state_for_id(palette_id: int) -> Block

Get block state for a given palette ID.

PARAMETER	DESCRIPTION
`palette_id`	Local palette identifier TYPE: `int`

RETURNS	DESCRIPTION
`Block`	state corresponding to the ID, or air block if ID not found

Notes

Returns Block(0, 0) for invalid or missing palette IDs.

read ¶

Python

read(buffer: ProtocolBuffer) -> None

Read palette data from network buffer.

PARAMETER	DESCRIPTION
`buffer`	Buffer containing serialized palette data TYPE: `ProtocolBuffer`

Notes

Clears existing palette data before reading new data. Expected format: varint length followed by varint state IDs.

DirectPalette ¶

Python

DirectPalette()

Direct palette using global palette IDs without local mapping.

Used for chunk sections with many unique block types where the overhead of maintaining a local palette exceeds the storage benefits.

ATTRIBUTE	DESCRIPTION
`bits_per_block`	Fixed at 13 bits for direct palette usage TYPE: `int`

Notes

Direct palettes store global block state IDs directly in the block data array, eliminating the need for a local ID mapping.

state_for_id `staticmethod` ¶

Python

state_for_id(palette_id: int) -> Block

Get block state for global palette ID.

PARAMETER	DESCRIPTION
`palette_id`	Global palette identifier TYPE: `int`

RETURNS	DESCRIPTION
`Block`	state corresponding to the ID, or air block for invalid IDs

Notes

Validates that the unpacked block ID and metadata are within valid ranges. Returns Block(0, 0) for invalid palette IDs.

read `staticmethod` ¶

Python

read(buffer: ProtocolBuffer) -> None

Read dummy palette data from buffer.

PARAMETER	DESCRIPTION
`buffer`	Buffer containing palette data TYPE: `ProtocolBuffer`

RAISES	DESCRIPTION
`AssertionError`	If dummy palette length is not 0

Notes

Direct palettes don't store local mapping data, so this method only verifies the expected dummy length of 0.

chunk

Block ¶

is_valid ¶

is_solid ¶

Chunk ¶

get_section ¶

set_block_state ¶

set_block_entity ¶

set_section ¶

ChunkSection ¶

get_block_id ¶

get_block ¶

get_block_entity ¶

set_block ¶

set_entity ¶

is_empty ¶

choose_palette staticmethod ¶

IndirectPalette ¶

add_state ¶

state_for_id ¶

read ¶

DirectPalette ¶

state_for_id staticmethod ¶

read staticmethod ¶

choose_palette `staticmethod` ¶

state_for_id `staticmethod` ¶

read `staticmethod` ¶