Unity WebGL supports features such as cursor locking and full-screen mode that are implemented using the HTML5 APIs, Element.requestPointerLock
and Element.requestFullscreen
.
Note: As browser support for cursor locking and full-screen mode varies, refer to the Mozilla documentation on cursor locking and full screen.
Cursor locking lets players lock their mouse cursor to the center of the game window. When the cursor is locked, it appears hidden in Unity and doesn’t move when the mouse moves. This is particularly helpful when playing first-person games, where the mouse cursor is typically used to control the orientation of the player’s angle.
To lock the cursor, use the Cursor.lockState
property. For example, the following code shows the cursor in locked state when the user clicks the left mouse button:
void Update()
{
if (Input.GetMouseButtonDown(0))
{
Cursor.lockState = CursorLockMode.Locked;
}
}
The cursor is automatically unlocked when you press the Esc key.
Use stickyCursorLock
to ensure that the state of Cursor.lockState
is persistent, even if the browser releases the cursor lock from the Unity canvas (typically using the Esc key), in which case the cursor is locked again the next time the canvas is in focus. The stickyCursorLock
property is commonly used in first-person games, where maintaining the cursor lock mode is particularly beneficial regardless of the browser behavior.
Therefore, if you set WebGLInput._stickyCursorLock
to true
, the Cursor.lockState
remains in CursorLockMode.Locked
state even if the Unity canvas HTML element is forced to unlock the cursor. If you set WebGLInput._stickyCursorLock
to false
, then Cursor.lockState
remains synchronized with the browser’s cursor lock state, and changes to CursorLockMode.None
if the canvas cursor lock is canceled by pressing the Esc key.
Note: In WebGL, stickyCursorLock
is set to true by default.
Use the full-screen mode to use the entire computer screen for your game. You can perform the following actions in full-screen mode:
Use the entire screen for your game.
Hide the browser user interface (UI) elements such as the address bar and tabs.
Hide the Unity player UI elements such as the title bar and toolbar.
To enable full-screen mode, use the Screen.fullScreen
property. For example, the following code shows the game in full-screen mode when the user presses the F key:
void Update()
{
if (Input.GetKeyDown(KeyCode.F))
{
Screen.fullScreen = true;
}
}
Note: The Screen.fullScreen
property is set to false
by default.
To exit full-screen mode, press ESC again, or hover the mouse pointer to the top of the screen to access the address bar and tabs.
Due to security concerns, browsers allow cursor locking and full-screen mode only in direct response to a user-initiated event such as a mouse-click or key press. Because Unity doesn’t support separate events and rendering loops, it defers event handling until the browser no longer acknowledges full-screen or cursor lock requests issued from Unity scripting as a direct response to the event which triggered it. Therefore, Unity triggers the request on the next user-initiated event, instead of the event that triggered the cursor lock or full-screen request.
To enable cursor lock or full-screen modes with acceptable results, set projects to trigger appropriate requests using mouse/key down events, instead of mouse/key up events. This way you can ensure that the deferred request is guaranteed to be triggered by the corresponding mouse/key up event if not by a user-initiated event earlier.
You can also use Unity’s UI.Button component to achieve the desired behavior by creating a subclass of Button
, which overrides the OnPointerDown
method.
Note: Some browsers might display a notification message or prompt the user to grant permission before entering full-screen mode or locking the cursor.
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.