world_objects

World objects package: lightweight in-world entities.

Contains small entity implementations such as dropped Item entities, procedural clouds, simple sky helpers, and the voxel_marker debug helper. Adding a package docstring improves autodoc index pages.

chunk

Chunk data structures, voxel management, and rendering logic.

This module defines the Chunk class, which serves as a volumetric container for a specific 3D region of the world. It manages the chunk’s Numpy arrays (voxels and lightmaps), hardware occlusion queries, and acts as the bridge between the Numba terrain generation and the OpenGL mesh builders.

class world_objects.chunk.Chunk(world, position)

Bases: object

Represents a 3D volumetric section of the world (e.g., 48x48x48 blocks).

Stores the voxel array, lightmap, and coordinates, and handles issuing draw calls for its corresponding ChunkMesh.

Parameters:

• world (Any) – The parent World instance this chunk belongs to.

• position (Tuple[int, int, int]) – The spatial chunk coordinate (e.g., (0, 0, 0)).

get_model_matrix()

Calculates the transformation matrix required to position this chunk correctly within the global 3D world space.

Return type:

Any

set_uniform()

Writes this chunk’s model matrix to the active shader.

Return type:

None

build_mesh()

Instantiates a ChunkMesh object to begin the greedy meshing process.

Return type:

None

render()

Issues the draw call for the opaque geometry (stone, dirt, grass) of this chunk.

Return type:

None

render_water()

Issues the draw call for the transparent geometry (water) of this chunk.

Return type:

None

build_voxels()

Helper function to allocate an empty array and immediately invoke the terrain generator.

Return type:

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

static generate_terrain(voxels, lightmap, chunk_x, chunk_y, chunk_z, perm_array, perm_grad_array, seed)

A highly parallelized Numba wrapper that populates a chunk’s voxel and lighting arrays deterministically based on the world seed.

Parameters:

• voxels (Any)

• lightmap (Any)

• chunk_x (int)

• chunk_y (int)

• chunk_z (int)

• perm_array (Any)

• perm_grad_array (Any)

• seed (int)

Return type:

None

static fill_initial_sunlight_only(voxels, lightmap, chunk_x, chunk_y, chunk_z, perm_array)

A Numba-optimized function to fill sunlight in a chunk’s lightmap without modifying the voxel data. Used during world loading to quickly restore lighting without regenerating terrain.

Parameters:

• voxels (Any)

• lightmap (Any)

• chunk_x (int)

• chunk_y (int)

• chunk_z (int)

• perm_array (Any)

Return type:

None

clouds

Procedural skybox and cloud layer management.

This module initializes the dynamic sky environment and is responsible for continuously passing updated session-time shader uniforms to animate the wind-swept traversal of the volumetric cloud geometry.

class world_objects.clouds.Clouds(app)

Bases: object

Manages the procedural 3D cloud layer in the sky.

Handles updating the time for cloud movement and rendering the cloud mesh. Provides the visual atmospheric layer that scrolls across the world origin.

Parameters:

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

update()

Updates the ‘u_time’ uniform in the cloud shader to animate their movement.

Return type:

None

render()

Issues the draw call to render the 3D clouds.

Return type:

None

item

Physical dropped item entity management.

This module manages the instantiation, 3D physics, collision handling, and rendering of items that pop out of broken blocks. The ItemManager utilizes a strict First-In-First-Out (FIFO) cap to forcefully limit active entities, guaranteeing smooth framerates regardless of how many blocks are exploded concurrently.

class world_objects.item.Item(app, position, voxel_id)

Bases: object

Represents a physical, dropped 3D item entity in the world.

Handles gravity, sliding friction, bouncing, and player pickup detection. Items are spawned when blocks are broken or when dropped from the inventory.

Parameters:

• app (Any) – The main application instance.

• position (Any) – A PyGLM vec3 or tuple representing the initial world spawn coordinates.

• voxel_id (int) – The block or item UID that dictates its visual mesh and inventory value.

update()

Applies continuous gravity and velocity updates, handles simple ground collisions, and destroys the item if it falls into the void or is collected by the player.

Return type:

None

get_model_matrix()

Returns the transformation matrix required to position, rotate, and scale the 3D item for rendering.

Return type:

Any

class world_objects.item.ItemManager(app)

Bases: object

Manages all active Item entities in the scene.

Handles updating physics, batched rendering, and enforcing an entity cap to prevent performance degradation from extreme item quantities.

Parameters:

app (Any) – The main application instance.

add_item(position, voxel_id)

Spawns a new item entity into the world. Enforces a First-In-First-Out (FIFO) limit to automatically despawn old items if too many are active at once.

Parameters:

• position (Any)

• voxel_id (int)

Return type:

None

load_item(voxel_id, position_x, position_y, position_z, velocity_x, velocity_y, velocity_z)

Restores a previously saved item entity into the world with its exact former position and velocity to bypass the random spawn burst.

Parameters:

• voxel_id (int)

• position_x (float)

• position_y (float)

• position_z (float)

• velocity_x (float)

• velocity_y (float)

• velocity_z (float)

Return type:

None

update()

Updates physics for all active items and removes ones marked as dead.

Return type:

None

render()

Renders all items that fall within the specific item render distance.

Return type:

None

sky

Procedural skybox and atmospheric background rendering.

This module generates the geometry for a full-screen quad that acts as the canvas for the sky shader. The shader itself handles rendering the dynamic day/night cycle, sun, moon, and stars directly behind all other 3D geometry.

class world_objects.sky.SkyMesh(app)

Bases: BaseMesh

Generates the geometry for the skybox, represented as a full-screen 2D quad.

This mesh does not require complex 3D geometry because the sky is procedurally generated entirely in the fragment shader using ray direction calculations.

Parameters:

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

get_vertex_data()

Returns the vertex coordinates for a full-screen quad spanning normalized device coordinates.

Return type:

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

class world_objects.sky.Sky(app)

Bases: object

Manages the skybox object, handling the rendering of the atmospheric background and celestial bodies.

Parameters:

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

render()

Issues the draw call for the skybox. Temporarily disables depth testing to ensure the sky is drawn strictly behind all other 3D geometry.

Return type:

None

voxel_marker

Dynamic 3D cursor block highlighting.

This module tracks the player’s active raycast target via the voxel handler and renders a real-time floating 3D wireframe box. It shifts its position dynamically based on whether the player is currently aiming to break a block or place a new one attached to a targeted face.

class world_objects.voxel_marker.VoxelMarker(voxel_handler)

Bases: object

Renders a 3D wireframe highlight around the voxel currently targeted by the player.

It tracks the voxel handler’s targeted position and visually outlines it. The marker adapts its position dynamically based on the interaction mode (breaking vs. placing).

Parameters:

voxel_handler (Any) – The world’s voxel handler instance tracking player raycasts.

update()

Updates the marker’s 3D position to match the currently targeted voxel. Adjusts position based on whether the player is aiming to break or place a block.

Return type:

None

set_uniform()

Sends the interaction mode and the calculated model transformation matrix to the voxel marker’s shader program.

Return type:

None

get_model_matrix()

Calculates the transformation matrix required to position the wireframe marker correctly at the targeted voxel’s world space coordinates.

Return type:

Any

render()

Issues the draw call for the wireframe cube if the player is actively targeting a valid block in the world.

Return type:

None