diff --git a/Frontend/Docs/Communicating from UE5 to the Player Page.md b/Frontend/Docs/Communicating from UE5 to the Player Page.md index 97074eb1..8272d2f1 100644 --- a/Frontend/Docs/Communicating from UE5 to the Player Page.md +++ b/Frontend/Docs/Communicating from UE5 to the Player Page.md @@ -1,31 +1,31 @@ -**TO DO**: Update this information to match the new front end. - ## Communicating from UE5 to the Player Page You can make your Unreal Engine application emit custom events to all connected player HTML pages, which you can respond to in the player's JavaScript environment. This lets you change your web page UI in response to gameplay events. To set this up: -1. In your Unreal Engine application, any time you want to emit an event to the player page, use the **Pixel Streaming > Send Pixel Streaming Response** node. Specify a custom string argument to the node to indicate to the player page what event has happened. +1. In your Unreal Engine application, any time you want to emit an event to the player page, you need an actor with a **Pixel Streaming Input** component. This component has access to the **Send Pixel Streaming Response** node. Specify a custom string argument to the node to send a message to the web frontend.

- Send game event + Send game event

-2. In the JavaScript of your player page, you'll need to write a custom event handler function that will be invoked each time the page receives a response event from the Unreal Engine application. It will be passed the original string argument that was sent by the **Send Pixel Streaming Response** node. For example: +2. In your TypeScript frontend implementation these messages are consumed by an event listener. This event will be invoked every time the frontend receives a custom message from the Unreal Engine application. The original string argument given to the **Send Pixel Streaming Response** node will be passed to the function as the `response` argument. For example: - function myHandleResponseFunction(data) { - console.warn("Response received!"); - switch (data) { - case "MyCustomEvent": - ... // handle one type of event - case "AnotherEvent": - ... // handle another event - } - } +```typescript + public myHandleResponseFunction(response: string) => void { + Logger.Info(Logger.GetStackTrace(), "Response received!"); + switch (response) { + case "MyCustomEvent": + ... // handle one type of event + case "AnotherEvent": + ... // handle another event + } + } +``` -3. Register your listener function by calling the `addResponseEventListener` function provided by `app.js`. You pass this function a unique name for your event listener, and your function. For example: +3. Register your listener function by using the `addResponseEventListener` function provided by the `PixelStreaming` object, found in PixelStreaming/PixelStreaming.ts. You pass this function a unique name for your event listener, and your function. For example: addResponseEventListener("handle_responses", myHandleResponseFunction); @@ -34,11 +34,11 @@ To set this up: removeResponseEventListener("handle_responses"); **_Tip:_** -If you want to pass more complex data, you can format the string you pass to the **Send Pixel Streaming Response** node as JSON. For example: +If you want to pass more complex data, you can format the string you pass to the **Pixel Streaming Input -> Send Pixel Streaming Response** node as JSON. For example:

Send Pixel Streaming response using JSON

