Imgn Game Engine Documentation

Overview

Imagine (Imgn) is a 3D game engine built in C++ with a focus on simplicity and performance. The engine is heavily inspired by the Hazel Engine and provides a solid foundation for creating 3D applications and games.

Table of Contents

1. Getting Started
2. Engine Architecture
3. Core Systems
4. Rendering System
5. Window Management
6. Building and Setup
7. API Reference
8. Examples

Getting Started

Prerequisites

• CMake 3.10 or higher
• C++17 compatible compiler
• OpenGL support
• GLFW library
• Assimp library
• spdlog library

Quick Start

1. Clone the repository
2. Build the engine using CMake
3. Create your application by inheriting from Imgn::Application

#include "Imgn.h"

class MyGame : public Imgn::Application
{
public:
    MyGame() = default;
    ~MyGame() = default;
};

std::shared_ptr<Imgn::Application> Imgn::CreateApplication()
{
    return std::make_shared<MyGame>();
}

Engine Architecture

Core Design

The Imgn engine follows a layered architecture:

graph TD
    A[Application Layer] --> B[Engine Core]
    B --> C[Renderer]
    C --> D[Platform Layer]

    A1[User Game Code] -.-> A
    B1[Logging, Events, Input] -.-> B
    C1[Graphics & Rendering] -.-> C
    D1[OS Abstraction] -.-> D

    style A fill:#1565c0,stroke:#90caf9,color:#ffffff
    style B fill:#6a1b9a,stroke:#ce93d8,color:#ffffff
    style C fill:#2e7d32,stroke:#a5d6a7,color:#ffffff
    style D fill:#ef6c00,stroke:#ffcc80,color:#ffffff

Loading

Key Components

• Application Layer: Entry point and main game loop
• Core Systems: Logging, events, input, file handling
• Renderer: Graphics pipeline, shaders, models, textures
• Window System: Cross-platform window management
• Platform Detection: OS-specific code handling

Core Systems

Logging System

The engine uses spdlog for comprehensive logging capabilities.

// Core engine logging
Imgn_LOG_CORE(Imgn_INFO, "Engine initialized successfully");

// Client application logging  
Imgn_LOG_CLIENT(Imgn_WARN, "Warning message: {}", warningText);

Log Levels:

• Imgn_TRACE: Detailed trace information
• Imgn_DEBUG: Debug information
• Imgn_INFO: General information
• Imgn_WARN: Warning messages
• Imgn_ERR: Error messages
• Imgn_CTCL: Critical errors

Debug and Assertions

// Debug break (Windows only currently)
Imgn_DEBUGBREAK();

// Assertions with custom messages
Imgn_ASSERT(condition, "Error message with parameter: {}", value);

// Simple assertions
Imgn_ASSERT_NO_MSG(condition);

Input System

The engine provides a comprehensive input system for keyboard and mouse:

// Keyboard input
enum class Key {
    Space = 32,
    A = 65, B = 66, C = 67,
    // ... full keyboard mapping
    F1 = 290, F2 = 291,
    // ... function keys
};

// Mouse input
enum class Mouse {
    ButtonLeft = 0,
    ButtonRight = 1,
    ButtonMiddle = 2,
    // ... additional mouse buttons
};

Rendering System

Core Renderer

The renderer supports OpenGL as the primary graphics API:

// Initialize renderer
Imgn::Renderer::Init(); // Sets context to OpenGL

Shader System

// Create and use shaders
Shader shader("vertex_path.glsl", "fragment_path.glsl");
shader.use();

// Set uniforms
shader.setBool("enableLighting", true);
shader.setInt("texture1", 0);
shader.setFloat("time", deltaTime);
shader.setVec3("lightPos", lightPosition);
shader.setMat4("model", modelMatrix);

Model Loading

The engine supports 3D model loading using Assimp:

// Load a 3D model
Model myModel("path/to/model.obj");

// Render the model
myModel.draw(shader);

Texture System

// Load and bind textures
Texture texture;
unsigned int textureID = texture.load("path/to/texture.png", "directory", false);

Primitive Rendering

// Create and render primitives
std::vector<float> vertices = {/* vertex data */};
std::vector<unsigned int> indices = {/* index data */};

Primitive primitive(vertices, indices, GL_TRIANGLES);
primitive.render();

Skybox Support

// Create skybox
std::vector<std::string> faces = {
    "right.jpg", "left.jpg", "top.jpg",
    "bottom.jpg", "front.jpg", "back.jpg"
};

Skybox skybox(faces);
skybox.bind();
// ... render skybox
skybox.unbind();

Camera System

