Game Engine Integration

The Game Engine Integration Sample demonstrates how to integrate the Beam Eye Tracker SDK into a game engine architecture. To avoid dealing with the many complexities of a real game-engine, this sample uses a dummy game engine architecture. However, the coding patterns are compatible with major game engines like Unity and Unreal Engine 5. It demonstrates:

• Wrapping the API as a custom game engine input device;

• Implementation of In-game camera control;

• Implementation of an Immersive HUD as in Dynamic HUDs;

• Holding game settings parameters and mapping them to input device parameters;

• Viewport geometry management;

• Camera recentering functionality, and;

• Auto-start capability for seamless user experience.

Note

Requirements: Windows 10 or newer, Linux, or macOS; CMake; a C++ compiler; and the Beam Eye Tracker application.

Language: C++.

Compiling and running the sample

As part of the C++ samples, you can find the game_engine_integration sample in the cpp/samples folder.

Prebuilt binaries may be included in cpp/samples/bin depending on the SDK package. You can also compile the sample yourself. To do so, run build_samples.bat on Windows or build_samples.sh on Linux/macOS from the cpp/samples folder. The script assumes you have CMake installed and that CMake can find a suitable C++ compiler/generator on your system. The CMakeLists.txt integrates the Beam Eye Tracker SDK as explained in Project configuration.

The program runs for 30 seconds. The console displays:

• Real-time camera position and rotation (only z translation and yaw are shown for simplicity);

• Current HUD opacity values which change whether you are looking at the top-left corner of the viewport, and;

• Recentering status updates (when pressing SPACE).

Moreover, you can observe that the camera’s z translation continuously increases to simulate the reference camera pose changes through the 3D world scene, while the immersive camera pose changes are additive to this base pose.

Warning

The current viewport geometry is hardcoded in get_rendering_area_viewport_geometry_from_engine and thus you won’t experience realistic behavior out of the box when running the sample. It assumes the game is rendering on the middle screen of three 1920x1080 monitors, with the left-most screen being the Windows main display.

If you want realistic behavior, for example, that the opacity output changes when you indeed look at the top-left corner of YOUR display, you need to modify the get_rendering_area_viewport_geometry_from_engine function to return a rectangle geometry that matches your setup (e.g. a given screen or window that you want to pretend is game-rendering area), but do respect the Unity-like viewport definition (bottom-left corner at (0, 0)) which is assumed for this specific sample.

Sample explained

The source code is distributed into three files:

my_game_engine.h

This file implements dummy classes that emulate a typical game engine object-oriented pattern:

• Base interfaces with common functions like BeginPlay, Tick, Update

• Simplified game engine architecture similar to Unity/Unreal

• Meant to be replaced by your engine’s actual functionality

my_game_engine.h

#ifndef MY_GAME_ENGINE_H
#define MY_GAME_ENGINE_H

#include <vector>
/**
 * Copyright (C) 2025 Eyeware Tech SA.
 *
 * All rights reserved.
 *
 * This file defines an extremely simplified game engine using OOP, similar to Unity and UE5
 * OOP paradigm. In real life we assume all of this is already defined in your engine.
 *
 * The good stuff is in files main.cpp and bet_game_engine_device.cpp.
 */

struct MyGameEngineTransform {
    // For this sample's purpose, we assume Unity's camera coordinate system which is the same as
    // Beam, except that x is inverted, and the rotations are left-handed, not right-handed.
    float rotation_x_degrees;
    float rotation_y_degrees;
    float rotation_z_degrees;
    float translation_x_inches;
    float translation_y_inches;
    float translation_z_inches;

    MyGameEngineTransform operator+(MyGameEngineTransform other) {
        return MyGameEngineTransform{this->rotation_x_degrees + other.rotation_x_degrees,
                                     this->rotation_y_degrees + other.rotation_y_degrees,
                                     this->rotation_z_degrees + other.rotation_z_degrees,
                                     this->translation_x_inches + other.translation_x_inches,
                                     this->translation_y_inches + other.translation_y_inches,
                                     this->translation_z_inches + other.translation_z_inches};
    }
};

class MyGameEngineObjectInterface {
  public:
    MyGameEngineObjectInterface(MyGameEngineObjectInterface *parent) : parent(parent) {}
    // Called frequently and periodically. delta_time in seconds.
    virtual void Tick(float delta_time) {};

