Forcing Vsync for Flatpak Apps

Forcing Vsync for Flatpak Apps

Some Flatpak apps may show screen tearing when launched from Batocera, especially on CRT setups using AMD GPUs with the modesetting driver.

Batocera launches Flatpak apps from simple .flatpak shortcut files, for example:

/userdata/roms/flatpak/Firefox.flatpak

The content of the file should only be the Flatpak application ID:

org.mozilla.firefox

Do not put commands inside the .flatpak file.

---

Example: Force vsync for Firefox Flatpak

Open a terminal or connect to Batocera using SSH.

Run:

flatpak override --user \
  --env=vblank_mode=3 \
  --env=MESA_VK_WSI_PRESENT_MODE=fifo \
  org.mozilla.firefox

This adds two Mesa environment variables for Firefox:

vblank_mode=3
MESA_VK_WSI_PRESENT_MODE=fifo

---

What these settings do

vblank_mode=3

Forces Mesa OpenGL applications to sync to vertical blank.

This can help reduce or remove tearing in OpenGL-based Flatpak apps.

MESA_VK_WSI_PRESENT_MODE=fifo

Forces Mesa Vulkan applications to prefer FIFO present mode.

FIFO is the normal Vulkan vsync mode.

---

Check that the setting was saved

Run:

flatpak override --user --show org.mozilla.firefox

You should see:

[Environment]
vblank_mode=3
MESA_VK_WSI_PRESENT_MODE=fifo

If you see this, the override is active.

---

Does this survive reboot?

Yes.

The override is saved in Batocera's persistent userdata area, so it will still be active after a reboot.

After rebooting, you can check again with:

flatpak override --user --show org.mozilla.firefox

---

Important: Keep the .flatpak launcher clean

The launcher file should contain only the Flatpak app ID.

Correct:

org.mozilla.firefox

Wrong:

flatpak override --user \
  --env=vblank_mode=3 \
  --env=MESA_VK_WSI_PRESENT_MODE=fifo \
  org.mozilla.firefox

If the .flatpak file contains the override command, Batocera will try to launch the whole command as if it was an app ID, and the Flatpak will fail to start.

---

Fix the Firefox launcher file

If you accidentally edited the launcher file incorrectly, you can reset it like this:

cat > /userdata/roms/flatpak/Firefox.flatpak <<'EOF'
org.mozilla.firefox
EOF

---

Undo the override

To remove the vsync override again:

flatpak override --user --unset-env=vblank_mode org.mozilla.firefox
flatpak override --user --unset-env=MESA_VK_WSI_PRESENT_MODE org.mozilla.firefox

Then check again:

flatpak override --user --show org.mozilla.firefox

---

Using this with another Flatpak app

First list installed Flatpak apps:

flatpak list --app

Find the application ID.

Then replace org.mozilla.firefox with the correct app ID.

Example format:

flatpak override --user \
  --env=vblank_mode=3 \
  --env=MESA_VK_WSI_PRESENT_MODE=fifo \
  APP.ID.HERE

---

Notes

This fix is useful for Flatpak apps launched through Batocera's EmulationStation Flatpak system.

It is especially useful on Xorg/modesetting setups where an app shows tearing.

It may not fix every application, because some apps use their own rendering path, compositor, frame limiter, or browser engine settings.