Architecture Overview

​

System Architecture

┌─────────────────────────────────────────────────────────┐
│                      main.cpp                           │
│  ┌──────────┐  ┌──────────┐  ┌───────────────────┐    │
│  │  GLFW/   │  │  Input   │  │  Game Loop        │    │
│  │  OpenGL  │  │ Callbacks│  │  - Update         │    │
│  │  Setup   │  │          │  │  - Render         │    │
│  └──────────┘  └──────────┘  └───────────────────┘    │
└─────────────────────────────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
   ┌────▼─────┐      ┌────▼─────┐      ┌────▼─────┐
   │  World   │      │  Player  │      │ Renderer │
   │          │◄─────┤          │      │          │
   │ - Chunks │      │ - Physics│      │ - Shaders│
   │ - Blocks │      │ - Input  │      │ - Texture│
   │ - Light  │      │ - Camera │      │ - UI     │
   └────┬─────┘      └──────────┘      └──────────┘
        │
   ┌────▼─────┐      ┌──────────┐      ┌──────────┐
   │  Chunk   │      │   Save   │      │  Audio   │
   │          │      │  System  │      │          │
   │ - Mesh   │      │ - NBT I/O│      │ - Music  │
   │ - Blocks │      │ - Terrain│      │          │
   │ - Light  │      │ - Stream │      │          │
   └──────────┘      └──────────┘      └──────────┘

​

Core Components

​

World System

• Chunk Management: Hash map of chunks keyed by chunk coordinates (glm::ivec3)
• Block Type Registry: Array of BlockType* loaded from data/blocks.mccpp
• Lighting System: Dual propagation queues for block light and skylight
• Rendering Pipeline: Visibility culling, shadow mapping, and draw calls

class World {
public:
    Shader* shader;
    Player* player;
    TextureManager* texture_manager;
    std::vector<BlockType*> block_types;
    std::unordered_map<glm::ivec3, Chunk*, Util::IVec3Hash> chunks;
    std::vector<Chunk*> visible_chunks;
    
    // Lighting queues
    std::deque<std::pair<glm::ivec3, int>> light_increase_queue;
    std::deque<std::pair<glm::ivec3, int>> light_decrease_queue;
    std::deque<std::pair<glm::ivec3, int>> skylight_increase_queue;
    std::deque<std::pair<glm::ivec3, int>> skylight_decrease_queue;
};

​

Chunk System

• Block Storage: 3D array uint8_t blocks[16][128][16]
• Lighting Data: Packed nibbles in uint8_t lightmap[16][128][16] (4 bits skylight + 4 bits block light)
• Mesh Generation: Subdivided into 16-block-tall subchunks for efficient updates
• GPU Upload: VAO/VBO with packed vertex data (position, UV, light)

const int CHUNK_WIDTH = 16;
const int CHUNK_HEIGHT = 128;
const int CHUNK_LENGTH = 16;

class Chunk {
    uint8_t blocks[CHUNK_WIDTH][CHUNK_HEIGHT][CHUNK_LENGTH];
    uint8_t lightmap[CHUNK_WIDTH][CHUNK_HEIGHT][CHUNK_LENGTH];
    std::map<std::tuple<int,int,int>, Subchunk*> subchunks;
};

​

Player & Entity System

• Physics Integration: Gravity, drag, AABB collision with block colliders
• Input Handling: Movement acceleration, sprint mechanics, flying mode
• Camera System: View/projection matrices with FOV adjustment for sprinting
• Interpolation: Smooth rendering between physics ticks

class Player : public Entity {
public:
    glm::mat4 p_matrix, mv_matrix, vp_matrix;
    float view_width, view_height;
    float near_plane, far_plane;
    float speed, target_speed;
    bool is_sprinting;
    glm::vec3 interpolated_position;
};

​

Rendering Pipeline

• Texture Array Atlas: All block textures in a single GL_TEXTURE_2D_ARRAY (TextureManager)
• Cascaded Shadow Maps (CSM): 4-cascade directional shadows from the sun
• Colored Lighting: Separate day/night and block light with smooth propagation
• Post-Processing: Underwater effects, fullscreen shader pass
• Chunk Sorting: Distance-based ordering for translucent rendering

​

Block Type System

• Model Templates: Cube, plant, liquid, slab, torch, door, ladder, etc. (src/models/)
• Texture Bindings: Face-specific texture assignments
• Properties: Transparency, colliders, light emission
• Data File: data/blocks.mccpp maps IDs to models/textures/names

​

Data Flow

​

Block Placement/Breaking

1. Raycast: HitRay traces from player eye position
2. Collision Check: World::try_set_block validates against player AABB
3. Block Update: World::set_block modifies chunk data
4. Light Update: Triggers light propagation queues
5. Mesh Update: Chunk::update_at_position queues affected subchunks
6. Neighbor Notification: Border blocks update adjacent chunks

​

Lighting Propagation

• Block Light: 15 levels, decays by 1 per block
• Skylight: 15 levels, no decay downward, 1 per horizontal
• Sources: Torches (block light), sky (skylight)
• Updates: Incremental per-tick with configurable step limits

​

Render Frame

1. Update Phase: Player physics, world tick, lighting propagation
2. Camera Setup: Update view/projection matrices
3. Visibility Culling: Sort chunks by distance, build visible set
4. Shadow Pass: Render depth for each CSM cascade
5. Main Pass: Draw opaque chunks, then translucent with depth writes disabled
6. Post-Process: Apply underwater/other effects
7. UI Overlay: Crosshair, health bar, F3 debug screen

​

Persistence

• Save System (src/save.cpp): Chunk streaming, load/save, terrain generation
• NBT Format: Gzipped NBT with ByteArray encoding for blocks/light
• Streaming: Loads chunks near player, unloads distant ones
• Fallback: Generates flat terrain if no save data exists

​

Threading Model

​

Performance Optimizations

• Subchunk Meshing: Only rebuild affected 16×16×16 regions when blocks change
• Incremental Lighting: Configurable steps per tick to avoid frame spikes
• Frustum Culling: Chunks sorted by distance, only visible ones rendered
• Texture Atlas: Single bind for all block textures
• Index Buffer: Shared IBO for all chunks (quad -> triangle conversion)

​

Dependencies

• GLFW: Window/input management
• GLAD: OpenGL loader
• GLM: Math library (vectors, matrices)
• stb_image: Texture loading
• stb_truetype: Font rendering
• miniaudio: Music playback
• zlib: NBT compression

​

Next Steps