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