Phaser 3 + Capacitor Android APK: White screens, texture rendering failures, and orientation issues

Phaser 3
1

Phaser 3 + Capacitor Android APK: Game works on web but has major issues on mobile

Setup

  • Phaser 3, Capacitor, Canvas: 2560×1440 landscape

  • TexturePacker multiatlas (2048×2048)

  • 7 mascot characters, each built from 15-25 sprite parts in Containers

Problem

My game works perfectly fine in desktop browsers (Chrome, Safari) with no issues at all. But when I build an APK using Capacitor for Android, everything breaks:

  1. Performance: The game lags and freezes on mobile even though it runs smoothly on web

  2. Textures not loading: Character assets fail to load — I get white blocks or blank areas where mascots should appear

  3. Screen not filling: The game only covers half the screen, with a white/gray bar on the side

  4. Orientation: Content displays sideways instead of landscape

I’ve already tried reducing atlas sizes from 4096 to 2048, setting Phaser.AUTO instead of WEBGL, and fixing CSS. None of these fully resolved the issues.

Has anyone successfully shipped a Phaser 3 game on Android via Capacitor? What am I missing? Any help would be appreciated.

2

I built a game in Phaser that I launched in Google Play, yes:

I used Ionic Appflow and Cordova with Ionic WebView instead of Capacitor. I’ve built a lot of apps in Cordova over the years, so I just went with what I know. Have you built any hybrid apps in the past? It turning out to be super annoying to build is kind of par for the course if you don’t know, hah. Like if it works the first time you build it, that’s a miracle.

For the screen orientation, you should be able to fix that either with a plugin or by changing the AndroidManifest file. For files not loading, you’re not by chance loading things like this, are you?

/img/myasset.png

What I mean is you’re not loading images or files with a slash at the beginning? That will make it look in the root of the file system, which is not the folder where your code is, so you should use relative URLs (no slash at the front)

img/myasset.png

For performance…yeah you usually have to optimize your code a lot for mobile. Example: when testing my game on a phone with low battery mode, collisions kept failing. I had to do a lot of optimizations to make the game run consistently on low battery.

For the screen fill, that can be involved. What resolution is your game?

Do you know how to debug your app with Google Chrome? If you want me to help you more on it, you can DM me with a link to your game and I can see if I can give you more specific tips and you can send me builds. I have some code I can send you that will alert any JS errors to the screen as well, which can be easier than remote debugging most of the time.

3

Oh and by the way, have you ever gone through the process of actually launching an app with Google Play? Because that’s also a nightmare.

4

Would you mind testing html2app.dev? It uses Flutter’s WebView. If you see the same issues there, you’ll know the problem isn’t with the wrapper (Capacitor vs. Flutter), but with your code itself.