Skip to content
This repository has been archived by the owner on Mar 1, 2024. It is now read-only.

Updating the Frontend Docs #152

Merged
merged 11 commits into from
Mar 23, 2023
58 changes: 28 additions & 30 deletions Frontend/Docs/Customizing Player Input Options.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,44 +4,42 @@ The frontend library exposes a number of configuration options through the [Conf

The following options are available in the frontend library:

**TO DO**: Update this information to match the new front end.
| Property | Default | Description |
| --- | --- | --- |
| HoveringMouseMode | false | Determines whether or not the player widget 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` object required in order to create a `PixelStreaming` 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.

<script>
inputOptions.controlScheme = ControlSchemeType.HoveringMouse;
inputOptions.fakeMouseWithTouches = true;
</script>
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.

<script>
registerHoveringMouseEvents = function() {}
registerLockedMouseEvents = function() {}
registerTouchEvents = function() {}
registerKeyboardEvents = function() {}
</script>
```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);
```