# anima-libera/qwy3 architecture

> Architecture diagram of the GitHub repository anima-libera/qwy3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anima-libera/qwy3
- Repository: https://github.com/anima-libera/qwy3

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Input Layer
    subgraph "CLI & Input Layer"
        cmdline["cmdline"]:::blue
        interface["interface"]:::blue
        widgets["widgets"]:::blue
        controls["default_controls.qwy3_controls"]:::grey
    end

    %% Game Core
    subgraph "Game Core"
        game_init["game_init"]:::blue
        game_loop["game_loop"]:::blue
        commands["commands"]:::blue
        lang["lang"]:::blue
    end

    %% World Generation
    subgraph "World Generation"
        world_gen["world_gen"]:::green
        structure_engine["structure_engine"]:::green
        noise["noise"]:::green
        texture_gen["texture_gen"]:::green
        atlas["atlas"]:::green
    end

    %% Chunk System
    subgraph "Chunk System"
        chunks["chunks"]:::green
        chunk_blocks["chunk_blocks"]:::green
        chunk_loading["chunk_loading"]:::green
        chunk_meshing["chunk_meshing"]:::green
    end

    %% Physics & Entities
    subgraph "Physics & Entities"
        physics["physics"]:::purple
        entities["entities"]:::purple
        entity_parts["entity_parts"]:::purple
    end

    %% Rendering Pipeline
    subgraph "Rendering Pipeline"
        rendering_init["rendering_init"]:::orange
        rendering["rendering"]:::orange
        camera["camera"]:::orange
        skybox["skybox"]:::orange
        simple_meshes["simple_meshes"]:::orange
        shaders["shaders"]:::orange
    end

    %% Multithreading & Task Scheduler
    subgraph "Multithreading & Task Scheduler"
        threadpool["threadpool"]:::blue
        tasks["tasks"]:::blue
    end

    %% Persistence & Resource Management
    persistence["Persistence (Save/Load)"]:::grey
    table_allocator["table_allocator"]:::purple

    %% External GPU
    GPU["GPU (WGPU API)"]:::orange

    %% Connections
    cmdline -->|"flags"| game_init
    interface -->|"input events"| game_loop
    widgets -->|"UI events"| game_loop
    controls -->|"control config"| interface

    game_init -->|"init config"| game_loop
    game_loop ---|"dispatch tick"| threadpool

    threadpool ---|"WorldGenTask"| world_gen
    world_gen -->|"StructureData"| chunk_loading
    noise -->|"NoiseData"| world_gen
    texture_gen -->|"TextureData"| atlas

    threadpool ---|"ChunkRequest"| chunk_loading
    chunk_loading -->|"RawChunkData"| chunks
    chunks -->|"BlockData"| chunk_blocks
    chunk_blocks -->|"Blocks"| chunk_meshing
    chunk_meshing -->|"MeshData"| rendering

    threadpool ---|"PhysicsTask"| physics
    threadpool ---|"EntityTask"| entities
    entities -->|"State"| entity_parts

    game_loop -->|"render call"| rendering
    rendering_init -->|"setup pipelines"| rendering
    rendering -->|"draw calls"| GPU

    persistence <-->|"save/load state"| chunks
    persistence <-->|"save/load state"| entities

    game_loop -->|"dispatch tasks"| tasks
    tasks -->|"work items"| threadpool

    game_loop -->|"allocator request"| table_allocator

    %% Click Events
    click cmdline "https://github.com/anima-libera/qwy3/blob/main/src/cmdline.rs"
    click interface "https://github.com/anima-libera/qwy3/blob/main/src/interface.rs"
    click widgets "https://github.com/anima-libera/qwy3/blob/main/src/widgets.rs"
    click controls "https://github.com/anima-libera/qwy3/blob/main/src/default_controls.qwy3_controls"
    click game_init "https://github.com/anima-libera/qwy3/blob/main/src/game_init.rs"
    click game_loop "https://github.com/anima-libera/qwy3/blob/main/src/game_loop.rs"
    click commands "https://github.com/anima-libera/qwy3/blob/main/src/commands.rs"
    click lang "https://github.com/anima-libera/qwy3/blob/main/src/lang.rs"
    click world_gen "https://github.com/anima-libera/qwy3/blob/main/src/world_gen/mod.rs"
    click structure_engine "https://github.com/anima-libera/qwy3/blob/main/src/world_gen/structure_engine.rs"
    click noise "https://github.com/anima-libera/qwy3/blob/main/src/noise.rs"
    click texture_gen "https://github.com/anima-libera/qwy3/blob/main/src/texture_gen.rs"
    click atlas "https://github.com/anima-libera/qwy3/blob/main/src/atlas.rs"
    click chunks "https://github.com/anima-libera/qwy3/blob/main/src/chunks.rs"
    click chunk_blocks "https://github.com/anima-libera/qwy3/blob/main/src/chunk_blocks.rs"
    click chunk_loading "https://github.com/anima-libera/qwy3/blob/main/src/chunk_loading.rs"
    click chunk_meshing "https://github.com/anima-libera/qwy3/blob/main/src/chunk_meshing.rs"
    click physics "https://github.com/anima-libera/qwy3/blob/main/src/physics.rs"
    click entities "https://github.com/anima-libera/qwy3/blob/main/src/entities.rs"
    click entity_parts "https://github.com/anima-libera/qwy3/blob/main/src/entity_parts.rs"
    click rendering_init "https://github.com/anima-libera/qwy3/blob/main/src/rendering_init.rs"
    click rendering "https://github.com/anima-libera/qwy3/blob/main/src/rendering.rs"
    click camera "https://github.com/anima-libera/qwy3/blob/main/src/camera.rs"
    click skybox "https://github.com/anima-libera/qwy3/blob/main/src/skybox.rs"
    click simple_meshes "https://github.com/anima-libera/qwy3/blob/main/src/simple_meshes.rs"
    click shaders "https://github.com/anima-libera/qwy3/tree/main/src/shaders/"
    click threadpool "https://github.com/anima-libera/qwy3/blob/main/src/threadpool.rs"
    click tasks "https://github.com/anima-libera/qwy3/blob/main/src/tasks.rs"
    click persistence "https://github.com/anima-libera/qwy3/blob/main/src/saves.rs"
    click table_allocator "https://github.com/anima-libera/qwy3/blob/main/src/table_allocator.rs"

    %% Styles
    classDef blue fill:#d0e7ff,stroke:#0366d6;
    classDef green fill:#e0ffe0,stroke:#28a745;
    classDef orange fill:#fff0d0,stroke:#d69f00;
    classDef purple fill:#f0e0ff,stroke:#6f42c1;
    classDef grey fill:#f6f8fa,stroke:#586069;
    classDef dashed stroke-dasharray: 5 5;
```
