meshes

Meshes package: greedy meshing, mesh builders and helpers.

This package implements the chunk mesh pipeline (greedy meshing, vertex packing, AO, and VBO upload helpers). Submodules expose BaseMesh, ChunkMesh, and specialized meshes used by the renderer.

Providing a clear package docstring helps Sphinx autodoc and autosummary generate a better overview page for the meshes package.

base_mesh

Base class architecture for OpenGL mesh generation.

This module provides the foundational BaseMesh class that all 2D and 3D renderable objects in Pyrite inherit from. It standardizes the creation of Vertex Array Objects (VAOs) and Vertex Buffer Objects (VBOs) through the ModernGL pipeline.

class meshes.base_mesh.BaseMesh

Bases: object

Abstract base class for all OpenGL geometry meshes.

Subclasses must implement the get_vertex_data method to supply the raw Numpy array data. The base class automatically handles uploading this data to the GPU and configuring the vertex attributes for the shader program.

get_vertex_data()

Abstract method to be overridden by subclasses. Should return a contiguous Numpy array containing the vertex data formatted according to self.vbo_format.

Return type:

Any

get_vao()

Constructs the OpenGL Vertex Buffer Object (VBO) and Vertex Array Object (VAO) by pulling the geometry data from get_vertex_data().

Return type:

Any

render()

Issues the draw call to the GPU for this mesh’s geometry.

Return type:

None

chunk_mesh

OpenGL geometry wrapper and VRAM manager for active world chunks.

This module links the generated Numba geometry data directly to the ModernGL VAO/VBO contexts. Crucially, it handles the dynamic VBO object pooling architecture, safely tracking and recycling massive GPU memory buffers on the fly to prevent strict VRAM memory leaking during chunk streaming.

class meshes.chunk_mesh.ChunkMesh(chunk)

Bases: BaseMesh

Manages the OpenGL geometry for a chunk, handling opaque and transparent meshes.

It interfaces with the greedy meshing builder to generate vertex data and utilizes a VBO pool to manage GPU memory efficiently. Ensures chunks can be seamlessly uploaded and released from VRAM during rapid world streaming.

Parameters:

chunk (Any) – The parent chunk instance this mesh is visually representing.

render()

Issues the draw call for the opaque portion of the chunk’s mesh, provided it has valid geometry to render.

Return type:

None

render_water()

Issues the draw call for the transparent water portion of the chunk’s mesh, starting from the end of the opaque vertex data.

Return type:

None

get_vao()

Retrieves or builds the Vertex Array Object (VAO) for the chunk. It first generates the raw vertex data, then attempts to recycle an appropriately sized VBO from the global pool to prevent memory leaks, allocating a new one if necessary.

Return type:

Any

get_vertex_data()

Triggers the greedy meshing algorithm to construct the optimized vertex payload (including ambient occlusion and lighting) from the chunk’s 3D voxel array.

Return type:

Tuple[Any, int, int]

chunk_mesh_builder

Numba-optimized Greedy Meshing algorithm and lighting evaluation.

This module scans 3D voxel arrays and mathematically combines adjacent, coplanar block faces into massive single polygons to drastically reduce GPU draw calls. It evaluates Ambient Occlusion (AO) and volumetric Breadth-First Search (BFS) lighting at every vertex lock-free across multiple CPU threads.

meshes.chunk_mesh_builder.get_ao(local_pos, world_pos, chunk_voxels, world_voxels, chunk_positions, plane)

Calculates the ambient occlusion (AO) value for a specific vertex on a block face. It checks the surrounding blocks in the specified plane to determine how occluded the corner is, returning a tuple of AO values for the four vertices of the face.

Parameters:

• local_pos (Tuple[int, int, int])

• world_pos (Tuple[int, int, int])

• chunk_voxels (Any)

• world_voxels (Any)

• chunk_positions (Any)

• plane (str)

Return type:

Tuple[int, int, int, int]

meshes.chunk_mesh_builder.get_vertex_light(local_vertex_pos, world_vertex_pos, plane, face_light, chunk_voxels, chunk_lightmap, world_voxels, world_lightmaps, chunk_positions)

Computes the smoothed lighting value for a specific vertex by sampling and averaging the sunlight and blocklight from the four surrounding blocks that share the vertex in the given plane.

Parameters:

• local_vertex_pos (Tuple[int, int, int])

• world_vertex_pos (Tuple[int, int, int])

• plane (str)

• face_light (int)

• chunk_voxels (Any)

