Building for 3DS - TheXTech/TheXTech GitHub Wiki

In December 2022, experimental support for Nintendo 3DS was added to TheXTech.

Dependencies

Building the Nintendo 3DS version of the game requires the homebrew devkitPro. devkitPro is supported on Linux, macOS and Windows. 3DS builds have primarily been tested on Linux-based operating systems. Please follow your platform's appropriate steps to install the devkitPro, and ensure that the environment variables DEVKITPRO and DEVKITARM is set as per the official instructions.

Once devkitPro is installed, you'll be using the CMake parameter -DCMAKE_TOOLCHAIN_FILE to tell CMake what parameters, compilers, and arguments it should use to cross-compile for Nintendo 3DS.

For example:

# Simplest Nintendo 3DS cross-compilation example
cmake -DCMAKE_TOOLCHAIN_FILE=$DEVKITPRO/cmake/3DS.cmake

A patched version of the SDL2 is built as a part of the build process for TheXTech.

Preparing to build

Before to start the build, you should obtain the source code for TheXTech. You can use the stable version as well as the latest in-development to test out any new experimental features and receive any further bugfixes earlier.

Stable version

If you want to build the stable version, you can simply download the source code archive from the official site or from GitHub releases:

And then, unpack the archive and open the terminal at the just-now unpacked directory that contains the source code for TheXTech.

Important note: Please never use the "Source code" links at Github releases: they are broken. Instead, download the thextech-full-src-v*.*.*.tar.gz or thextech-full-src-v*.*.*.tar.bz2 or thextech-full-src-v*.*.*.zip archive.

This project uses submodules and GitHub is unable to create source code packages that includes submodules too.

Development version

If you want to build the latest in-development version, then, instead of downloading the archive, you can clone the repository itself by running this in a terminal (please open the terminal at the directory where you want to put the clonned repository, so, you will know where it is):

git clone https://github.com/TheXTech/TheXTech.git

Then, Make sure all submodules have been pulled, otherwise, it won't build:

cd TheXTech
git submodule init
git submodule update

Building

At the TheXTech's source code directory, run next commands in the terminal:

  1. Make the building directory:

    mkdir build-3ds
cd build-3ds

  2. Run CMake configuration:

    For the optimized, fast build

    # when you want to use the regular GNU Make
cmake -DCMAKE_BUILD_TYPE=MinSizeRel \
      -DCMAKE_TOOLCHAIN_FILE=$DEVKITPRO/cmake/3DS.cmake ..

    # OR when you want to use Ninja which does better parallel processes management
cmake -G Ninja -DCMAKE_BUILD_TYPE=MinSizeRel \
      -DCMAKE_TOOLCHAIN_FILE=$DEVKITPRO/cmake/3DS.cmake ..

    For a slower, debug build (useful for verbose logging and detailed crash reports)

    # when you want to use the regular GNU Make
cmake -DCMAKE_BUILD_TYPE=Debug \
      -DCMAKE_TOOLCHAIN_FILE=$DEVKITPRO/cmake/3DS.cmake ..

    # OR when you want to use Ninja which does better parallel processes management
cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug \
      -DCMAKE_TOOLCHAIN_FILE=$DEVKITPRO/cmake/3DS.cmake ..

  3. Run the build itself: If you generated regular GNU Makefiles in the last step:

    # Run regular GNU Make build with 4 parallel tasks
# (suggested on 4-core CPU, if you have more cores, use a different number than 4)
make -j 4

    If you generated build.ninja files (using cmake -G Ninja ..., such as in the release example) in the last step:

    # Or run a Ninja build
ninja

    Now, you should be able to find your binaries in the build directory (the file named thextech.3dsx). See the next section for how to run them!

Running and debugging a build

The built game will not work until you will prepare the game root. The game root by default for Nintendo 3DS is located at sdmc:/3DS/thextech/. Please create this directory and place your preferred game assets inside that directory before attempting to launch the Nintendo 3DS version of the game. For debugging purposes you may simply copy a standard TheXTech asset pack to this directory, but see below for advice to significantly speed up the game.

Asset conversion

The 3DS (especially the Old 3DS) has a slow CPU. This is generally not a problem for gameplay because TheXTech's internal engine is highly optimized, but can cause problems when decompressing PNG textures and playing SPC sound files during gameplay. A conversion script is provided at utils/convertkit/gfx-convert-3ds.py, which converts an asset pack archive or a folder containing episodes to 3DS-optimized formats. This conversion script is written in Python 3 and requires the ImageMagick convert and ffmpeg utilities to be present in your PATH.

romfs packaging

libctru has a very slow filesystem library because all filesystem requests to the SD card need to be routed through the original 3DS firmware. This can be avoided by packaging all read-only assets into romfs archives, using the mkromfs3ds command included with devkitARM. The game's base assets should be installed at sdmc:/3DS/thextech/assets.romfs, and up to 52 other romfs packages containing episodes may also be copied to sdmc:/3DS/thextech/.

Pre-converted asset packs

  1. Download one of two archives with compatible assets:
  2. Rename the romfs archive to sdmc:/3DS/thextech/assets.romfs
  3. Once your game root directory is ready, you can move the built thextech.3ds file to the sdmc:/3ds/ directory (or any path of your preference) and run it through the Homebrew Launcher. You also can use the Citra emulator to verify the work of the game.

Troubleshooting:

  • Please ensure you have the latest devkitPro installed
  • Please ensure that the DEVKITPRO and DEVKITARM environment variables are set OR exported in your .bashrc (or similar)
  • Please ensure that your assets are installed at sdmc:/3ds/thextech/assets.romfs