🎮 ZVGE - Zig Vulkan Game Engine

Минималистичный, высокопроизводительный 3D движок на Zig + Vulkan

Build Status Zig Version License

✨ Features

✅ Implemented

• Vulkan Backend: Context, swapchain, double buffering
• Buffer Management: Vertex, index, uniform buffers with staging
• 3D Rendering: MVP matrices, depth testing, texturing
• Multiple Objects: Efficient multi-object rendering with descriptor sets
• Resource Management: RAII-style lifecycle, proper cleanup
• Configuration System: Centralized settings, compile-time validation
• Error Handling: Typed error sets, structured logging

🚧 In Progress

• Camera system
• Input handling
• Scene graph
• Performance profiling

📅 Planned

• PBR materials & lighting
• Shadow mapping
• Model loading (glTF 2.0)
• Skeletal animation
• Post-processing

🚀 Quick Start

Prerequisites

# Required
- Zig 0.16.0-dev or later
- Vulkan SDK 1.3+ 
- glslc (shader compiler)
- GLFW-compatible environment
# Optional (for profiling)
- RenderDoc
- NVIDIA Nsight Graphics

Build & Run

# Clone
git clone https://github.com/yourusername/zvge.git
cd zvge
# Build (Debug)
zig build
# Run
zig build run
# Build (Release, optimized)
zig build -Doptimize=ReleaseFast

Expected Output

info(zvge): Using device: NVIDIA GeForce RTX 3060
info(zvge): Max objects: 16, Frames in flight: 2
info(zvge): Initialization complete. Starting render loop with 2 objects...
info(zvge): FPS: 60.0 (16.67ms/frame)

🎯 Current State

Version: 0.2-dev
Objects Rendered: 2 textured cubes
Performance: 60 FPS @ ×ばつ600 (V-Sync)
Memory Usage: ~50MB GPU, ~10MB CPU

Demo Screenshot: (TODO: Add screenshot)

📁 Project Structure

zvge/
├── src/
│ ├── main.zig # Entry point, main render loop
│ ├── config.zig # Configuration constants
│ ├── errors.zig # Error types and utilities
│ ├── graphics/ # Low-level Vulkan abstractions
│ │ ├── context.zig # Instance, device, queues
│ │ ├── swapchain.zig # Presentation, double buffering
│ │ └── buffer.zig # GPU memory management
│ └── renderer/ # High-level rendering
│ ├── renderer.zig # Main renderer orchestration
│ ├── object.zig # Renderable object
│ ├── mesh.zig # Geometry (vertices, indices)
│ ├── texture.zig # Image loading, sampling
│ ├── pipeline.zig # Graphics pipeline state
│ └── uniform.zig # Uniform buffer objects
├── shaders/
│ ├── shader.vert # Vertex shader (GLSL)
│ └── shader.frag # Fragment shader (GLSL)
├── assets/
│ └── textures/ # Texture files
├── docs/ # Comprehensive documentation
└── build.zig # Build configuration

💻 API Examples

Creating a Renderable Object

constObject=@import("renderer/object.zig").Object;// Initialize object with mesh and texture
varobj=tryObject.init(allocator,&graphics_context,command_pool,null,// mesh_path (null = procedural cube)
"assets/textures/my_texture.jpg",frames_in_flight,);deferobj.deinit();// Update uniform buffer each frame
tryobj.updateUniform(frame_index,mvp_matrix);

Buffer Management

constBuffer=@import("graphics/buffer.zig").Buffer;// Create buffer with data (uses staging)
constvertex_buffer=tryBuffer.createWithData(&gc,command_pool,std.mem.sliceAsBytes(vertices),.{.vertex_buffer_bit=true},);defervertex_buffer.deinit();// Upload to uniform buffer (host-visible)
tryuniform_buffer.upload(std.mem.asBytes(&ubo));

Rendering

constRenderer=@import("renderer/renderer.zig").Renderer;// Initialize renderer
varrenderer=tryRenderer.init(allocator,&gc,extent);deferrenderer.deinit();// Setup descriptor sets
tryrenderer.initDescriptors(&pipeline,objects);// Record command buffers
tryrenderer.recordCommands(&pipeline,objects);// Render frame
conststate=tryrenderer.render();

📚 Documentation

Getting Started

• Quick Reference - Start here! Overview, commands, tips
• Code Review - Detailed architecture analysis
• Bug Fixes - Fixed issues and solutions

Advanced Topics

• Performance Guide - Optimization techniques
• Optimization Checklist - Quick wins
• Iteration Notes - Development progress

🏗️ Architecture Principles

Design Philosophy

1. KISS - Keep It Simple, Stupid
2. RAII - Resource Acquisition Is Initialization
3. Explicit > Implicit - No hidden magic
4. Fail Fast - Compile-time checks where possible
5. Performance - But not at cost of clarity

Code Style

• BSD-like - Clean, readable, professional
• LLVM ecosystem - Built for Clang/LLVM toolchain
• Linus-approved - Would pass Linus Torvalds review 😄

🎓 Learning Resources

For This Project

• Read docs/QUICK_REFERENCE.md for overview
• Check src/main.zig for entry point
• Explore src/renderer/ for rendering logic

External Resources

• Vulkan Tutorial - Excellent introduction
• Zig Language Reference
• zig-gamedev - Zig game libraries

🤝 Contributing

Contributions welcome! Please:

1. Follow existing code style (run zig fmt)
2. Add doc comments for public APIs
3. Test thoroughly (aim for no regressions)
4. Update docs if changing public APIs

📊 Benchmarks

Benchmarks on: NVIDIA RTX 3060, Vulkan 1.3, ×ばつ1080

🐛 Known Issues

• GLFW может требовать X11/Wayland runtime
• Validation layers могут замедлять Debug builds (ожидаемо)
• Нет graceful handling для window minimize (TODO)

📝 License

MIT License - см. LICENSE

🙏 Acknowledgments

• zglfw - GLFW bindings for Zig
• vulkan-zig - Vulkan bindings
• zmath - Math library
• zignal - Image loading
• Khronos Group - Vulkan API

Built with ❤️ using Zig + Vulkan

Гайды:

• Architecture Guide - архитектура движка
• Index Buffer Guide - зачем нужны индексы
• Textured Cube Guide - следующий шаг (3D)

Отчёты:

• REFACTORING_COMPLETE.md - 484→96 строк в main
• DONE.md - текущий статус

Roadmap

Сейчас: 2D геометрия (triangle, quad) с index buffers
Далее: 3D cube → textures → camera → lighting

Полный roadmap: docs/TEXTURED_CUBE_GUIDE.md

Философия

• KISS: простое > сложное
• Работает > красиво
• Измеряй перед оптимизацией
• Никаких абстракций "на будущее"

Проблемы?

rm -rf zig-cache && zig build # Очистка + пересборка

Validation errors? Проверь Vulkan SDK и логи.

Лицензия

MIT

"Talk is cheap. Show me the code." - Linus Torvalds