Sphaira - hbmenu replacement

Sphaira is hbmenu alternative. It currently has feature parity with hbmenu (that is, launches homebrew + nxlink) whilst adding quite a few features.



HomeBrew​

The main menu tab, it lists all the .nro found in "/switch/". From there, you can launch, sort, delete, create a forwarder etc.
You can navigate to the other menu tabs using "L" and "R", explained below.

FileBrowser​

By pressing "L" from the main menu, you can access the file browser. You can Cut, Copy, Delete, Rename etc.
You can select multiple files / folders by using the "ZR" button and then se the above functions of that group of files.

Forwaders can be created if the selected file has a file assoc, see below for more details.

Appstore​

sphaira features an appstore, using the api from https://hb-app.store/switch. It can be navigated to by pressing "R" from the main menu.
The appstore is feature parity with hb-appstore app, as well as installing the manifests in the same folder as hb-appstore, in order to not break compatibility between the two.

Themes​

sphaira comes with 3 themes, abyss (default), black and white (unfinished).
custom themes can be added to "/config/sphaira/themes/", here is the abyss theme for example:
INI:
[meta]
name=Abyss
author=TotalJustice
version=1.0.0
; unused currently
preview=romfs:/theme/preview.jpg

[theme]
background=0x0f111aff
grid=0x0f115c30
selected=0x0f115cff
selected_overlay=0x529cffff
text=0xffbc41ff
text_selected=0x529cffff

icon_audio=romfs:/theme/icon_audio.png
icon_video=romfs:/theme/icon_video.png
icon_image=romfs:/theme/icon_image.png
icon_file=romfs:/theme/icon_file.png
icon_folder=romfs:/theme/icon_folder.png
icon_zip=romfs:/theme/icon_zip.png
icon_nro=romfs:/theme/icon_nro.png

music can be added to a theme, as long as the music is converted to bfstm format. simply add an entry like so: `music=/config/sphaira/themes/music/bgmusic_pcm.bfstm`

Forwaders​

sphaira can create and install forwarders for any .nro. It will use the icon of the .nro and the name + author.

It can also install forwarders for files that have a file assoc. For example, if mgba is installed and a game is located in "/roms/gba/game.gba", then the "Install Fowarder" option will appear. In this case, it will try to scrape the icon of the game, otherwise it will use the icon of the .nro and the name will be a combination of the .nro name and game name.

File Assoc​

file assoc is a way to associate file extensions (.gba, .nro etc) with a homebrew app. For example, clicking on rom.gbc that has an file assoc will bring up a list of all the applications that can handle it.
This can be used for emulators, media players, text editors etc...

custom file assoc should go in the folder "/config/sphaira/assoc/"

the format is *very* simple, here is an example of vgedit.ini
INI:
[config]
supported_extensions=txt|json|cfg|ini|md|log

and again for mgba.ini
INI:
[config]
supported_extensions=gba|gbc|sgb|gb
database=Nintendo - Game Boy|Nintendo - Game Boy Color|Nintendo - Game Boy Advance

"path": (optional) fullpath to the .nro. if not specified, it uses the name of the ini, ie, mgba.ini will use mgba.nro.
"supported_extensions": list of extensions the application supports, separated by |. plea
"database": (optional) name of the rom database to use defined by the left-side of this table <https://gist.github.com/ITotalJustice/d5e82ba601ca13b638af9b00e33a4a86>..

All of the retroarch cores has file assoc built into sphaira, so if you download retroarch using the appstore, and then navigate to "/roms/gbc/game.gbc", gambatte and mgba will be available to be selected.

Games can be kept in .zip format, sphaira will peek into the .zip and find the real extension and use that for displaying icons / file assoc.

Roms​

roms should be placed in "/roms/system_name/" where system name is defined by this table right-side entries <https://gist.github.com/ITotalJustice/d5e82ba601ca13b638af9b00e33a4a86>.
this is the same layout emulation station uses. the reason for forcing roms to be in specific folders is due to many roms for different systems using the same file extension, ie, .bin / .cue or .chd.

