Getting started

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

RaZ is architectured as an ECS. If you already tried using Unity (among many other game engines), you won't be lost.

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

Important: To compile the following code, you must link against RaZ and optionnally several dependencies. To use the rendering part (RenderSystem, Window, etc...), you must link your program with specific arguments. Under Linux, you must specify -lGL -lX11 -lXrandr -lXcursor -lXinerama -lXxf86vm -lpthread -ldl. Under Windows, only -lRaZ -lopengl32 is required.

---

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 obviously 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

// Currently, shaders must be directly set within a render system; this is not the final wanted behavior and will change someday
// The following two are the standard ones available in the repo: https://github.com/Razakhel/RaZ/tree/master/shaders
render.getGeometryProgram().setShaders(Raz::VertexShader("vert.glsl"), Raz::FragmentShader("cook-torrance.glsl"));

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, as the time of writing, the render system accepts components of type Mesh, 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 window's size
camera.addComponent<Raz::Camera>(window.getWidth(), window.getHeight());

// 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 with a Mesh:

// 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>();
mesh.addComponent<Raz::Mesh>("ball.obj");

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:

... 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::Vec3f(0.f, 0.f, 1.f),   // Which will illuminate in a direction (forward in our case)
                               1.f,                         // With a given energy (intensity)
                               Raz::Vec3f(1.f));            // And a specific color (here white)

Let's try running our application once more:

And there you have it, all lit up!