• Stars
    star
    704
  • Rank 64,316 (Top 2 %)
  • Language
    C
  • Created over 7 years ago
  • Updated 6 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

The 3DS Homebrew Menu (∩ ͡° ͜ʖ ͡°)⊃━☆゚

The Homebrew Launcher

Presentation

The Homebrew Launcher (hbmenu for short) is the main menu used to list and launch homebrew applications. It is essentially a graphical shell around an existing homebrew loading mechanism. The following entrypoints are supported:

  • Luma3DS Rosalina (recommended): Works on all system versions from 4.0 onwards; it provides unrestricted access to 3DS system resources as well as nice extra features such as remote debugging (GDB). For more information read the Rosalina documentation.
  • Legacy *hax 2.x: This is a now-obsolete homebrew loading system that only provides limited access to 3DS system resources, as it only attacks a low privilege level. Support for this entrypoint is deprecated and may be removed in a future release.

3DS homebrew is built and distributed as executables with the .3dsx extension. Note that you may encounter files with the .cia extension - these are not homebrew executables that can be loaded using hbmenu.

Usage

To install hbmenu, simply copy boot.3dsx to the root of your SD card. If you are using a recent version of Luma3DS you probably already have a copy of hbmenu installed, as it comes bundled with it.

Use the D-Pad, Circle Pad or the touchscreen to select an application, and press A or touch it again to start it. Use the C-Stick alternatively on New 3DS to scroll the list of applications.

hbmenu supports starring applications, so that they are shown at the beginning of the list. The SELECT button stars/unstars the currently selected homebrew application.

On *hax 2.x, it is not possible to go back to the 3DS HOME menu using the HOME button. As an alternative, you can press the START button where you can reboot your console or relaunch HOME menu.

hbmenu starts in the sdmc:/3ds/ directory for applications and it will look for 3dsx files inside it. You can navigate the directory tree and open/browse folders as you would expect. Additionally, folders containing a 3dsx file with the same name as the folder (or alternatively boot.3dsx) will be detected as an application bundle folder, and it will be presented as a single icon that can directly launch the application.

Here is an example directory structure that hbmenu will have no trouble recognizing:

  • sdmc:/
    • 3ds/
      • games/
        • Hermes.3dsx
        • cubemadness.3dsx
      • Checkpoint/ (this folder will be detected as an application bundle)
        • Checkpoint.3dsx
        • ...
      • ftpd.3dsx
      • mgba.3dsx
      • 3dscraft.3dsx
      • blargSNES.3dsx
      • gameyob.3dsx
      • 3dnes.3dsx

If hbmenu does not find an icon file (either embedded in the executable or provided separately) to associate with a given 3dsx, it will display a default icon and the path to the executable as a fallback.

hbmenu also allows you to create "shortcuts" which are xml files containing a path to a 3dsx file and optional arguments to pass to the .3dsx. This file can also include a path to icon data as well as name, description and author text using tags as follows:

<shortcut>
    <executable>The path to the 3dsx file goes here.</executable>
    <icon>path to smdh icon data</icon>
    <arg>Place arguments to be passed to 3dsx here.</arg>
    <name>Name to display</name>
    <description>Description of homebrew app</description>
    <author>Name of the author</author>
</shortcut>

Arguments are space or tab separated but can use single or double quotes to contain whitespace.

Name, description and author will be read from the .3dsx if it has embedded SMDH data or from the supplied icon path. The fields in the xml file will then override their respective entries.

You should not hotswap the SD card while hbmenu is running since it compromises the 3DS OS's stability amongst other things. It is recommended that you instead use a file transfer homebrew application such as ftpd to transfer files without rebooting.

Technical notes

hbmenu does all its rendering in hardware thanks to the citro3d library. The 3DS system font is also used to render all text.

hbmenu uses some funky mechanisms to launch 3dsx files. If you're interested in launching 3dsx files from your own application, you should look here; although these mechanisms may change in the future.

Netloader

hbmenu contains support for the 3dslink protocol, which allows you to remotely load applications. Press Y to activate as usual then run 3dslink <3dsxfile> if your network can cope with UDP broadcast messages. If 3dslink says 3DS not found then you can use -a <ip address> to tell it where to send the file.

All the other arguments you give 3dslink will be passed as arguments to the launched 3dsx file. You can also specify argv[0] with -0 <argument> which is useful for setting the current working directory if you already have data files in a particular place, i.e. 3dslink myfile.3dsx -0 sdmc:/3ds/mydata/

3dslink is provided with devkitARM or you can download binaries from WinterMute's website.

Building

hbmenu uses zlib for compression and tinyxml2 for XML parsing. These libraries are provided by devkitPro through the portlibs mechanism. In order to install them, use the following command:

    pacman -S 3ds-zlib 3ds-tinyxml2 3ds-libconfig

(Note that dkp-pacman is used instead on systems that do not distribute pacman, such as macOS or Debian-based Linux distros)

Binaries of hbmenu can be downloaded from the Releases page.

File Associations

