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

Open Termux and run termux-change-repo and use the arrow keys provided by Termux to navigate the menu
Press space bar on each repo to make sure they are selected with an asterisk (*)
Select Ok and press enter
Select the Grimler mirror with space bar
Select Ok and press enter
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:

Open Termux and install SSHD: pkg install openssh
Set a password: passwd
Get your username: whoami
Get your ip address: ifconfig
On an RP3, it should be the inet value under wlan0
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

In Termux or SSH, run pkg update and pkg upgrade if you haven't already.
Install the X11 repo (required to get mesa package): pkg install x11-repo
Install the rest: pkg install mesa binutils git wget make python getconf zip apksigner clang
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/.
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:

Open Android system settings
Go to System > Advanced > Updater
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.

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
Change to the new folder: cd ./sm64-port-android
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
Download SDL requirements: ./getSDL.sh
Build the Audio File Library: make -C tools/audiofile
(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.
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 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, much like modern 3rd person games. However, I have experienced the camera clipping through walls and sometimes turning immediately after entering an area. 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.
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.
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 SM64 reloaded.

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 load with high resolution textures being loaded.

Cleaning up

If you want to change options, you will need to run make clean in the sm64-port-android folder to clean the build folder. This is will delete the custom assets folder as well.

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

Other notes

The game has a cheat 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.