Fixing jitter, stutter and input lag
What is jitter, stutter and input lag?
Jitter andstutter are two different alterations to visible motion ofobjects on screen that may affect a game, even when running at full speed. Theseeffects are mostly visible in games where the world moves at a constant speed ina fixed direction, like runners or platformers.
Input lag is unrelated to jitter and stutter, but is sometimes discussedalongside. Input lag refers to visible on-screen delay when performing actionswith the mouse, keyboard, controller or touchscreen. It can be related to gamecode, engine code or external factors (such as hardware). Input lag is mostnoticeable in games that use the mouse to aim, such as first-person games.Input lag can't be completely eliminated, but it can be reduced in several ways.
Distinguishing between jitter and stutter
A game running at a normal framerate without exhibiting any effect will appear smooth:
A game exhibitingjitter will shake constantly in a very subtle way:
Finally, a game exhibitingstutter will appear smooth, but appear tostop orroll back a frame every few seconds:
Jitter
There can be many causes of jitter, the most typical one happens when the gamephysics frequency (usually 60 Hz) runs at a different resolution than themonitor refresh rate. Check whether your monitor refresh rate is different from60 Hz.
This is generally not a problem, given that most monitors are 60 Hz, andstarting with Godot 3.1, a frame timer was introduced that tries to synchronizewith refresh as well as possible.
Sometimes only some objects appear to jitter (character or background). Thishappens when they are processed in different time sources (one is processed inthe physics step while another is processed in the idle step). Godot 3.1 doessome improvements to this, from allowing kinematic bodies to be animated in theregular_process() loop, to further fixes in the frame timer.
Stutter
Stutter may happen due to two different reasons. The first, and most obviousone, is the game not being able to keep full framerate performance. Solving thisis game specific and will require optimization.
The second is more complicated, because it is often not associated to the engineor game but the underlying operating system. Here is some information regardingstutter on different OSs.
On platforms that support disabling V-Sync, stuttering can be made lessnoticeable by disabling V-Sync in the project settings. This will however causetearing to appear, especially on monitors with low refresh rates. If yourmonitor supports it, consider enabling variable refresh rate (G-Sync/FreeSync)while leaving V-Sync enabled. This avoids mitigating some forms of stutteringwithout introducing tearing.
Forcing your graphics card to use the maximum performance profile can also helpreduce stuttering, at the cost of increased GPU power draw.
Windows
Windows is known to cause stutter in windowed games. This mostly depends on thehardware installed, drivers version and processes running in parallel (e.g.having many browser tabs open may cause stutter in a running game). To avoidthis, starting with 3.1, Godot raises the game priority to "Above Normal". Thishelps considerably but may not completely eliminate stutter.
Eliminating this completely requires giving your game full privileges to become"time critical", which is not advised. Some games may do it, but it is advisedto learn to live with this problem, as it is common for Windows games and mostusers won't play games windowed (games that are played in a window, e.g. puzzlegames, will usually not exhibit this problem anyway).
For fullscreen, Windows gives special priority to the game so stutter is nolonger visible and very rare. This is how most games are played.
When using a mouse with a polling rate of 1,000 Hz or more, consider using afully up-to-date Windows 11 installation which comes with fixes related to highCPU utilization with high polling rate mice. These fixes are not available inWindows 10 and older versions.
Tip
Games should use theExclusive Fullscreen window mode, as opposed toFullscreen which is designed to prevent Windows from automaticallytreating the window as if it was exclusive fullscreen.
Fullscreen is meant to be used by GUI applications that want to useper-pixel transparency without a risk of having it disabled by the OS. Itachieves this by leaving a 1-pixel line at the bottom of the screen. Bycontrast,Exclusive Fullscreen uses the actual screen size and allowsWindows to reduce jitter and input lag for fullscreen games.
Linux
Stutter may be visible on desktop Linux, but this is usually associated withdifferent video drivers and compositors. Some compositors may also trigger thisproblem (e.g. KWin), so it is advised to try using a different one to rule itout as the cause. Some window managers such as KWin and Xfwm allow you tomanually disable compositing, which can improve performance (at the cost oftearing).
There is no workaround for driver or compositor stuttering, other than reportingit as an issue to the driver or compositor developers. Stutter may be morepresent when playing in windowed mode as opposed to fullscreen, even withcompositing disabled.
Feral GameMode can be usedto automatically apply optimizations (such as forcing the GPU performance profile)when running specific processes.
macOS
Generally, macOS is stutter-free, although recently some bugs were reported whenrunning on fullscreen (this is a macOS bug). If you have a machine exhibitingthis behavior, please let us know.
Android
Generally, Android is stutter and jitter-free because the running activity getsall the priority. That said, there may be problematic devices (older Kindle Fireis known to be one). If you see this problem on Android, please let us know.
iOS
iOS devices are generally stutter-free, but older devices running newer versionsof the operating system may exhibit problems. This is generally unavoidable.
Input lag
Project configuration
On platforms that support disabling V-Sync, input lag can be made lessnoticeable by disabling V-Sync in the project settings. This will however causetearing to appear, especially on monitors with low refresh rates. It's suggestedto make V-Sync available as an option for players to toggle.
When using the Forward+ or Mobile rendering methods, another way to reducevisual latency when V-Sync is enabled is to use double-buffered V-Sync insteadof the default triple-buffered V-Sync. Since Godot 4.3, this can be achieved byreducing theDisplay > Window > V-Sync > Swapchain Image Count projectsetting to2. The downside of using double buffering is that framerate willbe less stable if the display refresh rate can't be reached due to a CPU or GPUbottleneck. For instance, on a 60 Hz display, if the framerate would normallydrop to 55 FPS during gameplay with triple buffering, it will have to drop downto 30 FPS momentarily with double buffering (and then go back to 60 FPS whenpossible). As a result, double-buffered V-Sync is only recommended if you canconsistently reach the display refresh rate on the target hardware.
Increasing the number of physics iterations per second can also reducephysics-induced input latency. This is especially noticeable when using physicsinterpolation (which improves smoothness but increases latency). To do so, setPhysics > Common > Physics Ticks Per Second to a value higher than thedefault60, or setEngine.physics_ticks_per_second at runtime in ascript. Values that are a multiple of the monitor refresh rate (typically60) work best when physics interpolation is disabled, as they will avoidjitter. This means values such as120,180 and240 are good startingpoints. As a bonus, higher physics FPSes make tunneling and physics instabilityissues less likely to occur.
The downside of increasing physics FPS is that CPU usage will increase, whichcan lead to performance bottlenecks in games that have heavy physics simulationcode. This can be alleviated by increasing physics FPS only in situations wherelow latency is critical, or by letting players adjust physics FPS to match theirhardware. However, different physics FPS will lead to different outcomes inphysics simulation, even whendelta is consistently used in your game logic.This can give certain players an advantage over others. Therefore, allowing theplayer to change the physics FPS themselves should be avoided for competitivemultiplayer games.
Lastly, you can disable input buffering on a per-rendered frame basis by callingInput.set_use_accumulated_input(false) in a script. This will make it so the_input() and_unhandled_input() functions in your scripts are called onevery input, rather than accumulating inputs and waiting for a frame to berendered. Disabling input accumulation will increase CPU usage, so it should bedone with caution.
Tip
On any Godot project, you can use the--disable-vsynccommand line argument to forcibly disable V-Sync.Since Godot 4.2,--max-fps<fps> can also be used to set a FPS limit(0 is unlimited). These arguments can be used at the same time.
Hardware/OS-specific
If your monitor supports it, consider enabling variable refresh rate(G-Sync/FreeSync) while leaving V-Sync enabled, then cap the framerate in theproject settings to a slightly lower value than your monitor's maximum refreshrate as perthis page.For example, on a 144 Hz monitor, you can set the project's framerate cap to141. This may be counterintuitive at first, but capping the FPS below themaximum refresh rate range ensures that the OS never has to wait for verticalblanking to finish. This leads tosimilar input lag as V-Sync disabled withthe same framerate cap (usually less than 1 ms greater), but without anytearing.
This can be done by changing theApplication > Run > Max FPS projectsetting or assigningEngine.max_fps at runtime in a script.
On some platforms, you can also opt into a low-latency mode in the graphicsdriver options (such as the NVIDIA Control Panel on Windows). TheUltrasetting will give you the lowest possible latency, at the cost of slightly loweraverage framerates. Forcing the GPU to use the maximum performance profilecan also further reduce input lag, at the cost of higher power consumption(and resulting heat/fan noise).
Finally, make sure your monitor is running at its highest possible refresh ratein the OS' display settings.
Also, ensure that your mouse is configured to use its highest polling rate(typically 1,000 Hz for gaming mice, sometimes more). High USB polling rates canhowever result in high CPU usage, so 500 Hz may be a safer bet on low-end CPUs.If your mouse offers multipleDPI settings, consider alsousing the highest possible setting and reducing in-game sensitivity to reduce mouse latency.
On Linux, disabling compositing in window managers that allow it (such as KWinor Xfwm) can reduce input lag significantly.
Reporting jitter, stutter or input lag problems
If you are reporting a stutter or jitter problem (opening an issue) not causedby any of the above reasons, please specify very clearly all the informationpossible about device, operating system, driver versions, etc. This may help tobetter troubleshoot it.
If you are reporting input lag problems, please include a capture made with ahigh speed camera (such as your phone's slow motion video mode). The capturemust have both the screen and the input device visible so that the number offrames between an input and the on-screen result can be counted. Also, makesure to mention your monitor's refresh rate and your input device's polling rate(especially for mice).
Also, make sure to use the correct term (jitter, stutter, input lag) based on theexhibited behavior. This will help understand your issue much faster. Provide aproject that can be used to reproduce the issue, and if possible, include ascreen capture demonstrating the bug.