From 50b7c155ad48a8aeb11a66b2a9ddbfe0300f9046 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Fri, 5 May 2023 20:33:21 +0200 Subject: [PATCH] Document focus and sleep caveats in Controllers, gamepads and joysticks - Improve line wrapping for long lines in scripts. - Remove outdated paragraphs about Godot 3.3 changes. --- .../inputs/controllers_gamepads_joysticks.rst | 94 ++++++++++++++++--- 1 file changed, 82 insertions(+), 12 deletions(-) diff --git a/tutorials/inputs/controllers_gamepads_joysticks.rst b/tutorials/inputs/controllers_gamepads_joysticks.rst index b50f801a6..53588f16e 100644 --- a/tutorials/inputs/controllers_gamepads_joysticks.rst +++ b/tutorials/inputs/controllers_gamepads_joysticks.rst @@ -57,8 +57,10 @@ There are 3 ways to get input in an analog-aware way: # The line below is similar to `get_vector()`, except that it handles # the deadzone in a less optimal way. The resulting deadzone will have # a square-ish shape when it should ideally have a circular shape. - var velocity = Vector2(Input.get_action_strength("move_right") - Input.get_action_strength("move_left"), - Input.get_action_strength("move_back") - Input.get_action_strength("move_forward")).clamped(1) + var velocity = Vector2( + Input.get_action_strength("move_right") - Input.get_action_strength("move_left"), + Input.get_action_strength("move_back") - Input.get_action_strength("move_forward") + ).limit_length(1.0) .. code-tab:: csharp @@ -70,8 +72,10 @@ There are 3 ways to get input in an analog-aware way: // The line below is similar to `get_vector()`, except that it handles // the deadzone in a less optimal way. The resulting deadzone will have // a square-ish shape when it should ideally have a circular shape. - Vector2 velocity = new Vector2(Input.GetActionStrength("move_right") - Input.GetActionStrength("move_left"), - Input.GetActionStrength("move_back") - Input.GetActionStrength("move_forward")).Clamped(1); + Vector2 velocity = new Vector2( + Input.GetActionStrength("move_right") - Input.GetActionStrength("move_left"), + Input.GetActionStrength("move_back") - Input.GetActionStrength("move_forward") + ).LimitLength(1.0); - When you have one axis that can go both ways (such as a throttle on a flight stick), or when you want to handle separate axes individually, @@ -208,6 +212,71 @@ If you want controller buttons to send echo events, you will have to generate at regular intervals. This can be accomplished with the help of a :ref:`class_Timer` node. +Window focus +^^^^^^^^^^^^ + +Unlike keyboard input, controller inputs can be seen by **all** windows on the +operating system, including unfocused windows. + +While this is useful for +`third-party split screen functionality `__, +it can also have adverse effects. Players may accidentally send controller inputs +to the running project while interacting with another window. + +If you wish to ignore events when the project window isn't focused, you will +need to create an :ref:`autoload ` called ``Focus`` +with the following script and use it to check all your inputs: + +:: + + # Focus.gd + extends Node + + var focused := true + + func _notification(what: int) -> void: + match what: + NOTIFICATION_APPLICATION_FOCUS_OUT: + focused = false + NOTIFICATION_APPLICATION_FOCUS_IN: + focused = true + + + func input_is_action_pressed(action: StringName) -> bool: + if focused: + return Input.is_action_pressed(action) + + return false + + + func event_is_action_pressed(event: InputEvent, action: StringName) -> bool: + if focused: + return Input.is_action_pressed(action) + + return false + +Then, instead of using ``Input.is_action_pressed(action)``, use +``Focus.input_is_action_pressed(action)`` where ``action`` is the name of +the input action. Also, instead of using ``event.is_action_pressed(action)``, +use ``Focus.event_is_action_pressed(event, action)`` where ``event`` is an +InputEvent reference ``action`` is the name of the input action. + +Power saving prevention +^^^^^^^^^^^^^^^^^^^^^^^ + +Unlike keyboard and mouse input, controller inputs do **not** inhibit sleep and +power saving measures (such as turning off the screen after a certain amount of +time has passed). + +To combat this, Godot enables power saving prevention by default when a project +is running. If you notice the system is turning off its display when playing +with a gamepad, check the value of **Display > Window > Energy Saving > Keep Screen On** +in the Project Settings. + +On Linux, power saving prevention requires the engine to be able to use D-Bus. +Check whether D-Bus is installed and reachable if running the project within a +Flatpak, as sandboxing restrictions may make this impossible by default. + Troubleshooting --------------- @@ -273,10 +342,15 @@ My controller works on a given platform, but not on another platform. Linux ~~~~~ -Prior to Godot 3.3, official Godot binaries were compiled with udev support -but self-compiled binaries were compiled *without* udev support unless -``udev=yes`` was passed on the SCons command line. This made controller -hotplugging support unavailable in self-compiled binaries. +If you're using a self-compiled engine binary, make sure it was compiled with +udev support. This is enabled by default, but it is possible to disable udev +support by specifying ``udev=no`` on the SCons command line. If you're using an +engine binary supplied by a Linux distribution, double-check whether it was +compiled with udev support. + +Controllers can still work without udev support, but it is less reliable as +regular polling must be used to check for controllers being connected or +disconnected during gameplay (hotplugging). HTML5 ~~~~~ @@ -285,7 +359,3 @@ HTML5 controller support is often less reliable compared to "native" platforms. The quality of controller support tends to vary wildly across browsers. As a result, you may have to instruct your players to use a different browser if they can't get their controller to work. - -Also, note that -`controller support was significantly improved `__ -in Godot 3.3 and later.