Lysa  0.0
Lysa 3D Engine
Integration

Dependencies

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

  • A C++23 compiler with C++ module support:
    • Windows: MSVC 19+, or LLVM+MinGW 21+
    • Linux: LLVM 21+ and msdf-atlas-gen (from HomeBrew for example)
    • macos: Xcode and Xcode command line tools, LLVM 22+ and msdf-atlas-gen from HomeBrew,
  • CMake 3.29+ with a build tool such as Ninja
  • Vulkan SDK 1.3+
  • Slang shader compiler (slangc must be on PATH or in the Vulkan SDK bin directory)
  • Vireo RHI (cloned separately)

For Linux, the following additional packages are also required:

  • vulkan-validation-layers
  • libc++
  • Install the latest Vulkan SDK manually and run setup-env.sh from the Vulkan installation directory to set the VULKAN_SDK environment variable.

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.

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.

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
lysa::ContextConfiguration config{};
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