Skip to content

Getting started

Jump to bottom
Romain Milbert edited this page Oct 25, 2025 · 30 revisions

If you are here, it means you're interested in experimenting with RaZ. For that, I thank you!

Getting RaZ

To use RaZ, you will need its necessary libraries & headers. To that end, you can either:

Using RaZ

Setup

To make your application, you can use whatever method works for you. In case you don't have one, I'll demonstrate using CMake:

cmake_minimum_required(VERSION 3.14)

project(YourApplication)

add_executable(${PROJECT_NAME})

target_compile_features(${PROJECT_NAME} PRIVATE cxx_std_20) # Using C++20
set_target_properties(${PROJECT_NAME} PROPERTIES CXX_EXTENSIONS OFF) # Disabling compiler extensions

target_include_directories(${PROJECT_NAME} SYSTEM PUBLIC path/to/RaZ/include)

target_link_directories(${PROJECT_NAME} PUBLIC path/to/RaZ/lib) # Where RaZ.lib/libRaZ.a is located
target_link_libraries(
    ${PROJECT_NAME}

    PUBLIC
        RaZ

        # Other dependencies; you can freely remove those for platforms you don't need

        # If you use rendering features (RenderSystem, Window, ...), add the following

        $<$<PLATFORM_ID:Windows>:opengl32>

        $<$<PLATFORM_ID:Linux>:dl>
        $<$<PLATFORM_ID:Linux>:pthread>
        $<$<PLATFORM_ID:Linux>:GL>
        $<$<PLATFORM_ID:Linux>:X11>
        $<$<PLATFORM_ID:Linux>:Xrandr>
        $<$<PLATFORM_ID:Linux>:Xcursor>
        $<$<PLATFORM_ID:Linux>:Xinerama>
        $<$<PLATFORM_ID:Linux>:Xxf86vm>

        $<$<PLATFORM_ID:Darwin>:OpenGL::GL> # Requires to call `find_package(OpenGL REQUIRED)` beforehand
        $<$<PLATFORM_ID:Darwin>:"-framework OpenGL">
        $<$<PLATFORM_ID:Darwin>:"-framework Cocoa">
        $<$<PLATFORM_ID:Darwin>:"-framework IOKit">
        $<$<PLATFORM_ID:Darwin>:"-framework CoreVideo">

        # If you use audio features, add the following
        # OpenAL needs to be installed; see https://github.com/Razakhel/RaZ/wiki/OpenAL

        $<$<PLATFORM_ID:Linux>:openal>

        $<$<PLATFORM_ID:Darwin>:"-framework OpenAL">
)

if (WIN32)
    target_compile_definitions(
        ${PROJECT_NAME}

        PRIVATE
            NOMINMAX # Defining this just in case
    )
endif ()

target_sources(
    ${PROJECT_NAME}

    PRIVATE
        main.cpp # This is your application's main file
        # Add other files if necessary
)

Making your first application

RaZ is architectured as an ECS. If you've already tried using Unity (among many other game engines), you won't be lost. If you did use Unity before, you can read that page to get you up to speed.

As a general rule, always check the demos. The fullDemo in particular, which is always maintained to include the most of the features.

To get started, let's see a simple example:

An application must always be initialized first. That's the entry point of your program. A World must be added, to hold entities which will actually define pretty much everything:

Raz::Application app;
Raz::World& world = app.addWorld(3); // '3' is the number of entities to reserve in advance

Now that both exist, your application will use systems. You can always define your own, but some already exist:

// The render system will handle all graphics logic; the given parameters will be used to create the window
auto& render = world.addSystem<Raz::RenderSystem>(1280, 720, "Example");

Raz::Window& window = render.getWindow(); // A render system possesses the window; we will need it later

Now, we need to add an entity. An entity is merely an aggregate of components, which will define the entities' behavior. Every system has a predefined set of components that it accepts. In our case, at the time of writing, the render system accepts components of type MeshRenderer, Light & Camera. Let's then add a Camera:

Raz::Entity& camera = world.addEntity();

// A camera needs viewport dimensions; we will use the same as the render system's
camera.addComponent<Raz::Camera>(render.getSceneWidth(), render.getSceneHeight());

// A Transform component must be added, so that the camera's position is defined
camera.addComponent<Raz::Transform>(Raz::Vec3f(0.f, 0.f, -5.f));

Great, we have a camera... But there's not much to see, is it? Let's add another entity which this time will have a MeshRenderer component:

// An entity can be directly created with a component
// That one will also need a Transform, so let's add it in-place
Raz::Entity& mesh = world.addEntityWithComponent<Raz::Transform>();

// Importing a mesh file & recovering its MeshRenderer part
// The Mesh can be added to the entity as well, should you need to keep the geometry
// For more information, see: https://github.com/Razakhel/RaZ/wiki/Import-a-mesh
mesh.addComponent<Raz::MeshRenderer>(Raz::MeshFormat::load("ball.obj").second);

Now that we should be able to see something, let's try running the application:

app.run();

Build & run your program. You should now see the incredible result:

RaZ - Lightless

... Well alright, it's a bit dark. To be able to see something, let's add another entity before the app is run:

// Once again, our light will need a Transform component
// Since we will use a directional light, no need to give it a position
Raz::Entity& light = world.addEntityWithComponent<Raz::Transform>();
light.addComponent<Raz::Light>(Raz::LightType::DIRECTIONAL, // Making a directional light
                               Raz::Axis::Forward,          // Which will illuminate in a direction
                               1.f,                         // With a given energy (intensity)
                               Raz::ColorPreset::White);    // And a specific color (here white)

Let's try running our application once more:

RaZ - Enlightened

And there you have it, all lit up!

Clone this wiki locally