Toggle Between Hover and Locked Mouse Using SDK

This guide explains how to switch between Hovering Mouse and Locked Mouse modes using the Eagle 3D Streaming Frontend SDK.

There are three ways to switch the mouse control scheme:

Switch Mouse Mode in iFrame: Refer to the Switch Between Hover and Locked Mouse in iFrame guide.
Switch Mouse Mode Using SDK: Covered in this guide.
Inside the Unreal App (Blueprint): Refer to the Switch Between Hover and Locked Mouse Using Blueprint guide.

Live Streaming URL:

https://e3ds.github.io/pixelstreaming-sdk/e3ds_streaming_FE.html

Demo Project GitHub Repository:

https://github.com/e3ds/pixelstreaming-sdk

Follow the steps below:

Step 1. Add the Mouse Control Functions

Add the following functions inside your scripts_demo.js file:

JavaScript

function setHoverMouse() {
    console.log("Switching to Hovering Mouse");
    e3ds_controller.switchMouseControlSchemeTo("HoveringMouse");
}

function setLockedMouse() {
    console.log("Switching to Locked Mouse");
    e3ds_controller.switchMouseControlSchemeTo("LockedMouse");
}

Explanation

Code	Meaning
`function setHoverMouse()`	Creates a function to switch the stream to Hovering Mouse mode.
`e3ds_controller.switchMouseControlSchemeTo("HoveringMouse");`	Switches the stream to Hovering Mouse mode.
`function setLockedMouse()`	Creates a function to switch the stream to Locked Mouse mode.
`e3ds_controller.switchMouseControlSchemeTo("LockedMouse");`	Switches the stream to Locked Mouse mode.

Hovering Mouse

The mouse cursor remains visible and can freely move across the webpage. This mode is recommended for UI-driven applications.

Locked Mouse

The mouse cursor is locked inside the streaming window, making it suitable for FPS, TPS, and free-look camera controls.

Step 2. Add Mouse Control Buttons

Add the following buttons to your HTML page:

HTML

<button onclick="setHoverMouse()">Hover Mouse</button>
<button onclick="setLockedMouse()">Lock Mouse</button>

Figure 2. Hover Mouse and Locked Mouse Buttons

Explanation

Code	Meaning
`<button>`	Creates a clickable button on the webpage.
`onclick="setHoverMouse()"`	Switches the stream to Hovering Mouse mode when clicked.
`onclick="setLockedMouse()"`	Switches the stream to Locked Mouse mode when clicked.
`Hover Mouse`	Text displayed on the Hover Mouse button.
`Lock Mouse`	Text displayed on the Lock Mouse button.

Step 3. Test the Mouse Control Buttons

Note: Wait until the Pixel Streaming session is fully connected before clicking the Hover Mouse or Lock Mouse buttons.

After adding the functions and buttons:

Open the SDK webpage.
Wait until the stream is fully started.
Click Lock Mouse to switch to Locked Mouse mode.

Figure 3. Switch to Locked Mouse Mode
Verify that the cursor becomes locked inside the streaming window.
Press Esc to release the cursor.
Click Hover Mouse to switch to Hovering Mouse mode.
Verify that the cursor can freely move again.

Figure 4. Switch to Hover Mouse Mode

Verify that the mouse behavior changes accordingly inside the streamed application.

Important

Mouse control changes are applied immediately without restarting the stream.
switchMouseControlSchemeTo() can be called at any time only after the unreal app has started successfully.
Hovering Mouse is recommended for UI-based applications.
Locked Mouse is recommended for FPS, TPS, and free-camera experiences.
Some browsers require Locked Mouse to be triggered by a user action such as clicking a button.

Troubleshooting

Issue	Possible Cause	Solution
Clicking the button does nothing	Pixel Streaming session is not fully connected	Wait until the Pixel Streaming session is fully connected before clicking the button.
`setHoverMouse` or `setLockedMouse` is not defined	Function is missing or not loaded	Make sure the functions are added to `scripts_demo.js` and the file is loaded correctly.
`e3ds_controller` is not defined	SDK has not initialized yet	Ensure the Eagle 3D Streaming SDK is fully loaded before calling `switchMouseControlSchemeTo()`.
Mouse behavior does not change	Invalid mouse control scheme value	Use only `HoveringMouse` or `LockedMouse`.
Locked Mouse does not activate	Browser requires user interaction	Trigger Locked Mouse from a direct user action, such as a button click.
Pressing Esc does not release the cursor	Browser Pointer Lock behavior	Click inside the stream first, then press Esc again. If needed, click Hover Mouse or reconnect the stream.

Need help?

If you need any assistance, feel free to reach out through any of the following channels:

🛠️ Support Portal: Contact Our Support Team

💬 Discord Community (Faster Support): Join Our Discord Community

📧 Email Support: support@eagle3dstreaming.com

🆓 Get Started for free

Facebook | GitHub | LinkedIn | YouTube