Skip to main content

Building Super Mario 64 on Retroid Pocket 3

This guide expands on chronoreverse's guide with my own discoveries and additional information. Updated for OTA update 1.0.0.50.

Requirements

  • An Android device, such as the RP3, with internet access
  • Termux from F-Droid on that device
  • A clean SM64 rom in .z64 format for either the US, JP, or EU region.
    I can not provide a link to this rom for legal reasons.
    Tool64 can be used to convert the rom from other formats.

Preparing Termux

Fix repo and mirror issues

Termux often selects the Bintray mirror by default, despite that this mirror is no longer available. This causes errors when trying to install packages via pkg. So it is recommended that you change the mirror to another. I recommend the Grimler mirror.

  1. Open Termux and run termux-change-repo and use the arrow keys provided by Termux to navigate the menu
  2. Press space bar on each repo to make sure they are selected with an asterisk (*)
  3. Select Ok and press enter
  4. Select the Grimler mirror with space bar
  5. Select Ok and press enter
  6. Back at the command prompt, run pkg update and pkg upgrade

Setup SSH (Optional)

Entering commands with the Android touch screen can be a pain. You can either connect a keyboard or setup SSH to remotely connect from a computer instead.

To enabled SSH on your Android device:

  1. Open Termux and install SSHD: pkg install openssh
  2. Set a password: passwd
  3. Get your username: whoami
  4. Get your ip address: ifconfig
    On an RP3, it should be the inet value under wlan0
  5. Start sshd: sshd

On your computer use a ssh client to connect. Windows 11, Linux, and Mac computers should be able to use the ssh command in commandline: ssh username@ipaddress -p 8022. Windows 10 and below maybe need to install an SSH client such as PuTTY.

SSHD will remain running in Termux so long as the app remains running, even in the background. You'll see it in the Android notification area if it's running (with the >_ icon). If the app closes completely, you will need to re-run sshd to start it again.

Installing build requirements

  1. In Termux or SSH, run pkg update and pkg upgrade if you haven't already.
  2. Install the X11 repo (required to get mesa package): pkg install x11-repo
  3. Install the rest: pkg install mesa binutils git wget make python getconf zip apksigner clang
  4. Place your SM64 rom in a folder in either your Internal device storage or SD card, such as Download.
    • Termux will mount your Internal storage to /sdcard/ and your SD card to a folder /storage/ with an ID that's different for different cards. You can check the ID using ls /storage/. It will be in a format such as 0123-4567. So if you place your rom in your Internal storage's Download folder, it will be in /sdcard/Download/ according to Termux. You will need to remember this location when it's time to build the game. In the below examples I use /sdcard/Download/.
  5. Give Termux access to your Internal storage and SD card: termux-setup-storage

Building the game

At the time of writing this, the latest version of the RP3's OTA updates is 1.0.0.50.

To check your version:

  1. Open Android system settings
  2. Go to System > Advanced > Updater
  3. Find your version number on the OTA screen.

1.0.0.37 and up users can run the ex/nightly build of the game. This version comes with an optional 60 FPS patch.
1.0.0.8 and below users cannot run the ex/nightly build, but can run the ex/master build to get the rest of the features.

  1. Clone the branch to build:
    • 1.0.0.37 an up users: git clone https://github.com/VDavid003/sm64-port-android --branch ex/nightly
    • 1.0.0.8 and below users: git clone https://github.com/VDavid003/sm64-port-android --branch ex/master
  2. Change to the new folder: cd sm64-port-android
  3. Copy your rom to the current folder. It must be named baserom.us.z64, baserom.eu.z64 or baserom.jp.z64: cp /sdcard/Download/sm64.z64 ./baserom.us.z64
  4. Download SDL requirements: ./getSDL.sh
  5. Build the Audio File Library:  make -j 4 -C tools/audiofile
  6. (Optional for 1.0.0.37 and up) If you want the 60 FPS patch: tools/apply_patch.sh enhancements/60fps_ex.patch

If you plan to use both the 60 FPS patch and a texture pack, please see the warning in the Adding custom assets section below.

Build options (features)

