# dpjudas/surrealengine architecture

> Architecture diagram of the GitHub repository dpjudas/surrealengine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dpjudas/surrealengine
- Repository: https://github.com/dpjudas/surrealengine

## Overview

##### Project type and purpose
- Surreal Engine is a monolithic, cross-platform C++ game engine meant to reimplement Unreal Engine 1. It can load UE1 game packages, run the Unrealscript VM, render maps via Vulkan, play audio, and host editor/debugger tools.

##### File structure
- Top‐level build: CMakeLists.txt, .github/workflows, LICENSE, README.
- Engine code under “SurrealEngine/”: modular subsystems—Audio, Collision (physics), Commandlet (batch tools), DebuggerApp, Editor, GC (garbage collection), Math, Native (C++ side of Unreal objects), Package (I/O), Render (scene traversal), RenderDevice/Vulkan (low-level GPU), UObject (game object model), Utils (helpers), VM (Unrealscript interpreter).
- UI layer under “SurrealEngine/UI/”: Launcher, Editor windows, error dialogs built on ZWidget (third-party).
- Executables produced: SurrealEngine (game runtime), SurrealEditor, SurrealDebugger.
- Third-party libraries: ZVulkan (Vulkan loader + GLSLang), ZWidget (UI toolkit), OpenAL-Soft (audio backend), SDL2/Wayland/DBus (windowing), mux of codecs (dr_flac, stb_vorbis, miniz, etc).

##### README for additional insights
- Confirms use of Vulkan, SDL2 (windowing), optional Wayland or native backends.
- Lists command-line interface for selecting maps, engine version, game folder.
- Describes three executables and runtime dependencies.

