Android Game Launcher

A clean Electron-based launcher for Android games running under Waydroid.

Automatically starts your Waydroid session on launch and shuts it down cleanly when you close the app.

---

Requirements

Before you begin, make sure you have the following installed on your system:

Requirement	Why
Node.js v18+	Runs the Electron app
npm	Installs dependencies
Waydroid	The Android container the launcher talks to

Install Node.js (if you don't have it)

# Ubuntu / Debian
sudo apt install nodejs npm

# Arch
sudo pacman -S nodejs npm

# Fedora
sudo dnf install nodejs

Install Waydroid (if you don't have it)

Follow the official guide at https://docs.waydro.id/usage/install-on-desktops

---

Quick Start

# 1. Clone or download this folder, then enter it
cd android-game-launcher

# 2. Install dependencies (one-time)
npm install

# 3. Run the launcher
npm start

That's it. The launcher will start your Waydroid session silently in the background and stop it when you close the window.

---

Building a standalone app (optional)

If you want a single file you can double-click without running npm start:

# Build an AppImage (runs on any Linux distro)
npm run build:appimage

# Or build a .deb package (Ubuntu / Debian)
npm run build:deb

The output will land in the dist/ folder.

---

Creating a keyboard shortcut (optional, idk if it works in all disros)

If you want to add a keyboard shortcut for the app:

go to your distro's settings and search for keyboard shortcuts

add a new script shortcut and type the command

npm start --prefix /path/to/your/files/android-game-launcher

OR

you can also build a standalone app using the above, and then set a shortcut to launch that.

---

Adding custom icons

If an app shows only a letter instead of its real icon, you can drop a PNG named after the package into this folder:

android-game-launcher/
  com.supercell.clashofclans.png   ← file name = package name
  com.yourapp.name.png

The launcher checks for these local files first before falling back to Waydroid's icon cache.

---

How icon loading works

Icons are resolved in this order:

1. Local PNG in the project folder (your custom overrides)
2. Waydroid's icon store at ~/.local/share/waydroid/data/icons/<package>.png
3. .desktop file Icon= path at ~/.local/share/applications/waydroid.<package>.desktop
4. hicolor icon theme cache at ~/.local/share/icons/hicolor/*/apps/<package>.png
5. Letter fallback if none of the above exist

Icons in the Waydroid store are populated automatically after you install an app and the Waydroid session has run at least once.

---

Troubleshooting

Apps show letters instead of icons Run the app once inside Waydroid first — icons are cached after the first launch. Then click Sync in the launcher.

"Waydroid Offline" in the header Make sure Waydroid is installed and has been initialized (waydroid init). The launcher will try to start it automatically but can't initialise it for you.

Nothing shows in the library Check that waydroid app list returns results in your terminal. If it's empty, open the Play Store from the launcher and install something.