B-Lec

A C++ 3D voxel game prototype demonstrating modular architecture with window management, rendering, input handling, and infinite chunk-based world system.

Features

• Modular Architecture: Clean separation of concerns across window, input, rendering, world, and debug systems
• 3D Rendering: OpenGL-based 3D graphics with camera control and mesh rendering
• Infinite Chunk-Based World: Minecraft-style chunked world (16×16×256 chunks) with on-demand loading and sparse storage
• Input Handling: Keyboard and mouse input with camera movement and look controls
• Debug Overlay: Real-time debugging information including FPS, camera position, and world statistics
• Cross-Platform: Windows, Linux, and macOS support through GLFW and standard C++17
• Minimal Dependencies: Only GLFW (windowing), OpenGL (rendering), and GLM (mathematics) required
• Lightweight Testing: Custom testing framework with dedicated test suite for each module

Quick Start

Prerequisites

• CMake 4.2+
• C++17 compiler (MSVC, GCC, or Clang)
• OpenGL 2.1 or higher
• Internet access for first build (dependencies are auto-downloaded)

Build and Run

Windows (Visual Studio):

mkdir build
cd build
cmake -G "Visual Studio 17 2022" -A x64 ..
cmake --build . --config Release
.\bin\Release\blec.exe

Linux/macOS:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel
./bin/blec

Controls

• W/A/S/D or Arrow Keys: Move forward/left/backward/right
• Space/Ctrl: Move up/down
• Mouse: Look around (mouse capture when in window)
• F12: Toggle debug overlay
• Esc: Pause game

Architecture Overview

B-Lec follows a modular architecture with clear separation of concerns:

• Window Module: GLFW window lifecycle and OS integration
• Input Module: Keyboard and mouse state tracking
• Render Module: OpenGL operations, font rendering, camera, and mesh management
• World Module: Infinite chunk-based world with on-demand chunk loading (16×16×256 blocks per chunk)
• Debug Module: Real-time debugging overlay and statistics

For detailed architecture, design principles, and module interactions, see docs/ARCHITECTURE.md.

Dependencies

Dependencies are automatically downloaded during build configuration:

• GLFW 3.4: Window creation and input event management
• GLM 1.0.2: Header-only mathematics library for 3D transformations
• OpenGL: Native graphics API (already on most systems)

Building with Tests

To build and run the test suite:

Windows:

cmake -G "Visual Studio 17 2022" -A x64 -DBUILD_TESTS=ON ..
cmake --build . --config Release
cmake --build . --target run_tests

Linux/macOS:

cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON ..
cmake --build . --parallel
cmake --build . --target run_tests

Contributing

We welcome contributions! This section explains how to participate in development.

Setting Up Your Development Environment

1. Clone and setup:

git clone https://github.com/yourusername/B-Lec.git
cd B-Lec
mkdir build
cd build

2. Configure with tests enabled:

# Windows
cmake -G "Visual Studio 17 2022" -A x64 -DBUILD_TESTS=ON ..

# Linux/macOS
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON ..

3. Build and verify:

cmake --build .
cmake --build . --target run_tests

Development Workflow

1. Understanding the Code

• Read the module header files in include/ for API documentation
• Check test files in code_testing/ for usage examples
• See docs/DEVELOPMENT.md for detailed module guides

2. Code Style

• Classes and functions: PascalCase
• Constants: kPascalCase (e.g., kWindowWidth)
• Variables: snake_case
• Member variables: snake_case_ (with trailing underscore)
• Use header guards: #ifndef BLEC_MODULE_CLASS_H
• Namespace: blec::module::ClassName

3. Making Changes

Adding a new function:

// 1. Add declaration to header
/// Explain what this function does
bool MyNewFunction();

// 2. Implement in source file
bool ClassName::MyNewFunction() {
    // Implementation with clear comments
    return true;
}

// 3. Write test case
TEST_CASE(TestMyNewFunction) {
    ASSERT_TRUE(MyNewFunction());
}

Modifying existing functions:

• Update header declaration if signature changes
• Update implementation in source file
• Find all usages with: grep -r "FunctionName" src/ include/
• Update affected tests
• Update documentation comments

Adding a new module:

• Create header: include/module/class.h
• Create implementation: src/module/class.cpp
• Add source file to CMakeLists.txt
• Create test file: code_testing/module/test_class.cpp
• Update test CMakeLists.txt
• Integrate in main.cpp if needed

4. Testing

Always run tests before committing:

cmake --build . --target run_tests

Follow these guidelines:

• One test case per function/behavior
• Test name starts with "Test"
• Test both success and error cases
• Use clear assertion messages

5. Documentation

When making changes, update:

• Code comments explaining "why", not just "what"
• docs/ARCHITECTURE.md for structural changes
• docs/BUILDING.md if build process changes
• This README if adding user-facing features

6. Committing and Pull Requests

Before submitting a PR, ensure:

• Code compiles without warnings
• All tests pass
• New code has unit tests
• Code follows naming conventions
• Complex logic is documented
• Commit messages are clear and descriptive

Resources for Contributors

• Building Guide - Comprehensive build instructions
• Architecture Documentation - System design and module details
• Development Guide - In-depth developer reference with examples
• Header file comments - API documentation and usage
• Test files - Code examples and edge cases

License

This project is licensed under the MIT License. See LICENSE file for details.

Getting Help

• Check the Development Guide for detailed explanations and code examples
• Review test files for usage patterns
• Search existing code for similar implementations
• Open an issue to discuss features or bugs