PyMinecraft

A voxel sandbox game with a custom Python engine built on ModernGL + GLFW + NumPy, developed against a 10-phase master plan (docs/plan/).

Infinite 256-tall procedural worlds with 13 biomes, rivers, ravines, caves and ore veins; villages, dungeons and mineshafts; a Nether dimension reached through obsidian portals. A multi-pass renderer with HDR, cascaded shadow maps, bloom and simplified voxel PBR (procedural normal + material maps). Flood-fill lighting with real voxel shadows and warm torch light. Flowing water and lava with a cellular-automata fluid sim. Survival with health, hunger, an inventory, shaped crafting, tools with tiers, and eating. An ECS driving 8 mob types with behaviour-tree AI (passive animals + hostile zombies, skeletons, creepers, spiders). A particle system, procedural audio, rain, a third-person view (F5), clouds and stars. Zero external assets — every texture is generated procedurally at startup (64×64 with PBR maps).

Caution

This is a simple test game generated by AI to explore the model's capabilities. It is not suitable for actual gameplay—it contains numerous bugs, highly limited features, and virtually no optimization.

Quick start

git clone https://github.com/Marak123/PyMinecraft.git
cd PyMinecraft
py -m pip install -r requirements.txt
py launcher.py

Requirements: Python 3.12+ and a GPU with OpenGL 3.3 (practically any).

Controls

Key	Action
W A S D	move
Space	jump / swim up / (while flying) ascend
Left Ctrl	sprint (with an FOV kick)
Left Shift	sneak — you cannot fall off edges / (while flying) descend
F	toggle flying (creative mode only)
F4	switch survival / creative mode
LMB	break block (hold to dig; tools dig faster) / attack mobs
RMB	place block / eat held food
MMB	pick targeted block
1–9 / mouse wheel	select hotbar slot
E	inventory & crafting (survival) / block picker (creative)
G	ignite a nether portal (looking at an obsidian frame)
F	fly (creative)  ·  F4 survival/creative  ·  F5 third person
F11	fullscreen  ·  F3 debug overlay  ·  F2 screenshot
ESC	pause + settings (render distance, FOV, vsync, shadows, bloom…)

Survival: 10 hearts + 10 hunger drumsticks. Fall/lava/drowning damage, starvation, regeneration when well-fed. Mined blocks (and slain mobs) drop items you walk over to collect. Craft planks → sticks → tools; better tool tiers mine faster and unlock harder ores. Eat apples and meat. Fight hostile mobs that spawn in the dark. Build an obsidian frame and ignite it (G) to travel to the Nether.

Creative: flying, instant breaking, no damage, full item picker.

Performance: ~45–55 FPS at render distance 8 with every effect on (RTX 3050 laptop); toggle shadows or bloom in the pause menu for a locked 60. See docs/ROADMAP.md for the phase-by-phase status.

The world saves automatically on exit (modified chunks only) to saves/world/. Settings (resolution, render distance, FOV, mouse sensitivity, seed) live in configs/settings.json — the file is created with defaults on first run.

Architecture

launcher.py          entry point
game/                game layer: main loop, player, hotbar, HUD
engine/
  core/              config, logging, frame clock, 3D math
  window/  input/    GLFW window, input snapshot
  camera/            FPS camera + frustum
  world/             blocks (data-driven), noise, terrain generator, chunks,
                     async streaming, day cycle, world persistence
  graphics/          mesher (NumPy, AO, 8-byte packed vertices),
                     procedural texture array, shaders, renderer
  physics/           AABB collisions, DDA raycast
configs/             blocks.json (block definitions), settings.json
tools/               smoke_test.py (offscreen render), logic_test.py

Principles: the engine knows nothing about gameplay; every subsystem is replaceable; blocks and items are data (configs/blocks.json), not classes — adding a block takes a JSON entry plus a 16×16 tile painter.

How it works (technical digest)

• 16×16×128 chunks (NumPy uint8). The streaming pipeline has three worker-thread stages — generate → light → mesh — with nested radii (each stage needs its neighbours from the previous one); GPU uploads happen on the main thread only, under a per-frame budget.
• Flood-fill lighting: two 0–15 fields per chunk. Sky light beams down and floods sideways (real voxel shadows: dark caves, shade under trees); block light floods out of torches, glowstone and lava. Fields are computed with iterative vectorised dilation on a 3×3-chunk window; edits relight a small box seeded with stored boundary light, which handles light removal without the classic two-phase BFS.
• Vectorised mesher: face culling + per-vertex ambient occlusion + smooth light (average of the four corner cells) + quad-diagonal flipping. A vertex is 2× uint32 (position, corner, AO, face, texture, emission, sky & block light), decoded in the vertex shader whose constant tables are generated from the same Python data the mesher uses.
• Multi-pass generator: continents → mountains (ridged noise) → climate (temperature × humidity) → biomes → terrain → caves (spaghetti + caverns, 3D noise at half resolution, ~3× faster) → ores → glowstone pockets → water → trees (oak + birch) → plants. Everything is a pure function of (seed, chunk), so trees grow seamlessly across chunk borders.
• Renderer: texture array (no UV bleeding), vectorised frustum culling with mesh-tight bounds, pooled chunk buffers (remeshes reuse GPU memory), opaque front-to-back, cutout without culling, water blended back-to-front with a waving surface, drifting procedural clouds; sky with a sun disc, a moon and night-time stars.

Tests

py tools/logic_test.py    # edits, persistence, physics, raycast (headless)
py tools/smoke_test.py    # offscreen render to PNG + micro-benchmark
py launcher.py --frames 300 --screenshot test.png   # full game, auto-close

Development plan: see docs/ROADMAP.md.

Author and license

Author: Marak123

The engine and game code were generated with Claude Fable 5 (Claude Code, Anthropic) from the author's project specification.

License: MIT.