Skip to content

ThemeManual

Jump to bottom
XorTroll edited this page Jul 25, 2024 · 3 revisions

Manual themeing guide

This guide details how to manually modify all the different themeable assets, which are properly described in the base specification (the two pages are pretty much complementary).

This is only required for manually making the themes completely by yourself: if you plan to use uDesigner this guide is not needed at all.

Basic regards

  • Themes are ZIP files internally containing key files. Asset paths must be followed carefully as they are case-sensitive.

  • All images support the following formats: PNG, JPG, WEBP

    • Because of this, the extension be indicated with a wildcard for all images (and only images) in this guide. For example, if an image is located at demo/Example.*, then uLaunch will search any of the following: demo/Example.png, demo/Example.jpg, demo/Example.webp...

    • If multiple of them are present, uLaunch will load the first one it finds (the order may be arbitrary)

  • Background music must be MP3 files, and sound effects must be WAV files. All audio is expected to be sampled at 44100 Hz.

  • All fields/settings are stored in specific JSON files, individually detailed below. All fields are required unless indicated otherwise.

  • The default theme can be checked as an example of most of the details explained in this guide (although it has no sound content).

Theme manifest

The manifest is located at theme/Manifest.json and has the following fields:

  • format_version: Integer containing the format version. The current version is 2, any theme with a lower value it is considered outdated.

  • name: String containing the theme name

  • description: String containing the theme description

  • author: String containing the theme author

  • release: String containing the theme release/version

The optional icon is located at theme/Icon.*.

Menus

uMenu (the uLaunch UI component being themed) has four menus whose names are pretty explanatory.

  • The main menu, whose components' settings are always inside main_menu:

MainMenu

  • The startup menu, whose components' settings are always inside startup_menu:

StartupMenu

  • The themes menu, whose components' settings are always inside themes_menu:

ThemesMenu

  • The settings menu, whose components' settings are always inside settings_menu:

SettingsMenu

(Note that the vast majority of a theme consists of main menu assets)

Common

  • Background: ui/Background.*

  • Font: ui/Font.ttf

UI settings

Settings are controlled at ui/UI.json.

These are the general settings:

  • Suspended application final alpha: integer suspended_app_final_alpha

  • Text color: RGB/RGBA hex-string text_color

  • Toast base color: RGB/RGBA hex-string toast_base_color

  • Toast text color: RGB/RGBA hex-string toast_text_color

  • Menu focus color: RGB/RGBA hex-string menu_focus_color

  • Menu background color: RGB/RGBA hex-string menu_bg_color

  • Dialog title color: RGB/RGBA hex-string dialog_title_color

  • Dialog content color: RGB/RGBA hex-string dialog_cnt_color

  • Dialog option color: RGB/RGBA hex-string dialog_opt_color

  • Dialog color: RGB/RGBA hex-string dialog_color

  • Dialog over color: RGB/RGBA hex-string dialog_over_color

All the following particular element cases (static images, texts and item menus) are entries customizable inside their respective menus: in other words, an example text element demo_text in the main menu will have its fields inside main_menu and inside demo_text.

As noted in the specification, images are split into static and non-static, where only static ones have their corresponding (layout) settings

Static image settings

All static images have the following (all optional) custom fields:

  • x: the absolute X coordinate, thus going from 0 to 1920 (ignored if the horizontal alignment is centered), defaults to 0 if not specified

  • y: the absolute Y coordinate, thus going from 0 to 1080 (ignored if the vertical alignment is centered), defaults to 0 if not specified

  • h_align: horizontal alignment (possible self-explanatory values: left, center, right), defaults to left if not specified

  • v_align: vertical alignment (possible self-explanatory values: top, center, bottom), defaults to top if not specified

  • visible: whether the image is visible (boolean true or false), defaults to true if not specified

    • Some elements are forced to be visible, thus this field is ignored (they are explicitly indicated below)

Text settings

All texts have the following (all optional) custom fields:

  • x, y, h_align, v_align: same as static images

  • font_size: Text font size (possible self-explanatory values: small for 27px, medium for 30px, medium-large for 37px, large for 45px), defaults to medium if not specified

Item menu settings

All item menus have the following (all optional) custom fields:

  • x, y, h_align, v_align: same as static images

Sound settings

Sound-related settings (currently only relative to BGM) are (optionally) controlled at sound/BGM.json.

For each menu (and globally outside), the following (all optional) settings can be customized:

  • bgm_loop boolean

  • bgm_fade_in_ms integer

  • bgm_fade_out_ms integer

Theme assets

Main menu

Top menu

  • Backgrounds (top_menu_bg in settings):

    • Background for application entry: ui/Main/TopMenuBackground/Application.*

    • Background for homebrew entry: ui/Main/TopMenuBackground/Homebrew.*

    • Background for folder entry: ui/Main/TopMenuBackground/Folder.*

    • Background for default/anything else: ui/Main/TopMenuBackground/Default.*

  • Battery text: battery_text

  • Battery top icons: battery_top_icon

    • ui/Main/TopIcon/Battery/10.*, ui/Main/TopIcon/Battery/20.*, etc. up to ui/Main/TopIcon/Battery/100.*

    • ui/Main/TopIcon/Battery/Charging.*

  • Time text: time_text

  • Date text: date_text

  • Connection top icons: connection_top_icon

    • ui/Main/TopIcon/Connection/0.*, ui/Main/TopIcon/Connection/1.*, ui/Main/TopIcon/Connection/2.*, ui/Main/TopIcon/Connection/3.*

    • ui/Main/TopIcon/Connection/None.*

  • Logo icon: logo_top_icon, not customizable and cannot be made invisible