• chunk_lightmap (Any)

• world_voxels (Any)

• world_lightmaps (Any)

• chunk_positions (Any)

Return type:

int

meshes.chunk_mesh_builder.pack_data(x, y, z, voxel_id, face_id, ao_id, flip_id, light_val)

Packs multiple pieces of vertex data (coordinates, voxel ID, face ID, AO ID, flip ID) into a single 32-bit unsigned integer to minimize memory usage and GPU bandwidth.

Parameters:

• x (int)

• y (int)

• z (int)

• voxel_id (int)

• face_id (int)

• ao_id (int)

• flip_id (int)

• light_val (int)

Return type:

Tuple[int, int]

meshes.chunk_mesh_builder.get_chunk_index(world_voxel_pos, chunk_positions)

Calculates the 1D index of a chunk in the global world arrays based on an absolute world voxel coordinate. Returns -1 if the chunk is not currently loaded or out of bounds.

Parameters:

• world_voxel_pos (Tuple[int, int, int])

• chunk_positions (Any)

Return type:

int

meshes.chunk_mesh_builder.get_neighbor_voxel_id(local_voxel_pos, world_voxel_pos, chunk_voxels, world_voxels, chunk_positions)

Retrieves the voxel ID of a neighboring block given its local and world coordinates. Safely handles cross-chunk boundaries by looking up the appropriate chunk in the world arrays.

Parameters:

• local_voxel_pos (Tuple[int, int, int])

• world_voxel_pos (Tuple[int, int, int])

• chunk_voxels (Any)

• world_voxels (Any)

• chunk_positions (Any)

Return type:

int

meshes.chunk_mesh_builder.get_neighbor_light(local_voxel_pos, world_voxel_pos, chunk_lightmap, world_lightmaps, chunk_positions)

Retrieves the packed lighting value (sunlight and blocklight) of a neighboring block given its local and world coordinates, safely crossing chunk boundaries if needed.

Parameters:

• local_voxel_pos (Tuple[int, int, int])

• world_voxel_pos (Tuple[int, int, int])

• chunk_lightmap (Any)

• world_lightmaps (Any)

• chunk_positions (Any)

Return type:

int

meshes.chunk_mesh_builder.is_transparent(voxel_id)

Checks if a given voxel ID corresponds to a transparent block (like air, water, glass, or leaves). Transparent blocks do not cull adjacent faces and do not cast hard ambient occlusion shadows.

Parameters:

voxel_id (int)

Return type:

bool

meshes.chunk_mesh_builder.is_void(local_voxel_pos, world_voxel_pos, chunk_voxels, world_voxels, chunk_positions)

Determines if a block at a given coordinate is empty or transparent, which is used specifically during the ambient occlusion calculation to see if a corner is occluded.

Parameters:

• local_voxel_pos (Tuple[int, int, int])

• world_voxel_pos (Tuple[int, int, int])

• chunk_voxels (Any)

• world_voxels (Any)

• chunk_positions (Any)

Return type:

bool

meshes.chunk_mesh_builder.add_data(vertex_data, index, *vertices)

Appends newly packed vertex data and its associated lighting value into the main mesh arrays, advancing the current index counter.

Parameters:

• vertex_data (Any)

• index (int)

• vertices (Tuple[int, int])

Return type:

int

meshes.chunk_mesh_builder.build_chunk_mesh(chunk_voxels, chunk_lightmap, format_size, chunk_pos, world_voxels, world_lightmaps, chunk_positions)

The core greedy meshing algorithm. It scans through a chunk’s voxel data slice by slice along the X, Y, and Z planes. It groups adjacent, identical, and coplanar block faces into massive single polygons, calculating ambient occlusion and smoothed lighting along the way. Returns the combined vertex data for both opaque and water meshes.

Parameters:

• chunk_voxels (Any)

• chunk_lightmap (Any)

• format_size (int)

• chunk_pos (Tuple[int, int, int])

• world_voxels (Any)

• world_lightmaps (Any)

• chunk_positions (Any)

Return type:

Tuple[Any, int, int]

cloud_mesh

Procedural cloud mesh generation and greedy meshing.

This module manages the volumetric cloud layer by generating 2D noise-based density maps and using a specialized 2D greedy meshing algorithm to compile optimized, low-polygon chunks of clouds that scroll across the sky.

class meshes.cloud_mesh.CloudMesh(app)

Bases: BaseMesh

Generates the geometry for the procedural 3D cloud layer.

