@3dsource/angular-unreal-module 0.0.170 → 0.0.172
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
|
@@ -23,10 +23,202 @@ The package is standalone and does not expose an NgModule.
|
|
|
23
23
|
|
|
24
24
|
### Styling
|
|
25
25
|
|
|
26
|
-
The package ships its own styles and
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
26
|
+
The package ships its own styles and requires no UI library. Everything it draws
|
|
27
|
+
on top of the video is customisable through three levels — take the cheapest one
|
|
28
|
+
that solves your case.
|
|
29
|
+
|
|
30
|
+
| Need | Level | Cost |
|
|
31
|
+
| ---------------------------------- | ------------- | -------------------------- |
|
|
32
|
+
| different colour / radius / font | design tokens | 3 lines of CSS |
|
|
33
|
+
| your own look for a whole block | class hooks | one class in global styles |
|
|
34
|
+
| a different set of elements inside | slots | one template |
|
|
35
|
+
|
|
36
|
+
The three levels compose: tokens recolour what stays, a class hook restyles one
|
|
37
|
+
block, a slot replaces what is inside it. A slot makes the class hook for the
|
|
38
|
+
same part irrelevant — the markup inside is then entirely yours.
|
|
39
|
+
|
|
40
|
+
#### What you can customise
|
|
41
|
+
|
|
42
|
+
These are the blocks the scene draws over the video. Nothing else is themed —
|
|
43
|
+
the video itself, and the dev-only overlays, are out of scope.
|
|
44
|
+
|
|
45
|
+
| Block | When the user sees it | Token-only | Class hook parts | Slot |
|
|
46
|
+
| -------------- | ---------------------------------- | ---------- | ------------------------------------------ | ------------------ |
|
|
47
|
+
| Loading status | while connecting, shows percentage | ✓ | `statusCard`, `statusMessage` | `unrealStatusSlot` |
|
|
48
|
+
| Resume / Start | stream paused or not yet started | ✓ | `resumeCard`, `resumeText`, `resumeButton` | `unrealResumeSlot` |
|
|
49
|
+
| AFK timeout | inactivity countdown before drop | ✓ | `afkScrim`, `afkCard`, `afkButton` | `unrealAfkSlot` |
|
|
50
|
+
|
|
51
|
+
Error dialogs (`unreal-error-modal`, `webrtc-error-modal`) are **not** part of
|
|
52
|
+
this contract: they have no class hook, no slot, and they read the
|
|
53
|
+
`@3dsource/source-ui-native` tokens (`--src-*`) rather than `--unreal-*`. They
|
|
54
|
+
also render outside the scene DOM — see the note under Design tokens.
|
|
55
|
+
|
|
56
|
+
#### 1. Design tokens
|
|
57
|
+
|
|
58
|
+
Set the `--unreal-*` variables on `app-unreal-scene` — custom properties inherit
|
|
59
|
+
through the DOM and reach every block inside.
|
|
60
|
+
|
|
61
|
+
```css
|
|
62
|
+
app-unreal-scene {
|
|
63
|
+
--unreal-surface-card: #101014;
|
|
64
|
+
--unreal-text-main: #f5f5f7;
|
|
65
|
+
--unreal-radius-card: 16px;
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
| Token | Default |
|
|
70
|
+
| ------------------------- | -------------------------------------------------------- |
|
|
71
|
+
| `--unreal-surface-card` | `#fff` |
|
|
72
|
+
| `--unreal-surface-screen` | `#fff` |
|
|
73
|
+
| `--unreal-surface-scrim` | `rgba(100, 100, 100, .7)` |
|
|
74
|
+
| `--unreal-text-main` | `#1f2937` |
|
|
75
|
+
| `--unreal-text-secondary` | `#6b7280` |
|
|
76
|
+
| `--unreal-font-family` | `system-ui, sans-serif` |
|
|
77
|
+
| `--unreal-radius-card` | `8px` |
|
|
78
|
+
| `--unreal-radius-pill` | `9999px` |
|
|
79
|
+
| `--unreal-shadow-card` | `0 26px 80px 0 rgba(0,0,0,.2), 0 0 1px 0 rgba(0,0,0,.2)` |
|
|
80
|
+
| `--unreal-accent` | `#017bff` |
|
|
81
|
+
| `--unreal-accent-hover` | `#016fe6` |
|
|
82
|
+
| `--unreal-accent-text` | `#fff` |
|
|
83
|
+
|
|
84
|
+
If `@3dsource/source-ui-native` is loaded, its tokens are used automatically
|
|
85
|
+
wherever you do not set an `--unreal-*` value.
|
|
86
|
+
|
|
87
|
+
> **Anything opened through CDK Dialog is out of reach.** The error dialogs
|
|
88
|
+
> render in a separate overlay container, outside the scene DOM, so variables
|
|
89
|
+
> set on `app-unreal-scene` never reach them — declare those on `:root`. Note
|
|
90
|
+
> that those dialogs read `--src-*`, not `--unreal-*`.
|
|
91
|
+
|
|
92
|
+
#### 2. Class hooks
|
|
93
|
+
|
|
94
|
+
Supply your own class for a part; it **replaces** the built-in decoration class.
|
|
95
|
+
The positioning class stays, so the scene layout cannot break.
|
|
96
|
+
|
|
97
|
+
```html
|
|
98
|
+
<app-unreal-scene [uiClasses]="{ resumeCard: 'my-card', statusCard: 'my-pill' }" />
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Parts: `resumeCard`, `resumeText`, `resumeButton`, `afkScrim`, `afkCard`,
|
|
102
|
+
`afkButton`, `statusCard`, `statusMessage`.
|
|
103
|
+
|
|
104
|
+
> **Your classes must live in global styles** (`styles.scss`). Declared in a
|
|
105
|
+
> component's own SCSS, Angular scopes them and they never reach the scene.
|
|
106
|
+
|
|
107
|
+
> **The two button parts behave differently.** `resumeButton` and `afkButton`
|
|
108
|
+
> put your class on the `<app-unreal-button>` host, but the `<button>` inside is
|
|
109
|
+
> a library component whose styles are scoped — and a scoped `.unreal-button`
|
|
110
|
+
> selector (0,2,0) outweighs a global `.my-cta button` (0,1,1). So the hook is
|
|
111
|
+
> good for the button's _outer_ box (width, margin, alignment); to change the
|
|
112
|
+
> button itself, use the `--unreal-accent*` tokens, or a slot if you want
|
|
113
|
+
> different markup altogether.
|
|
114
|
+
|
|
115
|
+
> **`afkScrim` and `--unreal-surface-scrim` have one caveat.** The package also
|
|
116
|
+
> ships a legacy partial, `src/lib/styles/unreal.scss`, which is not part of the
|
|
117
|
+
> published bundle and is not meant to be imported. It contains
|
|
118
|
+
> `.frame #videoPlayOverlay { background-color: … }` — an id selector that
|
|
119
|
+
> outweighs any class. If you import that partial anyway, it wins over both the
|
|
120
|
+
> class hook and the token for the AFK overlay background.
|
|
121
|
+
|
|
122
|
+
#### 3. Slots
|
|
123
|
+
|
|
124
|
+
Replace the contents of a block with your own markup. The module keeps the
|
|
125
|
+
wrapper and the visibility logic; you get the data through the template context.
|
|
126
|
+
|
|
127
|
+
```html
|
|
128
|
+
<app-unreal-scene>
|
|
129
|
+
<ng-template unrealResumeSlot let-ctx>
|
|
130
|
+
<button (click)="ctx.start()" class="my-cta">{{ ctx.isSecondStart() ? 'Resume' : 'Start' }}</button>
|
|
131
|
+
</ng-template>
|
|
132
|
+
|
|
133
|
+
<ng-template unrealStatusSlot let-ctx>
|
|
134
|
+
<my-progress [value]="ctx.percents()" />
|
|
135
|
+
</ng-template>
|
|
136
|
+
</app-unreal-scene>
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
| Directive | Context |
|
|
140
|
+
| ------------------ | --------------------------------------------- |
|
|
141
|
+
| `unrealResumeSlot` | `isSecondStart`, `isAfkDisconnect`, `start()` |
|
|
142
|
+
| `unrealAfkSlot` | `countdown` (seconds left), `reset()` |
|
|
143
|
+
| `unrealStatusSlot` | `percents`, `message` |
|
|
144
|
+
|
|
145
|
+
All context values except methods are Signals — call them in the template.
|
|
146
|
+
`percents` is `undefined` until the first value arrives — guard it if you render
|
|
147
|
+
it raw.
|
|
148
|
+
|
|
149
|
+
The context object is created once and never replaced; what changes are the
|
|
150
|
+
signals inside it. So `let-ctx` is stable and you can pass `ctx` around freely.
|
|
151
|
+
|
|
152
|
+
> **Markup inside a slot belongs to you, not to the library.** Angular scopes a
|
|
153
|
+
> template to the component that declares it, and your slot template is declared
|
|
154
|
+
> in _your_ component. Two consequences:
|
|
155
|
+
>
|
|
156
|
+
> - The library's own classes do nothing there. Writing `class="resume-box__text"`
|
|
157
|
+
> inside a slot will not pick up the module's styling — that class is scoped to
|
|
158
|
+
> the module.
|
|
159
|
+
> - Style slot content the way you style any of your own markup: your component's
|
|
160
|
+
> SCSS applies normally (no `::ng-deep`, no global stylesheet needed — unlike
|
|
161
|
+
> class hooks).
|
|
162
|
+
>
|
|
163
|
+
> The `--unreal-*` tokens **do** reach inside, because CSS custom properties
|
|
164
|
+
> inherit through the DOM. Read them if you want your markup to follow the same
|
|
165
|
+
> theme:
|
|
166
|
+
>
|
|
167
|
+
> ```scss
|
|
168
|
+
> .my-cta {
|
|
169
|
+
> background: var(--unreal-accent, #017bff);
|
|
170
|
+
> border-radius: var(--unreal-radius-card, 8px);
|
|
171
|
+
> }
|
|
172
|
+
> ```
|
|
173
|
+
|
|
174
|
+
#### Recipes
|
|
175
|
+
|
|
176
|
+
**Dark theme, nothing else.** One rule, no TypeScript:
|
|
177
|
+
|
|
178
|
+
```css
|
|
179
|
+
app-unreal-scene {
|
|
180
|
+
--unreal-surface-card: #101014;
|
|
181
|
+
--unreal-surface-screen: #0b0b0f;
|
|
182
|
+
--unreal-text-main: #f5f5f7;
|
|
183
|
+
--unreal-text-secondary: #a1a1aa;
|
|
184
|
+
--unreal-shadow-card: 0 20px 60px 0 rgb(0 0 0 / 60%);
|
|
185
|
+
}
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
**Your brand's accent on the buttons.** Buttons are recoloured with tokens, not
|
|
189
|
+
with a class hook — see the note above:
|
|
190
|
+
|
|
191
|
+
```css
|
|
192
|
+
app-unreal-scene {
|
|
193
|
+
--unreal-accent: #ff5f6d;
|
|
194
|
+
--unreal-accent-hover: #f0454f;
|
|
195
|
+
--unreal-accent-text: #fff;
|
|
196
|
+
}
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
If you need a button that is shaped differently, not just recoloured, replace
|
|
200
|
+
the whole block through `unrealResumeSlot` and render your own control.
|
|
201
|
+
|
|
202
|
+
**A completely different loading status.** Structure, not just skin — so this is
|
|
203
|
+
a slot. Visibility is still decided by the module:
|
|
204
|
+
|
|
205
|
+
```html
|
|
206
|
+
<app-unreal-scene>
|
|
207
|
+
<ng-template unrealStatusSlot let-ctx>
|
|
208
|
+
<my-brand-progress [value]="ctx.percents() ?? 0" />
|
|
209
|
+
</ng-template>
|
|
210
|
+
</app-unreal-scene>
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
#### What you cannot change
|
|
214
|
+
|
|
215
|
+
- **When a block appears.** Visibility stays with the module — the conditions
|
|
216
|
+
are non-trivial (connection state, reconnect flags, AFK timers) and duplicating
|
|
217
|
+
them in a host app is a reliable source of bugs.
|
|
218
|
+
- **Where a block sits in the scene.** Each customisable element keeps a
|
|
219
|
+
positioning class that a host class never replaces, so the scene layout cannot
|
|
220
|
+
be broken from outside. Move the block by restyling its container instead.
|
|
221
|
+
- **The video element and dev overlays** (`video-stats`, `stat-graph`).
|
|
30
222
|
|
|
31
223
|
## Setup
|
|
32
224
|
|
|
@@ -67,18 +259,18 @@ Omit `provideStore()` when the root NgRx store is already configured.
|
|
|
67
259
|
|
|
68
260
|
Available configuration fields:
|
|
69
261
|
|
|
70
|
-
| Field | Purpose
|
|
71
|
-
| ------------------------------ |
|
|
72
|
-
| `regionsPingUrl` | Region latency endpoint
|
|
73
|
-
| `dataChannelConnectionTimeout` | DataChannel connection timeout in ms
|
|
74
|
-
| `customErrorsEndpoint` | Custom error reporting endpoint
|
|
75
|
-
| `commandTelemetryReceiver` | Command telemetry endpoint
|
|
76
|
-
| `streamTelemetryV2Url` | Stream lifecycle telemetry endpoint
|
|
77
|
-
| `screenLockerContainerId` | Container used by the screen-locker overlay
|
|
262
|
+
| Field | Purpose |
|
|
263
|
+
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
264
|
+
| `regionsPingUrl` | Region latency endpoint |
|
|
265
|
+
| `dataChannelConnectionTimeout` | DataChannel connection timeout in ms |
|
|
266
|
+
| `customErrorsEndpoint` | Custom error reporting endpoint |
|
|
267
|
+
| `commandTelemetryReceiver` | Command telemetry endpoint |
|
|
268
|
+
| `streamTelemetryV2Url` | Stream lifecycle telemetry endpoint |
|
|
269
|
+
| `screenLockerContainerId` | Container used by the screen-locker overlay |
|
|
78
270
|
| `mode` | `'metabox'` (default) — full Metabox command protocol; `'default'` — stock Pixel Streaming app, the module sends no Metabox commands of its own |
|
|
79
|
-
| `fpsMonitor` | Enables FPS monitoring (currently off — the service is not instantiated)
|
|
80
|
-
| `autoHighResolution` | Raises resolution after the scene becomes idle
|
|
81
|
-
| `playwright` | Enables the test-specific service behaviour
|
|
271
|
+
| `fpsMonitor` | Enables FPS monitoring (currently off — the service is not instantiated) |
|
|
272
|
+
| `autoHighResolution` | Raises resolution after the scene becomes idle |
|
|
273
|
+
| `playwright` | Enables the test-specific service behaviour |
|
|
82
274
|
|
|
83
275
|
Use `{ provide: UNREAL_CONFIG, useValue: {} }` for the minimal configuration.
|
|
84
276
|
|
|
@@ -226,4 +418,4 @@ pnpm unreal:purge-cdn -- latest
|
|
|
226
418
|
pnpm unreal:purge-cdn -- dev
|
|
227
419
|
```
|
|
228
420
|
|
|
229
|
-
Repository tooling requires Node.js 24.16.0 or newer and pnpm 11.
|
|
421
|
+
Repository tooling requires Node.js 24.16.0 or newer and pnpm 11.21.0.
|