Dynamic Wallpapers in XMB Require Manual Directory Override & Fail to Apply

Is there an existing issue for this?

• This is a bug in RetroArch frontend
• I have searched the existing issues

Description

When applying themes, dynamic wallpapers do not display unless the dynamic_wallpapers_directory config entry is manually set in retroarch.cfg to point to the exact folder containing the PNGs.

Root Cause? (Observed)

RetroArch does not automatically update dynamic_wallpapers_directory when switching icon themes.

The wallpaper loader does not recurse subdirectories — if you point to /assets/wallpapers/ instead of /assets/wallpapers/"your theme", the PNGs are not found.

In my case, config drift also left menu_shader_pipeline = "0" and menu_wallpaper = "", which may indicate prior theme switching left dynamic_wallpapers_directory unset?

Long-Term Proposed Solution

Homogenize wallpaper selection with icon themes — eliminate the “side quest” into Directories by adding a Wallpaper Theme picker to Appearance.

Full Proposal: Homogenize Dynamic Wallpapers with a Theme Picker

Appearance Menu Integration

Add "Wallpaper Theme" dropdown in Settings → User Interface → Appearance, alongside "Menu Icon Theme".

Selecting an icon theme could optionally auto-set a matching wallpaper theme if available.

Wallpaper Pack Discovery

RetroArch scans /assets/wallpapers/ for subdirectories containing PNGs.

Display each as a selectable pack in the dropdown.

Optionally support a wallpaper.json manifest for:

Theme display name

Author/credits

Thumbnail preview

Auto-Linking

When an icon theme and wallpaper theme share the same name (or defined link in manifest), selecting the icon theme could auto-select the wallpaper theme.

Shader Conflict Warning

If menu_shader_pipeline is active and dynamic wallpapers are enabled, display a brief notification:

“Note: Shaders override dynamic wallpapers.”

Fallback Handling

If a wallpaper for a specific category is missing, use bg.png in the selected wallpaper pack, or the RetroArch default.

Backward Compatibility

Keep dynamic_wallpapers_directory in retroarch.cfg for advanced/manual setups.

This proposal adds a UI shortcut for casual users while retaining manual control for power users.

Expected behavior

RetroArch does not automatically update dynamic_wallpapers_directory when switching icon themes. wallpaper folder should be recursed, or the user should be prompted in the "Appearance" sub-menu to change wallpaper theme.
Actual behavior: RetroArch does not set dynamic_wallpapers_directory. must be done via directories menu, and must point to the exact folder that holds the dynamic set. although this makes total sense when you understand how retroarch works on the backend, this "side-quest" is non-intuitive to end-users, and seems to be the source of multiple tutorials and confusion in the community sinec dynamic wallpapers inclusion over 5 years ago.

Steps to reproduce the bug

1. Install RetroArch on Android (use github).
2. Install Retrorama assets and point directories to them:

Icons → /storage/emulated/0/RetroArch/assets/xmb/custom

Wallpapers → /storage/emulated/0/RetroArch/assets/wallpapers

3.In RetroArch:

Settings → User Interface → Appearance → Menu Icon Theme → "Custom" (Retrorama)

Dynamic Background: ON

4.Return to main menu → dynamic wallpapers do not match the icon theme. this can be reproduced with other, vanilla themese shipped with the current version of retroarch aswell.

Version/Commit

1.21.0

Bisect Results

No response

Present in the nightly version

I don't know

Platform & operating system

Android 14

Affected Cores

NA

Environment information

Platform: Android

Device: Samsung Galaxy Z Fold 5 (US variant)

OS: Android 14 (One UI 6.x)

RetroArch: 1.21.0 (Git 05f94af), Built: 2025-04-30

Assets: Custom theme pack with dynamic wallpapers under /assets/wallpapers//...

Relevant log output

Start by reproducing the issue on Android 14 using the reported Retrorama paths, then inspect how Appearance settings and dynamic_wallpapers_directory behave when switching icon themes. The issue proposes several possible solutions—recursive discovery, a wallpaper picker, auto-linking, fallback handling, and shader warnings—so completion requires narrowing the scope and defining the expected behavior.