pyworldgen 0.1.8

Deterministic procedural world generation: biomes, noise, roads, and smooth multi-biome composition.

pyworldgen

A unified, deterministic procedural biome-generation library. A seed plus parameters is the world — voxel grids, meshes, point clouds and saved chunks are all regenerable views of that compact source.

What's in it

• Biomes — implicit caves, Voronoi forests, river landscapes, and a neutral flat terrain.
• Composition — blend several biomes into one coherent world with smooth transitions.
• Roads — weighted anisotropic least-cost paths (Galin et al. 2010) over any terrain, with bridges and terrain grading.
• Chunked voxel world — block storage, generation-pass scheduler, streaming, deferred edits, sunlight.
• Geometry views — voxel meshers, surface point-cloud sampling with farthest-point downsampling, OBJ / MagicaVoxel .vox / PLY / XYZ export.
• Rendering — pure-numpy pinhole camera and software renderer, plus PyVista and matplotlib backends, with PNG / GIF / MP4 output.
• Spatial toolkit — spatial hash grid, BVH, KD-tree, R-tree, quad/octree, voxel DDA, graph + Dijkstra, farthest point sampling.

Everything shares one cross-language deterministic hash, so the same seed reproduces the same world bit-for-bit across Python, JavaScript and GLSL.

Quick start

import pyworldgen as bf

bf.list_generators()
# ['composite', 'flat', 'forest', 'implicit_cave', 'landscape', 'roads']

forest = bf.generate("forest",        seed="grenoble",   target_tree_count=60)
cave   = bf.generate("implicit_cave", seed="luxembourg", length=90.0)
land   = bf.generate("landscape",     seed="rhine")
world  = bf.generate("composite",     seed="atlas")

Export a biome as voxels, mesh, and a downsampled point cloud:

from pyworldgen.mesh import volume_to_mesh
from pyworldgen.pointcloud import sample_mesh_surface
from pyworldgen.io import volume_to_vox, mesh_to_obj, write_ply

volume_to_vox("cave.vox", cave)
mesh = volume_to_mesh(cave)
mesh_to_obj("cave.obj", mesh)

cloud = sample_mesh_surface(mesh, 40_000, seed=1)
write_ply("cave_points.ply", cloud.farthest_point_downsample(4_096))

Render a turntable fly-through:

import pyworldgen.rendering as rr

frames = rr.render_turntable(cloud, n_frames=48, elevation=18)
rr.save_gif(frames, "cave_orbit.gif", fps=20)

Installation

pip install -e .          # runtime
pip install -e ".[dev]"   # + pytest

Runtime dependencies: numpy, scipy, fpsample, matplotlib, pillow, imageio, pyvista. Optional extras: [viz] (scikit-image) and [geometry] (shapely, trimesh, mapbox-earcut).

Visualization scripts

python scripts/visualize_all.py --quick --out sample_visualizations
python scripts/render_biome.py composite --seed atlas --quick

Where to look next

• algo_specs/ — per-biome algorithm specs (cave, landscape, tree, flat).
• CITATIONS.md — paper-level references per source file.
• Module docstrings (pyworldgen.biomes.*, pyworldgen.roads, pyworldgen.compose, pyworldgen.noise, …) — the authoritative description of each layer, including scope and honest gaps versus the cited papers.
• tests/ — invariants and reproducibility checks worth reading as usage examples.