How to install AM2R v1.5.5 on PortMaster-compatible Linux handhelds

am2r-portmaster-install.md

AM2R PortMaster Setup Guide

This guide explains how to install AM2R v1.5.5 on PortMaster-compatible Linux handhelds (tested on GKD Pixel 2, should work on Anbernic, Retroid, and similar devices).

Required Files

You need three zip files. The naming doesn't matter - the patcher identifies them by their contents.

File	Size	Description	Source
AM2R Port	~4 MB	Base port files (gmloader, libs, scripts)	Install via PortMaster app or download from portmaster.games
AM2R v1.1	~72 MB	Original game files (contains data.win)	archive.org - look for AM2R_11.zip
Community Patch	~330 MB	Updates game to v1.5.5	GitHub

Installation Steps

1. Install the AM2R port via PortMaster

Open PortMaster on your device, search for "AM2R", and install it. This creates the directory structure and base files.

2. Download the required files

On your computer, download:

• AM2R_11.zip from archive.org (the original v1.1 game)
• AM2R-Autopatcher-Windows-master.zip from GitHub (the community patch)

3. Copy files to your SD card

Place both zip files in:

/roms/ports/am2r/assets/

Your directory structure should look like this:

ports/am2r/
├── AM2R.sh
├── am2r.gptk
├── am2r.md
├── am2r.port
├── assets/
│   ├── AM2R_11.zip              <-- Game files (required)
│   ├── AM2R-Autopatcher-Windows-master.zip  <-- Community patch (optional but recommended)
│   └── (other files may exist here)
├── cover.png
├── gmloader
├── libs/
├── patchscript
└── ...

4. Run the port

Launch AM2R from your device's game menu. The patcher will:

1. Detect the zip files
2. Extract and patch the game (takes 2-5 minutes)
3. Display "Patching process complete!"
4. Launch the game automatically on subsequent runs

Troubleshooting

Patcher completes instantly without actually patching

Cause: The patcher can't find a valid AM2R v1.1 zip file.

Solution: Ensure you have the correct AM2R_11.zip (or similar) that contains data.win in its root. The ~72 MB file from archive.org is correct. Other versions or repacks may have different internal structures.

"No valid AM2R zip file found" error

The patcher looks for a zip containing data.win in its root directory. Verify your AM2R zip:

unzip -l AM2R_11.zip | grep data.win

You should see a line showing data.win (not inside a subfolder).

macOS users: remove metadata files

If copying files from macOS, remove the ._ metadata files that macOS creates:

find /path/to/sdcard/ports/am2r/assets -name '._*' -delete

Patcher says "options.ini missing"

This usually means the community patch zip has the wrong structure. Re-download from the GitHub link above.

Game launches but immediately returns to patcher

Delete patchlog.txt from the ports/am2r/ directory and try again. This forces a fresh patch.

Without Community Patch

If you only want the base v1.1 game (not recommended - v1.5.5 has many improvements):

1. Only copy AM2R_11.zip to the assets folder
2. Run the port - it will install without the community patch

Technical Notes

• The patcher creates am2r.port (a zip archive) containing the final game assets
• Successful patching creates patchlog.txt - the patcher skips if this file exists
• Game config is stored in ports/am2r/conf/am2r/
• The game runs via gmloader, a GameMaker game loader for ARM Linux