How anima-libera/qwy3 works
Project Type and Purpose
• Qwy3 is a real-time 3D voxel game engine (Minecraft-like) written in Rust, leveraging WGPU for rendering.
• Its main responsibilities:
• Procedural world generation
• Chunk management (load/unload, mesh generation)
• Physics and entity simulation
• Real-time rendering with shaders
• Save/load game state
• Configurable controls via CLI and control files
Top-Level Components
A. CLI & Input Layer
• “cmdline” module parses flags (--gen-dist, --save, etc.)
• “interface” & “widgets” handle user input and on-screen UI
• External file: default_controls.qwy3_controls
B. Game Core
• “game_init” sets up subsystems (window, WGPU device, threadpool)
• “game_loop” drives the main tick: schedule tasks, swap frames
• “commands” & “lang” handle in-game console commands and localization
C. World Generation
• “world_gen” submodule (noise, structure_engine)
• “texture_gen” produces procedural textures/atlases (“atlas”)
D. Chunk System
• “chunks”, “chunk_blocks”, “chunk_loading”, “chunk_meshing”
• Responsible for: dividing world into chunks, palette compression, greedy meshing
E. Physics & Entities
• “physics” resolves AABB-voxel collisions
• “entities” & “entity_parts” simulate players, thrown blocks, ball animals
F. Rendering Pipeline
• “rendering_init” configures WGPU swapchain, pipelines
• “rendering”, “camera”, “skybox”, “simple_meshes”
• “shaders” folder: .wgsl and .rs shader modules for blocks, shadows, lines, textures
G. Multithreading & Task Scheduler
• “threadpool” & “tasks” modules
• Offloads world gen, meshing, physics, entity updates
H. Persistence (Save/Load)
• “saves” serializes/deserializes game state (chunks, entities, seed, player pos) to disk
• Uses Rust’s file I/O and compression
I. Resource Management
• “table_allocator” for efficient memory allocation
• “atlas” for texture atlas management
Relationships & Data Flows
• CLI → Game Core (initial configuration)
• Game Core → Threadpool (dispatch tasks each tick)
• Threadpool ↔ World Gen & Chunk System (generate, load, mesh)
• Threadpool ↔ Physics & Entities (update simulation)
• Rendering Pipeline → GPU via WGPU API → Display
• Persistence ↔ Chunk System & Entities (periodic save/load)
• Interface ↔ Game Core (input events)
Architectural Patterns & Design Principles
• Pipeline pattern: separate generation, simulation, and rendering in stages
• Task parallelism: thread pool dispatches independent tasks (world gen, physics, meshing)
• Module separation: each subsystem lives in its own Rust module
• Resource pooling: custom allocator for mesh buffers and textures
• Data-oriented design: chunk palette compression, batched mesh uploads
Final Checklist
• All major modules/components labeled clearly
• Notes on key technologies: Rust, WGPU, WGSL shaders, custom threadpool