FPSLocker Switch

FPSLocker
General
Author	masagrator
Type	Overlays
Version	2.1.0
License	MIT License
Last Updated	2024/12/19
Links
Download
Website
Source
Support Author

An overlay that with SaltyNX allows to set custom FPS in Nintendo Switch retail games.

You can see the video how it works (with Witcher 3 dynamic resolution config mod to make anything above 30 FPS available).

Note: Tool is utilizing detection of graphics API to manipulate FPS, and in special cases it requires using patches made per game for each version to get more than 30 FPS. You can find those patches here. Max supported yaml size is 32kB, though it can be expanded in the future.

Installation

Requirements:

• Atmosphere Switch
• SaltyNX 1.2.0+
• Tesla environment: ovlloader + Tesla Menu

Atmosphere CFW is required. SX OS and other CFWs are not supported. It's advised to use Atmosphere's USB Transfer Tool homebrew to transfer files. If you use Hekate's USB Mass Storage and you will be putting files using any other Operating System than Windows, you must run Hekate's Archive Bit Fixer after putting all files.

To install:

• Download SaltyNX, copy the folders SaltySD and atmosphere to the root of your SD card, accept any popup about overwriting folders.
• Download nx-ovlloader, copy atmosphere folder to the root of SD card, accept any popup about overwriting folders.
• Download Tesla Menu, copy switch folder to the root of SD card, accept any popup about overwriting folders.
• Download Status Monitor Overlay, copy Status-Monitor-Overlay.ovl to switch\.overlays folder. It may not be visible in USB Mass Storage, but it's there.
• Download FPSLocker, copy FPSLocker.ovl to switch\.overlays folder. It may not be visible in USB Mass Storage, but it's there.
• Download sys-clk, copy all 3 folders to the root of SD card, accept any popup about overwriting folders.

• Restart Switch, now you can access overlays by pressing all 3 buttons at once: L, D-Pad Down and Right Stick (aka pressing it).

Additionally for FPSLocker download newest set of patches from FPSLocker Warehouse for games that need more things to be tweaked to get proper FPS boost.

User guide

Overlay runs in two modes:

• When game is running.
• When game is not running.

When game is running

If game is supported by SaltyNX and you installed everything correctly, you will see menu where first line states NX-FPS plugin is running. Explanation of each line:

• Interval Mode - it's used by NVN API to set limiter to either 30 FPS (2) or 60 FPS (1).
• Custom FPS Target - it's used to lock game to certain FPS. If game is using engine proprietary FPS locks, it may not be able to unlock more than 30 FPS without additional patches.
• Big number on the right - it shows how many frames have passed in last second for currently running game. This is to confirm that lock is working as expected.
• Increase/Decrease FPS target - Shows up only in handheld mode. Change FPS Target by 5. Minimum is 15 FPS, max is 60 FPS.
• Change FPS target - Shows up only in docked mode. Shows up table with different FPS values, from 15 to 60.
• Disable custom FPS target - Removes FPS Target. Since we cannot predict what interval mode is expected at this point, it is in user's discretion to manipulate FPS to bring back correct interval before disabling FPS target.
• Advanced settings - submenu which consists of:
  • If game is using NVN
    • Window Sync Wait - this is dangerous setting that disabled can crash game, but in some can bring benefit of disabling double buffer vsync at the cost of small graphical glitches (check list of games compatible with this solution at the bottom of README). Use it with caution. It won't show if game is not using double buffer.
    • Set Buffering - if game is using any other buffering than double, this option will show that will allow you to force game to run at any other buffering that is not higher than original one (so f.e. you cannot change double buffer to triple buffer). Lowering buffer is recommended only for games that have near perfect performance at 30 or 60 FPS, but suffer from bad framepacing or big input lag. If you will force double buffer in games with uneven performance, FPS drops will be very severe. It can be applied only at boot of game, so after changing buffering you must save settings in FPSLocker and restart game.
      • Explanation of Set/Active/Available Buffers:
      • Set - how many buffers were set by using nvnWindowSetNumActiveTextures. If game is not using it, it will be 0. It can be used by games to set lower buffer value than reserved space allows. If this is detected to be used and lower than Available Buffers, you can use "(force)" variant next to default option. Without (force) it will reset to default settings.
      • Active - How many buffers are actually used by game.
      • Available - How many buffers is actually provided to NVN. We can use this information to force games to utilize all buffers when they are not doing it.
  • Convert config to patch file - if proper config file exists for this game and version, you will get an option to convert it to patch file that will be loaded when you will run this game next time. Patch is saved to SaltySD/plugins/FPSLocker/patches/*titleid_uppercase*/*buildid_uppercase*.bin
  • Delete patch file - if proper config file exists for this game and version, you will get an option to delete patch file so it won't be loaded when you will run this game next time.
  • Check/download config file - Checks in Warehouse repository if config for this game and version exists. If exists, it is downloaded and also checked if it's the same as the one on sdcard. If it's not, overlay will remove existing patch and config file, and user must manually convert new config to patch file. 0x312 error means we got unexpected file from github. Any other error code means that something is happening with your connection or github server.
