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.

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 /storage/9C33-6BBD/. 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, there are two versions of the RP3's OTA updates out in the wild, 1.0.0.8 and 1.0.0.37. 1.0.0.37 was released on accident and then pulled from the update servers. Which version you have will determine which branch of SM64 you can run.

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 users can run the ex/nightly build of the game. This version comes with an optional 60 FPS patch.
1.0.0.8 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 users: git clone https://github.com/VDavid003/sm64-port-android --branch ex/nightly
    • 1.0.0.8 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 -C tools/audiofile
  6. (1.0.0.37 users only) If you want the 60fps patch: tools/apply_patch.sh 60fps_ex.patch

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 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

When the build is finished, a base.zip can be found in build/us_pc/res/. This must be copied to /sdcard/Android/data/com.vdavid003.sm64port/files/res/ and then custom assets can be extracted to this same folder. If this folder is empty, the game will not load.

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/

Also be aware that the game may be slower to start up with high resolution textures being loaded. With this texture pack, mine takes about 20 seconds to get to the title screen, but then has no slow down after that.

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 ex/master and ex/nightly

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.

I suspect 1.0.0.37 included a graphics driver update, or something similar, that makes it compatible with the ex/nightly changes. Hopefully the next proper OTA update will also include the graphics update.

Back to top