Skip to main content

Getting Started with Rhea

This guide introduces Rhea through BasicApp, a small C++ application that creates a scene, camera, directional light, and textured cube.

Want to explore and edit a scene without writing C++? Start with First steps with Ceto: the Courtyard. Continue here when you want to build an application from source.

The engine and BasicApp have been built and run on Windows with Direct3D 11 and OpenGL, and on Linux under WSL with OpenGL. Rhea is experimental; an editor is not included and APIs may change.

Prerequisites​

  • A C++17 compiler and its platform development tools.
  • CMake 3.24 or newer.
  • Python 3 for build-time Fabric and type registry generation.
  • Git to obtain the repository and fetch Git-based dependencies.
  • Dependencies required by the selected graphics and platform backends.
  • Network access if CMake needs to download missing dependencies.

On Windows with MSVC, run the commands from a developer terminal with the compiler available. Ninja is required if you use the repository's Ninja presets. The commands below let CMake use its default generator instead.

See Build dependencies for required libraries, automatic downloads, and a vcpkg setup that disables Rhea downloads. The default BasicApp configuration enables SDL3, Bullet, and audio. nlohmann/json is always required by the top-level configuration; OpenSSL is optional and is not downloaded automatically.

Tested configurations are Windows with Direct3D 11 or OpenGL, and Linux under WSL with OpenGL. Native Linux installations and macOS have not been validated for this release. Specific compiler versions remain to be documented.

Configure and build BasicApp​

Obtain a checkout of the engine repository and open a terminal in its root, the directory containing Rhea/, Poseidon/, and the top-level CMakeLists.txt. Configure from the engine repository root, rather than from a parent development workspace.

cmake -S . -B out/basic-app -DRHEA_BUILD_APPS=OFF -DRHEA_BUILD_SAMPLES=ON -DPOSEIDON_BUILD_SAMPLES=OFF -DRHEA_BUILD_TESTS=OFF -DCMAKE_BUILD_TYPE=Debug
cmake --build out/basic-app --config Debug --target Rhea_Sample_01_BasicApp

This configuration selects the engine sample and omits Ceto and the renderer-only samples. It retains the default engine subsystem selections. See Build dependencies to provide libraries explicitly or use vcpkg.

If CMake cannot find Python, repeat configuration with -DPython3_EXECUTABLE pointing to your Python executable. For compiler or dependency errors, retain the configure output and check which tool or package it identifies before proceeding.

Run the sample​

Find the built executable named Rhea_Sample_01_BasicApp (Rhea_Sample_01_BasicApp.exe on Windows) inside out/basic-app. Its directory depends on the generator; multi-configuration generators may add a Debug directory.

The sample's build rules copy these assets next to the executable:

Data/
  basic_app/
  rhea/

Change your terminal's working directory to the directory containing the executable and run it. Keep the Data directory beside it. On Windows PowerShell, use:

.\Rhea_Sample_01_BasicApp.exe

On Linux, use:

./Rhea_Sample_01_BasicApp

The sample displays a textured, lit cube. Press Escape to exit.

If assets are missing, check the post-build copy output and the adjacent Data directory. If the application opens but renders incorrectly, report the operating system, graphics backend, and application output.

Make your first change​

Open Rhea/Samples/01_BasicApp/BasicApp.cpp. In createScene(), find the camera position:

camera->setLocalPosition(math::Vector3(0, 2, -7.5f));

Move it farther from the cube:

camera->setLocalPosition(math::Vector3(0, 2, -8));

Rebuild the same target from the repository root, then run the executable again. With the camera still looking at the origin, the cube should appear smaller. This demonstrates the edit-build-run workflow without requiring an editor.

Understand the example​

  • setup() loads the shader and texture before calling createScene(), which creates the scene, camera, lighting, cube mesh, and material.
  • onInput() handles Escape to request an exit.
  • main() initializes the application and enters its loop.
  • The sample links Rhea::Core, Rhea::Client, and RheaFabrics.

For engine composition, see the Architecture guide. To integrate Rhea into your own project, follow the next section.

Integrate Rhea into your own project​

Use a local engine checkout with CMake add_subdirectory. This gives you a visible engine source tree that you can inspect, modify, and debug alongside your application. A Git submodule is another way to keep that checkout in your project; select a known engine revision for reproducible builds.

Arrange the project as follows:

MyGame/
  external/
    rhea/
  src/
    main.cpp
  CMakeLists.txt

The external/rhea directory contains the complete engine repository. Use the following integration structure from the engine README:

cmake_minimum_required(VERSION 3.24)
project(MyGame LANGUAGES C CXX)

set(RHEA_SDK_DIR "${CMAKE_CURRENT_SOURCE_DIR}/external/rhea")

include("${RHEA_SDK_DIR}/Rhea/cmake/rhea_project.cmake")
add_subdirectory("${RHEA_SDK_DIR}")

add_executable(MyGame src/main.cpp)

target_link_libraries(MyGame PRIVATE
    Rhea::Core
    Rhea::Client
    RheaFabrics
)

rhea_project_end()

This describes project integration, rather than a complete graphical application. Your application still needs its initialization, selected services, and assets. Use BasicApp as the reference for those responsibilities; its build rules also show how to copy assets beside the executable.

Add any additional packages that register Fabrics before rhea_project_end(). This finalizes the Fabric registry after registration.

Select Fabrics​

To select a project-specific Fabric profile, set the following before including rhea_project.cmake:

set(RHEA_ENABLED_PROFILE_JSON
    "${CMAKE_CURRENT_SOURCE_DIR}/enabled.json"
)

The profile must contain the Fabric selections for your application. If no profile is provided, all registered Fabrics are enabled. Consult the engine's existing profiles for the format and available identifiers.

Configure and build​

From your application directory:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --config Debug --target MyGame

These commands assume you have supplied src/main.cpp and the application's required configuration and assets. The BasicApp checks do not independently validate this generic integration example. See Your First Project for a complete application walkthrough.

FetchContent can be used as an alternative dependency acquisition mechanism, but is not required for this workflow. Likewise, mwpkg is optional; the integration above uses standard CMake directly.

Next: Ceto and larger applications​

Ceto is an experimental viewer for user-provided scenes. It runs, but no demonstration scene is included. Use Ceto -d <directory> to select the directory exposed through the //local/ virtual asset path. For example, //local/example.scene refers to example.scene inside that directory. This option selects an asset directory, not a scene to open. A complete scene-authoring and viewer walkthrough is planned as a subsequent documentation step.

Novara is a larger external application for studying how Rhea is used in practice. It can be built independently when the path to a Rhea SDK checkout is supplied. Follow Novara's own build instructions for that setting and use a compatible engine revision. Neither Ceto nor Novara is needed to complete this introductory sample.