@3dsource/angular-unreal-module

A set of standalone Angular components, services, and providers for integrating Unreal Engine (WebRTC) scenes into Angular applications. It facilitates communication between Angular and Unreal Engine and enables interactive 3D experiences.

Overview

This package provides:

• Standalone Unreal scene component to embed UE stream
• Communication bridge (commands, UI interactions, input data)
• NgRx state and effects for 3D stream lifecycle
• Config and utilities for telemetry, errors, and regions ping
• Auto-reconnection support for WebRTC/DataChannel failures
• File receiving from Unreal Engine
• Analytics, FPS monitoring, and stream status telemetry
• Playwright testing mode with mock services

Installation

Prerequisites

• Angular 18+
• NgRx store and effects (v18+)
• Angular CDK (v18+) — used for dialog overlays
• provideHttpClient() — required by internal services (telemetry, signalling, regions ping, error reporting)

Peer Dependencies

This library requires the following peer dependencies (match or exceed versions):

{
  "@3dsource/source-ui-native": ">=1.0.9",
  "@3dsource/types-unreal": ">=0.0.7",
  "@3dsource/utils": ">=1.0.21",
  "@angular/cdk": ">=18.0.0",
  "@angular/common": ">=18.0.0",
  "@angular/core": ">=18.0.0",
  "@angular/forms": ">=18.0.0",
  "@ngrx/effects": ">=18.0.0",
  "@ngrx/store": ">=18.0.0"
}

Library Installation

npm i @3dsource/angular-unreal-module

Usage

The API is fully standalone (no NgModule). Use providers and components as shown below.

1) Provide the module services and store slice

Add providers in your application bootstrap (e.g., app.config.ts):

⚠️ Important: UNREAL_CONFIG is required — multiple internal services inject it without { optional: true }. Omitting it will cause a NullInjectorError at runtime. You can provide it with an empty object {} as a minimum.

import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideHttpClient } from '@angular/common/http';
import { provideStore } from '@ngrx/store';
import { provideEffects } from '@ngrx/effects';
import { provideAngularUnrealModule, UNREAL_CONFIG } from '@3dsource/angular-unreal-module';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter([]),
    provideHttpClient(),

    // Root NgRx (if not already added in your app)
    provideStore(),
    provideEffects(),

    // Required: Unreal initial configuration
    {
      provide: UNREAL_CONFIG,
      useValue: {
        customErrorsEndpoint: '', // Endpoint for custom error reporting
        commandTelemetryReceiver: '', // Endpoint for command telemetry
        regionsPingUrl: '', // URL prefix for regions latency ping
        screenLockerContainerId: '', // DOM container id for screen locker overlay
        dataChannelConnectionTimeout: 8000, // Timeout in ms for data channel connection (default: 8000)
        playwright: false, // Mirrors the provider flag for services/effects
        reconnect: {
          // Auto-reconnection configuration
          enabled: true, // Enable auto-reconnection (default: true)
          maxAttempts: 3, // Max reconnection attempts (default: 3)
          delayMs: 1000, // Delay between attempts in ms (default: 1000)
          onIceFailure: true, // Reconnect on ICE connection failure (default: true)
          onDataChannelClose: true, // Reconnect on DataChannel close (default: true)
        },
      },
    },

    // Unreal providers (adds feature state and effects internally)
    // Tip: pass { playwright: true } to switch to testing/dummy services
    provideAngularUnrealModule({ playwright: false }),
  ],
};

Minimal configuration

If you don't need custom endpoints, provide UNREAL_CONFIG with an empty object:

{ provide: UNREAL_CONFIG, useValue: {} },
provideAngularUnrealModule(),

2) Use the Unreal scene component

Import the component into a standalone component and use it in the template.

import { Component } from '@angular/core';
import { UnrealSceneComponent } from '@3dsource/angular-unreal-module';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [UnrealSceneComponent],
  template: ` <app-unreal-scene [isStudio]="false" [useContainerAsSizeProvider]="true" [studioResolutionSize]="{ width: 1920, height: 1080 }" (changeMouseOverScene)="onHover($event)"> </app-unreal-scene> `,
})
export class AppComponent {
  onHover(isOver: boolean) {
    // handle mouse over scene
  }
}

Component selector: <app-unreal-scene>

Inputs:

| Input | Type | Default | | ---------------------------- | ----------------------------------- | ------------------------------- | | isStudio | boolean | false | | useContainerAsSizeProvider | boolean | true | | studioResolutionSize | { width: number; height: number } | { width: 1920, height: 1080 } |

Outputs:

| Output | Type | | ---------------------- | --------------------------- | | changeMouseOverScene | OutputEmitterRef<boolean> |

3) Send commands / interactions to Unreal

Inject UnrealCommunicatorService to send commands or UI interactions. Types for command packets are provided by @3dsource/types-unreal.

There are three sending methods — choose based on your needs:

| Method | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | sendCommandToUnreal | Full pipeline: adds correlationId, records telemetry, dispatches NgRx commandStarted action. Recommended for application commands. | | emitUIInteraction | Sends the packet as a raw UIInteraction message. No telemetry or store dispatch. | | emitCommand | Sends the packet as a raw Command message (for console commands, resolution changes, etc.). |