This is a feature backported from nx-hbmenu. However, there is one notable difference: icons must be a 48x48 t3x-generated file with GPU_RGB565 as its color format.

Contributing

hbmenu is looking for contributors! We're making this repository public so that you, the community, can make hbmenu into the menu of your dreams. Or show you how to make your own, better menu! Of course we'd rather you improved hbmenu rather than went off and started fragmenting the userbase, but any contributions to the homebrew scene are welcome. Feel free to use code from hbmenu for your own projects, so long as you give credit to its original authors.

Credits

  • smea: code & original hbmenu version
  • fincs: code & rewrite
  • GEMISIS: code
  • mtheall: code
  • WinterMute: netloader code
  • Fluto: graphics
  • Arkhandar: graphics
  • dotjasp: graphics (regionfree icon)
  • gruetzkopf, TuxSH, AuroraWright, Soph1a7, SentientTurtle, Yami-chan, d3m3vilurr, daedreth, JixunMoe, yy-codes, MCPE-PC: translations

More Repositories

1

libctru

Homebrew development library for Nintendo 3DS/Horizon OS user mode (Arm11)
C
751
star
2

3ds-examples

Examples for 3DS using devkitARM, libctru, citro3d and citro2d
C
411
star
3

installer

NSIS
353
star
4

deko3d

Homebrew low level graphics API for Nintendo Switch (Nvidia Tegra X1)
C++
300
star
5

libnds

C library for Nintendo DS
C
296
star
6

libogc

C Library for Wii and Gamecube homebrew
C
280
star
7

citro3d

Homebrew PICA200 GPU wrapper library for Nintendo 3DS
C
243
star
8

wut

Let's try to make a Wii U Toolchain / SDK for creating rpx/rpl.
C
204
star
9

libgba

C Library for Nintendo GBA
C
184
star
10

pacman

C
157
star
11

citro2d

Library for drawing 2D graphics using the Nintendo 3DS's PICA200 GPU
C
150
star
12

buildscripts

Scripts for building devkitPro toolchains
Shell
147
star
13

pacman-packages

Shell
122
star
14

nds-hb-menu

C++
111
star
15

nds-examples

Assembly
93
star
16

gba-examples

Makefile
84
star
17

ndstool

C++
69
star
18

picasso

Homebrew PICA200 shader assembler
C++
63
star
19

docker

Dockerfiles for https://hub.docker.com/u/devkitpro/
Dockerfile
55
star
20

libfat

FAT library for GBA, DS, Gamecube & Wii
C
48
star
21

gba-tools

C
48
star
22

libtonc

C
45
star
23

grit

Game Raster Image Transmogrifier
C++
43
star
24

3dstools

C++
43
star
25

wii-examples

C
37
star
26

tex3ds

3DS Texture Conversion
C++
36
star
27

3ds_portlibs

Portlibs for 3DS
Makefile
34
star
28

gamecube-examples

C
33
star
29

dswifi

Wifi library for Nintendo DS
C
31
star
30

gamecube-tools

Tools for gamecube/wii projects
C++
30
star
31

dslink

Wifi code loader for Nintendo DS
C
28
star
32

maxmod

Assembly
23
star
33

dstools

C++
21
star
34

newlib

fork from sourceware git://sourceware.org / newlib-cygwin.git
C
17
star
35

wiiload

C
16
star
36

general-tools

C++
15
star
37

uam

Shader compiler for Nintendo Switch, targeting the deko3d API (based on mesa/nouveau sources)
C++
15
star
38

nds-bootloader

C
14
star
39

3dslink

C
12
star
40

mmutil

C
12
star
41

devkitarm-crtls

Assembly
11
star
42

dslink-host

C++
10
star
43

wut-tools

C++
10
star
44

install-dsilink

Assembly
9
star
45

wut-packages

packages for wiiu development
Shell
9
star
46

libnds-master

Makefile
8
star
47

libdrm_nouveau

C
8
star
48

switch-glad

Switch port of an autogenerated OpenGL 4.3 loader
C
7
star
49

libfilesystem

C
7
star
50

default-arm7

Makefile
7
star
51

gp32-tools

C++
7
star
52

gp32-examples

C
6
star
53

devkitarm-rules

Makefile
6
star
54

devkitppc-rules

Makefile
5
star
55

libmirko

C Library for Gamepark GP32
C
5
star
56

nds-exception-stub

C
5
star
57

orcus

Bare metal library for GP2X - no Linux here!
C
3
star
58

bzip2

a program and library for lossless, block-sorting data compression.
C
3
star
59

physfs

a library to provide abstract access to various archives. https://icculus.org/physfs/
C
3
star
60

gp2x-tools

C
2
star
61

devkitpro-keyring

Shell
2
star
62

.github

default devkitPro repo
1
star
63

devkita64-rules

Makefile
1
star
64

devkitpro.github.io

HTML
1
star
65

gp2x-examples

Makefile
1
star
66

gp2x-core

devkitarm core components for GP2X support
Assembly
1
star