Dependencies

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

A C++23 compiler with C++ module support:
- Windows: MSVC 19+, or LLVM+MinGW 21+
- Linux: LLVM 21+
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.

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):

Jolt Physics v5.5.0 (when PHYSIC_ENGINE_JOLT is ON)
FreeType VER-2-14-3
HarfBuzz 14.1.0
xxHash v0.8.3
LuaSocket v3.1.0 (when LUA_BINDINGS is ON)

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 it calls it from main(). This keeps your code fully platform-agnostic.

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