Packaging and Sharing LaunchBox Themes

Written By launchbox

Last updated About 1 month ago

Once a LaunchBox Desktop theme is working locally, the final step is packaging it so other users can install it cleanly. A good package should contain the theme files LaunchBox expects, avoid machine-specific paths, and be easy to test on a separate LaunchBox installation.

LaunchBox managed theme installs extract the downloaded archive directly into LBThemes\[Theme Name]. Because of that, the structure inside the archive matters.

Final Theme Folder Structure

A finished LaunchBox theme should be organized like this inside the user's LaunchBox folder:

LaunchBox\LBThemes\[Theme Name]\Views\MainView.xaml                                         SideBarView.xaml                                         BoxesContentView.xaml                                         ListContentView.xaml                                         GameDetailsView.xaml                                         PlatformFiltersDetailsView.xaml                                         ControlsView.xaml                                         ContentBackgroundView.xaml                                         WorkingView.xaml                                         NotificationView.xaml                                         NotificationListView.xaml                                   \Images                                   \Fonts                                   \Plugins

Only include the view files your theme customizes. Missing view files can fall back to the Default theme, so a theme does not need to include every possible XAML file unless it intentionally customizes all of them.

What to Put in the Zip

For managed installs, LaunchBox extracts the archive into:

LBThemes\[Theme Name]

That means the archive should contain the contents of the theme folder, not another nested copy of the theme folder.

Good archive structure:

Views    Images    Fonts    Plugins

Avoid this nested structure:

[Theme Name]\      Views      Images      Fonts

If the zip contains an extra top-level theme folder, LaunchBox may extract the files into LBThemes\[Theme Name]\[Theme Name], and the theme views will not be found.

Recommended Package Contents

  • Views folder with your customized XAML files

  • Images folder for theme-specific artwork

  • Fonts folder for theme-specific fonts

  • Plugins folder only if the theme requires theme-specific plugins

  • Any readme or license file that is useful for users

Do not include LaunchBox user data, game media, cache files, logs, backups, or files from another user's library.

Managed Theme Version File

When LaunchBox installs, updates, or repairs a managed LaunchBox theme, it writes a file named version inside the theme folder.

LBThemes\[Theme Name]\version

This file stores the installed theme version ID. LaunchBox uses it to identify the installed version and decide whether an update is available.

Theme authors generally do not need to create this file manually for managed downloads. LaunchBox writes it during install, repair, and update. For local development themes, it is normal for the theme to appear as installed but unidentified or without a managed installed version.

Theme Names Matter

LaunchBox identifies installed LaunchBox themes by folder name under LBThemes. The folder name should match the theme name users expect to see in the Themes and Media manager.

LBThemes\[Theme Name]

Use a stable folder name once the theme is shared. Renaming the folder effectively creates a separate local theme from LaunchBox's point of view.

Screenshots and Preview Media

The LaunchBox Themes and Media manager can show screenshots and preview video for managed themes. Those media entries are part of the theme listing data, not files that LaunchBox discovers from the local Images folder.

The theme's local Images folder is for artwork used by the theme's XAML. Theme listing screenshots and preview video are handled separately by the theme distribution system.

Use Portable Paths

Before packaging, check every image and font reference. Theme assets should use LAUNCHBOX_THEME_FOLDER.

LAUNCHBOX_THEME_FOLDER/Images/Background.jpg    LAUNCHBOX_THEME_FOLDER/Fonts/Poppins-Regular.ttf#Poppins

Avoid absolute paths like C:\LaunchBox\.... Those paths may work on the developer's machine but fail for users who installed LaunchBox somewhere else.

Clean the Theme Before Packaging

Before creating the zip, remove files that are not part of the theme itself.

  • Remove temporary files

  • Remove editor backup files

  • Remove old experimental XAML files that are not used

  • Remove personal notes that are not intended for users

  • Remove generated build folders unless they are required

  • Remove unused large images, videos, or fonts

Keeping the package small makes it easier to download, review, update, and troubleshoot.

Test the Package Like a User

Do not only test the working development folder. Test the final package after it has been zipped.

  1. Create the final zip file.

  2. Use a separate LaunchBox folder or clean test installation.

  3. Extract the package to LBThemes\[Theme Name].

  4. Open Tools > Manage > LaunchBox Themes and Media.

  5. Apply the theme.

  6. Let LaunchBox restart.

  7. Test the common views and workflows.

This catches nested-folder mistakes, missing assets, bad font paths, and files that only existed in the development copy.

What to Test Before Sharing

  • LaunchBox starts successfully with the theme applied

  • MainView.xaml loads and keeps the required license button and LicenseText binding

  • Sidebar navigation works across platforms, categories, playlists, and filters

  • Search and filter controls still work

  • Boxes and list views both load if customized

  • Game details and platform/filter details load correctly

  • Controls view works for status text, box size, volume, mute, and music controls if customized

  • Background, working, and notification views still behave correctly if customized

  • All images and fonts load from the packaged theme

  • The theme works after a full LaunchBox restart

Common Packaging Mistakes

  • Putting the theme folder inside the zip instead of the theme folder contents

  • Referencing files from the developer's local machine

  • Forgetting to include custom fonts

  • Forgetting to include custom images

  • Including a Plugins folder without the required plugin files

  • Packaging old test views that override newer working views

  • Renaming the theme folder after testing

  • Only testing the development folder instead of the final zip

In Short

Package the contents of the LaunchBox theme folder so they extract directly into LBThemes\[Theme Name]. Keep assets inside the theme, use LAUNCHBOX_THEME_FOLDER paths, remove development clutter, and test the final zip on a clean LaunchBox folder before sharing it.