# turanszkij/wickedengine architecture

> Architecture diagram of the GitHub repository turanszkij/wickedengine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/turanszkij/wickedengine
- Repository: https://github.com/turanszkij/wickedengine

## Overview

#### Purpose and Build Surface
Wicked Engine is a C++17 cross-platform 3D engine, embeddable framework, standalone scene editor, and Lua-scriptable runtime. The root build entry is `CMakeLists.txt`; the Windows solution is `WickedEngine.sln`. The engine is exposed as a static-library-style API through `WickedEngine/WickedEngine.h` and built by `WickedEngine/CMakeLists.txt`.

#### Application Entry Points
The primary shipped application is the editor, with platform launchers at `Editor/main_Windows.cpp`, `Editor/main_SDL2.cpp`, and `Editor/main_MacOS.mm`; its orchestration class is `Editor/Editor.cpp`. Consumer application templates start in `Samples/Template_Windows/main.cpp`, `Samples/Template_Linux/main.cpp`, or Apple/iOS equivalents. All host applications create `wi::Application`, attach a native window, activate a render path, then repeatedly run the engine frame loop.

#### Runtime Orchestration and UI
`WickedEngine/wiApplication.cpp` is the lifecycle boundary: initialization, window/frame execution, active render-path management, and engine subsystem coordination. Render paths separate application presentation from engine rendering: `WickedEngine/wiRenderPath.h`, `WickedEngine/wiRenderPath2D.cpp`, and `WickedEngine/wiRenderPath3D.cpp`. Editor tools operate on that runtime through docking-style component windows, notably `Editor/Editor.cpp`, `Editor/HierarchyWindow.cpp`, and `Editor/ComponentsWindow.cpp`.

#### Scene, ECS, Assets, and Import
The scene layer owns entities, components, serialization, and scene composition: `WickedEngine/wiScene.h`, `WickedEngine/wiScene_Components.cpp`, and `WickedEngine/wiScene_Serializers.cpp`. WISCENE is the native persisted scene format; `Content/models/*.wiscene` are runtime/editor inputs. The editor imports external OBJ, FBX, glTF/GLB, and PLY into scene data via `Editor/ModelImporter.h`, `Editor/ModelImporter_GLTF.cpp`, and `Editor/ModelImporter_FBX.cpp`. Resource loading/caching is bounded through `WickedEngine/wiResourceManager.cpp`.

#### Rendering and GPU Boundary
`WickedEngine/wiRenderer.cpp` converts scene state into GPU work; `WickedEngine/wiGraphicsDevice.h` is the graphics abstraction. Concrete backends are DirectX 12 (`WickedEngine/wiGraphicsDevice_DX12.cpp`), Vulkan (`WickedEngine/wiGraphicsDevice_Vulkan.cpp`), and Metal (`WickedEngine/wiGraphicsDevice_Metal.cpp`), selected by platform/arguments. HLSL shader sources and CPU/GPU shared layouts reside in `WickedEngine/shaders/`—for example `WickedEngine/shaders/ShaderInterop_Renderer.h`, `WickedEngine/shaders/objectPS.hlsl`, and `WickedEngine/shaders/tonemapCS.hlsl`. Shader compilation is encapsulated by `WickedEngine/wiShaderCompiler.cpp` and the offline compiler entry `WickedEngine/offlineshadercompiler.cpp`.

#### Simulation, Effects, and Media
Physics is integrated through the engine-facing boundary `WickedEngine/wiPhysics_Jolt.cpp` and embedded Jolt implementation under `WickedEngine/Jolt/Physics/PhysicsSystem.cpp`; scene components feed bodies/constraints and simulation results return to transforms. GPU-driven effects are first-class renderer inputs, including emitted particles (`WickedEngine/wiEmittedParticle.cpp`), hair (`WickedEngine/wiHairParticle.cpp`), ocean (`WickedEngine/wiOcean.cpp`), terrain, voxel grids, and Gaussian splats. Audio and video services are provided by `WickedEngine/wiAudio.cpp` and `WickedEngine/wiVideo.cpp`; bundled FAudio supports audio on applicable platforms.

#### Scripting, Input, and Platform Services
Lua is embedded in `WickedEngine/LUA/` and surfaced through `WickedEngine/wiLua.cpp`; `*_BindLua.cpp` files expose application, scene, render, input, audio, physics, and resource APIs. Scripts can control the same global/separate scenes and render paths used by C++. Input is abstracted in `WickedEngine/wiInput.cpp`, with SDL and platform-specific providers including `WickedEngine/wiSDLInput.cpp`. External runtime dependencies/infrastructure are primarily native graphics APIs, SDL2 on Linux, Apple Metal frameworks, Vulkan, and DX12 rather than networked services.