    // Called when the rendering loop starts.
    virtual void BeginPlay() {};

    // Called when the rendering loop stops.
    virtual void EndPlay() {};

    void set_local_transform(MyGameEngineTransform local_transform) {
        this->local_transform = local_transform;
        if (this->parent) {
            this->world_transform = this->parent->world_transform + this->local_transform;
        } else {
            this->world_transform = this->local_transform;
        }
    }

    MyGameEngineTransform local_transform{0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f};
    MyGameEngineTransform world_transform{0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f};

    MyGameEngineObjectInterface *parent;
};

class MyGameEngineHUDElement : public MyGameEngineObjectInterface {
  public:
    enum class Type {
        TOP_LEFT,
        TOP_RIGHT,
        BOTTOM_LEFT,
        BOTTOM_RIGHT,
    };

    MyGameEngineHUDElement(MyGameEngineHUDElement::Type type, MyGameEngineObjectInterface *parent)
        : MyGameEngineObjectInterface(parent), type(type) {}

    Type type;
    float opacity = 1.0f;
};

#endif // MY_GAME_ENGINE_H

bet_game_engine_device.h

Implements the MyGameEngineBeamEyeTrackerDevice which is the key class that you would typically implement for your specific game engine. You will see that it:

• manages the API instance;

• uses asynchronous data access using itself as the eyeware::beam_eye_tracker::TrackingListener;

• shows how to launch the Beam Eye Tracker at BeginPlay;

• computes HUD opacity values based on whether the user is looking at the HUD element or not, making said opacities part of the device output parameters;

• samples the smoothed sim game camera state once per render frame, processes the camera pose parameters, maps them to the game engine coordinates, and sets the mapped MyGameEngineTransform (yaw, pitch, roll, x, y, z) as a device output parameter;

• processes how game settings affect the device behavior and output.

Note

The sample uses asynchronous data access, but if you can’t guarantee that the TrackerListener will be alive until the handle is explicitly deregistered, you can use polling data access instead, which also does not block the main thread.

bet_game_engine_device.h

/**
 * Copyright (C) 2025 Eyeware Tech SA.
 *
 * All rights reserved.
 */

#ifndef BET_GAME_ENGINE_DEVICE_H
#define BET_GAME_ENGINE_DEVICE_H

#include "eyeware/beam_eye_tracker.h"
#include "my_game_engine.h"
#include <algorithm>
#include <cstdlib>
#include <exception>
#include <iostream>
#include <memory>

namespace {

constexpr float BET_SAMPLE_PI = 3.14159265358979323846f;
constexpr float BET_RADIANS_TO_DEGREES = 180.0f / BET_SAMPLE_PI;
constexpr float M_METERS_TO_INCHES = 39.3700787;

float update_hud_opacity(float prev_opacity, bool looking_at_hud, float delta_time) {
    // Implements asymmetric linear opacity update. You can use a nicer animation curve.
    const float opacity_rate_on_looking_at_hud = 10.0f;     // Fully visible in max 0.1 seconds
    const float opacity_rate_on_not_looking_at_hud = -1.0f; // Fully invisible in max 1 seconds
    const float min_opacity = 0.2f; // In case the HUD should not fully disappear

    const float opacity_update_rate =
        looking_at_hud ? opacity_rate_on_looking_at_hud : opacity_rate_on_not_looking_at_hud;
    return std::min(std::max(prev_opacity + opacity_update_rate * delta_time, min_opacity), 1.0f);
}

} // namespace

