Lysa  0.0
Lysa 3D Engine
Integration

Dependencies

Lysa supports Microsoft Windows, Linux (X11 & Wayland) and macOS (KosmicKrisp) and requires the following dependencies:

Clone the RHI repository

Install the Vulkan SDK

  • Vulkan SDK 1.4.x+ (Linux : run setup-env.sh from the Vulkan installation directory to set the VULKAN_SDK environment variable)
  • Slang shader compiler (slangc must be on PATH or use the one in the Vulkan SDK bin directory)

Install the build tools

For Microsoft Windows :

For Linux :

  • LLVM 22+ (typical packages to install : cmake ninja-build clang-22 clangd-22 libc++-22-dev libc++abi-22-dev clang-tools-22 lld-22 libpng-tools vulkan-validationlayers)

For macos (Apple Silicon only) :

  • LLVM 22+ from HomeBrew with CMake and Ninja

Integration

Lysa Engine is intended to be used as a Git submodule or a CMake subdirectory of your project.

For a stater project see the officiel Lysa templace project

1. Configure .env.cmake

Create a .env.cmake file at the root of your project to point to the Vireo RHI source. Optionally configure the NVIDIA PhysX paths if you use that backend:

# .env.cmake
set(VIREO_RHI_PROJECT_DIR "path/to/vireo_rhi")
# Only needed if PHYSIC_ENGINE_PHYSX is ON:
# set(PHYSX_INCLUDE "path/to/physx/include")
# set(PHYSX_LIBRARIES "path/to/physx/libs")

The engine's CMakeLists.txt will look for .env.cmake at CMAKE_CURRENT_SOURCE_DIR automatically if VIREO_RHI_PROJECT_DIR is not already defined.

2. Add the engine to your CMakeLists.txt

Set the desired feature flags before calling add_subdirectory, then link against lysa_engine:

# Tell the engine it is being embedded (suppresses standalone defaults)
set(LYSA_ENGINE_PROJECT_DIR ${CMAKE_CURRENT_SOURCE_DIR})
# Feature flags : enable what you need
set(DIRECTX_BACKEND ON)
set(FORWARD_RENDERER ON)
set(DEFERRED_RENDERER ON)
set(PHYSIC_ENGINE_JOLT ON)
set(PHYSIC_ENGINE_PHYSX OFF)
set(LUA_BINDINGS OFF)
add_subdirectory(path/to/lysa_engine)
add_executable(your_game
src/Main.cpp
# your other source files
)
target_link_libraries(your_game PUBLIC lysa_engine)
Note
PHYSIC_ENGINE_JOLT and PHYSIC_ENGINE_PHYSX are mutually exclusive.

Embedded Lua debugger

With LUA_BINDINGS=ON, LUA_DEBUGGER (default ON) embeds MobDebug 0.805 in Debug builds.

3. CMake options reference

Option Standalone default Description
DIRECTX_BACKEND ON DirectX 12 backend (Windows only)
FORWARD_RENDERER ON Include the forward rendering path
DEFERRED_RENDERER ON Include the deferred rendering path
PHYSIC_ENGINE_JOLT ON Jolt Physics backend (fetched automatically via FetchContent)
PHYSIC_ENGINE_PHYSX OFF NVIDIA PhysX backend (requires PHYSX_INCLUDE and PHYSX_LIBRARIES in .env.cmake)
LUA_BINDINGS OFF Lua scripting with LuaBridge bindings
LYSA_CONSOLE OFF Console-only build (no window or input system)
USE_SDL3 ON (Linux) SDL3 windowing (Linux only)

Automatically fetched dependencies (no manual installation required):

4. Application entry point

The engine provides the platform-specific main() / WinMain() for you. Your code must define lysaMain() instead:

import lysa;
int lysaMain() {
// Select the best backend for the platform
if constexpr (vireo::getPlatform() == vireo::Platform::WINDOWS) {
config.backendConfiguration.backend = vireo::Backend::DIRECTX;
}
lysa::Lysa engine(config);
// create window, scene, register events
engine.run();
return 0;
}

On Windows the engine calls lysaMain() from WinMain(). On Linux and macos it calls it from main().

5. Custom shaders

Application shaders are written in Slang and compiled to both DXIL (DirectX 12) and SPIR-V (Vulkan) at build time using the add_shaders() and compile_slang_shaders() CMake helpers provided by cmake/shaders.cmake:

include(path/to/lysa_engine/cmake/shaders.cmake)
set(MY_SHADERS
src/shaders/my_material.frag.slang
src/shaders/my_effect.comp.slang
)
add_shaders(my_game_shaders
${CMAKE_CURRENT_SOURCE_DIR}/shaders # output directory (app://shaders)
${CMAKE_CURRENT_SOURCE_DIR}/src/shaders
${MY_SHADERS}
)
add_dependencies(your_game my_game_shaders)

Compiled .dxil and .spv binaries are written to the output directory. The engine loads them at runtime by name (without extension) through the VFS app://shaders/ path.

Shader naming conventions used by the build system:

File suffix Profile Entry point
.vert.slang vs_6_6 vertexMain
.frag.slang ps_6_6 fragmentMain
.comp.slang cs_6_6 main

6. C++ module structure

All public interfaces use C++23 module files (.ixx) paired with .cpp implementations. Import the top-level lysa module to get the full engine API:

import lysa; // full engine API
import lysa.nodes; // optional: Lysa Nodes scene graph
import lysa.ui; // optional: Lysa UI library

When adding a new subsystem to your own project, follow the same pattern and use the build_target() CMake helper from cmake/compile_options.cmake to register a new library target with the correct compiler settings:

build_target(my_subsystem
"src/MySubsystem.cpp"
"src/MySubsystem.ixx"
)

7. Building

cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build