Tutorial
Updated
Setting up Visual Studio 2017 environment for Nintendo Switch homebrew development
Hello everyone!
After a whole week fighting with SDL2 I decided to make a similar tutorial to my first one: https://gbatemp.net/threads/tutoria...for-nintendo-3ds-homebrew-development.461083/
so anyone can easily create stuff for Nintendo Switch.
This tutorial is mainly made for Windows, so there are maybe some things you cannot use on MAC/Linux. Just change those as needed.
There's a simple console tutorial made by @WerWolv, so be sure to check it out here.
Introduction:
This guide shows how to set up the initial Nintendo Switch homebrew development environment using Visual Studio 2017 Community Edition. This guide should also apply to Visual Studio 2017 Professional/Enterprise and up. The last version I tested is Visual Studio 2022 (16/02/2022 . This setup will allow you to use Visual Studio's IntelliSense when working with your code, while being able to compile your code into .NRO files for homebrew applications. We can create .NSP o our homebrews with NRO2NSPBuilder.
By following this guide, you will be creating your own project from scratch in C++. However, should you feel like using a pre-made Visual Studio project template, you may use devkitPro Examples or my own template. If you want a game as reference, check any of my games: Good examples are T-REKT NX or TIL NX which has drag functions.
We will call Visual Studio 2017 Community as "VS2017" from here on out. As I mentioned before, Enterprise and Professional editions can be used as well.
Microsoft Visual C/C++ is not bundled with VS2017 by default. You must choose to install this package, as it is required for Nintendo Switch homebrew development. If you cannot find it in the VS2017 Installer, you can follow the instructions to obtain this package below.
Minum Requirements:
- Latest version of Visual Studio 2017 Community: https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx
- Microsoft Visual C/C++ package for Visual Studio 2017 Community.
- Latest stable version of devkitPro: http://devkitpro.org/wiki/Getting_Started
- Switch packages obtained by pacman packages
- Knowledge in C or C++.
- Creativity and time to make good stuff.
Notes:
To explain the inconsistencies of slashes, "\" and "/", used in this guide:
In Windows, of any editions, it uses backslashes "\" as file separators, and not forward slashes "/". This also means in Visual Studio of any editions, it natively uses backslashes "\" as file separators. If you see forward slashes "/", this clearly means it is used in Makefiles.
The usage of backslashes "\" was due to the forward slashes "/" being used as indicators for "switches" or "flags" (cmd.exe /w, or /help) in IBM software, and is not compatible to parse as file separators. MS-DOS adopted this, and to this day, forward slash switches are still used in many places.
Setup:
Adding more packages for devkitPro:
Using SDL in your project:
We will use NX-Shell's my SDL Helper modification. Let's see how it works:
Testing the homebrew:
YuZu now supports SDL Rendering in latest Canary:
https://github.com/yuzu-emu/yuzu-canary/releases
For testing in Real-Hardware we have two options:
- Copy the generated .nro to the SD/switch folder and test it from the HBMenu.
- Use NX Link:
NXLink is already installed with devkitpro if Switch tools are installed. If you don't have it, install switch tools with pacman.
- Go to the HBMenu in your switch and press Y to start the netloader. A pop-up will appear with the IP of your switch (It must be connected to Internet).
(You can do the commands directly in Windows CMD, but this is more comfy)
- Go back to your computer and create a text file with this commands:
Where the numbers are the IP shown in your switch's screen
Save the text file with .bat extension.
Just double click on the bat and it will start sending the HB to your switch. After the copy, the homebrew will run automatically.
Template:
In the template you will find a good example of how to create a game easily with template classes: Splash Screen, Title Screen, Intro Screen (cinematic) and Game Screen.
It has some UI classes for creating sprites, buttons and toggles. Sprites can be animated by frames. Sprites can be draggable with the Switch touch screen.
It has game data and multilanguage support with JSON.
Take a look to it, and if you need help, just ask.
Credits:
If this tutorial has been useful to you, credits are appreaciated.
For anything, just leave a comment below.
After a whole week fighting with SDL2 I decided to make a similar tutorial to my first one: https://gbatemp.net/threads/tutoria...for-nintendo-3ds-homebrew-development.461083/
so anyone can easily create stuff for Nintendo Switch.
This tutorial is mainly made for Windows, so there are maybe some things you cannot use on MAC/Linux. Just change those as needed.
There's a simple console tutorial made by @WerWolv, so be sure to check it out here.
Introduction:
This guide shows how to set up the initial Nintendo Switch homebrew development environment using Visual Studio 2017 Community Edition. This guide should also apply to Visual Studio 2017 Professional/Enterprise and up. The last version I tested is Visual Studio 2022 (16/02/2022 . This setup will allow you to use Visual Studio's IntelliSense when working with your code, while being able to compile your code into .NRO files for homebrew applications. We can create .NSP o our homebrews with NRO2NSPBuilder.
By following this guide, you will be creating your own project from scratch in C++. However, should you feel like using a pre-made Visual Studio project template, you may use devkitPro Examples or my own template. If you want a game as reference, check any of my games: Good examples are T-REKT NX or TIL NX which has drag functions.
We will call Visual Studio 2017 Community as "VS2017" from here on out. As I mentioned before, Enterprise and Professional editions can be used as well.
Microsoft Visual C/C++ is not bundled with VS2017 by default. You must choose to install this package, as it is required for Nintendo Switch homebrew development. If you cannot find it in the VS2017 Installer, you can follow the instructions to obtain this package below.
Minum Requirements:
- Latest version of Visual Studio 2017 Community: https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx
- Microsoft Visual C/C++ package for Visual Studio 2017 Community.
- Latest stable version of devkitPro: http://devkitpro.org/wiki/Getting_Started
- Switch packages obtained by pacman packages
- Knowledge in C or C++.
- Creativity and time to make good stuff.
Notes:
To explain the inconsistencies of slashes, "\" and "/", used in this guide:
In Windows, of any editions, it uses backslashes "\" as file separators, and not forward slashes "/". This also means in Visual Studio of any editions, it natively uses backslashes "\" as file separators. If you see forward slashes "/", this clearly means it is used in Makefiles.
The usage of backslashes "\" was due to the forward slashes "/" being used as indicators for "switches" or "flags" (cmd.exe /w, or /help) in IBM software, and is not compatible to parse as file separators. MS-DOS adopted this, and to this day, forward slash switches are still used in many places.
Setup:
1) Acquiring Microsoft Visual C/C++ for VS2017:
- Install VS2017. It will install Visual Studio Installer too.
- Run Visual Studio Installer.
- Click on Modify below VS2017.
- Click on Components > Select C++ components > Install.
VS2017 will then install Visual C/C++ packages. Follow the instructions, then continue to the next section.
2) Nintendo Switch Homebrew Development Setup:
- Install devkitPro, by following the instructions given in the Getting Started article.
- Run Visual Studio 2017 Community.
- On the Start page in VS2017, under the Start section, click "New Project...".
- When in the New Project wizard, click on Installed > Templates > Visual C++ > Makefile Project. It can be in Installed > C++ > MAKE.
- Down at the bottom, choose your project name, your solution location, and the solution action.
NOTE: MAKE SURE your solution location is located in a directory where the file path does NOT contain any WHITESPACES!
- Click OK.
- A new panel will show. Add the commands for Build, Rebuild, and Clean, as follows:
Build-> make
Rebuild-> make clean all
Clean-> make clean
- On the right pane, add the following path to the "Include Search Path":
\path\to\devkitPro\devkitA64\include
\path\to\devkitPro\libnx\include
$(ProjectDir)\include
- Click OK and the project will be setup.
If you want to add more folders to include:
- In the Solution Explorer, right click on your project, and choose Properties.
- On the left pane, click on General.
- Make sure under General, Configuration Type is set to Makefile.
- On the left pane, click on VC++ Directories.
- Under General, click on Include Directories, click on the arrow dropdown button on the right, and select <Edit>.
- Add the desired filepaths.
- Click OK to go back to the VS2017 editor.
- In the Solution Explorer, add a new item under the filter, "Source Files", by right clicking the filter, Add > "New Item...".
- In the Add New Item wizard, click on C++ File.
- Down at the bottom of the wizard, make sure the Location is the following, with the folder, "source" added at the end (And yes, it is all lowercase "source"):
\path\without\whitespace\to\project\source\
- Type your C++ file name (lets call it main.cpp), and click on "Add".
Add the following #if and #defines macros at the top of your CPP file:
Then add the following code to your C++ file after it:
This is the part where it gets tricky.
Ignore the errors in the Error List by turning it off or clicking "X of X Errors" once, where X is any given number.
If you see any squiggly lines underneath ANY letter or character in the code provide above, it means you have set your IntelliSense incorrectly. Make sure to double check all of the steps above, to see if you have missed any.
Tricky part is finished. Congratulations!
- In File Explorer, navigate to the following directory:
\path\to\devkitPro\examples\switch\templates\application
- Copy the Makefile file.
- In File Explorer, navigate back to your project root directory.
- Paste the Makefile file to the project root directory.
- In VS2017, in the Solution Explorer, right click on your project, Add > "Existing Item...".
- Select Makefile.
- Click on "Add".
- In the Solution Explorer, open the Makefile, so the file is opened in VS2017.
- Edit the name of the homebrew, the creator to fit your project.
- Save Makefile.
- In the Solution Explorer, right click on the Makefile, and select "Properties".
- In the Makefile Property Pages, make sure on the right pane, under General, the Item Type is Text, and the rest of the entries are empty.
- Click OK to exit back to VS2017 editor.
- Hit CTRL+SHIFT+B or in the taskbar, "Build > Build Solution" or "Build > Build [project name]", where [project name] is your project name. You can also click on the green button: Windows Debugger and it will compile too.
- In VS2017, in the Output tab, you should see your code being built via Makefile.
And that's it! From this point on, you are free to add anything you want.
- Install VS2017. It will install Visual Studio Installer too.
- Run Visual Studio Installer.
- Click on Modify below VS2017.
- Click on Components > Select C++ components > Install.
VS2017 will then install Visual C/C++ packages. Follow the instructions, then continue to the next section.
2) Nintendo Switch Homebrew Development Setup:
- Install devkitPro, by following the instructions given in the Getting Started article.
- Run Visual Studio 2017 Community.
- On the Start page in VS2017, under the Start section, click "New Project...".
- When in the New Project wizard, click on Installed > Templates > Visual C++ > Makefile Project. It can be in Installed > C++ > MAKE.
- Down at the bottom, choose your project name, your solution location, and the solution action.
NOTE: MAKE SURE your solution location is located in a directory where the file path does NOT contain any WHITESPACES!
- Click OK.
- A new panel will show. Add the commands for Build, Rebuild, and Clean, as follows:
Build-> make
Rebuild-> make clean all
Clean-> make clean
- On the right pane, add the following path to the "Include Search Path":
\path\to\devkitPro\devkitA64\include
\path\to\devkitPro\libnx\include
$(ProjectDir)\include
- Click OK and the project will be setup.
If you want to add more folders to include:
- In the Solution Explorer, right click on your project, and choose Properties.
- On the left pane, click on General.
- Make sure under General, Configuration Type is set to Makefile.
- On the left pane, click on VC++ Directories.
- Under General, click on Include Directories, click on the arrow dropdown button on the right, and select <Edit>.
- Add the desired filepaths.
- Click OK to go back to the VS2017 editor.
- In the Solution Explorer, add a new item under the filter, "Source Files", by right clicking the filter, Add > "New Item...".
- In the Add New Item wizard, click on C++ File.
- Down at the bottom of the wizard, make sure the Location is the following, with the folder, "source" added at the end (And yes, it is all lowercase "source"):
\path\without\whitespace\to\project\source\
- Type your C++ file name (lets call it main.cpp), and click on "Add".
Add the following #if and #defines macros at the top of your CPP file:
Code:
#if __INTELLISENSE__
typedef unsigned int __SIZE_TYPE__;
typedef unsigned long __PTRDIFF_TYPE__;
#define __attribute__(q)
#define __builtin_strcmp(a,b) 0
#define __builtin_strlen(a) 0
#define __builtin_memcpy(a,b) 0
#define __builtin_va_list void*
#define __builtin_va_start(a,b)
#define __extension__
#endif
#if defined(_MSC_VER)
#include <BaseTsd.h>
typedef SSIZE_T ssize_t;
#endifThen add the following code to your C++ file after it:
Code:
#include <switch.h>
#include <iostream>
int main(int argc, char* argv[])
{
consoleInit(NULL);
// Other initialization goes here. As a demonstration, we print hello world.
std::cout<<"Hello World!\n"<<std::endl;
// Configure our supported input layout: a single player with standard controller styles
padConfigureInput(1, HidNpadStyleSet_NpadStandard);
// Initialize the default gamepad (which reads handheld mode inputs as well as the first connected controller)
PadState pad;
padInitializeDefault(&pad);
// Main loop
while (appletMainLoop())
{
// Scan all the inputs. This should be done once for each frame
padUpdate(&pad);
// hidKeysDown returns information about which buttons have been
// just pressed in this frame compared to the previous one
u64 kDown = padGetButtonsDown(&pad);
if (kDown & HidNpadButton_A)
std::cout<<"Pressed A button!\n"<<std::endl;
if (kDown & HidNpadButton_Plus)
break; // break in order to return to hbmenu
// Your code goes here
// Update the console, sending a new frame to the display
consoleUpdate(NULL);
}
// Deinitialize and clean up resources used by the console (important!)
consoleExit(NULL);
return 0;
}This is the part where it gets tricky.
Ignore the errors in the Error List by turning it off or clicking "X of X Errors" once, where X is any given number.
If you see any squiggly lines underneath ANY letter or character in the code provide above, it means you have set your IntelliSense incorrectly. Make sure to double check all of the steps above, to see if you have missed any.
Tricky part is finished. Congratulations!
- In File Explorer, navigate to the following directory:
\path\to\devkitPro\examples\switch\templates\application
- Copy the Makefile file.
- In File Explorer, navigate back to your project root directory.
- Paste the Makefile file to the project root directory.
- In VS2017, in the Solution Explorer, right click on your project, Add > "Existing Item...".
- Select Makefile.
- Click on "Add".
- In the Solution Explorer, open the Makefile, so the file is opened in VS2017.
- Edit the name of the homebrew, the creator to fit your project.
- Save Makefile.
- In the Solution Explorer, right click on the Makefile, and select "Properties".
- In the Makefile Property Pages, make sure on the right pane, under General, the Item Type is Text, and the rest of the entries are empty.
- Click OK to exit back to VS2017 editor.
- Hit CTRL+SHIFT+B or in the taskbar, "Build > Build Solution" or "Build > Build [project name]", where [project name] is your project name. You can also click on the green button: Windows Debugger and it will compile too.
- In VS2017, in the Output tab, you should see your code being built via Makefile.
And that's it! From this point on, you are free to add anything you want.
Adding more packages for devkitPro:
We will use some libraries in our homebrews but for sure, we need SDL2. Let's install it!
- First we need to open the command window: Windows + R > cmd or Shift + Right Click > Open CMD Prompt Here
- For displaying the package list (to know package names), just type: pacman -Sl
- Install the packages with: pacman -Syuu [package1] [package2] [every package you want to install...]
Example: pacman -Syuu switch-sdl switch-sdl2_gfx switch-sdl2_image switch-sdl2_ttf switch-sdl2_net switch-sdl2_mixer
You may need to update portlibs by:
pacman -S switch-portlibs
NOTE: You can install as many packages as you need in your homebrew
- Once the packages are installed, to use SDL we need to add to the makefile this line:
and if you want to use every library as the template (you need every package installed):
- First we need to open the command window: Windows + R > cmd or Shift + Right Click > Open CMD Prompt Here
- For displaying the package list (to know package names), just type: pacman -Sl
- Install the packages with: pacman -Syuu [package1] [package2] [every package you want to install...]
Example: pacman -Syuu switch-sdl switch-sdl2_gfx switch-sdl2_image switch-sdl2_ttf switch-sdl2_net switch-sdl2_mixer
You may need to update portlibs by:
pacman -S switch-portlibs
NOTE: You can install as many packages as you need in your homebrew
- Once the packages are installed, to use SDL we need to add to the makefile this line:
Code:
LIBS := -lSDL2_ttf -lSDL2_gfx -lSDL2_image -lnxand if you want to use every library as the template (you need every package installed):
Code:
LIBS := -lSDL2_ttf -lSDL2_gfx -lSDL2_image -lSDL2_mixer -lpng -ljpeg -lglad -lEGL -lglapi -ldrm_nouveau -lvorbisidec -logg -lmpg123 -lmodplug -lstdc++ -lavformat -lavcodec -lswresample -lswscale -lavutil -lbz2 -lass -ltheora -lvorbis -lopus `sdl2-config --libs` `freetype-config --libs` -lnxUsing SDL in your project:
We will use NX-Shell's my SDL Helper modification. Let's see how it works:
First, we will download SDL_Helper.hpp, SDL_Helper.cpp, FontCache.c and FontCache.h from my template and place it in our source folder.
Now you can use SDL2. Congrats!
I recommend you to create an SDL_Helper object and send it's pointers.
For that, in the main.cpp copy this at the beggining of the method:
For loading an image we will use:
in the main loop, when you need to paint your texture just use:
I added rect method for multiple frames:
And opacity methods:
Once we exit the program, we need to delete everything:
Now you can use SDL2. Congrats!
I recommend you to create an SDL_Helper object and send it's pointers.
For that, in the main.cpp copy this at the beggining of the method:
Code:
plInitialize();
romfsInit();
SDL_Helper * helper = new SDL_Helper();
helper->SDL_HelperInit();For loading an image we will use:
Code:
SDL_Texture * myTexture;
helper->SDL_LoadImage(&myTexture, "romfs:/textureSprite.png");in the main loop, when you need to paint your texture just use:
Code:
helper->SDL_DrawImage(myTexture, x, y);
helper->SDL_Renderdisplay();I added rect method for multiple frames:
Code:
helper->SDL_DrawImageRect(myTexture, x, y, xOffset, yOffset, frameWidth, frameHeight);
helper->SDL_Renderdisplay();And opacity methods:
Code:
helper->SDL_DrawImageOpacity(myTexture, x, y, opacity);
helper->SDL_Renderdisplay();Once we exit the program, we need to delete everything:
Code:
plExit();
romfsExit();
helper->SDL_Exit();
delete(helper);Testing the homebrew:
YuZu now supports SDL Rendering in latest Canary:
https://github.com/yuzu-emu/yuzu-canary/releases
For testing in Real-Hardware we have two options:
- Copy the generated .nro to the SD/switch folder and test it from the HBMenu.
- Use NX Link:
NXLink is already installed with devkitpro if Switch tools are installed. If you don't have it, install switch tools with pacman.
- Go to the HBMenu in your switch and press Y to start the netloader. A pop-up will appear with the IP of your switch (It must be connected to Internet).
(You can do the commands directly in Windows CMD, but this is more comfy)
- Go back to your computer and create a text file with this commands:
Code:
cd path\to\devkitPro\tools\bin
nxlink -s -a 192.xxx.xxx.xxx path\to\homebrew.nroWhere the numbers are the IP shown in your switch's screen
Save the text file with .bat extension.
Just double click on the bat and it will start sending the HB to your switch. After the copy, the homebrew will run automatically.
Template:
In the template you will find a good example of how to create a game easily with template classes: Splash Screen, Title Screen, Intro Screen (cinematic) and Game Screen.
It has some UI classes for creating sprites, buttons and toggles. Sprites can be animated by frames. Sprites can be draggable with the Switch touch screen.
It has game data and multilanguage support with JSON.
Take a look to it, and if you need help, just ask.
Credits:
SDL2 references:
- joel16
- bernardo giordano
- Cheeze
- Cid2mizard
- WerWolv
- Credits for everyone involved in LibNX and Homebrew Development
- Thanks, SciresM for your awesome work in Atmosphere CFW.
- Smealum, because you deserve it, dude.
If this tutorial has been useful to you, credits are appreaciated.
For anything, just leave a comment below.
Last edited by Manurocker95,