// Note, for this sample, we keep explicit mentions to the namespace eyeware::beam_eye_tracker
// to make it easier to separate API related code.
class MyGameEngineBeamEyeTrackerDevice : public eyeware::beam_eye_tracker::TrackingListener,
                                         public MyGameEngineObjectInterface {
  public:
    MyGameEngineBeamEyeTrackerDevice(MyGameEngineObjectInterface *parent)
        : MyGameEngineObjectInterface(parent) {
        // We only need one instance of the API. You can also create it on "Begin Play" if you
        // want to, but here it is created in the constructor for simplicity and not to check
        // on pointer validity.
        try {
            m_bet_api = std::make_unique<eyeware::beam_eye_tracker::API>(
                "Game Engine Integration Sample",
                get_rendering_area_viewport_geometry_from_engine());
        } catch (const std::exception &error) {
            std::cerr << "Failed to create Beam Eye Tracker API: " << error.what() << std::endl;
            std::exit(EXIT_FAILURE);
        }
    }

    ~MyGameEngineBeamEyeTrackerDevice() { stop_bet_api_tracking_data_reception(); }

    void BeginPlay() override {
        if (m_auto_start_tracking) {
            // If auto start is toggled on, this will request the Beam app to launch and
            // or to start the webcam and initialize the tracking.
            // HEADS UP! Be wise when you call this. Ideally you want to call it when the game
            // rendering starts and accepts device input, as otherwise may start the webcam
            // at a random time and confuse the user.
            m_bet_api->attempt_starting_the_beam_eye_tracker();
        }

        // Register itself as the listener to receive tracking data from the Beam Eye Tracker
        // application on the on_tracking_state_set_update method asynchronously.
        if (m_listener_handle == eyeware::beam_eye_tracker::INVALID_TRACKING_LISTENER_HANDLE) {
            m_listener_handle = m_bet_api->start_receiving_tracking_data_on_listener(this);
        }
    }

    void EndPlay() override { stop_bet_api_tracking_data_reception(); }

    void Tick(float delta_time) override {
        // For the purpose of this sample, we assume a custom device output is the HUD opacity,
        // which is updated here.

        // Animate the opacity change depending on whether the user is looking at HUD elements.
        device_output_top_left_hud_opacity = update_hud_opacity(
            device_output_top_left_hud_opacity, m_is_user_looking_at_top_left_corner, delta_time);
        device_output_top_right_hud_opacity = update_hud_opacity(
            device_output_top_right_hud_opacity, m_is_user_looking_at_top_right_corner, delta_time);
        device_output_bottom_left_hud_opacity =
            update_hud_opacity(device_output_bottom_left_hud_opacity,
                               m_is_user_looking_at_bottom_left_corner, delta_time);
        device_output_bottom_right_hud_opacity =
            update_hud_opacity(device_output_bottom_right_hud_opacity,
                               m_is_user_looking_at_bottom_right_corner, delta_time);

        // Update viewport every 3 seconds in case the rendering area geometry changed.
        // In the Beam Eye Tracker application API, this operation is light-weight
        // so you could call it more frequently, but 3 seconds balances the trade-off between
        // slight-overhead (inc. game engine retrieval of the geometry) and responsiveness in case
        // the game was resized or moved. If you have an specific event for game window geometry
        // changes, may be better suited for this purpose.
        m_time_since_last_viewport_geometry_update += delta_time;
        if (m_time_since_last_viewport_geometry_update >= 3.0f) {
            m_bet_api->update_viewport_geometry(get_rendering_area_viewport_geometry_from_engine());
            m_time_since_last_viewport_geometry_update = 0.0f;
        }
    }

    // Functions for recentering the camera. Likely mapped to a hotkey press/release event.
    void recenter_camera_start() {
        if (m_bet_api) {
            m_bet_api->recenter_sim_game_camera_start();
        }
    }
    void recenter_camera_end() {
        if (m_bet_api) {
            m_bet_api->recenter_sim_game_camera_end();
        }
    }

    eyeware::beam_eye_tracker::ViewportGeometry get_rendering_area_viewport_geometry_from_engine() {
        // Implement here your Game Engine specific logic where you retrieve the rendering area
        // geometry, i.e., the viewport. We need to keep the eyeware::beam_eye_tracker::API up to
        // date with changes in the viewport geometry.

        // For this demo, assume this configuration: three physical monitors from left to right of
        // resolutions 1920x1080, 1920x1080, 1920x1080. The left-most monitor is configured in
        // Windows settings as the "Main display" (thus, it defines the (0, 0) coordinates in the
        // Windows Virtual Screen), and the game is rendering full screen in the center monitor.
        // Moreover, lets assume this game engine follows Unity's viewport standard, where the the
        // viewport (0, 0) coordinates are at the bottom-left corner of the rendering area.
        // Thus this coordinates would represent that configuration:
        eyeware::beam_eye_tracker::Point point_00 = {1920, 1079};
        eyeware::beam_eye_tracker::Point point_11 = {1920 + 1920 - 1, 0};

        return {point_00, point_11};
    }

    void on_tracking_data_reception_status_changed(
        eyeware::beam_eye_tracker::TrackingDataReceptionStatus status) override {

        // See TrackingDataReceptionStatus for explanation on all possible statuses.
        if (status ==
            eyeware::beam_eye_tracker::TrackingDataReceptionStatus::NOT_RECEIVING_TRACKING_DATA) {
            // If the tracking data reception status is NOT_RECEIVING_TRACKING_DATA is because the
            // Beam app is not open, the webcam is not active, the client was rejected from using
            // the API, the user is not signed in, etc. etc.. To "fix" this, manual intervention
            // from the user is required. Note that this state could be reached shortly after a call
            // to attempt_starting_the_beam_eye_tracker, which failed to achieve the auto-start.
            // You can try calling attempt_starting_the_beam_eye_tracker again, but it is a question
            // of user experience, as the user may be manually toggling off, but the game insists on
            // toggling on.

            // In this situation, makes sense to reset the device output to default values.
            // Animation curves could be used for a smoother transition.
            device_output_camera_local_transform = {0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f};

            device_output_top_left_hud_opacity = 1.0f;
            device_output_top_right_hud_opacity = 1.0f;
            device_output_bottom_left_hud_opacity = 1.0f;
            device_output_bottom_right_hud_opacity = 1.0f;

            m_is_user_looking_at_top_left_corner = true;
            m_is_user_looking_at_top_right_corner = true;
            m_is_user_looking_at_bottom_left_corner = true;
            m_is_user_looking_at_bottom_right_corner = true;
        }
    }

    void on_tracking_state_set_update(
        const eyeware::beam_eye_tracker::TrackingStateSet &tracking_state_set,
        const eyeware::beam_eye_tracker::Timestamp timestamp) override {
        // Async callback to retrieve the tracking data.
        //
        // Note: the SimGameCameraState held by tracking_state_set is a snapshot at the tracking
        // rate and is intentionally NOT consumed here. Instead, the immersive camera samples
        // the smoothed signal once per render frame via
        // sample_smoothed_sim_game_camera_state_for_current_render_frame() below. This delivers
        // a continuous in-game camera at the render rate rather than at the tracking rate.

        update_device_viewport_gaze_state_from_bet_api_input(tracking_state_set.user_state());

        update_device_game_immersive_hud_state_from_bet_api_input(
            tracking_state_set.game_immersive_hud_state());
    }

    /**
     * @brief Sample the smoothed sim camera state for the current render frame.
     *
     * Called once per Tick from the immersive camera object. Maps the smoothed pose to the
     * game engine's camera coordinate system and writes the result into
     * device_output_camera_local_transform.
     */
    void sample_smoothed_sim_game_camera_state_for_current_render_frame() {
        // Mapping sensitivity (default 0.5) to weight (default 1.0). Note this mapping
        // could be more complex, but the assumption is that a weight of 1.0 would make the
        // signal as configured by the user within the Beam Eye Tracker application.
        const float sim_game_camera_eye_tracking_weight =
            2.0f * m_sim_game_camera_eye_tracking_sensitivity;
        const float sim_game_camera_head_tracking_weight =
            2.0f * m_sim_game_camera_head_tracking_sensitivity;

        const eyeware::beam_eye_tracker::SimGameCameraState smoothed_state =
            m_bet_api->sample_smooth_sim_game_camera_state();
        if (smoothed_state.timestamp_in_seconds == eyeware::beam_eye_tracker::NULL_DATA_TIMESTAMP) {
            // No tracking input received yet, or filter params not yet synchronized. Keep the
            // previous transform: snapping to zero on a momentary interruption (e.g. user
            // briefly off-frame) would be a confusing user experience.
            return;
        }

        // This combines the signals into one transform.
        eyeware::beam_eye_tracker::SimCameraTransform3D bet_camera_local_transform =
            m_bet_api->compute_smooth_sim_game_camera_transform_parameters(
                smoothed_state, sim_game_camera_eye_tracking_weight,
                sim_game_camera_head_tracking_weight);

        // Map Beam coordinates to the game engine's coordinate system. Assuming the game
        // engine is using Unity's coordinate system (same as Beam, except that x is inverted
        // and the rotations are left-handed instead of right-handed).
        device_output_camera_local_transform.rotation_x_degrees =
            bet_camera_local_transform.pitch_in_radians * BET_RADIANS_TO_DEGREES;
        device_output_camera_local_transform.rotation_y_degrees =
            -bet_camera_local_transform.yaw_in_radians * BET_RADIANS_TO_DEGREES;
        device_output_camera_local_transform.rotation_z_degrees =
            -bet_camera_local_transform.roll_in_radians * BET_RADIANS_TO_DEGREES;

        device_output_camera_local_transform.translation_x_inches =
            -bet_camera_local_transform.x_in_meters * M_METERS_TO_INCHES;
        device_output_camera_local_transform.translation_y_inches =
            bet_camera_local_transform.y_in_meters * M_METERS_TO_INCHES;
        device_output_camera_local_transform.translation_z_inches =
            bet_camera_local_transform.z_in_meters * M_METERS_TO_INCHES;
    }

    void update_device_viewport_gaze_state_from_bet_api_input(
        const eyeware::beam_eye_tracker::UserState &user_state) {

        // Eye tracking coordinates referred to the viewport area.
        if (user_state.timestamp_in_seconds != eyeware::beam_eye_tracker::NULL_DATA_TIMESTAMP &&
            eyeware::beam_eye_tracker::cast_confidence(user_state.viewport_gaze.confidence) !=
                eyeware::beam_eye_tracker::TrackingConfidence::LOST_TRACKING) {

            // Normalized gaze coordinates in the viewport. Normalized as it is in the range [0, 1],
            // however, values outside this range are possible.
            device_output_viewport_normalized_gaze_x =
                user_state.viewport_gaze.normalized_point_of_regard.x;
            device_output_viewport_normalized_gaze_y =
                user_state.viewport_gaze.normalized_point_of_regard.y;
        }
    }

    void update_device_game_immersive_hud_state_from_bet_api_input(
        const eyeware::beam_eye_tracker::GameImmersiveHUDState &game_immersive_hud_state) {
        if (game_immersive_hud_state.timestamp_in_seconds !=
            eyeware::beam_eye_tracker::NULL_DATA_TIMESTAMP) {

            // Note: the input values are interpreted a "likelihood" or as a "probability", so
            // you can simply threshold it.
            m_is_user_looking_at_top_left_corner =
                game_immersive_hud_state.looking_at_viewport_top_left > 0.5f;
            m_is_user_looking_at_top_right_corner =
                game_immersive_hud_state.looking_at_viewport_top_right > 0.5f;
            m_is_user_looking_at_bottom_left_corner =
                game_immersive_hud_state.looking_at_viewport_bottom_left > 0.5f;
            m_is_user_looking_at_bottom_right_corner =
                game_immersive_hud_state.looking_at_viewport_bottom_right > 0.5f;

        } else {
            // There could be multiple reasons to receive a NULL_DATA_TIMESTAMP in the callback.
            // But in general it means an interruption of the normal tracking, the feature
            // itself, or other.

            // In this case, it makes sense to "reset" at set all the HUD as visible. For
            // example, assume the user is off-camera.
            m_is_user_looking_at_top_left_corner = true;
            m_is_user_looking_at_top_right_corner = true;
            m_is_user_looking_at_bottom_left_corner = true;
            m_is_user_looking_at_bottom_right_corner = true;
        }
    }

    //*********  VARIABLES ASSUMED TO BE LINKED TO IN-GAME SETTINGS ****************** */
    // Note: we don't define the setters to avoid clutter.
    /**
     * @brief Implement a user interface that allows to change this value.
     */
    bool m_auto_start_tracking = true;

    // For the in-game camera controls, assumed to be in the range [0, 1].
    float m_sim_game_camera_eye_tracking_sensitivity = 0.5f;
    float m_sim_game_camera_head_tracking_sensitivity = 0.5f;

    //************ VARIABLES REPRESENTING THE DEVICE STATE/OUTPUT ************ */
    // Note: we don't define the getters to avoid clutter.

    // Sim game camera local/additive transform
    MyGameEngineTransform device_output_camera_local_transform{0.0f, 0.0f, 0.0f, 0.0f, 0.0f, 0.0f};

    // Immersive HUD state. Here it is default opaque,  i.e., all the HUD is visible until
    // tracking data says otherwise. It's different than the boolean counterparts, as the
    // opacity changes are smooth across frames.
    float device_output_top_left_hud_opacity = 1.0f;
    float device_output_top_right_hud_opacity = 1.0f;
    float device_output_bottom_left_hud_opacity = 1.0f;
    float device_output_bottom_right_hud_opacity = 1.0f;

    // Normalized gaze coordinates in the viewport.
    float device_output_viewport_normalized_gaze_x = 0.0f;
    float device_output_viewport_normalized_gaze_y = 0.0f;

    //************************************************************************************ */

  private:
    bool m_is_user_looking_at_top_left_corner = true;
    bool m_is_user_looking_at_top_right_corner = true;
    bool m_is_user_looking_at_bottom_left_corner = true;
    bool m_is_user_looking_at_bottom_right_corner = true;

    void stop_bet_api_tracking_data_reception() {
        if (m_listener_handle != eyeware::beam_eye_tracker::INVALID_TRACKING_LISTENER_HANDLE) {
            m_bet_api->stop_receiving_tracking_data_on_listener(m_listener_handle);
            m_listener_handle = eyeware::beam_eye_tracker::INVALID_TRACKING_LISTENER_HANDLE;
        }
    }

    std::unique_ptr<eyeware::beam_eye_tracker::API> m_bet_api;
    eyeware::beam_eye_tracker::TRACKING_LISTENER_HANDLE m_listener_handle{
        eyeware::beam_eye_tracker::INVALID_TRACKING_LISTENER_HANDLE};
    float m_time_since_last_viewport_geometry_update{0.0f};
};