-Then, in your JavaScript event handler function, use `JSON.parse(data)` to decode the string back into a JavaScript object. +Then, in your response event handler function, use `JSON.parse(data)` to decode the string back into a TypeScript object. diff --git a/Frontend/Docs/Communicating from the Player Page to UE5.md b/Frontend/Docs/Communicating from the Player Page to UE5.md index 7077e9c6..b5d7f41c 100644 --- a/Frontend/Docs/Communicating from the Player Page to UE5.md +++ b/Frontend/Docs/Communicating from the Player Page to UE5.md @@ -1,51 +1,66 @@ -**TO DO**: Update this information to match the new front end. - ## Communicating from the Player Page to UE5 -The `app.js` file provides two JavaScript functions that you can call in your HTML player page to allow the user to send events and commands from the browser to the Unreal Engine application: +The frontend provides three functions that you can call in your HTML player page to allow the user to pass events and commands from the browser to your Unreal Engine application: + +* `emitCommand` Allows sending arbitrary commands to the game in the form of JSON objects. +* You can use `emitConsoleCommand` to send console commands back to Unreal Engine. For example, `stat fps` to show the frame rate. See [Using the emitCommand Function below](#using-the-emitcommand-function). +* `emitUIInteraction` sends any arbitrary string or object to the game. Use this function to send your own custom commands from your player UI, which you can respond to in your gameplay logic to produce any effect you need in your application. See [Using the emitUIInteraction Function below](#using-the-emituiinteraction-function). -* You can use `emitCommand` to send console commands back to Unreal Engine. For example, `stat fps` to show the frame rate. See [Using the emitCommand Function below](#using-the-emitcommand-function). -* `emitUIInteraction` sends any arbitrary string or JavaScript object to the game. Use this function to send your own custom commands from your player UI, which you can respond to in your gameplay logic to produce any effect you need in your application. See [Using the emitUIInteraction Function below](#using-the-emituiinteraction-function). ### Using the emitCommand Function -When you call the `emitCommand` function, you must pass it a JavaScript object. This object must contain a key that matches one of the following strings: +When you call the `emitCommand` function, you pass it an object which then gets converted to JSON and sent onward to the game. This can then be used for implementing any sort of custom functionality you may require. + +#### Reserved Keywords + +Though you are given free reign to organize commands how you see fit, if the object contains a key with one of the following reserved keywords it will be interpreted by the PixelStreaming module instead: * `ConsoleCommand` \- Use this key to execute a console command on the remote Unreal Engine application. The value of this key should be a string that contains the command you want to run, along with any parameters it needs. For example: - let descriptor = { - ConsoleCommand: 'stat fps' - } - emitCommand(descriptor); +```typescript + let descriptor = { + ConsoleCommand: 'stat fps' + } + emitCommand(descriptor); +``` **_NOTE:_** -Due to the power of the Unreal Engine console commands, the `emitCommand` function can present a security risk. In order for this function to work, you also need to provide the `-AllowPixelStreamingCommands` parameter on the command line when you launch your Unreal Engine application or start it from the Unreal Editor using the Standalone Game option. +Due to the power of the Unreal Engine console commands, the `emitConsoleCommand` function can present a security risk. In order for this function to work, you also need to provide the `-AllowPixelStreamingCommands` parameter on the command line when you launch your Unreal Engine application or start it from the Unreal Editor using the Standalone Game option. + + +### Using the emitConsoleCommand Function + +You may also use `emitConsoleCommand` to pass Unreal Engine console commands as a string. Like passing commands via `emitCommand`, you must provide `-AllowPixelStreamingCommands` on the command line when you launch your Unreal Engine application in order for these commands to be fielded. ### Using the emitUIInteraction Function -When you call the `emitUIInteraction` function, you can pass it a single string or JavaScript object. For example: +When you call the `emitUIInteraction` function, you can pass it a single string or object. For example: - emitUIInteraction("MyCustomCommand"); +```typescript + emitUIInteraction("MyCustomCommand"); +``` or - let descriptor = { - LoadLevel: "/Game/Maps/Level_2" - PlayerCharacter: { - Name: "Shinbi" - Skin: "Dynasty" - } - } - emitUIInteraction(descriptor); +```typescript + const descriptor = { + LoadLevel: "/Game/Maps/Level_2", + PlayerCharacter: { + Name: "Shinobi", + Skin: "Dynasty", + }, + }; + this.stream.emitUIInteraction(descriptor); +``` -If you pass a JavaScript object, the `emitUIInteraction` function converts it to a JSON string internally. It then passes the resulting string back to the Pixel Streaming Plugin in your Unreal Engine application, which raises an event on the input controller. In your application's gameplay logic, you bind your own custom event to handle these inputs, using the **Bind Event to OnPixelStreamingInputEvent** node. For example: +If you pass an object, the `emitUIInteraction` function converts it to a JSON string internally. It then passes the resulting string back to the Pixel Streaming Plugin in your Unreal Engine application, which raises an event on the input controller. In your application's gameplay logic, you bind your own custom event to handle these inputs, using the **Pixel Streaming Input > Bind Event to On Input Event** node. For example:

- Bind Event to OnPixelStreamingInputEvent + Bind Event to On Input Event