Utilizes simplex noise to map cloud density and a 2D greedy meshing algorithm to create an optimized, low-polygon mesh of cloud blocks.

Parameters:

app (Any) – The main application instance providing the ModernGL context.

get_vertex_data()

Coordinates the generation of the raw cloud density data and subsequently constructs the optimized 3D mesh vertex data required for rendering.

Return type:

ndarray[tuple[Any, …], dtype[uint16]]

static gen_clouds(cloud_data, perm_array)

Populates a 2D density grid using multi-octave simplex noise to procedurally determine the exact locations where clouds should form in the sky.

Parameters:

• cloud_data (Any)

• perm_array (Any)

Return type:

None

static build_mesh(cloud_data)

A specialized 2D greedy meshing algorithm that scans the generated cloud density grid. It mathematically combines adjacent, identical cloud blocks into massive single polygonal faces, drastically reducing the total number of vertices sent to the GPU.

Parameters:

cloud_data (Any)

Return type:

ndarray[tuple[Any, …], dtype[uint16]]

cube_mesh

Standard 3D cube mesh generator.

This module constructs the geometry for a basic 1x1x1 cube. It is primarily utilized for rendering the wireframe voxel marker that highlights targeted blocks in the world, ensuring the player knows exactly where they are aiming.

class meshes.cube_mesh.CubeMesh(app)

Bases: BaseMesh

Generates the geometry for a standard 3D cube.

Used primarily for the wireframe voxel marker that highlights targeted blocks. Constructs the vertices and UVs needed to map a simple texture over a unit cube.

Parameters:

app (Any) – The main application context providing the shaders.

static get_data(vertices, indices)

Flattens the structured lists of vertices and indices into a contiguous 1D Numpy array required by OpenGL.

Parameters:

• vertices (List[Any])

• indices (List[Tuple[int, int, int]])

Return type:

ndarray[tuple[Any, …], dtype[float16]]

get_vertex_data()

Defines the local 3D coordinates and 2D texture UVs for all six faces of the cube, and assembles them into the final vertex buffer payload.

Return type:

ndarray[tuple[Any, …], dtype[float16]]

item_mesh

OpenGL geometry generation for dropped items.

This module constructs the 3D mesh data required to render miniature, rotating blocks when an item is dropped or a block is destroyed in the world. It maps the faces explicitly so the shader can sample the correct block textures from the global atlas.

class meshes.item_mesh.ItemMesh(app)

Bases: BaseMesh

Generates the geometry for dropped 3D items and blocks in the world.

Builds a standard cube mesh formatted to support the global block texture atlas. It assigns proper face IDs so the shader can dynamically map the correct texture coordinate offsets from the atlas onto each side of the cube.

Parameters:

app (Any) – The main application instance containing the ModernGL context and shaders.

get_vertex_data()

Calculates and returns the complete set of vertices, texture coordinates, and face IDs required to construct a 3D block representation.

Return type:

ndarray[tuple[Any, …], dtype[float32]]

obj_mesh

Wavefront OBJ and MTL 3D model parsing and mesh generation.

This module reads standard .obj files to extract vertices, UVs, normals, and faces, along with parsing .mtl files for diffuse color mappings. It automatically triangulates polygons and centers the resulting geometry for rendering custom 3D tools and entities in the world.

class meshes.obj_mesh.ObjMesh(app, object_path, texture_id=None)

Bases: BaseMesh

Generates rendering geometry by parsing and loading standard 3D Wavefront (.obj) files.

Supports parsing material files (.mtl) for vertex colors and automatically centers the imported geometry around the origin.

Parameters:

• app (Any) – The main application instance providing the ModernGL context.

• object_path (str) – The absolute or relative file path to the .obj file.

• texture_id (Optional[int]) – The OpenGL texture ID to bind during rendering, if applicable.

render()

Issues the draw call to the GPU for this model. Optionally enables and binds an associated OpenGL texture if a texture ID was provided during initialization.

Return type:

None

parse_mtl(material_path)

Reads a Wavefront material (.mtl) file and extracts the diffuse color (Kd) values for each material, allowing the OBJ to render with its assigned base colors.

Parameters:

material_path (str)

Return type:

Dict[str, Dict[str, List[float]]]

get_vertex_data()

Parses the .obj file line by line to extract vertices, texture coordinates, and normals. Triangulates complex polygons using a triangle fan approach and mathematically centers the entire assembled geometry around the origin (0, 0, 0).

Return type:

ndarray[tuple[Any, …], dtype[float32]]