Revise Visual Studio setup documentation and enhance project generation script

- Updated the Visual Studio setup guide to recommend using a project generation script for easier configuration.
- Added detailed instructions for the new script, including features and usage examples.
- Improved the script to check for vcpkg installation and automatically install dependencies if missing.
- Introduced a test script to verify the project generation process with different configurations.
- Enhanced error handling and output messages in the project generation script for better user experience.

docs/visual-studio-setup.md

@@ -53,29 +53,39 @@ vcpkg install abseil:x64-windows
 vcpkg install gtest:x64-windows
 ```
 
-### 3. Configure Build System
+### 3. Generate Visual Studio Project Files
 
-#### Option A: Using Visual Studio Project File (Easiest)
+#### Option A: Using the Project Generation Script (Recommended)
-1. Open Visual Studio 2022
+1. Open PowerShell in the yaze project directory
-2. Select "Open a project or solution"
+2. Run the project generation script:
-3. Navigate to the yaze project folder and open `yaze.sln`
+   ```powershell
-4. The project is pre-configured with vcpkg integration and proper dependencies
+   .\scripts\generate-vs-projects.ps1
+   ```
+3. The script will:
+   - Check for CMake and Visual Studio installation
+   - Configure vcpkg integration
+   - Generate proper Visual Studio project files with all include paths
+   - Test the build to ensure everything works
+4. Open the generated `YAZE.sln` in Visual Studio
 5. Select your desired build configuration (Debug/Release) and platform (x64/x86)
 6. Press F5 to build and run, or Ctrl+Shift+B to build only
 
-#### Option B: Using CMake with Visual Studio (Recommended for developers)
+#### Option B: Manual CMake Configuration
+1. Open PowerShell in the yaze project directory
+2. Create build directory and configure:
+   ```powershell
+   mkdir build-vs
+   cd build-vs
+   cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake
+   ```
+3. Open the generated `YAZE.sln` in Visual Studio
+
+#### Option C: Using CMake with Visual Studio (For advanced users)
 1. Open Visual Studio 2022
 2. Select "Open a local folder" and navigate to the yaze project folder
 3. Visual Studio will automatically detect the CMake project
 4. Wait for CMake configuration to complete (check Output window)
 
-#### Option C: Using Command Line
-```cmd
-mkdir build
-cd build
-cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake
-```
-
 ### 4. Build Configuration
 
 #### Using Visual Studio Project File (.vcxproj)
@@ -95,9 +105,63 @@ cmake --build . --config Release --target yaze
 cmake --build . --config Debug --target yaze_test
 ```
 
+## Project Generation Script
+
+The `generate-vs-projects.ps1` script automates the Visual Studio project setup process:
+
+### Script Features
+- **Automatic CMake Detection:** Finds and configures CMake installation
+- **Visual Studio Integration:** Detects Visual Studio 2022 installation
+- **vcpkg Configuration:** Automatically configures vcpkg toolchain
+- **Dependency Installation:** Installs required packages via vcpkg
+- **Project Validation:** Tests the generated project to ensure it builds
+- **Include Path Verification:** Checks that all required include paths are present
+
+### Script Usage
+```powershell
+# Basic usage (Debug x64)
+.\scripts\generate-vs-projects.ps1
+
+# Release build
+.\scripts\generate-vs-projects.ps1 -Configuration Release
+
+# x86 build
+.\scripts\generate-vs-projects.ps1 -Architecture x86
+
+# Clean build
+.\scripts\generate-vs-projects.ps1 -Clean
+
+# With vcpkg
+.\scripts\generate-vs-projects.ps1 -UseVcpkg
+
+# Show help
+.\scripts\generate-vs-projects.ps1 -Help
+```
+
+### Testing the Setup
+Use the test script to verify the project generation works:
+```powershell
+.\scripts\test-vs-generation.ps1
+```
+
 ## Common Issues and Solutions
 
-### Issue 1: zlib Import Errors
+### Issue 1: Missing Include Files (SDL.h, etc.)
+**Problem:** `fatal error C1083: Cannot open include file: 'SDL.h'` or similar
+
+**Solution:**
+1. Use the project generation script: `.\scripts\generate-vs-projects.ps1`
+2. Ensure vcpkg is properly installed and configured
+3. Check that dependencies are installed:
+   ```cmd
+   vcpkg list
+   ```
+4. If using manual setup, ensure the vcpkg toolchain file is set:
+   ```cmd
+   cmake .. -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake
+   ```
+
+### Issue 2: zlib Import Errors
 **Problem:** `fatal error C1083: Cannot open include file: 'zlib.h'`
 
 **Solution:**
