Troubleshooting

🚨 Symptoms

• build.bat fails immediately
• Command prompt shows "g++ is not recognized"
• Cannot compile any C++ code

🔍 Causes

• MinGW-w64 is not installed
• Compiler is not in Windows PATH
• Wrong compiler version or architecture
• PATH not updated after installation

✅ Solutions

g++ --version
mingw32-make --version

🚨 Symptoms

• build.bat shows "Build Failed" message
• Compiler errors about missing files
• Linker errors about undefined references
• No executable created in build/ folder

🔍 Common Causes

• Missing Raylib libraries in lib/ folder
• Syntax errors in your code
• Missing header files
• Incorrect project structure
• Asset packing errors

✅ Solutions

SSOEngine/
├── 01_Core/
│   ├── build.bat
│   ├── main.cpp
│   ├── game.h
│   ├── tools/
│   ├── scripts/
│   └── assets/
├── include/
└── lib/

🚨 Symptoms

• Double-clicking .exe does nothing
• Window flashes and closes immediately
• Command window shows error messages
• "Failed to initialize graphics" error

🔍 Causes

• Missing OpenGL support
• Outdated graphics drivers
• Missing DLL files
• Antivirus blocking the executable
• Insufficient permissions

✅ Solutions

🚨 Symptoms

• Window opens but shows only black
• No game objects visible
• UI elements not showing
• Camera not working

🔍 Common Causes

• Missing BeginDrawing/EndDrawing calls
• Camera not properly set up
• Objects outside camera view
• ClearBackground covering everything
• Rendering order issues

✅ Solutions

while (!WindowShouldClose()) {
    // Update game logic
    Update(deltaTime);
    
    // Rendering
    BeginDrawing();
    ClearBackground(RAYWHITE);
    
    // Draw game objects
    DrawPlayer();
    DrawEnemies();
    
    EndDrawing();
}

🚨 Symptoms

• Textures show as white squares
• Sounds don't play
• Fonts don't load
• Build fails during asset packing

🔍 Causes

• Assets not in assets/ folder
• Incorrect file names (case-sensitive)
• Unsupported file formats
• File path issues
• Asset packing failed

✅ Solutions

SSOEngine/01_Core/assets/
├── images/
│   ├── player.png
│   └── enemy.png
├── sounds/
│   ├── shoot.wav
│   └── explosion.wav
└── fonts/
    └── main.ttf

🚨 Symptoms

• Compiler errors about asset variables
• assets_data.h not found
• Asset variables undefined

✅ Solutions

#include "assets_data.h"

// Correct usage
Texture2D playerTexture = LoadTextureFromMemory(
    asset_player_png,           // Variable name (file name with underscores)
    asset_player_png_size        // Size variable
);

// Incorrect usage
Texture2D bad = LoadTextureFromMemory(
    "player.png",               // String instead of variable
    12345                       // Wrong size
);

🚨 Symptoms

• Game feels sluggish or slow
• Frame rate drops below 60 FPS
• Stuttering during gameplay
• Input lag or delayed response

🔍 Common Causes

• Too many objects being rendered
• Inefficient collision detection
• Loading assets during gameplay
• Memory leaks
• Complex calculations every frame

✅ Solutions

// Bad: Drawing everything every frame
for (auto& enemy : allEnemies) {
    if (enemy.active) {
        DrawEnemy(enemy);  // Even if off-screen
    }
}

// Good: Only draw visible objects
for (auto& enemy : allEnemies) {
    if (enemy.active && IsOnScreen(enemy.position)) {
        DrawEnemy(enemy);
    }
}

// Bad: Check everything against everything
for (auto& bullet : bullets) {
    for (auto& enemy : enemies) {
        CheckCollision(bullet, enemy);  // O(n²)
    }
}

// Good: Spatial partitioning or early outs
for (auto& bullet : bullets) {
    if (!bullet.active) continue;
    
    for (auto& enemy : enemies) {
        if (!enemy.active) continue;
        if (Distance(bullet.pos, enemy.pos) > 100) continue; // Early out
        CheckCollision(bullet, enemy);
    }
}

void DrawFPS() {
    DrawFPS(10, 10);  // Raylib built-in FPS counter
    
    // Or custom FPS display
    static double lastTime = 0;
    static int frameCount = 0;
    static int fps = 0;
    
    double currentTime = GetTime();
    frameCount++;
    
    if (currentTime - lastTime >= 1.0) {
        fps = frameCount;
        frameCount = 0;
        lastTime = currentTime;
    }
    
    DrawText(TextFormat("FPS: %d", fps), 10, 40, 20, GREEN);
}

🚨 Symptoms

• Memory usage increases over time
• Game eventually crashes
• System becomes slow
• Out of memory errors

🔍 Common Causes

• Not unloading textures/sounds
• Creating objects without deleting
• Inefficient object pooling
• Large asset files

✅ Solutions

// Load resources once at startup
Texture2D playerTexture;
Sound shootSound;

void LoadAssets() {
    playerTexture = LoadTexture("assets/player.png");
    shootSound = LoadSound("assets/shoot.wav");
}

// Unload when done
void UnloadAssets() {
    UnloadTexture(playerTexture);
    UnloadSound(shootSound);
}

// For dynamic objects, use object pooling
class BulletPool {
private:
    std::vector pool;
    int nextAvailable = 0;
    
public:
    Bullet& GetBullet() {
        Bullet& bullet = pool[nextAvailable];
        nextAvailable = (nextAvailable + 1) % pool.size();
        return bullet;
    }
};