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

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,138 @@ 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
+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,
+      },
+    },
+  ],
+};
+```
 
-1. Import the UnrealModule in your Angular application:
+### 2) Use the Unreal scene component
 
-```typescript
-import { UnrealModule } from '@3dsource/angular-unreal-module';
+Import the component into a standalone component and use it in the template.
 
-@NgModule({
-  imports: [
-    UnrealModule.forRoot({
-      // Configuration options
-    }),
-  ],
+```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 }
+
+Outputs:
 
-### Communication with Unreal Engine
+- 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