voxel_handler

Block interaction handler for raycasting, placing, and breaking voxels.

This module implements the mathematical DDA (Digital Differential Analyzer) raycasting algorithm to cleanly trace the player’s line of sight through the 3D chunk grid. It triggers multithreaded lighting and meshing updates whenever the player adds or destroys blocks in the world.

class voxel_handler.VoxelHandler(world)

Bases: object

Performs raycasting from the player’s camera to interact with the voxel world. Handles calculating the targeted block, removing blocks (mining), and adding blocks (placing), while triggering necessary lighting and meshing updates.

Parameters:

world (Any) – The main world context containing the chunk array.

add_voxel()

Attempts to place the currently held block into the world at the targeted face. Checks for player collision, updates lighting (e.g. for Glowstone), and queues adjacent chunks for remeshing.

Return type:

None

rebuild_adjacent_chunks(world_pos, is_light_update=True)

Automatically queues neighboring chunks for mesh regeneration if a block modification occurs near a chunk border, or if it creates a large lighting update requiring neighbors to recalculate their block/sunlight visuals.

Parameters:

• world_pos (Any)

• is_light_update (bool)

Return type:

None

remove_voxel()

Breaks the targeted voxel, updates local block lighting (stripping or letting sunlight in), spawns a dropped item entity in Survival mode, and queues chunks for remeshing.

Return type:

None

set_voxel(mode='remove')

Wrapper to call either add_voxel or remove_voxel based on the mode.

Parameters:

mode (str)

Return type:

None

update()

Update per-frame voxel interaction state (casts the interaction ray).

This should be called from the main update loop to refresh the targeted voxel based on the player’s view.

Return type:

None

ray_cast()

Casts a ray forward from the camera’s position through the voxel grid using a fast voxel traversal algorithm. Determines the exact targeted voxel and its normal face.

Return type:

bool

get_voxel_id(voxel_world_pos)

Resolve a world-space voxel position to its chunk-local index and id.

Parameters:

voxel_world_pos (Any) – 3D position (vec-like) in world coordinates.

Returns:

A tuple of (voxel_id, voxel_index, voxel_local_pos, chunk) where voxel_id is 0 for empty space, voxel_index is the linear index inside the chunk voxel array, voxel_local_pos is the local 3D integer coordinate within the chunk, and chunk is the chunk object containing the voxel (or None if out of loaded range).

Return type:

Tuple[int, int, Any, Any]