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

package/LICENSE

@@ -1,14 +1,14 @@
-Copyright (c) 2025 3dsource
-All Rights Reserved.
-
-This software and associated documentation files (the “Software”) are proprietary
-and confidential. Unauthorized copying, modification, distribution, or any other
-use of the Software, in whole or in part, without the prior written consent of
-the copyright holder is strictly prohibited.
-
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
-COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Copyright (c) 2025 3dsource
+All Rights Reserved.
+
+This software and associated documentation files (the “Software”) are proprietary
+and confidential. Unauthorized copying, modification, distribution, or any other
+use of the Software, in whole or in part, without the prior written consent of
+the copyright holder is strictly prohibited.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,107 +1,163 @@
-# @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.
-
-## Overview
-
-The Angular Unreal Module 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
-
-## Installation
-
-### Prerequisites
-
-- Angular 19+
-- NgRx store and effects
-
-### Peer Dependencies
-
-This library requires the following peer dependencies:
-
-```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"
-}
-```
-
-### Library Installation
-
-```shell
-  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
-    }),
-  ],
-})
-export class AppModule {}
-```
-
-2. Use the Unreal scene component in your templates:
-
-```html
-<unreal-scene [config]="unrealConfig" (sceneReady)="onSceneReady($event)"> </unreal-scene>
-```
-
-### Communication with Unreal Engine
-
-The module provides services for sending commands to and receiving events from Unreal Engine:
-
-```typescript
-import { UnrealService } from '@3dsource/angular-unreal-module';
-
-@Component({ ... })
-export class MyComponent {
-  constructor(private unrealService: UnrealService) {
-  }
-
-  sendCommand() {
-    this.unrealService.sendCommand({
-      command: 'SomeCommand',
-      parameters: { /* command parameters */ }
-    });
-  }
-}
-```
-
-## 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
-
-## Examples
-
-Check the demo application for complete usage examples:
-
-```shell
-npm run demo:start
-```
+# @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 19+
+- NgRx store and effects
+
+### 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.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
+```
+
+## 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)
+    ...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 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
+
+Use 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
+```