RPG Maker to Android Wrapper

A native Android wrapper application designed to run and package RPG Maker MV and MZ games for Android devices. This project provides a streamlined way to port your web-exported RPG Maker games into a standalone Android APK/AAB, ready for distribution or the Google Play Store.

🚀 Features & Architecture

• Technology Stack: The native wrapper is built entirely in Kotlin (see MainActivity.kt), the modern, official language for Android development. The build system uses Gradle with Kotlin DSL (build.gradle.kts).
• Play Asset Delivery (PAD) Integration: Bypasses Google Play's 150MB limit by packaging the entire game directly into the App Bundle (AAB). (See the dedicated PAD section below)
• Native WebView Integration: Runs the RPG Maker HTML5/JS engine smoothly within a dedicated Android WebView.
• Modern Resource Handling: The app/build.gradle.kts is specifically configured to not compress game files (.json, .ogg, .m4a, .png, .jpg). This is crucial because compressing these assets during the Android build process often breaks RPG Maker's ability to load audio and images cleanly on mobile.
• Save Game Fix: The wrapper injects a JavaScript patch on launch to force RPG Maker MV/MZ to use localStorage for save files, bypassing the engine's default behavior of trying to write to the read-only Android assets folder.
• Easy Updating: Simple architecture to easily update your game files, app name, package ID, version, and icons all from a single configuration block.
• Back Button Handling & Multi-Language: Implements native Android OnBackPressedDispatcher support with an exit confirmation modal. The modal automatically translates itself based on the user's Android system language (Pre-configured for 🇬🇧 English [Default], 🇮🇹 Italian, 🇫🇷 French, 🇪🇸 Spanish, 🇩🇪 German, 🇷🇺 Russian, 🇯🇵 Japanese, and 🇨🇳 Simplified Chinese).

📦 Understanding Play Asset Delivery (PAD)

The project architecture includes a dedicated game_assets module configured as an Android Asset Pack (com.android.asset-pack).

Important

Why PAD? Google Play has a strict 150MB limit for basic APKs/AABs. Historically, exceeding this required cumbersome .OBB expansion files. PAD is the modern replacement: it packages your entire hefty RPG Maker www folder directly into the App Bundle (AAB).

Note

How it works: The game_assets pack uses install-time delivery. When a user downloads your game from the Play Store, Google automatically delivers the game_assets pack alongside the base app as a single, seamless installation, bypassing the 150MB limit without any extra code needed from you.

🛠️ How to Use

Follow these steps to package your RPG Maker game:

1. Export your Game: In RPG Maker MV or MZ, go to File > Deployment... and select the Web browsers option.
2. Locate the Wrapper Directory: In this Android project, navigate to the following directory:

   game_assets/src/main/assets/www/
   

3. Paste your Game Files: Copy all the contents from your RPG Maker web export folder (the audio, data, img, js folders, index.html, etc.) and paste them directly into the game_assets/src/main/assets/www/ directory. This will overwrite the placeholder index.html file.
4. Open in Android Studio: Open this entire project folder in Android Studio.
5. Build and Run: Sync the Gradle project if prompted. You can now build the APK or run the app directly on an emulator or a connected Android device!

⚙️ App Identity & Versioning

Before publishing, you must configure the basic identity and version numbers of your app. This entire configuration is handled in ONE single block of code inside the app/build.gradle.kts file.

1. Open the file app/build.gradle.kts
2. Locate the highlighted block in the defaultConfig section.
3. Modify the parameters as needed based on these rules:
   • applicationId: The unique identifier for your app on the Google Play Store (e.g., com.yourcompany.yourgame).
   • app_name: The name displayed on the user's home screen.
   • versionCode: This is internal. It MUST purely be an integer and MUST increase by at least 1 every time you upload a new version to the Play Console (e.g., 2, 3, 4).
   • versionName: This is external. It is the version number shown to the users on the Play Store listing (e.g., "1.0.1", "2.0").

Code Block to Modify:

        // ▼ CHANGE YOUR FINAL PLAY STORE GAME PACKAGE AND NAME HERE ▼
        applicationId = "com.yourname.gamename" 
        resValue("string", "app_name", "My Awesome Game")
        versionCode = 1
        versionName = "1.0"
        // ▲ ======================================================= ▲

🎨 Customizing Icons & Splash Screen

To make the app your own, you need to replace the default Android icons and configure the startup experience.

App Icons (Adaptive Icons)

Android requires icons in various resolutions. The easiest way to generate them is using Android Studio's built-in tool:

1. Prepare your logo as a high-resolution PNG (at least 512x512 pixels, ideally with a transparent background).
2. In Android Studio, right-click the app/src/main/res folder.
3. Select New > Image Asset.
4. In the Asset Studio window:
   • Icon Type: Keep "Launcher Icons (Adaptive and Legacy)".
   • Source Asset: Set the path to your 512x512 PNG.
   • Scaling: Adjust the slider to ensure your logo fits within the "Safe Zone" circle.
   • Background Layer: Choose a solid color or an image for the background behind your logo.
5. Click Next and Finish. This will automatically generate all required sizes (mipmap folders) and update your AndroidManifest.xml appropriately.

Splash Screen (App Startup)

By default, this wrapper is configured with a solid black splash screen background (@color/black) to blend seamlessly with typical RPG Maker game loads and avoid flashing white screens.

• To change the background color: Open app/src/main/res/values/themes.xml (and colors.xml if needed) and modify the <item name="android:windowBackground">@color/black</item> attribute.
• Note for Android 12+: Modern Android devices automatically generate a splash screen using your App Icon (configured above) centered on the window background color before transitioning to the WebView. If you desire a more complex, branded animated splash screen, you can implement the official androidx.core:core-splashscreen library.

⚠️ Important Note on Source Control (Git)

To keep the repository clean and avoid uploading massive game assets, the game_assets/src/main/assets/www/ directory is intentionally ignored within the .gitignore file.

The only tracked file in that directory is a placeholder index.html. It has been configured using git update-index --skip-worktree so that when you paste your actual game files over it, Git will not track or upload your game's source code to the remote repository.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.