• Save settings - save profile for currently running game that will be loaded next time by plugin on boot automatically. Don't use it if you disabled Sync Wait and you didn't test it properly that it won't cause crash. Profile is saved in SaltySD/plugins/FPSLocker/*titleid_uppercase*.dat
• Display settings - submenu related to display refresh rate. Consists of:
  • Increase refresh rate - Shows up only in handheld mode. Change display refresh rate up to 60 Hz. In OLED units it's blocked.
  • Decrease refresh rate - Shows up only in handheld mode. Change display refresh rate down to 40 Hz. In OLED units it's blocked.
  • Change refresh rate - Shows up only in docked mode. Choose display refresh rate from list.
  • Display Sync - When turned on, both options above are not available, display refresh rate is changed only when game is running, and matches refresh rate with FPS Target. In OLED units it works only in docked mode.
  • Docked Settings - submenu related to display refresh rate of external displays. Not accessible for Lite units. Consists of:
    • Allowed refresh rates - you can check and edit manually which refresh rates are enabled for currently connected external display. It consists of 40, 45, 50 and 55 Hz. By default 50 is turned on, everything else is turned off.
    • Refresh rate wizard - it goes automatically to next refresh rates, user is asked to press required button to confirm it's working, if not pressed for 15 seconds it goes to next refresh rate. After checking all refresh rates you are moved to Allowed refresh rates menu to check results.
    • Frameskip tester - It allows to check if your display is showing currently used signal at native refresh rates. Many displays may support for example 50 Hz, but they are still displaying stuff at 60 Hz. Instructions how to use it are provided when this menu is selected. This menu is also available in handheld mode.
    • Additional settings - submenu with options related to how FPSLocker/FPSLocker patches are working in docked mode. Currently you can choose from:
      • Allow patches to force 60 Hz - some FPSLocker patches are forcing 60 Hz to fix framepacing issues with 30 FPS cutscenes. When such change happens, game is paused for 4 seconds before continuing. By default is turned on. Turning it off will apply only FPS lock without changing refresh rate. This won't disable that 4 second delay.
      • Use lowest refresh rate for unmatched FPS targets - For example for 60 Hz display 35 FPS target doesn't have avaialble refresh rate matching it. By enabling this option you will get lowest enabled refresh rate in Allowed refresh rates menu. This option is disabled by default, which will result in setting 60 Hz in that case.

When game is not running

You will have two submenus to choose from (if you are using OLED model, you will be redirected automatically to Games list):

• Games list - It will list installed games (max 32) and as first option it's available "All" submenu. Inside each one you will find two options:
  • Delete settings - it will delete file created by "Save settings" option
  • Delete patches - it will delete file created by "Convert config to patch file" option
• Display settings - you can read about in previous section.

Sync Wait

Games where you can disable double buffer vsync by turning off Window Sync Wait in FPSLocker:

• Batman - The Telltale Series (Warehouse patch enables triple buffer, so there is no need to use this option)
• Pokemon Legends: Arceus
• Pokemon Scarlet
• Pokemon Violet
• Sonic Frontier
• The Legend of Zelda: Tears of the Kingdom (Warehouse patch enables triple buffer, so there is no need to use this option)
• Xenoblade Chronicles: Definitive Edition
• Xenoblade Chronicles 2
• Xenoblade Chronicles 3

Media

FPSLocker on Switch homebrew to unlock FPS in game (Tralala LS)

Changelog

2.1.0 2024/12/19

• Added support for changing refresh rates in docked mode. Read more in README.
• Changed some design choices of libtesla to make it less taxing on CPU. Fixes issues where opening FPSLocker could cause visible performance drop in some games.
• Whenever FPSLocker patch is currently forcing 60 Hz, overlay will inform about this in main menu.
• SaltyNX 1.2.0+ is REQUIRED! Using older SaltyNX versions can and probably will cause issues!
• For Xenoblade Chronicles and The Legend of Zelda games it is required to redownload config from Warehouse and convert it to patch, otherwise expect issues.

2.0.3 2024/10/11

• Check/download config file call is now done in a separate thread
  • This fixes problem with overlay being unresponsive
  • You get additional info
  • You still won't be able to exit Advanced settings until thread has finished work
  • Now there is a timeout that if thread runs for longer than 30 seconds, it will return, unlocking overlay
• Few text changes related to received informations from Check/download config file

2.0.2 2024/10/10