#endif // BET_GAME_ENGINE_DEVICE_H

main.cpp

This is the main function that manages the scene objects, the MyGameEngineBeamEyeTrackerDevice instance, and the game loop, in particular, it:

• Creates a HUD MyGameEngineImmersiveHUD consisting of a MyGameEngineHUDElement instance on each of the 4 corners of the viewport;

• Creates a scene in which a camera MyGameEngineImmersiveCamera is positioned as a child of a character head MyGameEngineCharacterHead, which provides a reference pose (see Control the in-game camera movement);

• Both the MyGameEngineImmersiveCamera and MyGameEngineCharacterHead instances hold pointers of the MyGameEngineBeamEyeTrackerDevice instance so that they react to eye and head tracking data at the Tick function;

• Implements a MyGameEngineHotkeysMapper which monitors if the user presses the SPACE key to recenter the camera, following Implement the camera recentering;

main.cpp

#include "bet_game_engine_device.h"
#include "my_game_engine.h"
#include <chrono>
#include <iomanip>
#include <iostream>
#include <memory>
#include <thread>

#if defined(_WIN32)
#include <windows.h>
#elif defined(__APPLE__)
#include <ApplicationServices/ApplicationServices.h>
#include <Carbon/Carbon.h>
#elif defined(__linux__)
#include <atomic>
#include <limits>
#else
#error                                                                                             \
    "game_engine_integration sample: unsupported platform (Windows, macOS, and Linux are supported)"
