Input

Introduction

Most 3D games need to switch the mouse between captured mode for gameplay and visible mode for menus. While simple in theory, several factors makes this more difficult to manage in practice:

• Outside factors can change the mouse mode, like the user pressing escape in a web build
• Godot has no signal to indicate when the mouse mode has been changed externally
• Settings menus often need to appear over both other menus and gameplay making it cumbersome to track and return to the correct mode

To make controlling the mouse mode more robust, ProtoJam provides a custom node which asserts the mouse based on its activation and priority.

Using MouseModeController

The MouseModeController node automatically requests its configured mouse mode every frame so long as it remains active and unpaused. If two or more mode controllers are active in the scene tree during a given frame then the controller with the highest priority will take effect.

To get the most benefit out of this node, users should add one to every scene which requires the mouse to be in a given mode and set a priority to reflect which scene should overrule others. For example, in a typical first person shooter the player's camera controller would have a mouse mode controller set to captured with a priority of 1 while the menus would have a controller set to visible with a priority of 2 (or higher).

Games that allow the settings menu to be accessed from other menus may wish to assign the setting menu's controller to a priority even higher than other menus so it does not conflict with them. A warning will be pushed to the Godot editor if a conflict was detected for a given frame.

Important

When using this node, users should not attempt to set the mouse mode manually via Input.mouse_mode. If programmatic control of the mouse mode is required, use MouseModeManager.request_mode(priority, mode) instead.

Using MouseModeManager

While MouseModeController is the preferred way to change mouse mode, users may also manually request a mode by calling MouseModeManager.request_mode(priority, mode) with the requested mode and priority.

Important

A requested mode is only applied for a single frame. Users must keep requesting their desired mode every frame to keep it.

Users should not skip requesting their desired mode when the current mode already matches it as this can cause the mode to oscillate between two states if another script or MouseModeController is attempting to assert a different mode. This ocurrs because the mode you are inspecting is for the current frame while a request to change modes takes effect on the next frame.