-You need to bind this event once, typically at the start of your game. Each time any player HTML page connected to an instance of your Unreal Engine application calls the `emitUIInteraction`function, your custom event is automatically invoked, regardless of the input passed to `emitUIInteraction`. +You need to bind this event once, typically at the start of your game. Each time any player HTML page connected to an instance of your Unreal Engine application calls the `emitUIInteraction` function, your custom event is automatically invoked, regardless of the input passed to `emitUIInteraction`. The custom event you assign (for example, the **UI Interaction** node in the image above) has an output named **Descriptor**, which you can use to retrieve the string that was sent to your Unreal Engine application by the `emitUIInteraction` function. You can use that value to determine how your gameplay code needs to respond each time `emitUIInteraction` is called. @@ -53,17 +68,18 @@ For example, the following Blueprint tests to see whether the input given to `em

- Search for substring + Search for substring

If you originally passed a JavaScript object to `emitUIInteraction`, you can retrieve the value of any key from that JSON object using the **Pixel Streaming > Get Json String Value** node. For example, the following Blueprint tests for a key named LoadLevel. If that key is present, it calls a custom function to handle the event:

- Get a JSON field value + Get a JSON field value

**_Tip:_** -If you need to retrieve a nested key, use the dot notation common in JavaScript for your key. -For example, `PlayerCharacter.Name` or `PlayerCharacter.Skin`. \ No newline at end of file +If you need to retrieve a nested key, use the dot notation common in TypeScript for your key. +For example, `PlayerCharacter.Name` or `PlayerCharacter.Skin`. + diff --git a/Frontend/Docs/Customizing Player Input Options.md b/Frontend/Docs/Customizing Player Input Options.md index 0ef9aae1..70013376 100644 --- a/Frontend/Docs/Customizing Player Input Options.md +++ b/Frontend/Docs/Customizing Player Input Options.md @@ -2,46 +2,44 @@ The frontend library exposes a number of configuration options through the [Config](/Frontend/library/src/Config/Config.ts) class. The values of these options can be modified to tweak certain inbuilt behaviour of the frontend. -The following options are available in the frontend library: +The following options are available in the frontend library to customize input: -**TO DO**: Update this information to match the new front end. +| Property | Default | Description | +| --- | --- | --- | +| HoveringMouseMode | false | Determines whether or not the video element captures and locks the mouse when the player interacts with the widget. When enabled, the mouse cursor hovers over the player widget without interacting with it. In order to send the mouse movements to the input controller of the Unreal Engine application, the user needs to click and hold the left button of the mouse. Otherwise, clicking on the player widget causes it to capture and lock the mouse cursor. Any further movements of the mouse are passed immediately to the input controller in the Unreal Engine application. This typically allows the user to move and rotate the camera by simply dragging the mouse. To release the cursor from the control of the player widget, the user can press the **Esc** key. | +| SuppressBrowserKeys | true | When this setting is enabled, the player widget will intercept function keys (**F1** to **F12**) and the **Tab** key, and pass those keypress events through to the Unreal Engine application rather than allowing the browser to process them normally.| This means, for example, that while this setting is active, pressing **F5** will not refresh the player page in the browser. Instead, that event is passed through to the Unreal Engine application, and has its usual function of switching the view to visualize shader complexity. +| FakeMouseWithTouches | false | When this option is enabled and the user is viewing the stream on a device with a touch screen such as a smartphone or tablet, this setting causes single-finger touch events to be interpreted by the Unreal Engine application as mouse clicks and drag events. Enabling this setting can provide users on mobile devices with the ability to partially control your Unreal Engine application, even when the application's input controller does not specifically handle touch input events. | -| Property | Default | Description | -| --- | --- | --- | -| controlScheme | `ControlSchemeType.LockedMouse` | Determines whether or not the player widget captures and locks the mouse when the player interacts with the widget.| -| suppressBrowserKeys | true |When this setting is enabled, the player widget will intercept function keys (**F1** to **F12**) and the **Tab** key, and pass those keypress events through to the Unreal Engine application rather than allowing the browser to process them normally.| This means, for example, that while this setting is active, pressing **F5** will not refresh the player page in the browser. Instead, that event is passed through to the Unreal Engine application, and has its usual function of switching the view to visualize shader complexity. -| fakeMouseWithTouches | false | When this option is enabled, and the user is viewing the stream on a device with a touch screen such as a smartphone or tablet, this setting causes single-finger touch events to be interpreted by the Unreal Engine application as mouse clicks and drag events. Enabling this setting can provide users on mobile devices with the ability to partially control your Unreal Engine application, even when the application's input controller does not specifically handle touch input events. | +When creating a frontend implementation, these options are visible via the [`Config`](/Frontend/library/src/Config/Config.ts) object required in order to create a [`PixelStreaming`](/Frontend/library/src/PixelStreaming/PixelStreaming.ts) stream for your frontend application. Simply set the values you want before initializing the stream object. +```typescript + const config = new Config({ useUrlParams: true }); + config.setFlagEnabled(Flags.HoveringMouseMode, true); + config.setFlagEnabled(Flags.FakeMouseWithTouches, true); -**_NOTE:_** The controlScheme accepts the following values: -* `ControlSchemeType.LockedMouse` - When this control scheme is active, clicking on the player widget causes it to capture and lock the mouse cursor. Any further movements of the mouse are passed immediately to the input controller in the Unreal Engine application. This typically allows the user to move and rotate the camera by simply dragging the mouse. To release the cursor from the control of the player widget, the user can press the **Esc** key. -* `ControlSchemeType.HoveringMouse` - When this control scheme is active, the mouse cursor hovers over the player widget without interacting with it. In order to send the mouse movements to the input controller of the Unreal Engine application, the user needs to click and hold the left button of the mouse. - - -You can set these values in your player page by including a code block like the following. Make sure that you run this code any time after you load the `app.js` file into the page, but before you call its `load` function. - - + const stream = new PixelStreaming(config); +``` ### Disabling User Input -To disable user input entirely for one or more types of input device, you can override the following functions in the JavaScript environment for your player page with empty implementations: +User input can be disabled entirely for one or more types of input device. This is controlled by the following input flags, all of which are enabled by default. -* **registerHoveringMouseEvents** - Disables all input mouse events when the inputOptions.controlScheme is set to ControlSchemeType.HoveringMouse. -* **registerLockedMouseEvents** - Disables all input mouse events when the inputOptions.controlScheme is set to ControlSchemeType.LockedMouse. -* **registerTouchEvents** - Disables touch events on mobile devices and tablets. -* **registerKeyboardEvents** - Disables all keyboard events. +* **MouseInput** - Allows mouse input events. +* **KeyboardInput** - Allows keyboard input events. +* **TouchInput** - Allows touch events on mobile devices and tablets. +* **GamepadInput** - Allows input events from gamepad controllers. +* **XRControllerInput** - Allows input events from XR controllers for use with AR and VR setups. -For example, you could include this block of JavaScript in your player HTML page to disable all inputs. As above, run this code any time after you load the `app.js` file into the page, but before you call its `load` function. +For example, you could set all of these flags to false in the `Config` object in order to block user input altogether. - +```typescript + const config = new Config({ useUrlParams: true }); + config.setFlagEnabled(Flags.MouseInput, false); + config.setFlagEnabled(Flags.KeyboardInput, false); + config.setFlagEnabled(Flags.TouchInput, false); + config.setFlagEnabled(Flags.GamepadInput, false); + config.setFlagEnabled(Flags.XRControllerInput, false); -To keep one or more types of inputs active, comment out or remove the line that corresponds to the type of input you want to keep. + const stream = new PixelStreaming(config); +``` diff --git a/Frontend/Docs/Customizing the Player Webpage.md b/Frontend/Docs/Customizing the Player Webpage.md index ed30bcc2..3372202a 100644 --- a/Frontend/Docs/Customizing the Player Webpage.md +++ b/Frontend/Docs/Customizing the Player Webpage.md @@ -1,21 +1,15 @@ -**TO DO**: Update this information to match the new front end. +## Recommended Reading +We recommend starting with the [sample implementations](/Frontend/implementations/EpicGames/src) in order to judge how to put a new player page together and integrate it with your Unreal Engine application. Additionally, if you have cloned the Pixel Streaming Infrastructure repository and made upstream changes, you can fork the repo and make a pull request. -## Customising the Player Webpage -The Pixel Streaming Signaling and Web Server provides a sample player page that is already set up to stream in media from your Unreal Engine application and to send mouse, keyboard, and touch events back to the application. You can use this default player page as-is, if it meets your needs.  - -Recent changes to Pixel Streaming have moved the front end and web server elements of Pixel Streaming to an external repository. We refer to this as the Pixel Streaming Infrastructure. -There are a few ways to access the Pixel Streaming infrastructure. -1. Directly access the github repository as found here: [https://github.com/EpicGames/PixelStreamingInfrastructure](https://github.com/EpicGames/PixelStreamingInfrastructure) -1. Use `git clone --branch UE5.1 https://github.com/EpicGames/PixelStreamingInfrastructure.git` in your preferred terminal (make sure you have git installed). -1. Navigate to `\Engine\Plugins\Media\PixelStreaming\Resources\WebServers` and run the `get_ps_servers` command (make sure to use the `.bat` script for Windows and `.sh` script for Linux accordingly). This will automatically pull the relevant branch of the Pixel Streaming infrastructure into that folder. -The git command mentioned above will pull the 5.1 branch of the infrastructure. If you need a different branch, please modify the git command accordingly. +## Customising the Player Webpage +The Pixel Streaming Signalling and Web Server provides a sample player page that is already set up to stream in media from your Unreal Engine application and to send mouse, keyboard, and touch events back to the application. You can use this default player page as-is, if it meets your needs. -For more information about the Pixel Streaming front end and webserver changes, see [Pixel Streaming Infrastructure](https://docs.unrealengine.com/5.1/en-US/pixel-streaming-infrastructure/) +However, with a little creativity and some knowledge of web technologies like TypeScript, HTML, and CSS, you can take full control over the player page, creating your own custom UIs for interacting with your Unreal Engine content remotely. You can trigger and respond to gameplay events, issue console commands to control the Unreal Engine's behavior, and more. +The pixel streaming infrastructure comes with a few [example implementations](/Frontend/implementations/) already provided which can be used to reference how the player webpage itself is structured. Any required HTML is added to the page when the [`Application`](/Frontend/ui-library/src/Application/Application.ts) is attached. Your application should have a `rootElement` comprising the the required HTML elements to form the basis for your player page. This element then needs to be attached to the page, in the example implementations this is attached directly to the body itself. -However, with a little creativity and some knowledge of web technologies like JavaScript and HTML, you can take full control over the player page, creating your own custom UIs for interacting with your Unreal Engine content remotely. You can trigger and respond to gameplay events, issue console commands to control the Unreal Engine's behavior, and more. +Further customizations can also be done using [`Overlays`](/Frontend/ui-library/src/Overlay). As the name suggests these are overlaid onto the player page when certain conditions are met, such as the player being [absent](/Frontend/ui-library/src/AFKOverlay.ts) from the keyboard. Look through [`Application`](/Frontend/ui-library/src/Application/Application.ts) source to see what those conditions are as well as how new overlays can be added. -We recommend using the default player page as a starting point for creating your own custom player page. You'll find this page at `PixelStreamingInfrastructure\SignallingWebServer\Public\player.html` under your Unreal Engine installation folder. Then, use the information on this page to learn how to extend your page and tie it in with your Project's gameplay logic. +For an overview on how to change the CSS style of the player and its component widgets, see [Customizing the Player Widget Style](/Frontend/Docs/Customizing%20the%20Player%20Widget%20Style.md). -Additionally, if you have cloned the Pixel Streaming Infrastructure repository and made upstream changes, you can fork the repo and make a pull request. \ No newline at end of file diff --git a/Frontend/Docs/Customizing the Player Widget Style.md b/Frontend/Docs/Customizing the Player Widget Style.md index 866b6856..be4346e4 100644 --- a/Frontend/Docs/Customizing the Player Widget Style.md +++ b/Frontend/Docs/Customizing the Player Widget Style.md @@ -1,11 +1,8 @@ -**TO DO**: Update this information to match the new front end. - ## Customizing the Player Widget Style -In your custom HTML player page, you should have defined the Pixel Streaming player widget: a `div` element with `id="player"`. You can use standard HTML and CSS methods to add styling to this widget. +CSS Styles for the frontend application are applied on page-load using [`PixelStreamingApplicationStyle`](/Frontend/ui-library/src/Styles/PixelStreamingApplicationStyles.ts) object, which is then applied to the page using the `PixelStreamingApplicationStyle.applyStyleSheet` method. This must be invoked in your implementation before the the application object is created and added to the page. -However, the widget may occasionally need to reinitialize its size. This typically occurs when the browser window is resized (if the widget is set to automatically fill the available space), or when the resolution of the input video stream is updated. When this happens, the `style` attribute of the player element is overwritten with new values, which can potentially overwrite values that you have set in your own HTML or JavaScript. +Rather than altering or extending the `PixelStreamingApplicationStyle` class, the constructor can be supplied with an object containing your desired CSS options as well as separate base color palettes (reused extensively by the default style) for light mode and dark mode. Further customizations to the base color palette can be made either by using the `setColorMode` method to select light mode or dark, or by invoking `applyPalette` with a custom `ColorPalette`. -To avoid this, you can set your custom CSS values in a special global variable named `styleAdditional`. Whenever `app.js` needs to resize the player and clear its style, it will append the values you set in the `styleAdditional` variable to the end of the new style attributes it assigns to the player element. For example, the following value changes the mouse cursor to a hand when the user hovers the mouse over the player widget: +This system will apply over any existing CSS in your implementation's HTML page and so it is recommended this method be used for the cleanest interoperability with the rest of the frontend infrastructure. - styleAdditional = 'cursor: grab; cursor: -moz-grab; cursor: -webkit-grab'; diff --git a/Frontend/Docs/HTML Page Requirements.md b/Frontend/Docs/HTML Page Requirements.md index 371f8948..c2791a0a 100644 --- a/Frontend/Docs/HTML Page Requirements.md +++ b/Frontend/Docs/HTML Page Requirements.md @@ -1,33 +1,39 @@ -**TO DO**: Update this information to match the new front end. - ## HTML Page Requirements -Your custom HTML player page must follow a few minimal requirements. - -* You must include the `/scripts/webRtcPlayer.js` file. This file handles communication between the browser and the Unreal Engine application, receiving and showing the media stream from the server. Do not modify this JavaScript file unless absolutely necessary. - - +Most of the HTML that will end up on the final page will actually be introduced by the Pixel Streaming application itself. Several example HTML pages are provided in the [sample implementations](/Frontend/implementations/EpicGames/src) where you can see the base page is very minimal, only serving as a space for the application to attach to and fill. The only concrete requirements are for ensuring there's sufficient space taken up by the element being attached to for the viewport to be visible on screen. In the sample implementations this is simply a `` tag set to fill the screen without scrolling. -* We highly recommend that you also include the */scripts/app.js* file as well. This file sets up event listeners that process the keyboard, mouse, and touch events. It also contains several functions and hooks that you can take advantage of in your player page, described in the sections below on this page. If you have some knowledge of JavaScript, you should feel free to dig into the code of this file and modify the default behavior to suit your needs. For example, if you want to disable keyboard inputs but leave mouse and touch events working, you will need to customize this file by finding and commenting out the code that handles keyboard events. +```html + + + - + + + + -* The page must have a `div` element with the ID `player`. This element is replaced with the video frames streamed from the UE5 application. + + -
+ -* You must call the `load` function provided by the `app.js` file when your page loads. For example, you can do this by adding an `onload` handler to the `body` tag: + +``` - +As can be seen in the [sample implementations](/Frontend/implementations/EpicGames/src/player.ts), you must specify which element on the page the Pixel Streaming viewport is to be appended to. In the sample implementations this is typically done in the `document.body.onload` event listener and in this case appended to the `document.body` element in the DOM, causing it to fill the whole page. +[//]: # (This has yet to be done) ### Player File Location and URL You have a few options for where you can place your custom HTML player page, and how client browsers can access it. -* You can make a folder called `custom_html` inside the root folder of your Signaling and Web Server, and place your custom HTML player page inside this folder. It will then be accessible by appending its filename to the IP address or hostname of the computer running the Signaling and Web Server. - For example, a file named `custom_html/myplayerpage.html` would be accessible at `http://127.0.0.1/myplayerpage.html`. -* You can customize the `HomepageFile` parameter for the Signaling and Web Server, and set the path to the filename of your custom HTML player page relative to the root folder of the Signaling and Web Server. It will then be accessible when you access the IP address or hostname of the computer running the Signaling and Web Server. - For example, if you save a file to `Engine/Source/Programs/PixelStreaming/WebServers/SignallingWebServer/myfolder/myplayerpage.html`, and you set the `HomepageFile` parameter to `myfolder/myplayerpage.html`, the page would be accessible without needing to provide a file name in the URL: `http://127.0.0.1/`. +* You can create a new implementation page and place it in [`/Frontend/implementations/EpicGames/src/`](/Frontend/implementations/EpicGames/src) alongside the sample implementations. This must consist of both a base `.html` page and the `.ts` source for your application's entrypoint. This will then be accessible by appending the name of the `html` file to IP address or hostname of the computer running the Signalling Server. + For example, the sample `stresstest` page can be accessed on a locally-running infrastructure at `http:/127.0.0.1/stresstest.html`. +* You can customize the `HomepageFile` parameter for the Signaling and Web Server, and set the path to the filename of your custom HTML player page relative to the [Frontend implementations source folder](/Frontend/implementations/src). It will then be accessible when you access the IP address or hostname of the computer running the Signaling and Web Server. * You can also use the **AdditionalRoutes** parameter for the Signaling and Web Server to customize the mapping between URL paths and local folders on your computer. -For additional details on these parameters, see also the [Pixel Streaming Reference](https://docs.unrealengine.com/5.1/en-US/unreal-engine-pixel-streaming-reference/). +For additional details on these parameters, see also the [Pixel Streaming Reference](https://docs.unrealengine.com/5.2/en-US/unreal-engine-pixel-streaming-reference/). + +### Building the Frontend +When starting the infrastructure Signalling Server, the Frontend should be built automatically. If not, you can run the [`setup script`](/SignallingWebServer/platform_scripts/) for your platform to do so. If you subsequently make any changes to your local copy of the frontend, you will need to run the script again, appending `--build` as an argument to force a rebuild. + diff --git a/Frontend/Docs/Resources/Images/afk-warning.png b/Frontend/Docs/Resources/Images/afk-warning.png index f12fe8e2..c48abc54 100644 Binary files a/Frontend/Docs/Resources/Images/afk-warning.png and b/Frontend/Docs/Resources/Images/afk-warning.png differ diff --git a/Frontend/Docs/Resources/Images/pixelstreaming-respond-json.JPG b/Frontend/Docs/Resources/Images/pixelstreaming-respond-json.JPG deleted file mode 100644 index 4030bbac..00000000 Binary files a/Frontend/Docs/Resources/Images/pixelstreaming-respond-json.JPG and /dev/null differ diff --git a/Frontend/Docs/Resources/Images/pixelstreaming-respond-json.png b/Frontend/Docs/Resources/Images/pixelstreaming-respond-json.png deleted file mode 100644 index 7a4fb7ae..00000000 Binary files a/Frontend/Docs/Resources/Images/pixelstreaming-respond-json.png and /dev/null differ diff --git a/Frontend/Docs/Resources/Images/pixelstreaming-respond-searchsubstring.JPG b/Frontend/Docs/Resources/Images/pixelstreaming-respond-searchsubstring.JPG deleted file mode 100644 index 57510bac..00000000 Binary files a/Frontend/Docs/Resources/Images/pixelstreaming-respond-searchsubstring.JPG and /dev/null differ diff --git a/Frontend/Docs/Resources/Images/pixelstreaming-respond-searchsubstring.png b/Frontend/Docs/Resources/Images/pixelstreaming-respond-searchsubstring.png deleted file mode 100644 index b6559c8f..00000000 Binary files a/Frontend/Docs/Resources/Images/pixelstreaming-respond-searchsubstring.png and /dev/null differ diff --git a/Frontend/Docs/Resources/Images/pixelstreaming-send-game-event.JPG b/Frontend/Docs/Resources/Images/pixelstreaming-send-game-event.JPG deleted file mode 100644 index 4e3e811f..00000000 Binary files a/Frontend/Docs/Resources/Images/pixelstreaming-send-game-event.JPG and /dev/null differ diff --git a/Frontend/Docs/Resources/Images/pixelstreaming-send-game-event.png b/Frontend/Docs/Resources/Images/pixelstreaming-send-game-event.png index 50bc1d81..85e40b3c 100644 Binary files a/Frontend/Docs/Resources/Images/pixelstreaming-send-game-event.png and b/Frontend/Docs/Resources/Images/pixelstreaming-send-game-event.png differ diff --git a/Frontend/Docs/Resources/Images/pixelstreaming-ui-interaction-event.png b/Frontend/Docs/Resources/Images/pixelstreaming-ui-interaction-event.png new file mode 100644 index 00000000..1ec2e09b Binary files /dev/null and b/Frontend/Docs/Resources/Images/pixelstreaming-ui-interaction-event.png differ diff --git a/Frontend/Docs/Resources/Images/pixelstreaming-ui-interaction-extract-json.png b/Frontend/Docs/Resources/Images/pixelstreaming-ui-interaction-extract-json.png new file mode 100644 index 00000000..35b4b7fe Binary files /dev/null and b/Frontend/Docs/Resources/Images/pixelstreaming-ui-interaction-extract-json.png differ diff --git a/Frontend/Docs/Resources/Images/pixelstreaming-ui-interaction-search-substring.png b/Frontend/Docs/Resources/Images/pixelstreaming-ui-interaction-search-substring.png new file mode 100644 index 00000000..4aecff3f Binary files /dev/null and b/Frontend/Docs/Resources/Images/pixelstreaming-ui-interaction-search-substring.png differ diff --git a/Frontend/Docs/Resources/Images/pixelstreaming-uiinteractionrespond.JPG b/Frontend/Docs/Resources/Images/pixelstreaming-uiinteractionrespond.JPG deleted file mode 100644 index e071491c..00000000 Binary files a/Frontend/Docs/Resources/Images/pixelstreaming-uiinteractionrespond.JPG and /dev/null differ diff --git a/Frontend/Docs/Table of Contents.md b/Frontend/Docs/Table of Contents.md index e69de29b..29147de4 100644 --- a/Frontend/Docs/Table of Contents.md +++ b/Frontend/Docs/Table of Contents.md @@ -0,0 +1,13 @@ +Pixel Streaming Infrastructure Frontend Documentation +--- + +* [Accessing the Pixel Streaming Blueprint API](/Frontend/Docs/Accessing%20the%20Pixel%20Streaming%20Blueprint%20API.md) +* [Communicating from the Player Page to Unreal Engine](/Frontend/Docs/Communicating%20from%20the%20Player%20Page%20to%20UE5.md) +* [Communicating from Unreal Engine to the Player Page](/Frontend/Docs/Communicating%20from%20UE5%20to%20the%20Player%20Page.md) +* [Customizing Player Input Options](/Frontend/Docs/Customizing%20Player%20Input%20Options.md) +* [Customizing the Player Webpage](/Frontend/Docs/Customizing%20the%20Player%20Webpage.md) +* [Customizing Player Widget Style](/Frontend/Docs/Customizing%20the%20Player%20Widget%20Style.md) +* [HTML Page Requirements](/Frontend/Docs/HTML%20Page%20Requirements.md) +* [The Settings Panel](/Frontend/Docs/Settings%20Panel.md) +* [Timing Out Inactive Connections](/Frontend/Docs/Timing%20Out%20Inactive%20Connections.md) + diff --git a/Frontend/Docs/Timing Out Inactive Connections.md b/Frontend/Docs/Timing Out Inactive Connections.md index ddfeb545..98aedd39 100644 --- a/Frontend/Docs/Timing Out Inactive Connections.md +++ b/Frontend/Docs/Timing Out Inactive Connections.md @@ -1,26 +1,34 @@ -**TO DO**: Update this information to match the new front end. - ## Timing Out Inactive Connections In some kinds of Pixel Streaming deployments, you may want to automatically disconnect users who have been inactive for a certain period of time. For example, if you have a limited pool of Unreal Engine applications available, with access to those instances controlled by a matchmaking server, you may need to drop inactive older connections in order to make sure that you have application instances available to handle new incoming connection requests. -You can configure your Pixel Streaming player page to detect when a user appears to be away from keyboard (AFK)—that is, when the user has not interacted with the player widget within a customizable time interval. The AFK system warns the user: +You can configure your Pixel Streaming implementation to detect when a user appears to be away from keyboard (AFK)—that is, when the user has not interacted with the player widget within a customizable time interval. The AFK system warns the user:

