Skip to content

Latest commit

 

History

History
219 lines (167 loc) · 6.44 KB

README.md

File metadata and controls

219 lines (167 loc) · 6.44 KB

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:

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

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