← All posts

Minecraft Java on the Anbernic RG40XXH (muOS): getting the PortMaster port to work

PortMaster has a Minecraft Java port (minecraftjava) that runs on muOS handhelds like the Anbernic RG40XXH. Installing it looks simple, but on our RG40XXH it didn’t start, then it froze, and it took several fixes to get a playable game. This post collects everything in one place.

Tested on: Anbernic RG40XXH (1 GB RAM) · muOS 2601.0 Jacaranda · PortMaster Minecraft port · Minecraft Java 1.12.2.

First: the port is only a launcher

The PortMaster port does not include Minecraft. It contains a launcher menu, start scripts, controller mapping and the ARM pieces Minecraft needs on a handheld. The game itself (the Minecraft Java Edition files) has to come from your own copy.

That means:

  • You need to own Minecraft: Java Edition (bought at minecraft.net, it comes with the Java & Bedrock bundle). The files come from the official Minecraft Launcher on your PC.
  • The port starts the game offline, without signing in. You’ll play as a local player with the default skin, and online-mode servers won’t let you join. LAN or offline-mode servers still work (put the address in server.txt in the port folder).

Only two Minecraft versions work

The port supports exactly:

Version Vanilla Forge
1.7.10 ✅ (fastest) ✅
1.12.2 ✅ ✅

Our first mistake was copying 1.12.1. It looks close enough, but the launcher menu only checks for 1.7.10 and 1.12.2, so the menu showed nothing but Exit. Don’t rename another version to 1.12.2 either. It has to be the real 1.12.2.

Step 1: get 1.12.2 on your PC

  1. Open the official Minecraft Launcher and sign in with the account that owns Java Edition.
  2. Go to Installations → New installation, choose release 1.12.2, and click Create.
  3. Click Play once and wait until the main menu appears. This downloads the libraries and sound/texture assets 1.12.2 needs. Then quit.

Your Minecraft folder is now complete:

System Folder
Windows %APPDATA%\.minecraft
macOS ~/Library/Application Support/minecraft
Linux ~/.minecraft

Step 2: copy the right folders to the right place

This was our second mistake. The version files don’t go in ports/minecraftjava/versions/. The start script loads them from the hidden .minecraft folder inside the port:

SD card 1 (muOS: /mnt/mmc)
└── ports/minecraftjava/.minecraft/
    ├── versions/1.12.2/   ← 1.12.2.jar and 1.12.2.json
    ├── libraries/         ← your PC's .minecraft/libraries folder (merge)
    └── assets/            ← your PC's .minecraft/assets folder (merge)

Copying only the .jar and .json isn’t enough. Minecraft 1.12.2 also needs about 30 libraries and the assets (sounds, language files, textures), about 200 MB in total. Without them it fails to start.

What “the whole folder” means: inside Minecraft’s folder on your computer (see the table above) there’s a libraries folder with many sub-folders (com, org, net…) full of .jar files, and an assets folder. Copy each of them with everything inside into ports/minecraftjava/.minecraft/ on the SD card.

Merge, don’t replace. The port already has its own libraries folder with the ARM version of LWJGL that makes Minecraft work on the handheld. When your computer asks, choose Merge (macOS) or copy into the existing folder and skip files that already exist (Windows). Choosing Replace deletes the port’s files and Minecraft won’t start. The same goes for versions and assets.

If you play many Minecraft versions on your PC, these folders can be large, since they hold files for every version. That’s fine: the handheld only uses what 1.12.2 needs.

Copy them with a card reader, or over Wi-Fi with muOS’s SFTP server (in an SFTP app the path shows as /SD1 (mmc)/ports/minecraftjava/.minecraft/). The port keeps its own ARM build of LWJGL, so copying your PC’s libraries folder doesn’t break anything.

If .minecraft is hidden on your computer: on macOS press ⌘ Shift . in Finder; on Windows enable View → Hidden items.

Step 3: start it

On the handheld, open Ports → Minecraft Launcher. The menu should now show Vanilla v1.12.2.

