world

Global 3D environment and multi-threading architecture controller.

The World manager orchestrates the engine’s asynchronous lifeblood: dynamic chunk streaming, ThreadPool dispatching for mesh generation and lighting, and background Write-Ahead Logging (WAL) SQLite disk saving/loading. It directly handles the GPU dispatch via hardware occlusion queries and dynamic vectorized frustum culling.

class world.World(app, save_name, world_seed)

Bases: object

Manages the global 3D voxel environment.

Responsible for chunk streaming, multithreaded terrain generation, mesh building queues, and persistent background SQLite disk storage. It acts as the central hub linking the player, terrain data, lighting updates, and GPU render dispatching.

Parameters:

• app (Any) – The main Pyrite application instance.

• save_name (str) – The string identifier/filename for the SQLite world database.

• world_seed (int) – The deterministic seed used for procedural terrain generation.

update()

Tick loop that handles continuous background data processing. Steps through loading chunks, dispatching thread-pool mesh tasks, and streaming logic.

Return type:

None

process_mesh_queue()

Pulls completed mesh data from background threads and safely initializes OpenGL Vertex Array Objects (VAOs) on the main thread, utilizing a recycling VBO pool to prevent VRAM memory leaks.

Return type:

None

process_load_queue()

Consumes asynchronously loaded/generated chunk data, registers it into the active world arrays, applies volumetric lighting (BFS), and schedules the chunk and its neighbors for mesh building.

Return type:

None

stream_chunks()

Checks the player’s position against the render distance to determine which distant chunks to unload, and which new surrounding chunks to queue for background loading.

Return type:

None

load_chunk(x, y, z)

Initializes a Chunk instance at the given coordinates and dispatches an asynchronous task to fetch or generate its actual voxel data.

Parameters:

• x (int)

• y (int)

• z (int)

Return type:

None

save_chunk_to_db(x, y, z, voxels, lightmap)

Compresses a chunk’s massive 1D voxel and lighting arrays using zlib, and executes a thread-safe write to the SQLite database.

Parameters:

• x (int)

• y (int)

• z (int)

• voxels (ndarray[tuple[Any, ...], dtype[uint8]])

• lightmap (ndarray[tuple[Any, ...], dtype[uint8]] | None)

Return type:

None

unload_chunk(position)

Removes a chunk from the active world space, triggers an asynchronous disk save, purges it from any pending queues, and recycles its VRAM.

Parameters:

position (Tuple[int, int, int])

Return type:

None

render()

Performs dynamic vectorized frustum culling and hardware occlusion queries to identify visible chunks, then safely dispatches rendering calls to the GPU.

Return type:

None

render_water()

A secondary rendering pass explicitly designed to draw transparent water meshes properly blended over the previously drawn opaque terrain.

Return type:

None

save()

Synchronously dumps all currently active chunks, inventory contents, player coordinates, and world metadata safely to the SQLite disk on exit.

Return type:

None