roms placed in subfolders are allowed, for example "/roms/psx/scooby-doo/scooby-doo.bin" is valid.

Themezer​

themes can be browsed and download by going Menu Options -> Misc -> Themezer. Themes will be downloaded to "/themes/sphaira/Theme Name - By Author/".
To install themes, launch "NXThemes Installer" and browse to the selected folder listed above.

Irs​

InfaRed Sensor. its a toy app i made 4(?) years ago where it shows the output of the joycon irs, use it to take a selfie :)

Web​

Launches the builtin web browser, it's not very good.

Nxlink​

For homebrew developers, nxlink is built into sphaira. You do not have to press any special buttons, just do "nxlink *.nro" and send your nro like normal, console logging works to be using "nxlink -s *.nro"
By default, this is enabled in the background, to disable it: Menu Options -> Network -> Nxlink.



That's most of the features spahira has. If you enjoy it so much that you'd rather it be launched over regular hbmenu, you can enable the option in "Menu Options -> Replace hbmenu on exit" where it will do just that. It will create a backup of hbmenu in "/switch/hbmenu.nro" should you wish to swap back.

2024121522512100-879193CD6A8B96CD00931A628B1187CB.jpg
2024121522505300-879193CD6A8B96CD00931A628B1187CB.jpg
2024121522502300-879193CD6A8B96CD00931A628B1187CB.jpg
2024121522513300-879193CD6A8B96CD00931A628B1187CB.jpg
2024121523033200-879193CD6A8B96CD00931A628B1187CB.jpg
2024121523074900-879193CD6A8B96CD00931A628B1187CB.jpg
2024121522514300-879193CD6A8B96CD00931A628B1187CB.jpg


Releases: https://github.com/ITotalJustice/sphaira/releases/
Bleeding-edge Releases: https://github.com/ITotalJustice/sphaira/actions
Source Code: https://github.com/ITotalJustice/sphaira
 

Attachments

  • 2024121523070300-879193CD6A8B96CD00931A628B1187CB.jpg
    2024121523070300-879193CD6A8B96CD00931A628B1187CB.jpg
    98.9 KB · Views: 11
Last edited by TotalJustice,

ItzMeGab

Active Member
Newcomer
Joined
Dec 5, 2023
Messages
26
Trophies
0
Age
25
XP
230
Country
Philippines
Great app, thanks for this!

I hope you could add an option for themes to be set to auto for light/dark system themes
 

TotalJustice

Well-Known Member
OP
Member
Joined
Jan 28, 2017
Messages
561
Trophies
2
XP
3,368
Country
United Kingdom
Great app, thanks for this!

I hope you could add an option for themes to be set to auto for light/dark system themes
Funny thing is, I was thinking about this today 😄 I'll add it for the next release.
The way I picture it working is it will be the default option for new installs. The "auto" option will be able to be selected from the themes menu, the same way the language "auto" feature works.
 
  • Like
Reactions: skills14

linuxares

The inadequate, autocratic beast!
Global Moderator
Joined
Aug 5, 2007
Messages
14,375
Trophies
3
XP
20,545
Country
Sweden
Funny thing is, I was thinking about this today 😄 I'll add it for the next release.
The way I picture it working is it will be the default option for new installs. The "auto" option will be able to be selected from the themes menu, the same way the language "auto" feature works.
I hope you add a TotalJustice easter egg somewhere in the software :3
 

ItzMeGab

Active Member
Newcomer
Joined
Dec 5, 2023
Messages
26
Trophies
0
Age
25
XP
230
Country
Philippines
Funny thing is, I was thinking about this today 😄 I'll add it for the next release.
The way I picture it working is it will be the default option for new installs. The "auto" option will be able to be selected from the themes menu, the same way the language "auto" feature works.
Cool! Also can you make the music, idk if it is the right term but something like global? I mean not theme specific, so whichever themes we are using, we can still have the music
 

TotalJustice