• Remake Advanced Settings page
  • Now "Check/download config file" when cannot find patch file in Warehouse, it will check games list for possible informations as:
    • If this titleid is listed
    • If titleid is listed, then if BID is listed and how patch recommendation looks like for it
    • If titleid is listed and BID is not listed, then how patch recommendation looks like for latest listed BID
  • More detailed informations when using options in FPSLocker Patches category

2.0.1 2024/08/19

• Fix a bug that was crashing OS when trying to disable/enable Display Sync while game not supported by SaltyNX was running.

2.0 2024/06/25

• Add Display settings menu to change LCD refresh rate (don't put Switch to dock with changed refresh rate while game is running, otherwise there is a chance game will crash), not available for OLED model. SaltyNX 0.8.0+ is required for this menu to show. More in readme.
• Add support for next revision of game configs that make them smaller and move most of calculations to FPSLocker overlay itself.
• Move from c++20 to c++23

1.2.8a 2024/03/11

• Fix "Set Buffering" in games with Quadruple Buffering.

1.2.8 2024/02/15

• Fix retrieving BID from games using new RTLD (such as Tomb Raider I-III Remastered).
• To fix compability with new RTLDs fully, it is necessary to update SaltyNX to at least 0.7.2 version.

1.2.7 2024/02/03

• Add support for downloading additional files from Warehouse if config file have "Addons" entry. Used currently only to fix compability issue in Tears of the Kingdom with atmosphere's romfs listing cache creation which allows loading romfs mods.

1.2.6a 2023/12/28

• Fix overlay lock not working since libnx 4.5.0 release.

v1.2.6 2023/12/08

• Add option in Advanced Settings to download config from repository Check/download config file. More in README.
• Slightly redesign Advanced Settings UI.

v1.2.5a 2023/11/21

• Fix saving settings if "plugins" folder doesn't exist inside SaltySD folder.

v1.2.5 2023/10/01

• Add support for SaltyNX 0.7.0+.

v1.2.4 2023/06/09

• Print titleid and buildid if no config is found
• Allow using all available buffers when game is not using all of them.
• For this release to properly work it is required to update NX-FPS to version 1.5.4

v1.2.3 2023/05/30

• Allow in games using Quadruple Buffering (for example Assassin's Creed The Ezio Collection) to force Triple Buffering.
• When saving settings with different Buffering than Double, Window Sync will be reseted to Enabled.

v1.2.2 2023/05/23

• Allow setting double buffer in games that are using triple buffer.
• More in README.
• NX-FPS 1.5.2+ is required.

v1.2.1 2023/05/20

• Add "Semi-Enabled" option for Window Sync that doesn't timeout nvnSyncWait if at least second consecutive frame was rendered below 8.3ms.
• At cost of slightly worse performance it solved issues in Tears of the Kingdom with longer loading times and screen tearing in menus at 60 FPS.
• It is required to update NX-FPS to version 1.5.1+ for this to work.

v1.2.0 2023/05/16

• Add support for MASTER_WRITE entry in FPSLocker patches that allows to patch any part of main before game is booted (when applied in Advanced Settings you will see "Master Write was loaded to game"). This is to allow patches to redirect assembly that normally read values from Read Only sections to code caves or patching executable to disable double buffer.
• Change name "Sync Wait" to "Window Sync Wait"
• Now if game config that can be converted to patch is not available, instead of error code overlay will print Game config file not found.
• NX-FPS 1.5.0+ is required to properly support new patches.

v1.1.4 2023/05/06

• FPSLocker now can show how many framebuffers is used by NVN and show it in Advanced Settings.
  • "Buffered frames: 2" = game is using real double buffer.
• Since this number cannot be changed on the fly, this is just an information update.

v1.1.3 2023/04/05

• Provide better API detection.
• Now you can see if game is using NVN, EGL or Vulkan in Advanced Settings.
• Requires updating NX-FPS to at least 1.3 version.

v1.1.2 2023/04/02

• Fix RTLD detection in older games to get proper BID (f.e. in L.A. Noire).

v1.1.1 2023/04/02

• Updated libtesla to fix random crash in docked mode related to freeing framebuffer.

v1.1.0 2023/03/19

• Add support for creating LOCK patches from yaml configs.

v1.0.0 2023/03/08

• First Release.

Credits

Thanks to ~WerWolv for creating Tesla environment, and ~cucholix + ~Monked for tests.

External links

• Twitter - https://twitter.com/masagratordev/status/1658144998313844736
• GitHub - https://github.com/masagrator/FPSLocker
• GitHub - https://github.com/masagrator/FPSLocker-Warehouse
• GBAtemp - https://gbatemp.net/threads/fpslocker-set-custom-fps-target-in-retail-games.627764/
• ForTheUsers - https://apps.fortheusers.org/switch/FPSLocker