import { Component, inject } from '@angular/core';
import { UnrealCommunicatorService } from '@3dsource/angular-unreal-module';
import { MetaBoxCommand } from '@3dsource/types-unreal';
import type { MetaBoxCommandPacket } from '@3dsource/types-unreal';

@Component({ standalone: true, template: '' })
export class MyComponent {
  private unreal = inject(UnrealCommunicatorService);

  sendSomeCommand() {
    // Recommended: use sendCommandToUnreal for full telemetry + store tracking
    this.unreal.sendCommandToUnreal({
      command: MetaBoxCommand.FChangeResolutionCommand,
      payload: { resolution: { x: 1920, y: 1080 } },
    });
  }

  sendRawUIInteraction() {
    // Low-level: sends UIInteraction message without telemetry tracking
    const packet = {
      command: 'CustomCommand',
      payload: { key: 'value' },
    } as MetaBoxCommandPacket;
    this.unreal.emitUIInteraction(packet);
  }
}

4) Store integration (actions & selectors)

The module registers an NgRx feature state unrealFeature. You can dispatch actions and select state in your components:

import { inject } from '@angular/core';
import { Store } from '@ngrx/store';
import { startStream, setConfig, setOrchestrationContext, disconnectStream, selectTotalProgress, selectShowLoader, unrealFeature } from '@3dsource/angular-unreal-module';

// Dispatch actions
const store = inject(Store);
store.dispatch(startStream({ config: { autoStart: true, warnTimeout: 120 } }));

// Select state
const progress = store.selectSignal(selectTotalProgress);
const isVideoPlaying = store.selectSignal(unrealFeature.selectIsVideoPlaying);
const dataChannelConnected = store.selectSignal(unrealFeature.selectDataChannelConnected);

Key selectors:

• selectTotalProgress — Scene load progress (0–1 float)
• selectShowLoader — Whether loader screen should be visible
• selectShowReconnectPopup — Whether reconnect popup should be shown
• selectIsVideoPlayingAndDataChannelConnected — Combined readiness check
• selectStreamConfig — Current stream configuration
• unrealFeature.selectCirrusConnected — Signalling server connection status
• unrealFeature.selectDataChannelConnected — Data channel status
• unrealFeature.selectViewportReady — Viewport readiness

Key actions:

• startStream — Start streaming with config
• setConfig — Update stream configuration
• setOrchestrationContext — Set orchestration URLs and environment
• disconnectStream — Disconnect with reason
• destroyUnrealScene — Full teardown
• reconnectPeer — Trigger peer reconnection

Exported API

Components

| Component | Selector | Description | | -------------------------------- | ------------------ | -------------------------------------- | | UnrealSceneComponent | app-unreal-scene | Main scene container with video stream | | AfkTimeoutModalComponent | — | AFK timeout warning modal | | FreezeFrameComponent | — | Freeze frame overlay | | LowBandwidthModalComponent | — | Low bandwidth warning modal | | LowBandwidthIndicatorComponent | — | Low bandwidth indicator | | ImageLoadingSrcComponent | — | Loading image overlay | | IntroSrcComponent | — | Intro image/video overlay | | VideoStatsComponent | — | Video statistics display | | StatGraphComponent | — | Statistics graph | | WebrtcErrorModalComponent | — | WebRTC error modal |

Services

| Service | Description | | ------------------------------ | ---------------------------------------------- | | UnrealCommunicatorService | Send commands and UI interactions to Unreal | | AggregatorService | Aggregates data channel messages from Unreal | | SignallingService | Manages WebSocket signalling connection | | VideoService | Manages video element and stats | | WebRtcPlayerService | Manages WebRTC peer connection | | FreezeFrameService | Handles freeze frame images | | AFKService | AFK (away from keyboard) detection and timeout | | DevModeService | Toggle dev mode for debugging | | FileReceiverService | Receives files from Unreal via data channel | | FileHandlerService | Processes received files | | RegionsPingService | Pings regions to determine latency | | CommandTelemetryService | Records command telemetry | | StreamStatusTelemetryService | Reports stream status telemetry | | AnalyticsService | Analytics event tracking | | FpsMonitorService | FPS monitoring |

Pipes

| Pipe | Description | | -------------- | ------------------------------- | | SafeHtmlPipe | Bypasses Angular HTML sanitizer |

Interfaces

| Interface | Description | | ----------------------- | --------------------------------------------- | | UnrealInitialConfig | Shape for UNREAL_CONFIG injection token | | ReconnectConfig | Auto-reconnection behavior configuration | | StreamConfig | Stream configuration (autoStart, warnTimeout) | | StreamResolutionProps | Stream resolution width/height |

Features

• Standalone Unreal Scene Component
• Command and UI Interaction API via UnrealCommunicatorService
• Event-driven status UI (freeze frame, video stats, play overlay, AFK, low bandwidth)
• NgRx-powered state management and effects
• Required initial configuration via UNREAL_CONFIG injection token
• Auto-reconnection on WebRTC/DataChannel failures (configurable)
• File receiving from Unreal Engine via data channel
• Analytics and FPS monitoring
• Playwright testing mode with mock service substitution

Examples

Check the demo application for complete usage examples:

npm run demo:start

See also: projects/demo/src/app/demo-layout/info-pages/unreal-scene-demo/constants/unreal.routes.ts for a real-world provider configuration example.

Engine requirements

• Node.js: >=20
• npm: >9