@3dsource/angular-unreal-module 0.0.100 → 0.0.101-dev.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -8,6 +8,7 @@ This package provides:
|
|
|
8
8
|
|
|
9
9
|
- Standalone Unreal scene component to embed UE stream
|
|
10
10
|
- Communication bridge (commands, UI interactions, input data)
|
|
11
|
+
- Callback listener for Unreal events and command responses
|
|
11
12
|
- NgRx state and effects for 3D stream lifecycle
|
|
12
13
|
- Config and utilities for telemetry, errors, and regions ping
|
|
13
14
|
- Auto-reconnection support for WebRTC/DataChannel failures
|
|
@@ -192,12 +193,12 @@ export class MyComponent {
|
|
|
192
193
|
|
|
193
194
|
### 4) Store integration (actions & selectors)
|
|
194
195
|
|
|
195
|
-
The module registers an NgRx feature state `
|
|
196
|
+
The module registers an NgRx feature state `commandsFeature`. You can dispatch actions and select state in your components:
|
|
196
197
|
|
|
197
198
|
```ts
|
|
198
199
|
import { inject } from '@angular/core';
|
|
199
200
|
import { Store } from '@ngrx/store';
|
|
200
|
-
import { startStream, setConfig, setOrchestrationContext, disconnectStream, selectTotalProgress, selectShowLoader,
|
|
201
|
+
import { startStream, setConfig, setOrchestrationContext, disconnectStream, selectTotalProgress, selectShowLoader, commandsFeature } from '@3dsource/angular-unreal-module';
|
|
201
202
|
|
|
202
203
|
// Dispatch actions
|
|
203
204
|
const store = inject(Store);
|
|
@@ -205,8 +206,8 @@ store.dispatch(startStream({ config: { autoStart: true, warnTimeout: 120 } }));
|
|
|
205
206
|
|
|
206
207
|
// Select state
|
|
207
208
|
const progress = store.selectSignal(selectTotalProgress);
|
|
208
|
-
const isVideoPlaying = store.selectSignal(
|
|
209
|
-
const dataChannelConnected = store.selectSignal(
|
|
209
|
+
const isVideoPlaying = store.selectSignal(commandsFeature.selectIsVideoPlaying);
|
|
210
|
+
const dataChannelConnected = store.selectSignal(commandsFeature.selectDataChannelConnected);
|
|
210
211
|
```
|
|
211
212
|
|
|
212
213
|
**Key selectors:**
|
|
@@ -216,9 +217,9 @@ const dataChannelConnected = store.selectSignal(unrealFeature.selectDataChannelC
|
|
|
216
217
|
- `selectShowReconnectPopup` — Whether reconnect popup should be shown
|
|
217
218
|
- `selectIsVideoPlayingAndDataChannelConnected` — Combined readiness check
|
|
218
219
|
- `selectStreamConfig` — Current stream configuration
|
|
219
|
-
- `
|
|
220
|
-
- `
|
|
221
|
-
- `
|
|
220
|
+
- `commandsFeature.selectCirrusConnected` — Signalling server connection status
|
|
221
|
+
- `commandsFeature.selectDataChannelConnected` — Data channel status
|
|
222
|
+
- `commandsFeature.selectViewportReady` — Viewport readiness
|
|
222
223
|
|
|
223
224
|
**Key actions:**
|
|
224
225
|
|
|
@@ -229,6 +230,61 @@ const dataChannelConnected = store.selectSignal(unrealFeature.selectDataChannelC
|
|
|
229
230
|
- `destroyUnrealScene` — Full teardown
|
|
230
231
|
- `reconnectPeer` — Trigger peer reconnection
|
|
231
232
|
|
|
233
|
+
### 5) Listen for Unreal callbacks
|
|
234
|
+
|
|
235
|
+
Inject `UnrealCallbackService` to listen for callback events from Unreal Engine and to observe command responses.
|
|
236
|
+
|
|
237
|
+
There are two methods:
|
|
238
|
+
|
|
239
|
+
| Method | Description |
|
|
240
|
+
| ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
|
|
241
|
+
| `fromUnrealCallback` | Listens for callbacks matching a command or event key. Supports MetaBox commands and custom Unreal callback events. |
|
|
242
|
+
| `observeCommandResponse` | Sends a command and waits for its matching response by `correlationId`. Includes timeout and error handling. |
|
|
243
|
+
|
|
244
|
+
**Custom Unreal callback events** (defined in `UnrealCallbackEventMap`):
|
|
245
|
+
|
|
246
|
+
| Event | Payload Type |
|
|
247
|
+
| -------------------------- | --------------------------------------------------- |
|
|
248
|
+
| `onSceneState` | `FSceneState` |
|
|
249
|
+
| `onFocusObject` | `FProductPayload` |
|
|
250
|
+
| `cameraChanged` | `FCameraChangedPayload` |
|
|
251
|
+
| `onObjectTransformChanged` | `{ objectName: string; transform: FTransformJson }` |
|
|
252
|
+
| `onChangeSequence` | `unknown` |
|
|
253
|
+
| `onFinishedSequence` | `unknown` |
|
|
254
|
+
|
|
255
|
+
```ts
|
|
256
|
+
import { Component, inject } from '@angular/core';
|
|
257
|
+
import { UnrealCallbackService } from '@3dsource/angular-unreal-module';
|
|
258
|
+
import { UnrealCommunicatorService } from '@3dsource/angular-unreal-module';
|
|
259
|
+
import { MetaBoxCommand } from '@3dsource/types-unreal';
|
|
260
|
+
|
|
261
|
+
@Component({ standalone: true, template: '' })
|
|
262
|
+
export class MyComponent {
|
|
263
|
+
private callbackService = inject(UnrealCallbackService);
|
|
264
|
+
private communicator = inject(UnrealCommunicatorService);
|
|
265
|
+
|
|
266
|
+
listenForCallbacks() {
|
|
267
|
+
// Listen for a MetaBox command callback
|
|
268
|
+
this.callbackService.fromUnrealCallback(MetaBoxCommand.FLoadProductCommand).subscribe((data) => console.log('Product loaded:', data));
|
|
269
|
+
|
|
270
|
+
// Listen for a custom Unreal event
|
|
271
|
+
this.callbackService.fromUnrealCallback('cameraChanged').subscribe((data) => console.log('Camera changed:', data));
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
sendAndObserve() {
|
|
275
|
+
// Send a command and observe its response (with correlationId matching)
|
|
276
|
+
this.callbackService
|
|
277
|
+
.observeCommandResponse(
|
|
278
|
+
{ command: MetaBoxCommand.FLoopBackCommand },
|
|
279
|
+
(data) => this.communicator.sendCommandToUnreal(data),
|
|
280
|
+
60000, // timeout in ms (default: 60000)
|
|
281
|
+
true, // emit on timeout (default: true)
|
|
282
|
+
)
|
|
283
|
+
.subscribe((response) => console.log('Response:', response));
|
|
284
|
+
}
|
|
285
|
+
}
|
|
286
|
+
```
|
|
287
|
+
|
|
232
288
|
## Exported API
|
|
233
289
|
|
|
234
290
|
### Components
|
|
@@ -248,23 +304,24 @@ const dataChannelConnected = store.selectSignal(unrealFeature.selectDataChannelC
|
|
|
248
304
|
|
|
249
305
|
### Services
|
|
250
306
|
|
|
251
|
-
| Service | Description
|
|
252
|
-
| ------------------------------ |
|
|
253
|
-
| `UnrealCommunicatorService` | Send commands and UI interactions to Unreal
|
|
254
|
-
| `
|
|
255
|
-
| `
|
|
256
|
-
| `
|
|
257
|
-
| `
|
|
258
|
-
| `
|
|
259
|
-
| `
|
|
260
|
-
| `
|
|
261
|
-
| `
|
|
262
|
-
| `
|
|
263
|
-
| `
|
|
264
|
-
| `
|
|
265
|
-
| `
|
|
266
|
-
| `
|
|
267
|
-
| `
|
|
307
|
+
| Service | Description |
|
|
308
|
+
| ------------------------------ | --------------------------------------------------------------- |
|
|
309
|
+
| `UnrealCommunicatorService` | Send commands and UI interactions to Unreal |
|
|
310
|
+
| `UnrealCallbackService` | Listen for Unreal callback events and observe command responses |
|
|
311
|
+
| `AggregatorService` | Aggregates data channel messages from Unreal |
|
|
312
|
+
| `SignallingService` | Manages WebSocket signalling connection |
|
|
313
|
+
| `VideoService` | Manages video element and stats |
|
|
314
|
+
| `WebRtcPlayerService` | Manages WebRTC peer connection |
|
|
315
|
+
| `FreezeFrameService` | Handles freeze frame images |
|
|
316
|
+
| `AFKService` | AFK (away from keyboard) detection and timeout |
|
|
317
|
+
| `DevModeService` | Toggle dev mode for debugging |
|
|
318
|
+
| `FileReceiverService` | Receives files from Unreal via data channel |
|
|
319
|
+
| `FileHandlerService` | Processes received files |
|
|
320
|
+
| `RegionsPingService` | Pings regions to determine latency |
|
|
321
|
+
| `CommandTelemetryService` | Records command telemetry |
|
|
322
|
+
| `StreamStatusTelemetryService` | Reports stream status telemetry |
|
|
323
|
+
| `AnalyticsService` | Analytics event tracking |
|
|
324
|
+
| `FpsMonitorService` | FPS monitoring |
|
|
268
325
|
|
|
269
326
|
### Pipes
|
|
270
327
|
|
|
@@ -274,17 +331,20 @@ const dataChannelConnected = store.selectSignal(unrealFeature.selectDataChannelC
|
|
|
274
331
|
|
|
275
332
|
### Interfaces
|
|
276
333
|
|
|
277
|
-
| Interface
|
|
278
|
-
|
|
|
279
|
-
| `UnrealInitialConfig`
|
|
280
|
-
| `ReconnectConfig`
|
|
281
|
-
| `StreamConfig`
|
|
282
|
-
| `StreamResolutionProps`
|
|
334
|
+
| Interface | Description |
|
|
335
|
+
| -------------------------- | ---------------------------------------------------------------------------- |
|
|
336
|
+
| `UnrealInitialConfig` | Shape for `UNREAL_CONFIG` injection token |
|
|
337
|
+
| `ReconnectConfig` | Auto-reconnection behavior configuration |
|
|
338
|
+
| `StreamConfig` | Stream configuration (autoStart, warnTimeout) |
|
|
339
|
+
| `StreamResolutionProps` | Stream resolution width/height |
|
|
340
|
+
| `UnrealCallbackEventMap` | Custom Unreal callback events pushed from Unreal via data channel |
|
|
341
|
+
| `UnrealCallbackDescriptor` | Combined map of MetaBoxCommandList and UnrealCallbackEventMap callback types |
|
|
283
342
|
|
|
284
343
|
## Features
|
|
285
344
|
|
|
286
345
|
- Standalone Unreal Scene Component
|
|
287
346
|
- Command and UI Interaction API via `UnrealCommunicatorService`
|
|
347
|
+
- Callback listener and command response observer via `UnrealCallbackService`
|
|
288
348
|
- Event-driven status UI (freeze frame, video stats, play overlay, AFK, low bandwidth)
|
|
289
349
|
- NgRx-powered state management and effects
|
|
290
350
|
- **Required** initial configuration via `UNREAL_CONFIG` injection token
|