/$$$$$$$$ /$$$$$$ /$$$$$$ /$$$$$$ /$$$$$$$ /$$$$$$ /$$$$$$$$ /$$$$$$$$
|_____ $$ |_ $$_/ /$$__ $$ /$$__ $$| $$__ $$ /$$__ $$| $$_____/|__ $$__/
/$$/ | $$ | $$ \__/| $$ \__/| $$ \ $$| $$ \ $$| $$ | $$
/$$/ | $$ | $$ /$$$$| $$ | $$$$$$$/| $$$$$$$$| $$$$$ | $$
/$$/ | $$ | $$|_ $$| $$ | $$__ $$| $$__ $$| $$__/ | $$
/$$/ | $$ | $$ \ $$| $$ $$| $$ \ $$| $$ | $$| $$ | $$
/$$$$$$$$ /$$$$$$| $$$$$$/| $$$$$$/| $$ | $$| $$ | $$| $$ | $$
|________/|______/ \______/ \______/ |__/ |__/|__/ |__/|__/ |__/
A high-performance Minecraft-style voxel engine built with Zig, SDL3, and a modern Vulkan graphics pipeline.
| Component | Minimum | Recommended |
|---|---|---|
| OS | Linux (NixOS), Windows (WSL2) | Linux (NixOS) |
| GPU | Vulkan 1.2, 4GB VRAM | Vulkan 1.3, 8GB+ VRAM |
| RAM | 8 GB | 16 GB |
| Storage | 2 GB | 4 GB SSD |
| Build Tools | Nix package manager | Nix (latest) |
Note: All builds require Nix for reproducible dependency management (SDL3, Vulkan, glslang).
ZigCraft is a technical exploration of high-performance voxel rendering techniques. It features a custom-built graphics abstraction layer, advanced terrain generation, and a multithreaded job system to handle massive world streaming with zero hitching.
- Vulkan RHI: Modern, explicit graphics API with persistent UBO mapping for high performance.
- PBR Rendering: Physically Based Rendering with Cook-Torrance BRDF for realistic materials.
- Cascaded Shadow Maps (CSM): 3 cascades with configurable PCF sampling (4-16 samples).
- Atmospheric Scattering: Physically-based day/night cycle with dynamic fog and sky rendering.
- Advanced Graphics Menu: Real-time control over shadow quality, PBR, resolution scaling, and MSAA.
- Floating Origin & Reverse-Z: Industry-standard techniques to eliminate precision jitter and Z-fighting at scale.
- Greedy Meshing: Optimized chunk generation reducing draw call overhead and triangle counts.
- Biomes & Climate: Multi-noise system based on temperature and humidity (11+ biomes).
- Infinite Terrain: Seed-based, deterministic generation with domain warping and 3D caves.
- Volumetric Clouds: Procedural, shadowed cloud layers that integrate with the atmosphere.
- Level of Detail (LOD): Hierarchical LOD system enabling 100+ chunk render distances using simplified terrain meshes and specialized rendering.
- Greedy Meshing: Optimized vertex data generation for maximum throughput.
- Multithreaded Pipeline: Dedicated worker pools for generation (4 threads) and meshing (3 threads).
- Job Prioritization: Proximity-based task scheduling ensures immediate loading of local chunks.
- Comprehensive Testing: 58+ unit tests covering math, worldgen, and core engine modules.
- Refined App Lifecycle: Modular architecture with extracted systems for rendering, input, and world management.
| Render Distance | FPS (ReleaseFast) | GPU Used |
|---|---|---|
| 32 chunks | 120+ | RTX 3060 |
| 64 chunks | 90+ | RTX 3060 |
| 128 chunks | 60+ | RTX 3060 |
Benchmarks measured on RTX 3060 @ 1080p with HIGH quality preset
| PBR Materials | Cascaded Shadows | Biomes |
|---|---|---|
|
|
|
More screenshots coming soon!
| Key | Action |
|---|---|
| WASD | Movement |
| Space / Shift | Jump / Crouch (Fly Up / Down) |
| Left Ctrl | Sprint |
| Mouse | Look |
| Left Click / Right Click | Mine Block / Place Block |
| Tab | Toggle Mouse Capture / Menu |
| I | Open Inventory |
| 1-9 | Select Hotbar Slot |
| F / T | Toggle Wireframe / Textures |
| V | Toggle VSync |
| U / K | Toggle Shadow Debug / Cycle Cascades |
| M | Toggle World Map |
| N | Freeze / Unfreeze Time |
| F2 | Toggle FPS Counter |
| F3 | Toggle Creative Mode |
| F5 | Toggle Block Info |
| Esc | Menu / Pause |
Note: Time of day can be set via the inventory screen (buttons for DAWN, NOON, DUSK, NIGHT) |
This project uses Nix for a reproducible development environment.
After cloning or creating a new worktree, run the setup script to enable git hooks:
./scripts/setup-hooks.shThis configures a pre-push hook that runs:
zig fmt --check src/- formatting checkzig build test- full test suite
To bypass in emergencies: git push --no-verify
- Run:
nix develop --command zig build run - Release build:
nix develop --command zig build run -Doptimize=ReleaseFast
- All Tests:
nix develop --command zig build test - Single Test:
nix develop --command zig build test -- --test-filter "Test Name"
src/engine/: Core engine components (RHI, Math, UI, Input, Jobs).src/world/: Voxel-specific logic (Greedy Meshing, World Manager, Chunks).src/world/worldgen/: Procedural terrain, noise, and biome systems.assets/: GLSL shaders and textures.scripts/: Helper scripts for asset processing.libs/: (Planned) Extracted standalone math and noise libraries.
The engine supports HD texture packs with full PBR maps. To standardize high-resolution source imagery (4k JPEGs, EXRs) into engine-ready 512px PNGs, use the provided helper script:
# Standardize an entire pack
./scripts/process_textures.sh assets/textures/pbr-test 512The script automatically handles resizing and naming conventions for _diff, _nor_gl, _rough, and _disp maps.
We welcome contributions! See CONTRIBUTING.md for the full development workflow.
# Clone and setup
git clone https://github.com/OpenStaticFish/ZigCraft.git
cd ZigCraft
./scripts/setup-hooks.sh
# Enter dev environment and run tests
nix develop --command zig build testmain (production)
└─ dev (staging)
├─ feature/* # New features
├─ bug/* # Non-critical fixes
├─ hotfix/* # Critical fixes
└─ ci/* # CI/workflow changes
All PRs target the dev branch. Use our PR templates (feature.md, bug.md, hotfix.md, ci.md) for best practices.
# Clean build artifacts
rm -rf zig-out/ .zig-cache/
# Update Nix channels (if using older Nix)
nix-channel --update- Linux: Ensure
vulkan-loaderand GPU drivers are installed - NVIDIA: Proprietary drivers recommended for best performance
- Verify: Run
vulkaninfoto check Vulkan support
Shaders are validated during zig build test. If glslang fails:
# Install glslang via Nix
nix develop # glslang is included in the dev shell- Try
zig build run -Doptimize=ReleaseFastfor optimized builds - Reduce render distance in-game: Press
Esc→ Graphics → Render Distance - Disable VSync if FPS is capped at 60
| Discussions | GitHub Discussions |
| Issues | GitHub Issues |
| License | MIT License |
Built with ❤️ by the OpenStaticFish community
MIT License - see LICENSE for details.