// Ollo for Unreal Engine

Ollo integrates directly into Unreal Engine as a ready-to-use plugin exposing real-time blink and attention signals to both Blueprint and C++ gameplay systems.

Quick start

Engine support

UE 5.3+
Windows
Webcam or external frame source

Install the plugin

Extract the SDK to:

<YourProject>/Plugins/Ollo/

Then place your license key in:

<YourProject>/Plugins/Ollo/ThirdParty/ollo/bin

Enable the plugin:

Restart the editor.

Using Ollo in Blueprints

Recommended defaults

Setting	Value
CameraIndex	0
Width	640
Height	480
FPS	30
Enable Pose Normalization	Enabled
Telemetry Enabled	Enabled

Leave ModelPath empty to use the built-in runtime model.

Notes

• Bind delegates before calling Start() so startup failures and early events are not missed.
• Deinitialize() automatically performs a safe shutdown when the game exits, but explicit stopping is recommended for controlled runtime teardown.

C++ Quick Start

Basic Actor Example

// MyBlinkActor.h
#pragma once
#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "OlloTypes.h"
#include "MyBlinkActor.generated.h"

UCLASS()
class AMyBlinkActor : public AActor
{
    GENERATED_BODY()
protected:
    virtual void BeginPlay() override;
    virtual void EndPlay(const EEndPlayReason::Type Reason) override;

private:
    UFUNCTION() // Required for dynamic delegates
    void OnBlink(const FOlloBlinkEvent& Event);
};

// MyBlinkActor.cpp
#include "MyBlinkActor.h"
#include "OlloSubsystem.h"

void AMyBlinkActor::BeginPlay()
{
    Super::BeginPlay();

    UOlloSubsystem* Ollo = UOlloSubsystem::Get(this);
    if (!Blinkd) return;

    // Bind before Start so you don't miss startup_failed
    Ollo->OnBlinkDetected.AddDynamic(this, &AMyBlinkActor::OnBlink);
    Ollo->OnStartupFailed.AddDynamic(this, &AMyBlinkActor::HandleStartupFailed);

    // Empty string = use built-in model, camera 0, defaults
    Ollo->Start(FString(), 0, 640, 480, 30, true, true);
}

void AMyBlinkActor::EndPlay(const EEndPlayReason::Type Reason)
{
    if (UOlloSubsystem* Ollo = UOlloSubsystem::Get(this))
    {
        Ollo->OnBlinkDetected.RemoveDynamic(this, &AMyBlinkActor::OnBlink);
        Ollo->Stop();
    }
    Super::EndPlay(Reason);
}

void AMyBlinkActor::OnBlink(const FOlloBlinkEvent& Event)
{
    UE_LOG(LogTemp, Log,
        TEXT("Blink #%lld | %.1f ms | quality: %d"),
        Event.Sequence, Event.DurationMs, (int)Event.Quality);

    // Do whatever: trigger animation, spawn effect, etc.
}

// Also add this to the header and implement it:
UFUNCTION()
void HandleStartupFailed(const FString& Error)
{
    UE_LOG(LogTemp, Error, TEXT("[Ollo SDK] Could not start: %s"), *Error);
}

Key rule: Any function you bind to a DYNAMIC delegate must itself be a UFUNCTION otherwise the binding silently does nothing at runtime.

Architecture

Why Game Instance Subsystem?

Ollo is implemented as a UGameInstanceSubsystem.

This means:

• Tracking persists across level transitions
• Gameplay systems can access Ollo globally
• The runtime initializes once
• Shutdown is centralized and predictable

Typical usage:

Threading model

Ollo processes tracking data asynchronously and dispatches gameplay events safely on the game thread.

Internal flow:

OnBlinkDetected is always broadcast on the game thread and is safe to use directly in gameplay systems, animation logic and Blueprint graphs.

Event system

On Player Blink

UPROPERTY(BlueprintAssignable)
FOlloBlinkDelegate OnBlinkDetected;

Fired whenever a blink is detected.

Event Fields

Field	Description
Sequence	Incrementing blink event ID
Timestamp	Detection timestamp
DurationMs	Blink duration
Quality	Confidence/quality classification

Polling API

For systems that prefer polling instead of delegates:

IsBlinkDetected()
GetBlinkCount()
GetLastBlinkTime()

Useful for:

• Tick-driven systems
• Animation graphs
• Behavior trees
• Lightweight gameplay checks

Runtime control

Start Ollo

bool Start(...)

Starts:

• Camera capture
• Runtime initialization
• Signal processing
• Event dispatcher

Returns:

• true on successful startup