Well-Known Member
OP
Member
Joined
Jan 28, 2017
Messages
561
Trophies
2
XP
3,368
Country
United Kingdom
Cool! Also can you make the music, idk if it is the right term but something like global? I mean not theme specific, so whichever themes we are using, we can still have the music
Yes, that's already done in the theme V2 branch. You can set the music in /config/sphaira/theme/default_music.bfstm
I'll explain more of the changes when I finally get around to making a new release
 

2K417

.......
Member
Joined
Feb 2, 2023
Messages
348
Trophies
0
XP
1,360
Country
Philippines
anyone else expecting crashing while opening breeze or exiting when sphaira is your default hbmenu

can someone pls. replicate this if it will crash your switch

go to album > open sphaira > make it your default hbemnu

start a game > in my case Ys Memoire The Oath In Felghana > launch breeze / exit breeze > game crash

reboot switch > go to album > open sphaira > disable sphaira as default hbmenu = it wont change back to default hbmenu

PS: to return to default hbmenu > replace hbmenu with this

switch info
switch v2
Current Version: 19.0.1 / AMS 1.8.0 / E
 

cucholix

00000780 00000438
Member
Joined
Jan 17, 2017
Messages
3,286
Trophies
2
Age
45
XP
6,626
Country
Chile
anyone else expecting crashing while opening breeze or exiting when sphaira is your default hbmenu

can someone pls. replicate this if it will crash your switch

go to album > open sphaira > make it your default hbemnu

start a game > in my case Ys Memoire The Oath In Felghana > launch breeze / exit breeze > game crash

reboot switch > go to album > open sphaira > disable sphaira as default hbmenu = it wont change back to default hbmenu

PS: to return to default hbmenu > replace hbmenu with this

switch info
switch v2
Current Version: 19.0.1 / AMS 1.8.0 / E
Try disabling custom sysmodes before you open album
 

TotalJustice

Well-Known Member
OP
Member
Joined
Jan 28, 2017
Messages
561
Trophies
2
XP
3,368
Country
United Kingdom
Version 0.6.0 is out!

* white theme.
* add github downloader, add entries in `/config/sphaira/github/name.json`
* fix appstore bug where i forgot to add a break in a switch case.
* greatly optimise asset downloading by using etags to cache all assets and only re-downloading upon the etag changing.
* all internal events now have a timeout, meaning if many events happen at once, it will only process as much as possible within the given timeslice.
* lazy loading images are now capped at loading 2 per frame. this removes frame drops when scrolling through the appstore (due to slow io).
* daybreak detection now supports custom paths.
* ftp server now uses ftpsrv config and all of its moutpoints.
* ftp server download (write) speed has been greatly improved by using ftpsrv io code.
* option to restore hbmenu when disabling the "Replace hbmenu on exit" option.
* add custom mount points for fs (sd and image).
* patch forwarder npdm to support the new debug flags.
* add touch screen support.
* improve the load time of libpulsar (sound loading lib).
* option to set default background music, place file in `/config/sphaira/themes/default_music.bfstm`
* revamp themes, now more customisable.
* add theme inheritance, greatly simplifying creating new themes.
* fix popup list being drawn offscreen.
* fix scrollbar being draw offscreen.
* sidebar text will now scroll if the length of the text is too big for the region.

A default music file can now be set without the need to create a new theme to specify said music. I've attached an example using the GameCube menu music.

For theme creation, refer to the examples in the themes folder and this post for what each entry is for.

For GitHub downloader, see the examples in the github folder. In summary, all that is needed is a url to the github page. In sphaira, clicking on the entry will return all assets to download from the latest release. You can filter out using text found in the assets. For example, ftpsrv has builds for different platforms, and has 2 builds for the switch, both releases contain the name "switch". so to only display those 2 releases, you would add "switch" in the assets field, see here for an example.

2025011301014900-CA43EC7375AB1E2BC8AFC050C0941918.jpg

2025011301021700-CA43EC7375AB1E2BC8AFC050C0941918.jpg