// Initialize camera
Camera camera;
camera.initialize(window);

// Update camera each frame
camera.update(deltaTime);

// Handle mouse look
camera.look(mouseX, mouseY);

// Use camera matrices
shader.setMat4("view", camera.view);
shader.setMat4("projection", camera.projection);

Camera Controls:

• WASD: Movement
• E/Q: Up/Down movement
• Mouse: Look around

Window Management

Window Creation

// Create window with default options
auto window = Imgn::Window::Create();

// Create window with custom options
Imgn::WindowOptions options(1920, 1080, "My Game");
auto window = Imgn::Window::Create(options);

Window Interface

// Get window properties
uint32_t width = window->GetWidth();
uint32_t height = window->GetHeight();

// Enable/disable V-Sync
window->SetVsync(true);
bool vsyncEnabled = window->IsVsync();

Window Options

struct WindowOptions {
    uint32_t Width = 1920;
    uint32_t Height = 1080;
    std::string Title = "Imgn Application";
};

Building and Setup

CMake Configuration

The engine uses CMake for cross-platform building:

# Engine build (Imgn/CMakeLists.txt)
cmake_minimum_required(VERSION 3.10)
project(Imgn)
set(CMAKE_CXX_STANDARD 17)

# Create shared library
add_library(Imgn SHARED ${SRC})

# Link required libraries
target_link_libraries(Imgn PRIVATE 
    opengl32 
    glfw3 
    assimp-vc143-mtd 
    spdlogd
)

Client Application Setup

# Application build (Sandbox/CMakeLists.txt)
cmake_minimum_required(VERSION 3.10)
project(Sandbox)

# Link against Imgn engine
target_link_libraries(Sandbox PRIVATE Imgn.lib)
target_compile_definitions(Sandbox PRIVATE Imgn_DYNAMIC_LINK)

Required Definitions

// For DLL usage
#define Imgn_DYNAMIC_LINK

// Platform detection (automatic)
#define Imgn_PLATFORM_WINDOWS  // On Windows

API Reference

Application Class

class Application {
public:
    Application();
    virtual ~Application();
    
    void Init() const;    // Initialize engine systems
    void Run() const;     // Start main loop
};

// Client must implement
std::shared_ptr<Application> CreateApplication();

Entry Point

The engine provides an automatic entry point:

// Automatically defined for Windows
int main(int argc, char** argv) {
    auto app = Imgn::CreateApplication();
    app->Init();
    app->Run();
    return 0;
}

Platform Detection

#ifdef Imgn_PLATFORM_WINDOWS
    // Windows-specific code
    #define Imgn_DEBUGBREAK() __debugbreak()
#else
    #error "Platform doesn't support debugbreak yet!"
#endif

Examples

Basic Application

#include "Imgn.h"

class MyApp : public Imgn::Application {
public:
    MyApp() {
        Imgn_LOG_CLIENT(Imgn_INFO, "Application created");
    }
    
    ~MyApp() {
        Imgn_LOG_CLIENT(Imgn_INFO, "Application destroyed");
    }
};

std::shared_ptr<Imgn::Application> Imgn::CreateApplication() {
    return std::make_shared<MyApp>();
}

Rendering Example

class RenderApp : public Imgn::Application {
private:
    Shader shader;
    Model model;
    Camera camera;
    
public:
    void Initialize() {
        // Load resources
        shader = Shader("vertex.glsl", "fragment.glsl");
        model = Model("assets/model.obj");
        camera.initialize(window);
    }
    
    void Update(float deltaTime) {
        camera.update(deltaTime);
        
        // Render
        shader.use();
        shader.setMat4("view", camera.view);
        shader.setMat4("projection", camera.projection);
        
        model.draw(shader);
    }
};

File Structure

Imgn/
├── src/
│   ├── Imgn/
│   │   ├── Core/           # Core engine systems
│   │   ├── Renderer/       # Graphics and rendering
│   │   └── Window/         # Window management
│   └── Imgnpch.h          # Precompiled header
├── vendor/
│   ├── include/           # Third-party headers
│   └── lib/              # Third-party libraries
└── CMakeLists.txt        # Build configuration

Sandbox/                  # Example application
├── src/
│   └── Sandbox.cpp       # Application implementation
└── CMakeLists.txt        # Application build config

Contributing

The Imgn engine is open for contributions. When adding new features:

1. Follow the existing code style
2. Add appropriate logging
3. Update documentation
4. Test on target platforms

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

Acknowledgments

• Inspired by the Hazel Engine
• Uses GLFW for window management
• Uses Assimp for 3D model loading
• Uses spdlog for logging
• Uses stb_image for image loading