Entry menu

  • Background: entry_menu_bg, located at ui/Main/EntryMenuBackground.*

  • Left icon: entry_menu_left_icon, located at ui/Main/EntryMenuLeftIcon.*

  • Right icon: entry_menu_right_icon, located at ui/Main/EntryMenuRightIcon.*

  • Current entry main text: cur_entry_main_text

  • Current entry sub text: cur_entry_sub_text

Entry icons

  • Empty entry icon: ui/Main/EntryIcon/Empty.*

  • Folder entry icon: ui/Main/EntryIcon/Folder.*

  • Default application entry icon: ui/Main/EntryIcon/DefaultApplication.*

  • Default homebrew entry icon: ui/Main/EntryIcon/DefaultHomebrew.*

  • Mii editor entry icon: ui/Main/EntryIcon/MiiEdit.*

  • Web browser entry icon: ui/Main/EntryIcon/WebBrowser.*

  • Album entry icon: ui/Main/EntryIcon/Album.*

  • Controller support entry icon: ui/Main/EntryIcon/Controllers.*

  • Settings entry icon: ui/Main/EntryIcon/Settings.*

  • Themes entry icon: ui/Main/EntryIcon/Themes.*

Input bar

  • Background: input_bar, located at ui/Main/InputBarBackground.*

Quick icons

  • Power quick icon: ui/Main/QuickIcon/Power.*

  • Mii editor quick icon: ui/Main/QuickIcon/MiiEdit.*

  • Web browser quick icon: ui/Main/QuickIcon/WebBrowser.*

  • Album quick icon: ui/Main/QuickIcon/Album.*

  • Controller support quick icon: ui/Main/QuickIcon/Controllers.*

  • Settings quick icon: ui/Main/QuickIcon/Settings.*

  • Themes quick icon: ui/Main/QuickIcon/Themes.*

Over icons

  • Cursor over icon: ui/Main/OverIcon/Cursor.*

  • Border over icon: ui/Main/OverIcon/Border.*

  • Selected over icon: ui/Main/OverIcon/Selected.*

  • Suspended over icon: ui/Main/OverIcon/Suspended.*

  • Homebrew takeover application over icon: ui/Main/OverIcon/HomebrewTakeoverApplication.*

Sound

  • BGM: sound/Main/Bgm.mp3

  • Post suspend: sound/Main/PostSuspend.wav

  • Cursor move: sound/Main/CursorMove.wav

  • Page move: sound/Main/PageMove.wav

  • Entry select: sound/Main/EntrySelct.wav

  • Entry move: sound/Main/EntryMove.wav

  • Entry swap: sound/Main/EntrySwap.wav

  • Entry cancel select: sound/Main/EntryCancelSelect.wav

  • Entry move into: sound/Main/EntryMoveInto.wav

  • Home press: sound/Main/HomePress.wav

  • Logoff: sound/Main/Logoff.wav

  • Launch application: sound/Main/LaunchApplication.wav

  • Launch homebrew: sound/Main/LaunchHomebrew.wav

  • Close suspended: sound/Main/CloseSuspended.wav

  • Open folder: sound/Main/OpenFolder.wav

  • Close folder: sound/Main/CloseFolder.wav

  • Open mii editor: sound/Main/OpenMiiEdit.wav

  • Open web browser: sound/Main/OpenWebBrowser.wav

  • Open user page: sound/Main/OpenUserPage.wav

  • Open settings: sound/Main/OpenSettings.wav

  • Open themes: sound/Main/OpenThemes.wav

  • Open controllers: sound/Main/OpenControllers.wav

  • Open album: sound/Main/OpenAlbum.wav

  • Open quick menu: sound/Main/OpenQuickMenu.wav

  • Close quick menu: sound/Main/CloseQuickMenu.wav

  • Resume application: sound/Main/ResumeApplication.wav

  • Create folder: sound/Main/CreateFolder.wav

  • Create homebrew entry: sound/Main/CreateHomebrewEntry.wav

  • Entry remove: sound/Main/EntryRemove.wav

  • Error: sound/Main/Error.wav

Startup menu

  • Info text (welcome message): info_text

  • Users menu: users_menu

Sound

  • BGM: sound/Startup/Bgm.mp3

  • User create: sound/Startup/UserCreate.wav

  • User select: sound/Startup/UserSelect.wav

Themes menu

  • Info text (descriptive message): info_text

  • Themes menu: themes_menu

Sound

  • BGM: sound/Themes/Bgm.mp3

  • Theme change: sound/Themes/ThemeChange.wav

  • Back: sound/Themes/Back.wav

Settings menu

  • Info text (descriptive message): info_text

  • Settings menu: settings_menu

  • Editable setting icon: ui/Settings/SettingEditableIcon.*

  • Non-editable setting icon: ui/Settings/SettingNonEditableIcon.*

Sound

  • BGM: sound/Settings/Bgm.mp3

  • Setting edit: sound/Settings/SettingEdit.wav

  • Setting save: sound/Settings/SettingSave.wav

  • Back: sound/Settings/Back.wav

Available pages

Clone this wiki locally