procedural-3d-engine/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code when working with this Vulkan-based 3D engine codebase.

Project Overview

A modern Vulkan-based 3D engine built on Sascha Willems' Vulkan examples framework, featuring procedural shape generation, scene management, and ImGui integration. The engine uses dynamic rendering (VK_KHR_dynamic_rendering) and C++20 standards.

Build System

Quick Build

# From project root (inihb/)
mkdir build && cd build
cmake .. && cmake --build . --config Release

Platform-Specific

• Windows: cmake .. -G "Visual Studio 16 2019" -A x64
• Linux: cmake .. && make -j$(nproc)
• Output: build/bin/Release/ProceduralEngine3D.exe

Dependencies

• Vulkan SDK (required)
• C++20 compatible compiler
• CMake 3.10.0+

Architecture

Core Systems

• Application (src/core/Application.cpp): Main Vulkan application class inheriting from VulkanExampleBase
• Base Framework (base/): Sascha Willems' Vulkan infrastructure
• Scene Management (src/scene/): Object and shape management
• UI System (src/ui/): ImGui-based interface
• Camera System (base/camera.hpp): Orbit camera with focus functionality

Vulkan Features

• Dynamic rendering (no render passes/framebuffers)
• Modern Vulkan 1.3+ practices
• Multi-platform window system integration
• Validation layer support

Key Files

Core Components

• src/core/Application.cpp - Main application class with Vulkan setup
• base/camera.hpp - Camera system with orbit mode and F key focus
• src/scene/SceneManager.cpp - Scene graph and object management
• src/ui/UIManager.cpp - ImGui integration and panels

Vulkan Infrastructure (Sascha Willems Base)

• base/VulkanExampleBase.h - Main Vulkan framework
• base/VulkanDevice.hpp - Vulkan device abstraction
• base/VulkanSwapChain.hpp - Swapchain management
• base/VulkanBuffer.hpp - Buffer utilities

Build Configuration

• CMakeLists.txt - Main build configuration
• BUILD.md - Detailed build instructions

Camera System

F Key Focus Feature

The camera system supports focusing on selected objects:

• Press F to focus camera on selected object
• Automatically calculates optimal viewing distance
• Switches to orbit mode around focused object
• Mouse rotation orbits around the focused object center

Implementation Details

• camera.focusOnObject() - Sets orbit center and optimal distance
• camera.updateOrbitPosition() - Handles spherical coordinate positioning
• Hybrid system: standard Sascha camera + orbit mode using glm::lookAt()

Development Guidelines

Testing Changes

1. Build with cmake --build . --config Release
2. Run from build/bin/Release/
3. Use F key to test camera focus functionality
4. Check console output for debug information

Vulkan Debugging

• Enable validation layers with -v command line flag
• Use --listgpus to see available Vulkan devices
• Check VK_LAYER_KHRONOS_validation environment variable

Adding Features

• Follow Sascha Willems patterns for Vulkan code
• Use dynamic rendering (no render passes)
• Implement proper buffer management and synchronization
• Add ImGui panels for new features

Common Tasks

Build and Run

cd build
cmake --build . --config Release
bin/Release/ProceduralEngine3D.exe

Shader Compilation

Shaders are in GLSL and compiled to SPIR-V:

• Location: shaders/glsl/
• Compiled automatically during build
• Use glslc or glslangValidator for manual compilation

Clean Build

rm -rf build && mkdir build && cd build
cmake .. && cmake --build . --config Release

Camera Controls

• Mouse: Look around (standard mode) or orbit (after F key focus)
• WASD: Move camera
• F: Focus on selected object
• Mouse Wheel: Zoom (in orbit mode changes distance)

Command Line Options

Available options (use --help for full list):

• -v, --validation: Enable validation layers
• -w, --width: Set window width
• -h, --height: Set window height
• -f, --fullscreen: Start in fullscreen
• -g, --gpu: Select GPU device
• --listgpus: List available Vulkan devices

Technical Notes

Modern Vulkan Usage

• Uses VK_KHR_dynamic_rendering extension
• No traditional render passes or framebuffers
• Leverages Vulkan 1.3+ features where available
• Proper synchronization with timeline semaphores

Memory Management

• Buffer utilities handle staging automatically
• Proper cleanup in destructors
• Device memory allocation through base framework

Threading

• Single-threaded main loop
• Vulkan command buffer recording on main thread
• UI rendering integrated with main render loop