##### Elements
- Green for engine subsystems
- Blue for UI/tools
- Gray for third-party dependencies
- Orange for core foundation (PackageManager, VM, GC)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Third-Party Layer
    subgraph "Third-Party Libraries"
        ZVulkan["ZVulkan"]:::third
        ZWidget["ZWidget"]:::third
        OpenAL["OpenAL-Soft"]:::third
        Codecs["Codec Libraries"]:::third
        SDL["SDL2/Wayland/DBus"]:::third
    end

    %% Engine Core Foundation (Orange)
    subgraph "Engine Core"
        direction TB
        EngineCore["Game Loop & Core Init"]:::core
        PackageManager["PackageManager"]:::core
        GC["Garbage Collector"]:::core
        VM["Unrealscript VM"]:::core
    end

    %% Engine Subsystems (Green)
    subgraph "Engine Subsystems"
        direction TB
        Rendering["RenderSubsystem"]:::engine
        VulkanDevice["Vulkan RenderDevice"]:::engine
        Audio["AudioDevice"]:::engine
        Physics["Physics/Collision"]:::engine
        UObjectFW["UObject Framework"]:::engine
        MathUtils["Math & Utils"]:::engine
        Native["Native Bridge"]:::engine
    end

    %% Tools & UI (Blue)
    subgraph "Tools & UI"
        direction TB
        LauncherUI["Launcher UI"]:::ui
        EditorUI["Editor UI"]:::ui
        DebuggerUI["Debugger UI"]:::ui
        Commandlets["Commandlets"]:::ui
    end

    %% Executables
    subgraph "Executables"
        direction TB
        SurrealRuntime["SurrealEngine"]:::ui
        SurrealEditorExe["SurrealEditor"]:::ui
        SurrealDebuggerExe["SurrealDebugger"]:::ui
    end

    %% Data and Control Flow
    CLI["CLI Args"]:::core
    CLI -->|select mode| LauncherUI
    CLI -->|direct launch| SurrealRuntime

    LauncherUI -->|launch| SurrealRuntime
    SurrealRuntime -->|uses| EngineCore
    SurrealEditorExe -->|links to| EngineCore
    SurrealDebuggerExe -->|links to| EngineCore

    EngineCore -->|loads assets| PackageManager
    PackageManager -->|reads pk3/ini| Codecs

    EngineCore -->|init GC| GC
    EngineCore -->|start VM| VM
    EngineCore -->|per-frame| Rendering
    EngineCore -->|per-frame| Audio
    EngineCore -->|per-frame| Physics
    EngineCore -->|per-frame| VM
    EngineCore -->|per-frame| Native

    Rendering -->|draw calls| VulkanDevice
    VulkanDevice -->|Vulkan API| ZVulkan
    Audio -->|audio output| OpenAL
    LauncherUI -->|UI render| ZWidget
    EditorUI -->|UI render| ZWidget
    DebuggerUI -->|UI render| ZWidget
    LauncherUI -->|windowing| SDL
    EditorUI -->|windowing| SDL
    DebuggerUI -->|windowing| SDL
    Commandlets -->|batch ops| PackageManager
    Commandlets -->|script tasks| VM

    UObjectFW -->|object model| VM
    Native -->|native calls| VM
    MathUtils -->|helpers| Physics
    MathUtils -->|helpers| Rendering

    %% Click Events
    click EngineCore "https://github.com/dpjudas/surrealengine/blob/master/SurrealEngine/Engine.cpp"
    click PackageManager "https://github.com/dpjudas/surrealengine/blob/master/SurrealEngine/Package/PackageManager.cpp"
    click GC "https://github.com/dpjudas/surrealengine/blob/master/SurrealEngine/GC/GC.cpp"
    click Rendering "https://github.com/dpjudas/surrealengine/blob/master/SurrealEngine/Render/RenderSubsystem.cpp"
    click VulkanDevice "https://github.com/dpjudas/surrealengine/blob/master/SurrealEngine/RenderDevice/Vulkan/VulkanRenderDevice.cpp"
    click Audio "https://github.com/dpjudas/surrealengine/blob/master/SurrealEngine/Audio/AudioDevice.cpp"
    click Physics "https://github.com/dpjudas/surrealengine/blob/master/SurrealEngine/Collision/CollisionHash.cpp"
    click VM "https://github.com/dpjudas/surrealengine/blob/master/SurrealEngine/VM/Bytecode.cpp"
    click UObjectFW "https://github.com/dpjudas/surrealengine/blob/master/SurrealEngine/UObject/UObject.cpp"
    click MathUtils "https://github.com/dpjudas/surrealengine/blob/master/SurrealEngine/Math/mat.cpp"
    click Native "https://github.com/dpjudas/surrealengine/blob/master/SurrealEngine/Native/NObject.cpp"
    click Commandlets "https://github.com/dpjudas/surrealengine/blob/master/SurrealEngine/Commandlet/Commandlet.cpp"
    click EditorUI "https://github.com/dpjudas/surrealengine/blob/master/SurrealEngine/UI/Editor/EditorMainWindow.cpp"
    click LauncherUI "https://github.com/dpjudas/surrealengine/blob/master/SurrealEngine/UI/Launcher/LauncherWindow.cpp"
    click DebuggerUI "https://github.com/dpjudas/surrealengine/blob/master/SurrealEngine/DebuggerApp.cpp"

    %% Styles
    classDef engine fill:#a3dca6,stroke:#2f8f2f,color:#000
    classDef ui fill:#a6c8ff,stroke:#2f53b3,color:#000
    classDef third fill:#d3d3d3,stroke:#888888,color:#000
    classDef core fill:#fbd38d,stroke:#e09d1b,color:#000
    class EngineCore,PackageManager,GC,VM core
    class Rendering,VulkanDevice,Audio,Physics,UObjectFW,MathUtils,Native engine
    class LauncherUI,EditorUI,DebuggerUI,Commandlets,SurrealRuntime,SurrealEditorExe,SurrealDebuggerExe,CLI ui
    class ZVulkan,ZWidget,OpenAL,Codecs,SDL third
```