@@ -111,12 +175,12 @@ cmake --build . --config Debug --target yaze_test
    vcpkg list zlib
    ```
 
-### Issue 2: Executable Runs Tests Instead of Main App
+### Issue 3: Executable Runs Tests Instead of Main App
 **Problem:** Running `yaze.exe` starts the test framework instead of the application
 
 **Solution:** This has been fixed in the latest version. The issue was caused by linking `gtest_main` to the main executable. The fix removes `gtest_main` from the main application while keeping `gtest` for testing capabilities.
 
-### Issue 3: SDL2 Configuration Issues
+### Issue 4: SDL2 Configuration Issues
 **Problem:** SDL2 not found or linking errors
 
 **Solution:**
@@ -126,7 +190,7 @@ cmake --build . --config Debug --target yaze_test
    ```
 2. Ensure the project uses the vcpkg toolchain file
 
-### Issue 4: Build Errors with Abseil
+### Issue 5: Build Errors with Abseil
 **Problem:** Missing Abseil symbols or linking issues
 
 **Solution:**

scripts/generate-vs-projects.ps1

@@ -138,14 +138,52 @@ if (-not (Test-Path $BuildDir)) {
     New-Item -ItemType Directory -Path $BuildDir | Out-Null
 }
 
-# Check if vcpkg is available
+# Check if vcpkg is available and properly configured
 $VcpkgPath = Join-Path $SourceDir "vcpkg\scripts\buildsystems\vcpkg.cmake"
-$UseVcpkg = Test-Path $VcpkgPath
+$VcpkgInstalled = Join-Path $SourceDir "vcpkg\installed"
+
+# Check for vcpkg in common locations
+$VcpkgPaths = @(
+    Join-Path $SourceDir "vcpkg\scripts\buildsystems\vcpkg.cmake",
+    "$env:VCPKG_ROOT\scripts\buildsystems\vcpkg.cmake",
+    "$env:ProgramFiles\vcpkg\scripts\buildsystems\vcpkg.cmake",
+    "$env:ProgramFiles(x86)\vcpkg\scripts\buildsystems\vcpkg.cmake"
+)
+
+$UseVcpkg = $false
+foreach ($path in $VcpkgPaths) {
+    if (Test-Path $path) {
+        $VcpkgPath = $path
+        $UseVcpkg = $true
+        break
+    }
+}
 
 if ($UseVcpkg) {
     Write-Host "Using vcpkg toolchain: $VcpkgPath" -ForegroundColor Green
+    
+    # Check if vcpkg is properly installed with required packages
+    if (Test-Path $VcpkgInstalled) {
+        Write-Host "vcpkg packages directory found: $VcpkgInstalled" -ForegroundColor Green
+    } else {
+        Write-Host "vcpkg packages not installed. Installing dependencies..." -ForegroundColor Yellow
+        
+        # Try to install vcpkg dependencies
+        $VcpkgExe = Join-Path (Split-Path $VcpkgPath -Parent -Parent) "vcpkg.exe"
+        if (Test-Path $VcpkgExe) {
+            Write-Host "Installing vcpkg dependencies..." -ForegroundColor Yellow
+            & $VcpkgExe install --triplet $Architecture-windows
+            if ($LASTEXITCODE -ne 0) {
+                Write-Host "Failed to install vcpkg dependencies" -ForegroundColor Red
+                Write-Host "Please run: vcpkg install --triplet $Architecture-windows" -ForegroundColor Yellow
+            }
+        } else {
+            Write-Host "vcpkg.exe not found. Please install dependencies manually." -ForegroundColor Yellow
+        }
+    }
 } else {
     Write-Host "vcpkg not found, using system libraries" -ForegroundColor Yellow
+    Write-Host "Note: This may cause missing dependency issues. Consider installing vcpkg." -ForegroundColor Yellow
 }
 
 # Determine generator and architecture
@@ -171,7 +209,9 @@ $CmakeArgs = @(
     "-DYAZE_ENABLE_ROM_TESTS=OFF",
     "-DYAZE_ENABLE_EXPERIMENTAL_TESTS=ON",
     "-DYAZE_ENABLE_UI_TESTS=ON",
-    "-DYAZE_INSTALL_LIB=OFF"
+    "-DYAZE_INSTALL_LIB=OFF",
+    "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON",
+    "-DCMAKE_VERBOSE_MAKEFILE=ON"
 )
 
 if ($UseVcpkg) {
@@ -182,8 +222,8 @@ if ($UseVcpkg) {
     )
 }
 