If it still only shows Exit, check ports/minecraftjava/Launcherlog.txt. An error like versions/1.12.1/1.12.1.json: line 1: {assetIndex:: command not found means the launch script ROMS/Ports/Minecraft Launcher.sh was edited by hand. Reinstall the port from PortMaster to get the original script back.

Don’t leave backup copies in ROMS/Ports. We saved the old script there as Minecraft Launcher.sh.bak, and muOS listed it as a second game called “Minecraft Launcher.sh”. Launching that ran the broken old script again. Keep backups somewhere else.

Fix: stutter, freezing or hanging

This is the most common problem, and it’s almost always settings, not a broken install.

What it looks like

  • It plays fine at first, then gets slower and slower, and after a few minutes it seems frozen.
  • Buttons react seconds late.
  • The whole handheld stops responding, even the SFTP server, until you restart it.

In our case, ports/minecraftjava/log.txt showed Can't keep up! Did the system time change, or is the server overloaded? Running 2227ms behind, skipping 44 tick(s) and the game went from 30 frames a second to one frame every 8–12 seconds. It wasn’t a crash, just overload.

Why it happens

The RG40XXH has 1 GB of RAM and a phone-class chip. The port gives Java only 384 MB. If you copied your settings from a PC, Minecraft tries to load a render distance of 12 chunks with fancy graphics and smooth lighting. The handheld can’t keep up, memory runs out, and Java spends most of its time cleaning memory instead of running the game.

The settings that fix it

Change these in Options → Video Settings, or edit ports/minecraftjava/.minecraft/options.txt (with the game closed):

Setting (in-game) options.txt Set to Why
Render Distance renderDistance 4 (try 5–6 later) By far the biggest effect on speed and memory
Graphics fancyGraphics false (Fast) Simpler leaves, water and shadows
Smooth Lighting ao 0 (Off) Saves CPU on every block
Clouds renderClouds false Less to draw
Mipmap Levels mipmapLevels 0 Less memory for textures
Max Framerate maxFps 30 Steady 30 instead of trying for more
VSync enableVsync false Avoids extra waiting between frames
Particles particles 2 (Minimal) Fewer effects in fights and rain
Entity Shadows entityShadows false Less to draw

In options.txt those lines look like this:

renderDistance:4
fancyGraphics:false
ao:0
renderClouds:false
mipmapLevels:0
maxFps:30
enableVsync:false
particles:2
entityShadows:false

After this change our RG40XXH played smoothly.

If it still stutters

Try these one at a time:

  1. Lower the render distance to 3 or even 2 in big, busy worlds.
  2. Start a new world or play near spawn. Huge worlds with many loaded chunks, farms or lots of animals use more memory.
  3. Restart the game after long sessions. Memory builds up over time.
  4. Switch to 1.7.10. It’s the lightest version the port supports, and the port’s own notes recommend it for the best performance.
  5. Advanced: more memory for Java. The limit is set in ports/minecraftjava/1.12.2.start (it picks XMX=384M on 1 GB devices). Raising it to 448M can reduce stutter, but muOS, the display layer and the game all share the same 1 GB. Go higher and the system may kill the game instead. Change it only if the steps above aren’t enough, and keep a copy of the original file outside ROMS/Ports.

Frozen right now?

Press R2 + SELECT + B (muOS force-quit). If nothing responds, hold POWER for about 10 seconds. Your world is kept, but you lose anything since the last autosave. Then lower the settings before playing again.

Harmless: log.txt fills with GL ERROR 1282 @ Post render. That comes from the port’s graphics compatibility layer and doesn’t cause the slowdown.

Controls

Button Action
Left stick Move
Right stick Look around, and the mouse pointer in menus
A Jump
B Drop item
X / Y Inventory
R2 Break / attack (left click)
L2 Place / use (right click)
L1 / R1 Hotbar
L3 / R3 Sprint / sneak
START Pause menu

To quit when the game won’t let you: R2 + SELECT + B is muOS’s force-quit. Pause first so the world saves.

Still open: the death screen

One problem we haven’t solved yet: after dying, some players can’t click Respawn. The pointer works on the title screen and in the inventory, and the log shows the controller sending movement, so the cause is still unclear. We’ll update this post when we find the fix. Until then, avoid lava and deep water.

Summary

  1. Own Minecraft Java Edition, and install 1.12.2 (or 1.7.10) once with the official launcher.
  2. Copy versions/1.12.2, libraries and assets into ports/minecraftjava/.minecraft/.
  3. Keep ROMS/Ports clean, with no .bak scripts.
  4. Use low video settings (render distance 4, fast graphics, 30 FPS). If it still stutters, see the troubleshooting steps above.

Questions or a fix for the death screen? Email feedback@pocketkode.com.

Minecraft is a trademark of Mojang Synergies AB. PocketKode is not affiliated with Mojang, Microsoft, PortMaster, muOS or Anbernic.