Stop Ollo

void Stop()

Stops:

• Capture
• Processing
• Signal dispatch

Safe to call multiple times.

Feeding external frames

Ollo can process externally managed frame sources using:

FeedFrameRGBA(...)

Use cases:

• Custom capture pipelines
• Virtual cameras
• Cinematic systems
• Remote streams
• XR integrations
• Proprietary hardware

This bypasses Ollo-managed camera capture and allows the runtime to operate on externally supplied RGBA frames.

Diagnostics

Startup failures

OnStartupFailed

Triggered if:

• Camera initialization fails
• Runtime setup fails
• Invalid configuration is provided

Retrieve additional details with:

Function	Description
GetLastErrorCode()	Returns the last runtime error code.
GetLastErrorString()	Returns the last runtime error message.

Best practices

Initialization

Recommended:

• Start Ollo once during application startup
• Keep tracking persistent during gameplay

Avoid repeatedly starting/stopping between levels unless necessary.

Bind before initialization

Always bind delegates before calling Start().

This ensures:

• Startup failures are captured
• No early blink events are missed

Avoid heavy logic inside delegates

Blink delegates execute on the game thread.

Keep handlers lightweight and defer expensive work when possible.

API Reference

UOlloSubsystem

Main runtime subsystem used to start tracking, receive blink events and query runtime state.

Accessible globally through:

UOlloSubsystem::Get(WorldContextObject)

Because Ollo is implemented as a UGameInstanceSubsystem, the runtime persists across level transitions unless explicitly stopped.

Runtime control

Function	Description
Start(...)	Starts camera capture and the Ollo runtime.
Stop()	Stops tracking and shuts down the runtime safely.
IsRunning()	Returns whether the runtime is currently active.
GetVersion()	Returns the current Ollo runtime version string.

Start(...)

bool Start(
    const FString& ModelPath,
    int32 CameraIndex = 0,
    int32 Width = 640,
    int32 Height = 480,
    int32 FPS = 30,
    bool bEnablePoseNormalization = true,
    bool bTelemetryEnabled = true
)

Starts the Ollo tracking runtime.

Parameters

Parameter	Description
ModelPath	Path to a custom model. Leave empty to use the built-in model.
CameraIndex	Webcam device index.
Width	Capture resolution width.
Height	Capture resolution height.
FPS	Target camera framerate.
bEnablePoseNormalization	Stabilizes tracking under head movement.
bTelemetryEnabled	Enables local runtime telemetry.

Returns

Value	Meaning
true	Runtime initialized successfully.
false	Startup failed. Use GetLastErrorString() for details.

Blink signals

Function	Description
IsBlinkDetected()	Returns whether a blink is currently detected.
GetBlinkCount()	Returns total detected blink count.
GetLastBlinkTime()	Returns timestamp of the most recent blink.

Delegates & events

OnBlinkDetected

UPROPERTY(BlueprintAssignable)
FOlloBlinkDelegate OnBlinkDetected;

Broadcast whenever a blink is detected.

Blink event payload (FOlloBlinkEvent)

Field	Description
Sequence	Incrementing blink event identifier.
Timestamp	Detection timestamp in seconds.
DurationMs	Blink duration in milliseconds.
Quality	Detection quality classification.

OnStartupFailed

UPROPERTY(BlueprintAssignable)
FOlloStartupFailedDelegate OnStartupFailed;

Triggered when the runtime fails to initialize.

Common causes:

• Camera unavailable
• Invalid configuration
• Runtime initialization failure

External Frame Input

FeedFrameRGBA(...)

bool FeedFrameRGBA(
    const TArray<uint8>& Pixels,
    int32 Width,
    int32 Height,
    double TimestampSec
)

Feeds externally managed RGBA frames into the Ollo runtime.

Use this when:

• using a custom camera pipeline
• integrating XR devices
• processing virtual camera feeds
• supplying rendered textures or remote streams

Returns

Value	Meaning
true	Frame accepted successfully.
false	Runtime rejected the frame or is not active.

Accessing the subsystem

Get(...)

static UOlloSubsystem* Get(UObject* WorldContextObject);

Retrieves the active Ollo subsystem from any valid world context.

Common usage locations:

• Actors
• Components
• GameInstance
• Blueprint graphs
• Gameplay systems

Lifecycle notes

Ollo automatically shuts down during subsystem deinitialization.

Recommended usage pattern:

Start once during application startup
Keep runtime persistent during gameplay
Stop only when tracking is no longer needed

For most projects, starting Ollo once and keeping the subsystem active across level transitions is the recommended approach.