@3dsource/angular-unreal-module 0.0.44 → 0.0.46

package/README.md

@@ -1,16 +1,15 @@
 # @3dsource/angular-unreal-module
 
-A standalone Angular component for integrating Unreal Engine scenes into web applications. This module facilitates
-communication between Angular applications and Unreal Engine, enabling interactive 3D experiences.
+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
 
-The Angular Unreal Module provides:
+This package provides:
 
-- Seamless integration of Unreal Engine content in Angular applications
-- Communication bridge between Angular and Unreal Engine
-- State management for 3D scene interactions
-- Configurators for customizing Unreal Engine applications
+- 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
 
@@ -21,82 +20,139 @@ The Angular Unreal Module provides:
 
 ### Peer Dependencies
 
-This library requires the following peer dependencies:
+This library requires the following peer dependencies (match or exceed versions):
 
 ```json
 {
-  "@3dsource/source-ui-native": "^1.0.7",
-  "@3dsource/types-unreal": "^0.0.1",
-  "@3dsource/utils": "^1.0.13",
-  "@angular/cdk": "^19.2.0",
-  "@angular/common": "^19.2.0",
-  "@angular/core": "^19.2.0",
-  "@angular/forms": "^19.2.0",
-  "@ngrx/effects": "^19.1.0",
-  "@ngrx/operators": "^19.1.0",
-  "@ngrx/store": "^19.1.0"
+  "@3dsource/source-ui-native": ">=1.0.9",
+  "@3dsource/types-unreal": ">=0.0.5",
+  "@3dsource/utils": ">=1.0.21",
+  "@angular/cdk": ">=19.0.0",
+  "@angular/common": ">=19.0.0",
+  "@angular/core": ">=19.0.0",
+  "@angular/forms": ">=19.0.0",
+  "@ngrx/effects": ">=19.0.0",
+  "@ngrx/store": ">=19.0.0"
 }
 ```
 
 ### Library Installation
 
 ```shell
-  npm i @3dsource/angular-unreal-module
+npm i @3dsource/angular-unreal-module
 ```
 
 ## Usage
 
-### Basic Integration
-
-1. Import the UnrealModule in your Angular application:
-
-```typescript
-import { UnrealModule } from '@3dsource/angular-unreal-module';
-
-@NgModule({
-  imports: [
-    UnrealModule.forRoot({
-      // Configuration options
-    }),
+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)
+    ...provideAngularUnrealModule(),
+
+    // Optional initial config
+    { provide: UNREAL_CONFIG, useValue: { 
+        // customErrorsEndpoint?: string,
+        // commandTelemetryReceiver?: string,
+        // regionsPingUrl?: string,
+        // screenLockerContainerId?: string,
+        // dataChannelConnectionTimeout?: number,
+      } 
+    },
   ],
+};
+```
+
+### 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 AppModule {}
+export class AppComponent {
+  onHover(isOver: boolean) {
+    // handle mouse over scene
+  }
+}
 ```
 
-2. Use the Unreal scene component in your templates:
+Component selector: <app-unreal-scene>
 
-```html
-<unreal-scene [config]="unrealConfig" (sceneReady)="onSceneReady($event)"> </unreal-scene>
-```
+Inputs:
+- isStudio: boolean = false
+- useContainerAsSizeProvider: boolean = true
+- studioResolutionSize: { width: number; height: number } = { width: 1920, height: 1080 }
 
-### Communication with Unreal Engine
+Outputs:
+- changeMouseOverScene: EventEmitter<boolean>
 
-The module provides services for sending commands to and receiving events from Unreal Engine:
+### 3) Send commands / interactions to Unreal
 
-```typescript
-import { UnrealService } from '@3dsource/angular-unreal-module';
+Use UnrealCommunicatorService to send commands or UI interactions. Types for command packets are provided by @3dsource/types-unreal.
 
-@Component({ ... })
+```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 {
-  constructor(private unrealService: UnrealService) {
-  }
+  private unreal = inject(UnrealCommunicatorService);
 
-  sendCommand() {
-    this.unrealService.sendCommand({
+  sendSomeCommand() {
+    const packet: MetaBoxCommandPacket = {
       command: 'SomeCommand',
-      parameters: { /* command parameters */ }
-    });
+      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
 
-- **Unreal Scene Component**: Embed Unreal Engine content in Angular applications
-- **Command API**: Send commands to Unreal Engine
-- **Event Handling**: React to events from Unreal Engine
-- **State Management**: NgRx integration for managing 3D scene state
-- **Configuration Options**: Customize the Unreal Engine integration
+- 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
 

package/fesm2022/3dsource-angular-unreal-module.mjs

@@ -3099,7 +3099,7 @@ class UnrealEffects {
             })));
         });
         this.forceLBMOff$ = createEffect(() => {
-            return fromEvent(document, 'visibilitychange').pipe(map(() => document.visibilityState === 'visible'), filter(Truthy), withLatestFrom(this.store.select(unrealFeature.selectLowBandwidth)), filter(([, isLowBandwidth]) => !!isLowBandwidth), tapLog('forceLBMOff$'), map(() => changeLowBandwidth({ lowBandwidth: false })));
+            return fromEvent(document, 'visibilitychange').pipe(map(() => document.visibilityState === 'visible'), filter(Truthy), withLatestFrom(this.store.select(unrealFeature.selectLowBandwidth)), filter(([, isLowBandwidth]) => isLowBandwidth), tapLog('forceLBMOff$'), map(() => changeLowBandwidth({ lowBandwidth: false })));
         });
         this.resetFreezeFrameOnLowBandwidthTriggered$ = createEffect(() => {
             return this.actions$.pipe(ofType(changeLowBandwidth), map(({ lowBandwidth }) => lowBandwidth), distinctUntilChanged(), map(() => setFreezeFrame({ dataUrl: null, progress: null })));
@@ -3240,7 +3240,7 @@ const selectIsVideoPlayingAndDataChannelConnected = createSelector(unrealFeature
 const selectSignalingParameters = createSelector(unrealFeature.selectSsData, unrealFeature.selectAwsInstance, unrealFeature.selectSsInfo, (data, instance, ssInfo) => {
     const info = [];
     if (data) {
-        info.push(`${data.cirrusVersion}, ${data.branchInfo}`);
+        info.push(`${data.cirrusVersion}, ${data.branchInfo}, ${data.instanceType}`);
         info.push(`Unreal App Version: ${data.streamerVersion}`);
         info.push(`APP: ${data.streamPath}${data.streamApp}`);
     }