Main entry points: [`WickedEngine/wiScene.h`](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiScene.h) (Scene and ECS), [`WickedEngine/wiApplication.cpp`](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiApplication.cpp) (Application lifecycle), [`WickedEngine/wiRenderer.cpp`](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiRenderer.cpp) (Renderer), [`Editor/Editor.cpp`](https://github.com/turanszkij/wickedengine/blob/master/Editor/Editor.cpp) (Scene editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build Surface"]
  node_root_build["Root build<br/>CMake build<br/>[CMakeLists.txt]"]
  node_engine_build["Engine library build<br/>CMake target<br/>[CMakeLists.txt]"]
  node_engine_api["Engine API<br/>C++ API<br/>[WickedEngine.h]"]
end

subgraph group_hosts["Host Applications"]
  node_editor_launchers["Editor launchers<br/>platform entry points<br/>[main_Windows.cpp]"]
  node_editor["Scene editor<br/>editor host<br/>[Editor.cpp]"]
  node_sample_hosts["Consumer templates<br/>sample hosts<br/>[main.cpp]"]
end

subgraph group_runtime["Engine Runtime"]
  node_application["Application lifecycle<br/>runtime orchestrator<br/>[wiApplication.cpp]"]
  node_render_paths["Render paths<br/>presentation layer<br/>[wiRenderPath.h]"]
  node_input["Input service<br/>input abstraction<br/>[wiInput.cpp]"]
  node_lua["Lua scripting<br/>script runtime<br/>[wiLua.cpp]"]
  node_physics["Physics integration<br/>simulation boundary<br/>[wiPhysics_Jolt.cpp]"]
  node_media["Audio and video<br/>media services<br/>[wiAudio.cpp]"]
end

subgraph group_rendering["Rendering"]
  node_renderer["Renderer<br/>GPU work builder<br/>[wiRenderer.cpp]"]
  node_graphics_device["Graphics device<br/>graphics abstraction<br/>[wiGraphicsDevice.h]"]
  node_shaders["Shader sources<br/>HLSL and shared layouts"]
  node_shader_compiler["Shader compiler<br/>shader pipeline"]
  node_effects["GPU effects<br/>renderer inputs"]
end

subgraph group_content["Scene and Content"]
  node_scene["Scene and ECS<br/>scene model<br/>[wiScene.h]"]
  node_scene_serialization["WISCENE serialization<br/>scene persistence"]
  node_model_import["Model import<br/>asset importer<br/>[ModelImporter.h]"]
  node_resources["Resource manager<br/>asset cache"]
end

node_root_build -->|"builds"| node_engine_build
node_engine_build -->|"exports"| node_engine_api
node_editor_launchers -->|"start"| node_editor
node_editor -->|"hosts"| node_application
node_sample_hosts -->|"embed"| node_application
node_application -->|"activates"| node_render_paths
node_application -->|"coordinates"| node_input
node_application -->|"runs per frame"| node_renderer
node_editor -->|"edits"| node_scene
node_editor -->|"uses"| node_model_import
node_model_import -->|"creates scene data"| node_scene
node_scene -->|"persists"| node_scene_serialization
node_scene -->|"references"| node_resources
node_scene -->|"feeds bodies and constraints"| node_physics
node_physics -->|"updates transforms"| node_scene
node_lua -.->|"controls"| node_application
node_lua -.->|"controls"| node_scene
node_render_paths -->|"presents through"| node_renderer
node_scene -->|"provides render state"| node_renderer
node_effects -->|"contribute GPU work"| node_renderer
node_renderer -->|"submits GPU work"| node_graphics_device
node_shader_compiler -->|"compiles"| node_shaders
node_renderer -->|"uses programs and layouts"| node_shaders
node_application -->|"coordinates"| node_media

click node_root_build "https://github.com/turanszkij/wickedengine/blob/master/CMakeLists.txt"
click node_engine_build "https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/CMakeLists.txt"
click node_engine_api "https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/WickedEngine.h"
click node_editor_launchers "https://github.com/turanszkij/wickedengine/blob/master/Editor/main_Windows.cpp"
click node_editor "https://github.com/turanszkij/wickedengine/blob/master/Editor/Editor.cpp"
click node_sample_hosts "https://github.com/turanszkij/wickedengine/blob/master/Samples/Template_Windows/main.cpp"
click node_application "https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiApplication.cpp"
click node_render_paths "https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiRenderPath.h"
click node_input "https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiInput.cpp"
click node_lua "https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiLua.cpp"
click node_scene "https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiScene.h"
click node_scene_serialization "https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiScene_Serializers.cpp"
click node_model_import "https://github.com/turanszkij/wickedengine/blob/master/Editor/ModelImporter.h"
click node_resources "https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiResourceManager.cpp"
click node_physics "https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiPhysics_Jolt.cpp"
click node_renderer "https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiRenderer.cpp"
click node_graphics_device "https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiGraphicsDevice.h"
click node_shader_compiler "https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiShaderCompiler.cpp"
click node_effects "https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiEmittedParticle.cpp"
click node_media "https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiAudio.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_build,node_engine_build,node_engine_api toneBlue
class node_editor_launchers,node_editor,node_sample_hosts toneAmber
class node_application,node_render_paths,node_input,node_lua,node_physics,node_media toneMint
class node_renderer,node_graphics_device,node_shaders,node_shader_compiler,node_effects toneRose
class node_scene,node_scene_serialization,node_model_import,node_resources toneIndigo
```

## Components

### Build Surface

- [Root build](https://github.com/turanszkij/wickedengine/blob/master/CMakeLists.txt): CMake build · Top-level cross-platform build entry. · `CMakeLists.txt`
- [Engine library build](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/CMakeLists.txt): CMake target · `WickedEngine/CMakeLists.txt`
- [Engine API](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/WickedEngine.h): C++ API · Static-library-style public engine surface. · `WickedEngine/WickedEngine.h`

### Host Applications

- [Editor launchers](https://github.com/turanszkij/wickedengine/blob/master/Editor/main_Windows.cpp): platform entry points · `Editor/main_Windows.cpp`
- [Scene editor](https://github.com/turanszkij/wickedengine/blob/master/Editor/Editor.cpp): editor host · Docking-style editor orchestration and tools. · `Editor/Editor.cpp`
- [Consumer templates](https://github.com/turanszkij/wickedengine/blob/master/Samples/Template_Windows/main.cpp): sample hosts · `Samples/Template_Windows/main.cpp`

### Engine Runtime

- [Application lifecycle](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiApplication.cpp): runtime orchestrator · Owns initialization, windows, frame execution, and active render path. · `WickedEngine/wiApplication.cpp`
- [Render paths](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiRenderPath.h): presentation layer · Separates application presentation from 2D/3D rendering. · `WickedEngine/wiRenderPath.h`
- [Input service](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiInput.cpp): input abstraction · `WickedEngine/wiInput.cpp`
- [Lua scripting](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiLua.cpp): script runtime · Bindings expose engine application, scene, rendering, and service APIs. · `WickedEngine/wiLua.cpp`
- [Physics integration](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiPhysics_Jolt.cpp): simulation boundary · `WickedEngine/wiPhysics_Jolt.cpp`
- [Audio and video](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiAudio.cpp): media services · `WickedEngine/wiAudio.cpp`

### Rendering

- [Renderer](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiRenderer.cpp): GPU work builder · Converts scene state and effects into GPU work. · `WickedEngine/wiRenderer.cpp`
- [Graphics device](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiGraphicsDevice.h): graphics abstraction · Selects DX12, Vulkan, or Metal backend by platform and arguments. · `WickedEngine/wiGraphicsDevice.h`
- **Shader sources**: HLSL and shared layouts
- [Shader compiler](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiShaderCompiler.cpp): shader pipeline · Compiles runtime and offline shader variants. · `WickedEngine/wiShaderCompiler.cpp`
- [GPU effects](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiEmittedParticle.cpp): renderer inputs · Particles, hair, ocean, terrain, voxel grids, and Gaussian splats. · `WickedEngine/wiEmittedParticle.cpp`

### Scene and Content

- [Scene and ECS](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiScene.h): scene model · Owns entities, components, composition, and serialization. · `WickedEngine/wiScene.h`
- [WISCENE serialization](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiScene_Serializers.cpp): scene persistence · `WickedEngine/wiScene_Serializers.cpp`
- [Model import](https://github.com/turanszkij/wickedengine/blob/master/Editor/ModelImporter.h): asset importer · Imports OBJ, FBX, glTF/GLB, and PLY into scene data. · `Editor/ModelImporter.h`
- [Resource manager](https://github.com/turanszkij/wickedengine/blob/master/WickedEngine/wiResourceManager.cpp): asset cache · Bounds resource loading and caching. · `WickedEngine/wiResourceManager.cpp`

## Connections

- Root build → Engine library build: builds
- Engine library build → Engine API: exports
- Editor launchers → Scene editor: start
- Scene editor → Application lifecycle: hosts
- Consumer templates → Application lifecycle: embed
- Application lifecycle → Render paths: activates
- Application lifecycle → Input service: coordinates
- Application lifecycle → Renderer: runs per frame
- Scene editor → Scene and ECS: edits
- Scene editor → Model import: uses
- Model import → Scene and ECS: creates scene data
- Scene and ECS → WISCENE serialization: persists
- Scene and ECS → Resource manager: references
- Scene and ECS → Physics integration: feeds bodies and constraints
- Physics integration → Scene and ECS: updates transforms
- Lua scripting → Application lifecycle: controls
- Lua scripting → Scene and ECS: controls
- Render paths → Renderer: presents through
- Scene and ECS → Renderer: provides render state
- GPU effects → Renderer: contribute GPU work
- Renderer → Graphics device: submits GPU work
- Shader compiler → Shader sources: compiles
- Renderer → Shader sources: uses programs and layouts
- Application lifecycle → Audio and video: coordinates