AFK timeout warning

-If the user continues not to respond, the AFK system ultimately disconnects their session. +If the user continues not to respond, the AFK system waits 10 more seconds before ultimately disconnecting their session. Any user interaction with the player panel resets the AFK timer. This includes mouse moves and drags, mouse button presses, keyboard presses, touch events on mobile devices, and custom interactions you set up with the `emitCommand` and `emitUIInteraction` functions. -To use the AFK system, set the following three properties in the JavaScript of your player page. Do this after you load the `app.js` file, but before you call its `load` function. +To use the AFK system, set the following properties in the [`Config`](https://github.com/EpicGames/PixelStreamingInfrastructure/blob/master/Frontend/library/src/Config/Config.ts) object passed used to create a [`PixelStreaming`](https://github.com/EpicGames/PixelStreamingInfrastructure/blob/master/Frontend/library/src/PixelStreaming/PixelStreaming.tx) stream. + +| Property | Default | Description | +| --- | --- | +| `Flags.AFKDetection` | `false` | Determines whether the AFK system should check for user interactions. | +| `NumericParameters.AFKTimeoutSecs` | `120` | Sets the maximum time interval, in seconds, that the user can remain away from keyboard before seeing a warning overlay in the player widget. | + +For example, to activate AFK Detection and set it to kick in after five minutes, you would do the following in your implementation: -| Property | Description | -| --- | --- | -| `afk.enabled` | Determines whether the AFK system should check for user interactions. The default is `false`; set this value to `true` to time out inactive connections. | -| `afk.warnTimeout` | Sets the maximum time interval, in seconds, that the user can remain away from keyboard before seeing a warning overlay in the player widget. The default is `120`, or two minutes. | -| `afk.closeTimeout` | After the `afk.warnTimeout` interval has elapsed and the user sees a warning message about being disconnected, this variable sets the time interval, in seconds, before the user's connection is automatically disconnected unless they interact with the player widget. The default is `10`. | +```typescript +const config = new Config({ useUrlParams: true }); +config.setFlagEnabled(Flags.AFKDetection, true); +config.setNumericSetting(NumericParameters.AFKTimeoutSecs, 300); + +const stream = new PixelStreaming(config); +``` **_Tip:_** -If you want to customize the content of the overlay, you can redefine the `updateAfkOverlayText()` function in your player page. In your implementation, set the `afk.overlay.innerHTML` property to the HTML that you want the player widget to display when users have been away longer than the AFK timeout value. +If you want to customize the content of the overlay, you can replace the [`AFKOverlay`](https://github.com/EpicGames/PixelStreamingInfrastructure/blob/master/Frontend/ui-library/src/Overlay/AFKOverlay.ts) class. You must then also extend the [`Application`](https://github.com/EpicGames/PixelStreamingInfrastructure/blob/master/Frontend/ui-library/src/Application/Application.ts) class in order to use the new overlay. +