KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

InnocenceEngine

★ 195 Open GitHub ↗

Cross-platform modern game engine.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Innocence Engine
![Screen capture](https://github.com/zhangdoa/InnocenceEngine/blob/master/ScreenCapture.jpg)
[![Trello website](https://img.shields.io/badge/Trello-Roadmap-00bfff.svg)](https://trello.com/b/iEYu58hu/innocence-engine)
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/3c0ea60f7c46491d87236822f6de35a6)](https://www.codacy.com/app/zhangdoa/InnocenceEngine?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=zhangdoa/InnocenceEngine&amp;utm_campaign=Badge_Grade)
[![CodeFactor](https://www.codefactor.io/repository/github/zhangdoa/innocenceengine/badge)](https://www.codefactor.io/repository/github/zhangdoa/innocenceengine)
[![GPL-3.0 licensed](https://img.shields.io/badge/license-GPL--3.0-brightgreen.svg)](https://raw.githubusercontent.com/zhangdoa/InnocenceEngine/master/LICENSE.md)
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fzhangdoa%2FInnocenceEngine.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fzhangdoa%2FInnocenceEngine?ref=badge_shield)
[![Blog](https://img.shields.io/badge/My-Blog-ff884d.svg)](http://zhangdoa.com/)
[![Twitter Follow](https://img.shields.io/twitter/follow/espadrine.svg?style=social&label=Follow)](https://twitter.com/zhangdoa)

[![Appveyor Windows](https://img.shields.io/appveyor/job/build/zhangdoa/innocenceengine/Windows%20build?label=Windows&logo=windows)](https://ci.appveyor.com/project/zhangdoa/innocenceengine)
[![Appveyor macOS](https://img.shields.io/appveyor/job/build/zhangdoa/innocenceengine/macOS%20build?label=macOS&logo=apple)](https://ci.appveyor.com/project/zhangdoa/innocenceengine)
[![Appveyor Linux](https://img.shields.io/appveyor/job/build/zhangdoa/innocenceengine/Linux%20build?label=Linux&logo=ubuntu)](https://ci.appveyor.com/project/zhangdoa/innocenceengine)
> "A poet once said, 'The whole universe is in a glass of wine.'"
> -- Richard Feynman, 1963

## Simplified Architecture
![Architecture](https://github.com/zhangdoa/InnocenceEngine/blob/master/Innocence%20Engine's%20Belly.svg)

## Features

- Strict **E**ntity–**C**omponent–**S**ystem architecture, No OOP overhead/console-like programming experience/allow unlimited feature module extension.

```cpp
// the "E"
auto l_testEntity = g_Engine->getEntityManager()->Spawn(false, ObjectLifespan::Scene, "testEntity/");

// the "C"
auto l_testTransformComponent = g_Engine->getComponentManager()->Spawn<TransformComponent>(l_testEntity, false, ObjectLifespan::Scene);

l_testTransformComponent->m_localTransformVector.m_pos = Vec4(42.0f, 1.0f, PI<float>, 1.0f);

// the engine has several "S" to handle the engine-side businesses, while users have the freedom to implement their own systems
class TestSystem : public ISystem {};
```

- Custom container, string and math classes, minimum STL overhead/No 3rd-party math library dependency.

```cpp
RingBuffer<float> l_testRingBuffer(32);
// All custom containers have a thread-safe version
Array<float, true> l_testThreadSafeArray;
FixedSizeString<64> l_testString;

l_testString = "Hello,World/";

for (size_t i = 0; i < l_testString.size(); i++)
{
	l_testRingBuffer.emplace_back((float)i);
}

l_testThreadSafeArray.reserve();
l_testThreadSafeArray.emplace_back(l_testRingBuffer[42]);

auto l_maxPoint = Vec4(l_testThreadSafeArray[0], l_testRingBuffer[1], l_testRingBuffer[16], 1.0f);
auto l_minPoint = Vec4(42.0f, l_testThreadSafeArray[0], -l_testRingBuffer[16], 1.0f);

auto l_testAABB = InnoMath::generateAABB(l_maxPoint, l_minPoint);
```

- Job-graph based parallel task model, fully utilize modern hardware/lock-free in client logic code.

```cpp
std::function<void()> f_JobA;
f_JobA = []()
{
	g_Engine->getLogSystem()->Log(LogLevel::Warning, "I'm worried that C++ would be quite a mess for me.");
};

auto f_JobB = [=](int val)
{
	g_Engine->getLogSystem()->Log(LogLevel::Success, "There are always some user-friendly programming languages waiting for you, just search for more than ", val, " seconds you'll find them.");
	return true;
};

// Job A will be executed on thread 5 as soon as possible
auto l_testTaskHandleA = g_Engine->getTaskSystem()->Submit("ANonSenseTask", 5, nullptr, f_JobA);

// Job B will be executed with a parameter just after Job A finished
auto l_testTaskHandleB = g_Engine->getTaskSystem()->Submit("NotANonSenseTask", 2, l_testTaskHandleA.m_Task, f_JobB, std::numeric_limits<int>::max());

// Blocking-wait on the caller thread
l_testTaskHandleB.m_Task->Wait();
// Or use with a Producer-Customer model
auto l_testResult = l_testTaskHandleB.m_Future->Get();
```

- Object pool memory model, O(1) allocation/deallocation.

```cpp
struct POD
{
	float m_Float;
	int m_Int;
	void* m_Ptr;
};

auto l_objectPoolInstance = TObjectPool<POD>::Create(65536);
auto l_PODInstance =l_objectPoolInstance->Spawn();
l_PODInstance->m_Float = 42.0f;
l_objectPoolInstance->Destroy(l_PODInstance);
TObjectPool<POD>::Destruct(l_objectPoolInstance);
```

- Logic Client-as-a-plugin style, the only coding rule is using the engine's interfaces to write your gameplay code and write whatever you want.

- The major graphics API support, from OpenGL 4.6 to DirectX 11, from DirectX 12 to Vulkan, and Metal, all supported by one unified interface.

- Client-Server rendering architecture, supports any kind of user-designed rendering pipeline from the first triangle draw call to the last swap chain presentation.

```cpp
auto l_renderingServer = g_Engine->getRenderingServer();

// m_RPDC = l_renderingServer->AddRenderPassDataComponent("LightPass/");
l_renderingServer->CommandListBegin(m_RPDC, 0);
l_renderingServer->BindRenderPassDataComponent(m_RPDC);
l_renderingServer->CleanRenderTargets(m_RPDC);
l_renderingServer->BindGPUResource(m_RPDC, ShaderStage::Pixel, m_SDC, 17);
l_renderingServer->DrawIndexedInstanced(m_RPDC, m_quadMesh);
l_renderingServer->CommandListEnd(m_RPDC);

// Execute on separate threads
l_renderingServer->ExecuteCommandList(m_RPDC);
l_renderingServer->WaitForFrame(m_RPDC);
```

- Physically-based lighting, photometry lighting interface with support of real life light measurements like color temperature, luminous flux and so on.

- Default rendering client support features like:
  - Tiled-deferred rendering pipeline
  - Retro Blinn-Phong/Classic Cook-Torrance BRDF (Disney diffuse + Multi-scattering GGX specular) for opaque material
  - OIT rendering (w.r.t. transparency and thickness)
  - SSAO
  - CSM with VSM/PCF filters
  - Procedural sky
  - Large scale terrain rendering with cascaded tessellation
  - Motion Blur
  - TAA
  - ACES tone mapping

- Real-time GI, baked PRT for the complex large scale scene or bake-free SVOGI for the limited small scale scene, fully dynamic and lightmap-free.

- Unified asset management, using popular JSON format for all text data and support easy-to-use binary data I/O.

- Physics simulation, NVIDIA's PhysX integrated.

- GUI Editor, Qt-based, easy to extend, easy to modify.

And so on...

## How to build?
All scripts are in /Script folder

### Windows

Tested OS version: Windows 11 version 22H2

##### Prerequisites

- MSVC 17.53+ (engine-only)
- CMake 3.26+
- Qt Creator 10.0.0+
- MSVC 16.11.25+ (editor-only)

#### Build Engine

Run following scripts will build Debug and Release configurations in parallel:

```powershell
SetupWin.ps1
BuildAssimpWin.ps1
BuildPhysXWin.ps1
BuildGLADWin.ps1
BuildEngineWin.ps1
PostBuildWin.ps1
```

#### Build Editor

1. Open `Source\Editor\InnoEditor\InnoEditor.pro` with Qt Creator
2. Change "Projects - Build Settings - General - Build directory" to `..\..\..\Bin` for Debug, Profile and Release build configurations
3. Change "Projects - Run Settings - Run - Working directory" to `..\..\..\Bin`
4. Build the project

### Linux

Tested OS version: Ubuntu 18.04 LTS

##### Prerequisites

- GCC 8.0 or Clang 7.0 or higher
- CMake 3.10 or higher
- OpenGL library(lGL)

#### Build Engine

Run following scripts:

### macOS

Tested OS version : macOS 10.13.6, 10.15.4

##### Prerequisites

- CMake 3.10 or higher
- Apple Clang 10.0 or LLVM Clang 8.0 or higher

#### Build Engine

Run following scripts:

## How to use?

1. Implement `ILogicClient` and  `IRenderingClient` classes and put the implementation source file inside `Source/Client/LogicClient` and `Source/Client/RenderingClient`
2. Change the CMake variable `INNO_LOGIC_CLIENT` and  `INNO_RENDERING_CLIENT` in `Source\CMakeLists.txt` to your client modules class name
3. Build engine and launch through `Bin/${BuildConfig}/InnoEditor.exe` or `Bin/${BuildConfig}/InnoMain.exe` on Windows, or corresponding executable file on Linux and macOS

## How to debug

### Windows

1. Open the workspace folder in VSCode.
2. Set debug launch arguments in `./vscode/launch.json`.
3. Start debug with "Launch" button (default F5)

### Linux

1. Use Atom to load the working copy folder
2. Install gcc-compiler package
3. Select build/makefile and hit "Compile and Debug" button (default F6)
4. (Optional) Change launch arguments in Source/Engine/Platform/LinuxMain/CMakeLists.txt

### macOS

1. Open Build/InnocenceEngine.xcodeproj
2. Select "Product" - "Run" (⌘ + R)

## How to bake scene?

### Windows

Run following script:

``` powershell
BakeScene.ps1 -sceneName [scene file name without extension]
```

## Available launch arguments

```
-mode [value]
```
| Value |Notes |
| --- | --- |
| 0 | engine will handle the window creation and event management, for "slave-client" model like the normal game client |
| 1 | engine requires client providing an external window handle, for "host-client" model like the external editor |

```
-renderer [value]
```
| Value | --- | Notes |
| --- | --- | --- |
| 0 | OpenGL | Not available on macOS, currently supported version 4.6 (Deprecated) |
| 1 | DirectX 11 |  Only available on Windows, currently supported version 11.4 (Deprecated) |
| 2 | DirectX 12 | Only available on Windows, currently supported version 12.1 |
| 3 | Vulkan | Not available on macOS, currently supported 1.1.92.1 (WIP) |
| 4 | Metal | Only available on macOS, currently supported version 2 (WIP) |

```
-loglevel [value]
```
| Value |Notes |
| --- | --- |
| 0 | print verbose level and all the other higher level log messages |
| 1 | only print success level and higher level log messages |
| 2 | only print warning level and higher level log messages |
| 3 | only print error level log messages |

## Shader languages compatibilities

You need [DirectXShaderCompiler](https://github.com/microsoft/DirectXShaderCompiler/releases) to generate compiled shader for runtime

- Run `Scripts/HLSL2DXIL.ps1` to generate DXIL file from HLSL shader file for DirextX 12
- Run `Scripts/HLSL2SPIR-V.ps1` to generate SPIR-V file from HLSL shader file for Vulkan
- Run `Scripts/ParseGLSL.bat` then `GLSL2SPIR-V.bat` to generate SPIR-V file from GLSL shader file for OpenGL (Deprecated)

## License
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fzhangdoa%2FInnocenceEngine.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fzhangdoa%2FInnocenceEngine?ref=badge_large)

## References & Dependencies

### Third-party libraries

[assimp](https://github.com/assimp)

[GLAD](https://github.com/Dav1dde/glad)

[dear imgui](https://github.com/ocornut/imgui)

[stb](https://github.com/nothings/stb)

[JSON for Modern C++](https://github.com/nlohmann/json)

[PhysX](https://github.com/NVIDIAGameWorks/PhysX)

### Assets

[Free3D]( https://thefree3dmodels.com)

[Musopen](https://musopen.org)

[Free PBR Materials](https://freepbr.com/)

[HDR Labs](http://www.hdrlabs.com/)

## Inspirations

### Books

[C++ Primer (4th Edition)](https://www.amazon.com/Primer-4th-Stanley-B-Lippman/dp/0201721481)

[A Tour of C++](https://www.amazon.com/Tour-C-Depth/dp/0321958314)

[Effective C++: 55 Specific Ways to Improve Your Programs and Designs (3rd Edition)](https://www.amazon.com/Effective-Specific-Improve-Programs-Designs/dp/0321334876)

[Inside the C++ Object Model (1st Edition)](https://www.amazon.com/Inside-Object-Model-Stanley-Lippman/dp/0201834545)

[Effective Modern C++: 42 Specific Ways to Improve Your Use of C++11 and C++14](https://www.amazon.com/Effective-Modern-Specific-Ways-Improve/dp/1491903996)

[API Design for C++ (1st Edition)](https://www.amazon.com/API-Design-C-Martin-Reddy/dp/0123850037)

[Advanced C and C++ Compiling (1st Edition)](https://www.amazon.com/Advanced-C-Compiling-Milan-Stevanovic/dp/1430266678)

[Data Structures and Algorithms in C++ (4th Edition)](https://www.amazon.com/Data-Structures-Algorithms-Adam-Drozdek-ebook/dp/B00B6F0F5S)

[Game Engine Architecture (1st Edition)](https://www.amazon.com/Game-Engine-Architecture-Jason-Gregory/dp/1568814135)

[Game Programming Patterns](https://www.amazon.com/Game-Programming-Patterns-Robert-Nystrom/dp/0990582906)

[Game Coding Complete (4th Edition)](https://www.amazon.com/Game-Coding-Complete-Fourth-McShaffry/dp/1133776574)

[Real-Time Rendering (4th Edition)](https://www.amazon.com/Real-Time-Rendering-Fourth-Tomas-Akenine-Mo-ebook/dp/B07FSKB982)

[Physically Based Rendering : From Theory to Implementation(2nd Edition)](https://www.amazon.com/Physically-Based-Rendering-Second-Implementation/dp/0123750792)

[Computer Graphics with Open GL (4th Edition)](https://www.amazon.com/Computer-Graphics-Open-GL-4th/dp/0136053580)

[OpenGL Programming Guide: The Official Guide to Learning OpenGL, Version 4.5 with SPIR-V (9th Edition)](https://www.amazon.com/OpenGL-Programming-Guide-Official-Learning/dp/0134495497)

[Calculus (6th Edition)](https://www.amazon.com/CALCULUS-Sixth-James-Stewart/dp/B00722RNC2)

[Linear Algebra and Its Applications (3rd Edition)](https://www.amazon.com/Linear-Algebra-Its-Applications-3rd/dp/0201709708)

And more...

### Online tutorials & resources

[cppreference.com](https://en.cppreference.com)

[Standard C++](https://isocpp.org)

[Modernes C++](http://modernescpp.com/index.php)

[Mathematics - Martin Baker](http://www.euclideanspace.com/maths)

[Wolfram MathWorld: The Web's Most Extensive Mathematics Resource](http://mathworld.wolfram.com)

[GameDev.net](https://www.gamedev.net/)

[Gamasutra](http://www.gamasutra.com)

[Scratchapixel](https://www.scratchapixel.com)

[Advances in Real-Time Rendering in 3D Graphics and Games](http://advances.realtimerendering.com)

[OpenGL Wiki](https://www.khronos.org/opengl/wiki)

[Learn OpenGL](https://learnopengl.com)

[OpenGL Step by Step](http://ogldev.atspace.co.uk)

[DirectX 11 official documents](https://docs.microsoft.com/en-us/windows/win32/direct3d11/atoc-dx-graphics-direct3d-11)

[DirectX 12 official documents](https://docs.microsoft.com/en-us/windows/win32/direct3d12/direct3d-12-graphics)

[RasterTek - DirectX 10, DirectX 11, and DirectX 12 tutorials](http://www.rastertek.com/)

[Vulkan official documents](https://www.khronos.org/registry/vulkan/)

[Vulkan Tutorial](https://vulkan-tutorial.com/)

[Metal official documents](https://developer.apple.com/metal/)

[Sébastien Lagarde's blog](https://seblagarde.wordpress.com)

[Stephen Hill's blog](http://blog.selfshadow.com)

[thebennybox's YouTube channel](https://www.youtube.com/user/thebennybox)

[Randy Gaul's Game Programming Blog](http://www.randygaul.net)

And more...

InnocenceEngine

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README