{"id":25348355,"url":"https://github.com/switchgdx/switch-gdx","last_synced_at":"2025-04-07T10:25:44.130Z","repository":{"id":45462673,"uuid":"481481710","full_name":"SwitchGDX/switch-gdx","owner":"SwitchGDX","description":"A LibGDX Nintendo Switch Homebrew and Xbox/UWP backend","archived":false,"fork":false,"pushed_at":"2025-01-13T03:01:03.000Z","size":8560,"stargazers_count":87,"open_issues_count":3,"forks_count":9,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-31T09:08:10.963Z","etag":null,"topics":["cplusplus","game-development","homebrew","java","libgdx","nintendo-switch","uwp","xbox"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SwitchGDX.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-14T05:47:56.000Z","updated_at":"2025-03-21T04:04:15.000Z","dependencies_parsed_at":"2025-02-28T17:13:26.636Z","dependency_job_id":"ab37f1dc-d7cd-4ec9-9e07-bf1566a466b1","html_url":"https://github.com/SwitchGDX/switch-gdx","commit_stats":null,"previous_names":["switchgdx/switch-gdx"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SwitchGDX%2Fswitch-gdx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SwitchGDX%2Fswitch-gdx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SwitchGDX%2Fswitch-gdx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SwitchGDX%2Fswitch-gdx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SwitchGDX","download_url":"https://codeload.github.com/SwitchGDX/switch-gdx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247633969,"owners_count":20970429,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cplusplus","game-development","homebrew","java","libgdx","nintendo-switch","uwp","xbox"],"created_at":"2025-02-14T15:14:14.831Z","updated_at":"2025-04-07T10:25:44.110Z","avatar_url":"https://github.com/SwitchGDX.png","language":"C++","readme":"# SwitchGDX\n[![Release](https://jitpack.io/v/com.thelogicmaster/switch-gdx.svg)](https://jitpack.io/#com.thelogicmaster/switch-gdx)\n\n## About\nThis is a Nintendo Switch Homebrew and Xbox UWP backend for the [LibGDX](https://libgdx.com) game framework. It uses\nthe [Clearwing VM](https://github.com/TheLogicMaster/clearwing-vm) project to transpile Java to C++ along with custom\nnative bindings for LibGDX. It supports Nintendo Switch Homebrew builds using LibNX, and Xbox/Windows Store with UWP.\nSee the SwitchGDX [thread](https://discord.com/channels/348229412858101762/965372515285352468) on the LibGDX Discord \nserver for support.\n\n## Ports\nSee [Ports](PORTS.md) for a list of current ports.\n\n**Mindustry, Pixel Wheels, and Shattered Pixel Dungeon Ports**\n![Mindustry](media/Mindustry.png)\n![Pixel Wheels](media/PixelWheels.png)\n![Shattered Pixel Dungeon](media/ShatteredPixel.png)\n\n## Features\n- Full GDX Reflection support\n- GDX Controllers support for all Switch controller layouts\n- GDX Preferences for persistent data\n- Desktop builds for debugging with emulated controller inputs\n- Xbox UWP builds\n\n## Compatibility\nThe majority of LibGDX is fully supported. A few features such as GL30 and audio recording are currently unsupported.\n\n## Extensions\nFreeType, Controllers, and Box2D are supported. Bullet may be supported in the future.\n\n## JVM Languages\nSince Clearwing takes Bytecode as an input, it can support any JVM language. The main limitation would be the Clearwing\nruntime library, which is limited and may not support all required functionality, though this can typically be easily\nadded as needed. Java and Kotlin have been tested and work.\n\n## Libraries\nPure Java libraries should work without any extra work, assuming they don't use unsupported runtime library features or\nJNI. Libraries compiled with newer Java versions could also pose an issue. If a library uses JNI, custom native\nbindings could be provided and things should just work, the shared library loading API has no effect. See\n[Libraries](LIBRARIES.md) for a list of tested libraries.\n\n## Todo\n- Bullet bindings\n- Multithreaded AssetManager support\n- Switch-specific API (Controller remapping)\n- Controller analog trigger support, remapping API, rumble\n- I18N non-simple\n- Sound effect pitch control\n- GL30\n- Set main thread exception handler to show error dialog\n- Fix sockets\n- VSCode project support\n- Keyboard input support\n- Mac OS support\n- Fix second launch crash on Switch (Probably cleanup issue)\n\n## Limitations\nSee the [Clearwing](https://github.com/TheLogicMaster/clearwing-vm) documentation for the limitations inherent to the \"VM\"\n- Only one Music instance can play at a time\n- Sound effects are limited to OGG and WAV, Music supports MP3, OGG, and WAV\n- Unused classes are optimized out, use the `reflective` `switch.json` config option to prevent it for specific classes for reflection\n- Socket server only supports IPv4 (Not supported at all at present)\n\n## Installation\nIn addition to the C++ dependencies, JDK 17 is required. Rsync is used for incremental compilation, and CMake is used\nfor building the generated C++ project.\n\n### Linux\n- Install CMake, Ninja, Rsync, Texinfo, SDL2, SDL2_Mixer, GLEW, zlib, Freetype, curl, Bullet\n- With APT: `sudo apt install build-essential texinfo rsync cmake ninja-build libsdl2-mixer-dev zlib1g-dev libglew-dev libfreetype-dev libcurl4-gnutls-dev libzzip-dev`\n- Install [devkitPro pacman](https://github.com/devkitPro/pacman/releases/tag/v1.0.2)\n- `dkp-pacman -S switch-zlib switch-libvorbis switch-zziplib switch-sdl2 switch-sdl2_mixer switch-freetype switch-glad switch-curl switch-bulletphysics dkp-toolchain-vars`\n\n### Windows\n- Ensure the project directory is as close to the filesystem root as possible to avoid Windows path limits (In 2025...)\n- Install MSYS2\n- Open a mingw64 shell: `C:\\msys64\\msys2_shell.cmd -mingw64`\n- Install dependencies: `pacman -S gcc git rsync texinfo mingw-w64-x86_64-cmake mingw-w64-x86_64-zziplib mingw-w64-x86_64-glew mingw-w64-x86_64-SDL2_mixer mingw-w64-x86_64-freetype mingw-w64-x86_64-bullet`\n- Install [devkitPro Updater](https://github.com/devkitPro/installer/releases/latest) with Switch packages selected (Leave downloaded files)\n- Open DevKitPro's MSYS2: `C:\\devkitPro\\msys2\\msys2_shell.cmd -mingw64`\n- Install dependencies: `pacman -S switch-zlib switch-zziplib switch-sdl2_mixer switch-libvorbis switch-freetype switch-glad switch-curl dkp-toolchain-vars texinfo`\n- Build LibFFI for Switch\n\n### UWP\n- Follow `Windows` steps above\n- Install CMake for Windows\n- Install Visual Studio 2022 and C++/UWP support (`Desktop development with C++`, `Windows application development`)\n- Run twice (Rebuild) for DLLs and assets to properly be copied for some reason\n\n## Project Setup\nFor reference, there's an `example` project provided with the needed Gradle config to build a SwitchGDX project. If you\nare creating a new LibGDX project, there's a fork of the project builder, [gdx-liftoff](https://github.com/tommyettinger/gdx-liftoff), \nwith the SwitchGDX backend [here](https://github.com/TheLogicMaster/gdx-liftoff). Just enable the Switch backend, and it\nwill take care of the rest. To add SwitchGDX to an existing project, a new Gradle subproject needs to be created, \nadding the `switch` directory with the icon, `switch.json` config file, `build.gradle` file, and the actual `src`\ndirectory with the `SwitchLauncher` source class. The module needs to be added to `settings.gradle`, and the \n`clearwingVersion` and `switchGdxVersion` properties need to be set in either `gradle.properties` or the top level \n`build.gradle`, depending on the project layout. The switch `build.gradle` can be mostly copy-pasted, changing only\nthe title and author variables and the asset copy paths, if not in `core/assets`. Any source paths to be used with the\njnigen style native code inlining also needs to be added to the transpiler arguments in `switch/build.gradle`. As far\nas [libraries](LIBRARIES.md) are concerned, if they require using GDX reflection, then those classes need to be added\nto the `switch.json` `reflective` class pattern list. The list of verified libraries details the needed config \nentries. To enable the Ryujinx emulator, download/install it then set `ryujinxPath` in the `local.properties` file \n(Create if needed). Make sure Java Home points to Java 17 or select a Java 17 JDK as the Gradle JDK in Intellij build \nsettings. Ensure that the project itself compiles with the Java 8 language level. \n\n## Usage\nAll the main tasks are present in the `switchgdx` Gradle group in the `switch` submodule. The first time transpiling\nwill be quite long, but subsequent runs will be comparatively snappy. Incremental compilation is achieved here by\ntranspiling into one directory then using rsync to only copy the changed files into the final C++ project directory.\n- __transpile__: Run the transpiler and generate the C++ project\n- __run__: Transpile, then run the C++ project in desktop-mode with emulated controller inputs (Yuzu layout)\n- __nro__: Transpile, then build a Nintendo Switch Homebrew NRO executable\n- __deploy__: Build NRO, then deploy to a Switch over LAN using NxLink\n- __ryujinx__: Build NRO, then run in Ryujinx emulator\n- __uwp__: Transpile, then open UWP project in Visual Studio\n\n### Deploying to Switch\nEnsure that the Homebrew Launcher is opened to the NetLoader before running the deploy task. By default, it tries\npinging the Switch to find it, but manually specifying the IP in the nxlink command may be necessary depending on the \nnetwork.\n\n### UWP\nThe UWP task opens Visual Studio, where the project settings need to be adjusted for the signing certificate and remote \ndeployment options for running on an Xbox console in devkit mode. Running a debug build should be as simple as building\nthe project and running it. There's a bug where the UWP project needs to be manually rebuilt to for the assets to be \ncopied over into the UWP build directory. The first time \nthe task is run will be quite slow, as it needs to install the VCPKG dependencies. Currently,\nfor Release builds to link successfully, the debug runtime library (/MDd) needs to be used. \n\n## Debugging\nThe project can be debugged as a normal C++ project with your IDE of choice. CLion works out of the box with\nthe CMake project. Simply run one of the Gradle tasks to transpile the project, then\nopen the `\u003cproject\u003e/switch/build/\u003cproject\u003e` directory with CLion as a CMake project. A Run configuration should be automatically created. \nSet the working directory in the run config to the `switch/build/\u003cproject\u003e` project directory so that assets\ncan be properly loaded at runtime. To trace back a native crash, simply press the debug icon next to the run\nconfiguration, and it should jump right to the exception and show the native stack trace. By inspecting the\ngenerated code and call stack, null fields can be found and traced back to Java source code by looking at the\n`LINE_NUMBER` line numbers. Code changes may lead to additional classes being included by the transpiler, in which case\nthe CLion CMake project needs to be reloaded using `Tools/Cmake/Reload CMake Project` or it won't compile.\nIf using Windows, the MinGW toolchain has to be selected under the project build settings. To debug a Java\nException being thrown, setting a breakpoint at the throw statement can be quite useful. If it's a place you can't\neasily add print-lines like a library, `printf` combined with `stringToNative` can also be helpful to print out a\nJava string, potentially obtained from `Object#toString`. In CLion, `stringToNative` can also be evaluated while\ndebugging, which is often extremely useful for dynamically inspecting values without recompiling.\n### Windows\nOn Windows, if you change the working directory in CLion, it doesn't seem to find the required shared libraries, so\nmanually copying the DLLs from `C:\\msys64\\mingw64\\bin` into the executable directory may be necessary. Adding\nthe directory to the `Path` doesn't seem to be sufficient.\n\n## Test Suite\nThe `tests` module is for running the GDX test suite and verifying GDX functionality. See [Tests](TESTS.md) for working\nfeatures. Building the test module requires building the tests module JAR in the libgdx repo and putting it in \n`tests/libs`, in addition to the lwjgl3 test module JAR for the required assets. The `tests` module is disabled if the \n`tests/libs` directory doesn't exist to not break JitPack builds and such.\n\n## Notes\n- Concurrent access to files is more limited on Switch where it might normally work on PC, so ensure files are closed properly\n- For Switch, all threads need to be joined manually, or it will crash on exit or when ran a second time. Any program \nthreads must be manually stopped/joined on dispose.\n- If using SNAPSHOT Gradle dependency (Not recommended), refresh Gradle dependencies using the Intellij Gradle menu to not use cached versions and update to the latest.\n- The UWP project generation has a bug where the project has to be manually rebuilt in Visual Studio for the assets to be properly copied\n- When using Joycons individually, the inputs will be rotated horizontally. Controllers must be remapped from the home menu for now. \n- `Controllers#getCurrentController` returns a controller representing all controller input, rather than the last controller.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswitchgdx%2Fswitch-gdx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswitchgdx%2Fswitch-gdx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswitchgdx%2Fswitch-gdx/lists"}