#endif

namespace {
std::vector<MyGameEngineObjectInterface *> devices;

#if defined(__linux__)
// Toggled on each Enter in LinuxRecenterInputThread: first press simulates key-down, second
// simulates key-up, matching start/end edges in Tick like Windows/macOS hold detection.
std::atomic<bool> g_linux_recenter_virtually_held{false};

void LinuxRecenterInputThread() {
    while (true) {
        std::cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');
        const bool cur = g_linux_recenter_virtually_held.load();
        g_linux_recenter_virtually_held.store(!cur);
    }
}
#endif

bool IsRecenterKeyDown() {
#if defined(_WIN32)
    return (GetAsyncKeyState(VK_SPACE) & 0x8000) != 0;
#elif defined(__APPLE__)
    return CGEventSourceKeyState(kCGEventSourceStateCombinedSessionState, kVK_Space) != 0;
#elif defined(__linux__)
    return g_linux_recenter_virtually_held.load();
#endif
}
} // namespace

// See bet_game_engine_device.h for showing the "integration" of the Beam API as a device in the
// engine See this file to see how it interacts with the other objects in the engine.
class MyGameEngineImmersiveHUD : public MyGameEngineObjectInterface {
  public:
    MyGameEngineImmersiveHUD(MyGameEngineObjectInterface *parent)
        : MyGameEngineObjectInterface(parent) {}

