09. Theme Design guide - spruceUI/spruceOS GitHub Wiki

Making themes for SpruceOS is simplier than you think!

This guide will help you go through the theme making process in a step by step approach.

Spruce themes are simple folders located in /SDCARD/themes/.

To get started, you can either create your own folder or use the ready-made theme template as a starting point.

• CLICK HERE TO DOWNLOAD TEMPLATE

If you prefer to create one manually, navigate to /SDCARD/themes/ and make a new folder named however you want.

In 3.1.0 or above Spruce has a secret designer mode. In your SDCARD/spruce/flags folder create an extensionless file named designer_mode. Next time you boot Spruce will set it so all consoles are shown and you have access to our ThemePacker app to automatically pack themes compatible with our ThemeUnpacker system.

Inside your theme folder, create a config.json file or edit the template one.

This file will store some metadata and information to customize your theme.

The first part is the general theme information (metadata), name, author and description

{
    "name": "Theme Name",
    "author": "Your Name",
    "description": "Theme Description",

The next part is for the battery percentage text at the top right of the screen (next to the battery icon, you need to enable it in advanced settings). You can define color, size and font (we'll see this later):

    "batteryPercentage": {
        "color": "#HEXCOL",
        "font": "your-font.ttf",
        "size": 24
    },

This part is for the title text on top of the screen (like "apps", "settings", "games"). You can define color, font and size

    "title": {
        "font": "your-font.ttf",
        "size": 31,
        "color": "#HEXCOL"
    },

This part is for the hint text on bottom of the screen ("A open" and "B back", only some themes like the default one have it). You can define color, font and size

    "hint": {
        "font": "your-font.ttf",
        "size": 21,
        "color": "#HEXCOL"
    },

This part is for the text on the bottom-right of the screen (the text that counts which element you selected, like in apps). Eg. in a text like 7/10, the text 7/ is currentpage and 10 is total. You can define color, font and size

    "currentpage": {
        "font": "your-font.ttf",
        "size": 33,
        "color": "#HEXCOL"
    },
    "total": {
        "font": "your-font.ttf",
        "size": 32,
        "color": "#HEXCOL"
    },

(TODO)

    "grid": {
        "font": "your-font.ttf",
        "grid1x4": 24,
        "grid3x4": 24,
        "color": "#HEXCOL",
        "selectedcolor": "#HEXCOL"
    },
    "list": {
        "font": "your-font.ttf",
        "size": 24,
        "color": "#HEXCOL",
        "selectedcolor": "#HEXCOL"
    }
}

In the root folder of your theme, you can have multiple fonts you link to in the previous json we've seen.

-> config.json
-> font1.ttf
-> font2.ttf
-> font3.ttf
-> skin
-> skin_640_480
-> icons
-> sound

Now it's time to change spruce's skin. The /skin/ folder is the one that has the most impact on how the UI looks. If you get creative you can really do a lot here. I'll do my best to explain what all the files do:

• background.png is the background you see everywhere. MainUI, GamesUI, SettingsUI and AppsUI. If you don't see this in apps/settings it's beacuse you have a background for unselected list elements!
• bg-list-l.png is the background you see on selected list items with a bigger height, like in the apps list. bg-list-s.png is the one you see on items with a smaller height, like in settings, pop-ups, or in the games list.
• from bg-pop-menu-1.png to bg-pop-menu-4.png are the background of the pop-up you get when you click the home button in the menu. The number in the file name represents the number of elements in the pop-up list. You can see bg-pop-menu-2.png on the pop-up in main menu, bg-pop-menu-4.png when you click the home button in a game list and bg-pop-menu-3.png when you do it in the favorites list. Spruce does not use number 1 these files.
• div-line-h.png is the line shown at the top of each list element. in apps, game lists, settings etc.
• Empty.png this icon is shown when a list is empty, like in favorites.

• bg-title.png is the background of the top bar
• headphone-icon.png is the icon shown in the status bar when you connect headphones
• from ic-power-charge-0%.png to ic-power-charge-100%.png are the icons that get shown when you're charging the device. If you see duplicates with -backup at the end of the file name it's just something spruce does to add the percentage.
• from power-0%-icon.png to power-100%-icon.png are the battery icons. duplicates with -backup are normal.
• icon-A-54.png and icon-B-54.png are the help icons shown in the bottom bar of the screen (A open and B back)
• from icon-volume-00.png to icon-volume-20.png are the volume level icons
• from icon-wifi-signal-01.png to icon-wifi-signal-04.png are the wifi signal
• miyoo-topbar.png logo in the top left
• tips-bar-bg.png is the background of the bottom bar

• dot-a.png and dot-n.png are the bullet icons that represent which main menu element is selected. dot-a for selected, dot-b for unselected.
• ic-app-f.png, ic-favorite-f.png, ic-game-f.png, ic-setting-f.png and ic-recent-f.png are the 4/5 icons shown in main menu for a selected element.
• ic-app-n.png, ic-favorite-n.png, ic-game-n.png, ic-setting-n.png and ic-recent-n.png , same as above but for unselected elements.

• bg-game-item-f.png is the background of a selected game, bg-game-item-n.png is for unselected games
• ic-favorite-mark.png is the icon you see next to a game added to your favorites
• num-bg.png is the list number of the game when you change view
• list-num.png is the text of the numbers you see when you change view
• preview-bg.png is the background you see in boxarts
• thumb-default.png is the default boxart you see when a game doesn't have one

These 6 files are for the loading animation when you run a game:

• files from app_loading_01.png to app_loading_05.png are for the icon animation.
• file app_loading_bg is for the background beneath the icon. You need to update icons show changes in this! Just select another theme, go back to menu to change icons, then select your theme again.
• progress-dot.png in progress loading, when indexing all the game files (clicking refresh roms in main menu), these 3 dots will show up.

• bg-btn-01-f is for selected keyboard keys, bg-btn-01-n for unselected ones
• bg-btn-02-f and bg-btn-02-n same as above but for the 5 keys at the bottom row of the keyboard. Here, icon-delete.png is the DEL icon, icon-space.png is the TAB icon, icon-abc.png and icon-character.png are the symbols/letters icons, icon-OK.png and icon-START.png are in the OK/start button, icon-shift.png and icon-shift-active.png are for the SHIFT icon.
• icon-L2.png for the L2 icon and icon-R2.png for R2
• icon-x.png and icon-y.png are the X and Y buttons
• input.png is the space where you see the input

• bg-io-testing.png is the image of the a30 you see in hardware test
• bg-keysetting.png image of the a30 you see in Button Remap
• bg-keysetting-f.png BG you get on a selected key in Button Remap
• ic-MENU.png menu button icon you see at the bottom in button remap
• ic-MENU+A.png help icon you can see at the bottom in Hardware test
• color.png icon for the display option
• fixit.png icon for the fixes option
• icon-brightness-48.png for the brightness option
• icon-device-info-48.png for the device info and hardware test options
• icon-factory-reset-48.png for the factory reset option
• icon-joystick-calibrate.png for the calibrate joystick option
• icon-joystick-test.png for the joystick test option
• icon-key-setting-48.png for the button remap option
• icon-language-48.png for the change language option
• icon-left-arrow-24.png and icon-right-arrow-24.png are the arrows you see in brightness, volume etc.
• icon-setting-wifi.png for the Wi-Fi option
• icon-Shutdown.png for the shutdown otpion
• icon-theme.png for the themes option
• icon-usb-storage.png spruce disabled usb support but this could come back
• icon-wifi-locked.png in the wifi options, next to wifis. icon-wifi-connected.png doesn't seem to work but maybe in the future?
• joystick-test-bg.png and joystick-test-dot.png you see these in joystick test
• all files starting with mask- are shown in hardware test (apart from mask-add.png, mask-LR.png and mask-minus.png which are not shown!)
• pop-bg.png is the background of the pop-up you see when you click shutdown
• sound-icon.png is the icon for volume and bgm volume

The /skin_640_480/ folder is where you'll need to put the files that modify the in-game menu UI.

• empty.png is the icon or text that shows when a save slot is empty.
• icon-A-27.png and icon-b-27.png are the A and B icons that show at the bottom of the screen.
• icon-left-arrow-24.png and icon-right-arrow-24.png are the arrow icons.
• icon-menu-right-arrow-24.png is the icon that shows on the menu list, on "save" and "load", when selected.
• list-item-select-bg-short.png is the background of selected menu list items.
• menu-bg-7.png and menu-sub-bg.png are the backgrounds of the menu.
• menu-sub-title-bg.png is the background of the topbar you see on the save or load sub menu.
• statbg.png is the bottom bar (where you see A and B buttons)

This is pretty easy, in this folder you have a list of all consoles supported by Spruce, these files represent unselected icons in the games menu. Here you can also find 2 additional folders:

• in /icons/sel/ you have the same list of consoles, but this time they represent selected icons.
• in /icons/app/ you have a list of icons of all the apps in spruce (you can find them in the apps menu)

In this folder you only have 2 files:

• change.wav is the short sound you hear when you move around the UI
• bgm.mp3 is music that plays in the background, currently not working in spruce. Best practice at this point is to include a blank bgm file for when we fix it, or have it in already so you won't need to update in the future.

When it comes to releasing your themes to users you can release it as a contained zip/7z/rar as you would like and direct them to extract it into their themes folder.

Starting with Spruce v3.0.0 spruce now includes a theme unpacker/packer utility so users don't need to extract them themselves and gives better self contained packages with faster transfers to SDCards.

If you want to release your theme as a version that is compatible with Theme Unpacker, on your SDCard place the theme in the /Themes/ folder as you would if you were going to use it. Go to your /App/ folder on your SDCard and find the ThemePacker app. Open and edit the ThemePacker's config.json you should see "@label" within the config. Remove the @ symbol. This will allow the A30 to see the app. Place your SDcard back into your A30 and start up. Navigate to the ThemePacker app and run it. This will pack all the themes on your device except the SPRUCE theme into a ThemeUnpacker compatible 7z file. After it finishes check your /Theme/ directory for the 7z. Get that file off your A30 however you wish, and use this for your release.

Just direct users to put the 7z file in their /Themes/ directory and Spruce will handle the rest on next boot!