2025011301003900-CA43EC7375AB1E2BC8AFC050C0941918.jpg
 

Attachments

  • gamecube_music.zip
    3.7 MB · Views: 8
  • github_download_examples.zip
    2.1 KB · Views: 5

LudoTheGreat

New Member
Newbie
Joined
Jan 13, 2025
Messages
1
Trophies
0
Age
49
XP
6
Country
United States
I've lurked here for so many years. I had to create a login just to say how brilliant this is. It is coming together extremely nice. Thanks (everyone) for all the work on it.
 
  • Like
Reactions: TotalJustice

TotalJustice

Well-Known Member
OP
Member
Joined
Jan 28, 2017
Messages
561
Trophies
2
XP
3,368
Country
United Kingdom
0.6.1 is out

This is a bug fix release, so no new features.

The main change is that audio is now disabled in applet mode. The reason for this if a game is currently launched and it uses multiple audren services, then launching sphaira would result in a fatal (crash). You can read more info about it here. I do plan to do a proper fix by writing a new audio driver for libpulsar, however this is non-trivial and pretty low on my to-do list.
Post automatically merged:

0.6.2 is out

Slight change with how audio is disabled. Audio is now only disabled if launched in applet mode with a suspended (background) game running. Meaning, if you launch sphaira from the home menu with no games currently running, audio will still function.
 
Last edited by TotalJustice,

Site & Scene News

Popular threads in this forum

General chit-chat
Help Users
  • No one is chatting at the moment.
  • _Ruri_ @ _Ruri_:
    G'night
  • _Ruri_ @ _Ruri_:
    @Faust03, Sad ☹️ they're delicious
  • Faust03 @ Faust03:
    they have mexican street corn ones over here that I thought were alright
  • _Ruri_ @ _Ruri_:
    Haven't tried them, maybe we don't have them here 🤔
  • Faust03 @ Faust03:
    maybe not
  • Faust03 @ Faust03:
    where do you live?
  • _Ruri_ @ _Ruri_:
    Italy
  • Faust03 @ Faust03:
    Oh, cool!
  • Faust03 @ Faust03:
    Always wanted to go there
  • _Ruri_ @ _Ruri_:
    Nice! Food's pretty good here, that's the thing I like most lol. You can make delicious pasta dishes with good ingredients without spending too much money. Art and history are also pretty interesting, there are a lot of stuff to see
    +2
  • K3Nv3 @ K3Nv3:
    Gays
  • _Ruri_ @ _Ruri_:
    They're turning the frogs gay
  • Faust03 @ Faust03:
    probably
  • Marusu @ Marusu:
    more spambots! yaaay...
  • K3Nv3 @ K3Nv3:
    More complaining yay
  • Scarlet @ Scarlet:
    As soon as you see them just stick them on your ignore list. That way you'll at least
    not see anything in your recent content page or get notifications for them
  • _Ruri_ @ _Ruri_:
    How do I tell if someone's a spambot?
  • Scarlet @ Scarlet:
    They make a thread titled "¿Cómo comunicarme por telefono Lufthansa España? #LUFTHANSA"
    +1
  • Scarlet @ Scarlet:
    A good indicator is a thread in a non-English language. If it also has something that looks like a phone number, it's pretty much guaranteed to be spam.
    +2
  • lwiz @ lwiz:
    Had to switch registration to manual on couple of small forums I administer after AI got through our registration questions (single language area and forums concerning wooden boats and handicrafts)... Bit of bother, but not too bad yet - just too cumbersome method for big forum like this
  • zanytofu @ zanytofu:
    Hey. Does anyone know how to change date of birth in profile? I've tried sending a message to admin but I didn't get a reply
  • zanytofu @ zanytofu:
    I tried here https://gbatemp.net/misc/contact, maybe I'm wrong
  • SylverReZ @ SylverReZ:
    @zanytofu, Ask a supervisor. Admins don't really assist with those requests.
  • zanytofu @ zanytofu:
    Thanks, will try
    zanytofu @ zanytofu: Thanks, will try