    void BeginPlay() override {
        // Get a reference to the Beam Eye Tracker device.
        beam_eye_tracker_device = dynamic_cast<MyGameEngineBeamEyeTrackerDevice *>(devices.at(0));

        // Dummy hud ui_elements added to all corners
        ui_elements.push_back(MyGameEngineHUDElement{MyGameEngineHUDElement::Type::TOP_LEFT, this});
        ui_elements.push_back(
            MyGameEngineHUDElement{MyGameEngineHUDElement::Type::TOP_RIGHT, this});
        ui_elements.push_back(
            MyGameEngineHUDElement{MyGameEngineHUDElement::Type::BOTTOM_LEFT, this});
        ui_elements.push_back(
            MyGameEngineHUDElement{MyGameEngineHUDElement::Type::BOTTOM_RIGHT, this});
    }
    // Implemented in bet_game_engine_device.cpp to identify
    void Tick(float delta_time) override {
        for (auto &element : ui_elements) {
            switch (element.type) {
            case MyGameEngineHUDElement::Type::TOP_LEFT:
                element.opacity = beam_eye_tracker_device->device_output_top_left_hud_opacity;
                break;
            case MyGameEngineHUDElement::Type::TOP_RIGHT:
                element.opacity = beam_eye_tracker_device->device_output_top_right_hud_opacity;
                break;
            case MyGameEngineHUDElement::Type::BOTTOM_LEFT:
                element.opacity = beam_eye_tracker_device->device_output_bottom_left_hud_opacity;
                break;
            case MyGameEngineHUDElement::Type::BOTTOM_RIGHT:
                element.opacity = beam_eye_tracker_device->device_output_bottom_right_hud_opacity;
                break;
            }
        }
    }

