@3dsource/angular-unreal-module/README.md

Angular Unreal module for connect with unreal engine stream

# @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

## Installation

### Prerequisites

- Angular 18+
- NgRx store and effects (v18+)

### Peer Dependencies

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

```json
{
  "@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

```shell
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):

```ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
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([]),
    // Root NgRx (if not already added in your app)
    provideStore(),
    provideEffects(),

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

    // Optional initial config
    {
      provide: UNREAL_CONFIG,
      useValue: {
        // customErrorsEndpoint?: string,
        // commandTelemetryReceiver?: string,
        // regionsPingUrl?: string,
        // screenLockerContainerId?: string,
        // dataChannelConnectionTimeout?: number,
        // playwright?: boolean, // mirrors the provider flag; can be used by services/effects
      },
    },
  ],
};
```

### 2) Use the Unreal scene component

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

```ts
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:

- isStudio: boolean = false
- useContainerAsSizeProvider: boolean = true
- studioResolutionSize: { width: number; height: number } = { width: 1920, height: 1080 }

Outputs:

- changeMouseOverScene: EventEmitter<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`.

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

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

  sendSomeCommand() {
    const packet: MetaBoxCommandPacket = {
      command: 'SomeCommand',
      parameters: {
        /* command parameters */
      },
    } as MetaBoxCommandPacket;

    // Records telemetry and dispatches store events
    this.unreal.sendCommandToUnreal(packet);
    // Or use:
    // this.unreal.emitCommand(packet); // to send as Command message
    // this.unreal.emitUIInteraction(packet); // to send as UIInteraction
  }
}
```

## Features

- Standalone Unreal Scene Component
- Command and UI Interaction API via UnrealCommunicatorService
- Event-driven status UI (freeze frame, video stats, play overlay)
- NgRx-powered state management and effects
- Optional initial configuration via UNREAL_CONFIG token

## Examples

Check the demo application for complete usage examples:

```shell
npm run demo:start
```

## Engine requirements

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