-# Configure CMake to generate build files (but don't overwrite existing project files)
+# Configure CMake to generate Visual Studio project files
-Write-Host "Configuring CMake for build system..." -ForegroundColor Yellow
+Write-Host "Configuring CMake to generate Visual Studio project files..." -ForegroundColor Yellow
 Write-Host "Command: cmake $($CmakeArgs -join ' ')" -ForegroundColor Gray
 
 & cmake @CmakeArgs $SourceDir
@@ -193,13 +233,18 @@ if ($LASTEXITCODE -ne 0) {
     exit 1
 }
 
-# Check if the existing solution file is present and valid
+# Check if CMake generated the solution file in the build directory
-$ExistingSolutionFile = Join-Path $SourceDir "YAZE.sln"
+$GeneratedSolutionFile = Join-Path $BuildDir "YAZE.sln"
-if (Test-Path $ExistingSolutionFile) {
+if (Test-Path $GeneratedSolutionFile) {
-    Write-Host "✅ Using existing Visual Studio solution: $ExistingSolutionFile" -ForegroundColor Green
+    Write-Host "✅ CMake generated Visual Studio solution: $GeneratedSolutionFile" -ForegroundColor Green
+    
+    # Copy the generated solution to the source directory for convenience
+    $SourceSolutionFile = Join-Path $SourceDir "YAZE.sln"
+    Copy-Item $GeneratedSolutionFile $SourceSolutionFile -Force
+    Write-Host "✅ Copied solution file to project root: $SourceSolutionFile" -ForegroundColor Green
     
     # Verify the solution file is properly structured
-    $SolutionContent = Get-Content $ExistingSolutionFile -Raw
+    $SolutionContent = Get-Content $GeneratedSolutionFile -Raw
     if ($SolutionContent -match "YAZE\.vcxproj") {
         Write-Host "✅ Solution file references YAZE.vcxproj correctly" -ForegroundColor Green
         
@@ -211,25 +256,90 @@ if (Test-Path $ExistingSolutionFile) {
         }
     } else {
         Write-Host "❌ Solution file does not reference YAZE.vcxproj" -ForegroundColor Red
-        Write-Host "Please ensure the solution file includes the YAZE project" -ForegroundColor Yellow
+        Write-Host "Please check CMake configuration" -ForegroundColor Yellow
+    }
+    
+    # Check if the project file exists and has proper include paths
+    $ProjectFile = Join-Path $BuildDir "YAZE.vcxproj"
+    if (Test-Path $ProjectFile) {
+        Write-Host "✅ Project file generated: $ProjectFile" -ForegroundColor Green
+        
+        # Check for common include paths in the project file
+        $ProjectContent = Get-Content $ProjectFile -Raw
+        $IncludePaths = @(
+            "src/lib/",
+            "src/app/",
+            "src/lib/asar/src",
+            "src/lib/imgui",
+            "incl/"
+        )
+        
+        $MissingIncludes = @()
+        foreach ($include in $IncludePaths) {
+            if ($ProjectContent -notmatch [regex]::Escape($include)) {
+                $MissingIncludes += $include
+            }
+        }
+        
+        if ($MissingIncludes.Count -eq 0) {
+            Write-Host "✅ All required include paths found in project file" -ForegroundColor Green
+        } else {
+            Write-Host "⚠️  Warning: Missing include paths in project file:" -ForegroundColor Yellow
+            foreach ($missing in $MissingIncludes) {
+                Write-Host "    - $missing" -ForegroundColor Yellow
+            }
+        }
+        
+        # Check for SDL2 include paths
+        if ($ProjectContent -match "SDL2" -or $ProjectContent -match "sdl2") {
+            Write-Host "✅ SDL2 include paths found in project file" -ForegroundColor Green
+        } else {
+            Write-Host "⚠️  Warning: SDL2 include paths not found in project file" -ForegroundColor Yellow
+        }
+    } else {
+        Write-Host "❌ Project file not found: $ProjectFile" -ForegroundColor Red
     }
     
     # Open solution in Visual Studio if available
     if (Get-Command "devenv" -ErrorAction SilentlyContinue) {
         Write-Host "Opening solution in Visual Studio..." -ForegroundColor Yellow
-        & devenv $ExistingSolutionFile
+        & devenv $SourceSolutionFile
     } elseif (Get-Command "code" -ErrorAction SilentlyContinue) {
         Write-Host "Opening solution in VS Code..." -ForegroundColor Yellow
-        & code $ExistingSolutionFile
+        & code $SourceSolutionFile
     } else {
-        Write-Host "Visual Studio solution ready: $ExistingSolutionFile" -ForegroundColor Cyan
+        Write-Host "Visual Studio solution ready: $SourceSolutionFile" -ForegroundColor Cyan
     }
 } else {
-    Write-Host "❌ Existing solution file not found: $ExistingSolutionFile" -ForegroundColor Red
+    Write-Host "❌ CMake failed to generate solution file: $GeneratedSolutionFile" -ForegroundColor Red
-    Write-Host "Please ensure YAZE.sln exists in the project root" -ForegroundColor Yellow
+    Write-Host "Please check CMake configuration and dependencies" -ForegroundColor Yellow
     exit 1
 }
 
+# Test build to verify the project can compile
+Write-Host ""
+Write-Host "Testing build to verify project configuration..." -ForegroundColor Yellow
+
+$TestBuildArgs = @(
+    "--build", $BuildDir,
+    "--config", $Configuration,
+    "--target", "yaze"
+)
+
+Write-Host "Running test build: cmake $($TestBuildArgs -join ' ')" -ForegroundColor Gray
+& cmake @TestBuildArgs
+
+if ($LASTEXITCODE -eq 0) {
+    Write-Host "✅ Test build successful! Project is properly configured." -ForegroundColor Green
+} else {
+    Write-Host "❌ Test build failed. There may be configuration issues." -ForegroundColor Red
+    Write-Host "Please check the build output above for specific errors." -ForegroundColor Yellow
+    Write-Host "Common issues:" -ForegroundColor Yellow
+    Write-Host "  - Missing vcpkg dependencies" -ForegroundColor Gray
+    Write-Host "  - Incorrect include paths" -ForegroundColor Gray
+    Write-Host "  - Missing library dependencies" -ForegroundColor Gray
+}
+
 Write-Host ""
 Write-Host "🎉 Visual Studio project configuration complete!" -ForegroundColor Green
 Write-Host ""
@@ -249,3 +359,8 @@ Write-Host "Available architectures:" -ForegroundColor Cyan
 Write-Host "  - x64 (64-bit Intel/AMD)" -ForegroundColor Gray
 Write-Host "  - x86 (32-bit Intel/AMD)" -ForegroundColor Gray
 Write-Host "  - ARM64 (64-bit ARM)" -ForegroundColor Gray
+Write-Host ""
+Write-Host "Troubleshooting:" -ForegroundColor Cyan
+Write-Host "  - If you get missing include errors, ensure vcpkg is properly installed" -ForegroundColor Gray
+Write-Host "  - Run: vcpkg install --triplet $Architecture-windows" -ForegroundColor Gray
+Write-Host "  - Check that all dependencies are available in your environment" -ForegroundColor Gray

scripts/test-vs-generation.ps1

@@ -0,0 +1,55 @@
+# Test script to verify Visual Studio project generation
+# This script tests the generate-vs-projects.ps1 script with different configurations
+
+param(
+    [switch]$Clean = $false,
+    [switch]$Verbose = $false
+)
+
+Write-Host "Testing Visual Studio project generation for YAZE..." -ForegroundColor Green
+
+# Test configurations
+$TestConfigs = @(
+    @{ Config = "Debug"; Arch = "x64" },
+    @{ Config = "Release"; Arch = "x64" }
+)
+
+$ScriptPath = Join-Path $PSScriptRoot "generate-vs-projects.ps1"
+
+foreach ($testConfig in $TestConfigs) {
+    Write-Host ""
+    Write-Host "Testing configuration: $($testConfig.Config) $($testConfig.Arch)" -ForegroundColor Cyan
+    
+    $TestArgs = @(
+        "-Configuration", $testConfig.Config,
+        "-Architecture", $testConfig.Arch
+    )
+    
+    if ($Clean) {
+        $TestArgs += "-Clean"
+    }
+    
+    if ($Verbose) {
+        $TestArgs += "-Verbose"
+    }
+    
+    Write-Host "Running: .\generate-vs-projects.ps1 $($TestArgs -join ' ')" -ForegroundColor Gray
+    
+    try {
+        & $ScriptPath @TestArgs
+        
+        if ($LASTEXITCODE -eq 0) {
+            Write-Host "✅ Configuration $($testConfig.Config) $($testConfig.Arch) passed" -ForegroundColor Green
+        } else {
+            Write-Host "❌ Configuration $($testConfig.Config) $($testConfig.Arch) failed" -ForegroundColor Red
+        }
+    } catch {
+        Write-Host "❌ Configuration $($testConfig.Config) $($testConfig.Arch) failed with exception: $($_.Exception.Message)" -ForegroundColor Red
+    }
+}
+
+Write-Host ""
+Write-Host "Test complete!" -ForegroundColor Green
+Write-Host ""
+Write-Host "If all tests passed, the Visual Studio project generation is working correctly." -ForegroundColor Cyan
+Write-Host "You can now open YAZE.sln in Visual Studio and build the project." -ForegroundColor Cyan