    std::vector<MyGameEngineHUDElement> ui_elements;

    MyGameEngineBeamEyeTrackerDevice *beam_eye_tracker_device{nullptr};
};

class MyGameEngineImmersiveCamera : public MyGameEngineObjectInterface {
  public:
    MyGameEngineImmersiveCamera(MyGameEngineObjectInterface *parent)
        : MyGameEngineObjectInterface(parent) {}

    void BeginPlay() override {
        // Get a reference to the Beam Eye Tracker device.
        beam_eye_tracker_device = dynamic_cast<MyGameEngineBeamEyeTrackerDevice *>(devices.at(0));
    }

    void Tick(float delta_time) override {
        // Sample the smoothed sim game camera state from the Beam API for the current render
        // frame. This is the recommended pattern for an in-game camera: smoothing rate adapts
        // to the render loop rather than to the tracking rate.
        beam_eye_tracker_device->sample_smoothed_sim_game_camera_state_for_current_render_frame();

        // Updates the local pose.
        // What is critical to notice is that this updates the world_transform by adding up the
        // parent's world_transform with the now given local_transform.
        this->set_local_transform(beam_eye_tracker_device->device_output_camera_local_transform);
    }

    MyGameEngineBeamEyeTrackerDevice *beam_eye_tracker_device{nullptr};
};

class MyGameEngineHotkeysMapper : public MyGameEngineObjectInterface {
  public:
    MyGameEngineHotkeysMapper(MyGameEngineObjectInterface *parent)
        : MyGameEngineObjectInterface(parent) {
#if defined(__linux__)
        std::thread(LinuxRecenterInputThread).detach();
#endif
    }

    void BeginPlay() override {
        // Get a reference to the Beam Eye Tracker device.
        beam_eye_tracker_device = dynamic_cast<MyGameEngineBeamEyeTrackerDevice *>(devices.at(0));
    }
    void Tick(float delta_time) override {
        const bool recenter_key_pressed = IsRecenterKeyDown();
        if (recenter_key_pressed != was_recenter_key_pressed) {
            if (recenter_key_pressed) {
                beam_eye_tracker_device->recenter_camera_start();
            } else {
                beam_eye_tracker_device->recenter_camera_end();
            }
            was_recenter_key_pressed = recenter_key_pressed;
        }
    }

    bool was_recenter_key_pressed = false;
    MyGameEngineBeamEyeTrackerDevice *beam_eye_tracker_device{nullptr};
};

class MyGameEngineCharacterHead : public MyGameEngineObjectInterface {
  public:
    MyGameEngineCharacterHead(MyGameEngineObjectInterface *parent)
        : MyGameEngineObjectInterface(parent) {}