Almost time to build, but this is where we have some options we can pick from. These options are included in the build command in the format of NAME=VALUE, such as VERSION=us. There will be an example of this later.

  • VERSION (us, eu, jp)
    Rom region. If you're building from and EU or JP rom, you need to set this to eu or jp. It is already set to us by default.
  • DEBUG (0, 1)
    Enables the debug build. This is already disabled by default in the ex/nightly build, but not ex/master. So 1.0.0.8 users should set this to 0 to disable it.
  • TOUCH_CONTROLS (0, 1)
    These are on screen touch controls, meant for phones and tablets. This is enabled (1) by default. Set to 0 for devices that have hardware controls such as the RP3. When disabled, touching the screen acts as the B button for some reason.
  • EXT_OPTIONS_MENU (0, 1)
    An expanded options menu on the pause menu. This is enabled (1) by default in both branches. I recommend leaving it on as it gives you more game options such as camera, control, display, and sound options. Use 0 to disable it.
  • BETTERCAMERA (0, 1)
    Disabled by default (0), but I recommend enabling it (1). This implements PuppyCam in to the game to give you smoother camera control using the R analog stick, similar to modern 3rd person games. However, there are some quirks such as the camera often clipping through walls and turning unexpectedly after using doors. This is going to be entirely up to you if you want to use it or not.
  • TEXTURE_FIX (0, 1)
    Disabled (0) by default. Enabling it (1) fixes some known texture glitches in the game, such as the smoke texture.
  • NODRAWINGDISTANCE (0, 1)
    This is disabled (0) by default, and like the better camera option, it is up to you if you want to use it. With it enabled (1), all NPCs and objects on the current map are always loaded and active. For example in this screen shot you can see the chain chomp always lunging toward Mario even at long distance. This may have unintended side effects on the gameplay, but I haven't run in to any so far.
    Screenshot_20221029-123410.png
  • EXTERNAL_DATA (0, 1)
    Disabled (0) by default. Enable (1) if you want to load texture packs or other custom assets. See the custom assets section below for more information.

The build command

Use the make command to build with your preferred options. For example:
make -j 4 DEBUG=0 TOUCH_CONTROLS=0 BETTERCAMERA=1 NODRAWINGDISTANCE=1 TEXTURE_FIX=1 EXT_OPTIONS_MENU=1 EXTERNAL_DATA=1
Building can take several minutes.

Once the build is finished, an apk file will be available in build/us_pc. Copy it to your Internal storage or SD card.
cp build/us_pc/sm64.us.f3dex2e.apk /sdcard/Download/

Open your Files app, navigate to the folder where you copied the apk file, and open it to install it. If you enabled EXTERNAL_DATA, do not run the game just yet and read the next section.

Adding custom assets

If the game is built with EXTERNAL_DATA enabled, a base.zip can be found in build/us_pc/res/. This must be copied or extracted to /sdcard/Android/data/com.vdavid003.sm64port/files/res/ and then custom assets can be extracted to this same folder. If base.zip or any files are missing from that folder, the game will not load and tell you a file is missing.

Here's an example using GhostlyDark's SM64 Reloaded texture pack.

cp build/us_pc/res/base.zip /sdcard/Android/data/com.vdavid003.sm64port/files/res/
wget https://evilgames.eu/texture-packs/files/sm64-reloaded-v2.3.0-pc-1080p.zip
unzip sm64-reloaded-v2.3.0-pc-1080p.zip -d /sdcard/Android/data/com.vdavid003.sm64port/files/res/

The game may take longer to load with texture packs installed. With SM64 Reloaded's 1080p pack, the game takes me about 20 seconds to start.

Using the 60 FPS patch with high resolution texture packs may impact performance. With the FPS patch enabled while using SM64 Reloaded's 1080p pack, the game runs at about 30-40 fps in most open levels and 40-60 while running around the castle interior.
Any framerate lower than 60 FPS will slow down the game. This is because the game's logic is still running at 30 fps, but the patch forces additional frames to be generated on the fly to insert in between proper frames.

Cleaning up

If you want to rebuild with new options, you will need to run make clean in the sm64-port-android folder first.

To remove the entire cloned repo, return to the Termux home folder using cd ~ and run rm -Rf sm64-port-android.

Other notes

Cheats menu

The game has a cheats menu included, but I believe you must build with the expanded options menu enabled (EXT_OPTIONS_MENU=1) to use it. To enable the cheats menu on RP3, pause the game and press L3 three times. You will hear a sound effect confirming that it has been enabled. You can then find the CHEATS menu in the R options menu under EXIT GAME.

The moon jump cheat says to press L to use it, but it is actually L3 by default on the RP3.

The differences between the ex/master and ex/nightly branches

There's actually multiple differences, but mainly ex/nightly includes graphics code updates from the original sm64-port repo. The RP3 on 1.0.0.8 can't handle these updates for some reason, resulting in a black screen when loading the game if built from ex/nightly. The 60 FPS patch included with ex/nightly is also designed for these changes and does not work with ex/master.

Back to top