    void Tick(float delta_time) override {
        // Just pretend the character is moving forward very slowly.
        this->world_transform.translation_z_inches += 0.01f * M_METERS_TO_INCHES * delta_time;
    }
};

int main() {
    std::unique_ptr<MyGameEngineBeamEyeTrackerDevice> beam_eye_tracker_device =
        std::make_unique<MyGameEngineBeamEyeTrackerDevice>(nullptr);
    devices.push_back(beam_eye_tracker_device.get());

    // Basic components, whose parent will be ignored as that's irrelevant in this sample.
    MyGameEngineCharacterHead character_head(nullptr);
    MyGameEngineImmersiveHUD immersive_hud(nullptr);
    MyGameEngineHotkeysMapper hotkeys_mapper(nullptr);
    MyGameEngineImmersiveCamera immersive_camera(&character_head);

    // We could put all in a list, but will be made explicit for clarity.

    //============= INITIALIZING THE GAME RENDERING =============
    for (auto &device : devices) {
        // Initializes the Beam device and API
        device->BeginPlay();
    }
    hotkeys_mapper.BeginPlay();
    immersive_hud.BeginPlay();
    immersive_camera.BeginPlay();
    character_head.BeginPlay();

    //============= FRAME LOOP at 60 FPS =============
    auto prev_frame_time = std::chrono::system_clock::now();
    const auto end_time = prev_frame_time + std::chrono::seconds(30); // Run for 30 seconds.
    while (std::chrono::system_clock::now() < end_time) {
        auto frame_start = std::chrono::system_clock::now();
        const float delta_time =
            std::chrono::duration<float>(frame_start - prev_frame_time).count();
        prev_frame_time = frame_start;

        hotkeys_mapper.Tick(delta_time);
        // We assume that devices are updated before the HUD and camera.
        for (auto &device : devices) {
            device->Tick(delta_time);
        }
        // In theory, here the parent-child relationship would drive the ordering, but we'll just
        // fake it by updating the character head first, then the camera, then the HUD.
        character_head.Tick(delta_time);
        immersive_hud.Tick(delta_time);

        immersive_camera.Tick(delta_time);

        // Note: if you want to see "real" responses for the top-left HUD element opacity when you
        // look to the top-left corner of your display, please edit
        // MyGameEngineBeamEyeTrackerDevice::get_rendering_area_viewport_geometry_from_engine and
        // hard-code the correct geometry of your display.

        // Note: you should see the printed z values to grow slowly as the character head is moving
        // forward slowly, but also increase or decrease in values as you move towards or away from
        // the webcam. Hold SPACE to recenter (Windows/macOS); on Linux use Enter twice to
        // simulate hold then release.
        std::cout << "[Game cam: z_pos_inches=" << std::fixed << std::setprecision(2)
                  << immersive_camera.world_transform.translation_z_inches
                  << " ; yaw_degrees=" << std::fixed << std::setprecision(2)
                  << immersive_camera.world_transform.rotation_y_degrees << "] and ["
                  << "HUD top left opacity=" << std::fixed << std::setprecision(2)
                  << immersive_hud.ui_elements.at(0).opacity << "]";
        if (hotkeys_mapper.was_recenter_key_pressed) {
            std::cout << " Recentering!" << std::endl;
        } else {
            std::cout << std::endl;
        }

        // Sleep for 16ms to simulate 60-ish FPS
        std::this_thread::sleep_for(std::chrono::milliseconds(16));
    }
    //============= SHUTTING DOWN THE GAME RENDERING =============
    for (auto &device : devices) {
        device->EndPlay(); // Shuts down the Beam device and API
    }
    immersive_hud.EndPlay();
    immersive_camera.EndPlay();
    character_head.EndPlay();
}

Other highlights

• The sample assumes that the game engine is using a Unity-like coordinate system for the camera pose (yaw, pitch, roll, x, y, z definitions) and viewport geometry (origin (0, 0) at bottom-left corner of the rendering area). The Beam SDK camera state uses the SDK 2.2 rotation convention described in Mapping to the game engine coordinate system.

• The demonstrated game settings are head tracking sensitivity, eye tracking sensitivity and auto-start behavior toggle, which would typically be exposed in the game’s UI.

• Note how the opacity fade in and fade out is animated to make a smoother experience, but fade in is much faster than fade out.