Android RPG Maker MV Guide

[Xilefian]

The originating tutorial along with direct support can be found at:
hbgames.org/forums/viewtopic.php?f=48&p=939401

Index

• Prerequisites
• Creating the Android app
• Testing (Optional)
• Create Debug APK
• Customisation
  
• Crosswalk vs WebView

What is the MV Android Client

The MV Android Client is a runtime client for the Android™ operating system intended to play games created with the RPG Maker MV game development tool-kit.

• Download Source
• View on GitHub

The tutorial uses the MV Android Client to compile an RPG Maker MV project for Android (deployed as an Android APK).

Prerequisites

MV Android Client

Obtain the MV Android Client source code from the URL:
github.com/AltimitSystems/mv-android-client/zipball/master
Or by cloning the GitHub repository with git:
github.com/AltimitSystems/mv-android-client.git

This is a zip folder of the latest version of the MV Android Client.

Extract this zip folder to a memorable location (such as your computer Desktop folder).

Development Environment

The official IDE for Android application development is Android Studio by Google.

Android Studio can be downloaded for macOS, Microsoft Windows and Linux at the following URL:
developer.android.com/studio

The Android Studio install instructions for your platform can be found at the following URL: developer.android.com/studio/install.html

Android SDK Libraries

When opening Android Studio for the first time, you will be presented with a welcome window describing the version of Android Studio you have installed with some quick options for creating a project.

If this is not the first time you are opening Android Studio and you are presented with a previous project, you can reach the welcome window by closing your current project from the File menu and then selecting Close Project.

At the lower right of the welcome window is the Configure menu. Open this menu and select SDK Manager to start the Android SDK Manager. This is where you can download the required Android SDK libraries for a project.

You may also open the Android SDK Manager from within an opened project via the Tools menu, selecting the Android sub menu and then choosing the SDK Manager.

Required SDK Platforms

The Android SDK Manager has three tabs; SDK Platforms, SDK Tools and SDK Update Sites.

To download the required SDK Platforms, make sure the SDK Platforms tab is selected. This is where you can download the development libraries for the many versions of Android.

It is usually best to select the most recent version of Android for installation. As of the writing of this tutorial, the most recent version of Android is "Android 8.0 (Oreo)".

Check the box to the left of the version of Android you wish to install the SDK for and click Apply to begin downloading the required SDK Platforms.

Required SDK Tools

Once the SDK Platform is downloaded, select the SDK Tools tab to begin downloading the tools needed for developing Android apps.

From this list, check the boxes to the left of the following SDK Tools:

• Android SDK Build-Tools
• Android SDK Platform-Tools
• Android SDK Tools
• Support Repository

If you wish to test your app on a real device you may need to also check the Google USB Driver if you are on Windows.

Click Apply to begin downloading the required SDK Tools.

Deployed RPG Maker MV Project

To prepare your RPG Maker MV project for Android you must export it from the File menu, selecting the Deployment... option.

In the Deployment window that appears, make sure the Android / iOS Platform is selected. You may check the Exclude unused files option, however this may break some Plugins that depend on additional files.

Remember to select an Output Location for the deployment, you can do this by clicking the Choose... button. You will need to find this output location later so make sure it's in an easy to find, memorable place (such as your computer Desktop folder).

Click OK to begin the deployment.

Creating the Android app

Open MV Android Client

From the Android Studio welcome screen, select Open an existing Android Studio project.

Find the folder where you extracted the MV Android Client source code downloaded at the beginning of the Prerequisites section.

Select this folder so it is highlighted and then click OK. It may take some time for Android Studio to build the project after opening it.

Wait for the project to settle in Android Studio. The project will automatically download additional libraries that it needs, so an internet connection is required for loading the project.

Once everything is settled, expand the Project tab at the upper far left and expand the Build Variants tab at the lower far left.

Expanding the app folder in the Project tab should have the manifests, java code and xml values.

The Build Variants section can be used to switch between Crosswalk and WebView as the default web-engine.

Crosswalk development ended in January 2017, so it is better to use WebView, however older devices may not be fully compatible with WebView features. See the end of this tutorial for a more in-depth explanation on Crosswalk vs WebView.

Import deployed RPG Maker MV project

Create Assets folder

If the Assets folder is not visible within the app folder of Android Studio then it must be created. The Assets folder is used to store the deployed RPG Maker MV project.

Right-click on the app folder to open the context menu. Open the New submenu, then open the Folder submenu lower down. From here, click the Assets Folder to begin creating the Assets folder.

Simply click OK on the window that appears.

Copy RPG Maker MV project files

Find the deployed RPG Maker MV project that you created during the Prerequisites. Inside here should be a www folder.

Select the www folder so it is highlight and copy this folder by right-clicking on it and selecting the copy option.

Back in Android Studio, you want to now right-click on the Assets folder and paste the www folder by selecting the paste option.

In the Copy window that appears, make sure Open copy in editor is un-checked to prevent the MV project files from opening in Android Studio and then click OK.

Depending on the size of your MV project, it may take a while to copy it into Android Studio.

Modify applicationId

The Android applicationId must be unique to your project.

Expand the Gradle Scripts and open the build.gradle (Module: app) file.

You should see something similar to the above image. Find the line inside defaultConfig that has applicationId.

Change the text inside the quotes to a new applicationId. Android applicationIds must contain no spaces and must be lower-case Latin characters with periods between each word.

Generally, they are domain names in reverse with the app name at the end. An example for a project call "Adventure" made at HBGames.org would be "org.hbgames.adventure".

If you do not have a website domain, you can use your first and last name. A project called "Owl Chronicles" by someone called "Harry Potter" would be "potter.harry.owlchronicles".

It must be unique to your project and your studio.

Testing (optional)

If you have an Android phone you may connect it to your computer to test your MV project directly.

A guide for setting up a phone for testing is available at this URL:
developer.android.com/studio/run/device.html

Alternatively, you may create an Android emulator instance. An emulator runs on your computer and does not require an Android phone.

A guide for setting up an emulator instance for testing is available at this URL:
developer.android.com/studio/run/emulator.html

Create Debug APK

From Android Studio, select Build and then click Build APK.

This will compile and build your app, which may take some time. When it is complete, at the lower right of Android Studio you will see a confirmation message with a handy link to your APK.

Clicking the link will open up the folder for you, where you can copy and share the APK.

This is a debug APK, so it is not ready for publishing to the Google Play Store. This tutorial will not cover publishing a release APK and support will not be given for issues related to APKs built for release. For information on creating a release APK see the URL:
developer.android.com/studio/publish

Customisation

Most of the customisation can be done within the values.xml file.

App Name

To rename your app, open the values.xml file and find the app_name entry. By default, the app is called RPG Maker MV.

Unicode must be used for non-Latin characters (such as Chinese characters). Use a unicode converter to generate these for XML.

App Website

The website URL is configured in the values.xml file. Change the app_host to your website domain and app_scheme to HTTP or HTTPS. As an example, if my website is http://www.hbgames.org then my app_scheme will be "http" and my app_host will be "hbgames.org".

After that, my website will need to be associated with the app. See the section "Associate your app with your website" at the URL:
developer.android.com/studio/write/app-link-indexing.html

App Icon

Open up the res/mipmap folders to view the app icons.

There are multiple icons here to handle the different versions of Android and the different sized icons for different devices.

You may delete all these icons to remove the default icon, however you must replace the icons with two icons, one named "app_icon" and another named "app_icon_round".

These can be PNG images, or you can create them with Android Studio by right-clicking on the mipmap folder, opening the New submenu and selecting Image Asset.

A guide for the Image Asset Studio is at the URL:
developer.android.com/studio/write/image-asset-studio.html

Remember to have two icons named "app_icon" and "app_icon_round"! Ideally, app_icon_round would be a circular icon.

Crosswalk vs WebView

Crosswalk is an Intel project that aimed to create a portable WebView alternative for Android that worked across multiple versions of Android. crosswalk-project.org

You may know of Crosswalk from Intel XDK, Cordova and PhoneGap. It is also featured as part of the "official" Android deployment guide for RPG Maker MV.

Modern Android has separated the WebView component from the operating system, so now old versions of Android can receive critical security updates for WebView without needing a complete operating system update. This has made Crosswalk redundant as Crosswalk's main goal was to provide WebView updates for old versions of Android.

So why use Crosswalk? Unfortunately, WebView updates haven't enabled some features for older devices. Namely, WebAudio and WebGL might not be available for old Android phones. Crosswalk may have these implemented for old devices, so with Crosswalk there is a possibility that compatibility can be improved.

This is not a win-win situation, however. WebView can work on even older version of Android than Crosswalk (Going as far back as Android 3.0 Honeycomb API 11). WebView may even be faster than Crosswalk for newer devices.

The critical difference is that Crosswalk is no-longer in development, so it will not receive security updates. If a bug appears in Crosswalk that allows people to hack devices and break phones through your app or game then you're out of luck. With WebView, an update from Google will fix the issue rapidly.

WebView is also a core part of Android itself. Using Crosswalk can increase the size of the APK as all the Crosswalk libraries and files for all the potential versions of Android and phone devices need to be included as well.

The recommendation from security-conscious developers such as myself is that WebView should be used and Crosswalk avoided. Crosswalk should be used at your own risk.

If a serious security issue for Crosswalk does appear in the future, it will be removed from future versions of the MV Android Client.

 

[Companion Wulf]

Oh, I have to try this soon. Didn't even know this existed, so thanks for sharing.

 

[NowhereGaming]

Amazing work! Thanks for this. Your hard work is GREATLY appreciated! That tool is good stuff - I had no idea it was out there.

 

[momijisu]

This is great stuff - frustratingly Android has already made it somewhat outdated - sadly didn't work for me - in the SDK Manager I no longer have an Android Support Library in the SDK Tools. Not sure if this was where it all went wrong?

I followed the rest of the steps - and it built an apk (yay) -but then crashes on the device when installing (APK from unknown sources allowed).

 

[Xilefian]

This is great stuff - frustratingly Android has already made it somewhat outdated - sadly didn't work for me - in the SDK Manager I no longer have an Android Support Library in the SDK Tools. Not sure if this was where it all went wrong?

The support library should be there. It's never going to disappear as it's a critical feature of Android. If it's definitely missing, but the APK builds fine, then everything is okay.

I expect that having the support library written in the gradle file is making your Android Studio automatically download it, without needing to install it manually through the SDK Tools.

If you manage to get it working without installing the Support Library, then I will remove that part from this guide.

I followed the rest of the steps - and it built an apk (yay) -but then crashes on the device when installing (APK from unknown sources allowed).

This isn't a crash! This means you need to enable external APKs to be installed (Android default security does not allow programs to be "side-loaded").

You should be able to do this in the "security" settings of your device (Enable apps from unknown sources, or something).
Search for "android enable unknown sources" on Google for some guides (it's very easy).


Most devices don't need to do this when in developer mode and plugged into your development machine, as development machine + developer mode tends to equate to a trusted source, but your mileage will vary on this one.

 

[Emilien]

Hi !!

I followed your tutorial but when I put my application on my tablet, I installed it but when I arrived on my tablet it say

Error
Your browser does not support WebGL.

My tablet is on Android 4.4.4 maybe it's that ? If yes how can we change our projet to android 4.4.4

Can you help me please
I try everything to pass my project on phone because it'is a class project but there I don't know what to do

Thanks you

 

[Xilefian]

Hi !!

I followed your tutorial but when I put my application on my tablet, I installed it but when I arrived on my tablet it say

Error
Your browser does not support WebGL.

Can you help me please
I try everything to pass my project on phone because it'is a class project but there I don't know what to do

Thanks you

Aha, I was worried there'd be someone who'd get this error.

Would you mind telling me what tablet you have exactly?

The error means your tablet has a very old web browser, the best solution for your particular problem is to disable WebGL, which can be done by opening the strings.xml file (see part five!) and look at the mv_project_index string, it should have at the end "webgl=yes" change that "yes" to "no". EDIT: It just has "?webgl", get rid of that.

In the future, I'll update the code so it detects WebGL and automatically sets that yes/no, but for now you will have to disable it.

UPDATE: android_102.zip should fix the WebGL detection, download that.

 

[Emilien]

Aha, I was worried there'd be someone who'd get this error.

Would you mind telling me what tablet you have exactly?

The error means your tablet has a very old web browser, the best solution for your particular problem is to disable WebGL, which can be done by opening the strings.xml file (see part five!) and look at the mv_project_index string, it should have at the end "webgl=yes" change that "yes" to "no".

In the future, I'll update the code so it detects WebGL and automatically sets that yes/no, but for now you will have to disable it.

Thank you very much for you super fast response !!
My tablet is a MIPAD and I make all what you said but know it's write
Error
Your browser does not support Web Audio API.
I think that it's the same problem ;) my old tablet
I really want to thank you because without you I could not have succeeded so I will go modify the credits of my game just for you, that's the least of things!

 

[Xilefian]

WebAudio is a hard one to solve as that's a strict requirement of default RPG Maker MV.

I don't think there's a solution I can give for WebAudio. I may be able to hack something, but it would be done in code in the future, not anytime soon.

Also, the fix would disable audio, so your game would have no sounds on low-spec devices like your tablet.

The CrossWalk browser may be able to solve these things, I've done some experiments with CrossWalk, but because it's no longer in development I dropped the idea of supporting it. Perhaps I can make it an optional fallback if WebGL and WebAudio aren't supported. It would force the minimum Android version requirement up slightly and it would make things more complicated.

I'll investigate this Saturday if I have free time (unlikely).

EDIT: Good news, I just found that "noaudio" is a real query option, so you could change your mv_project_index to be "file:///android_asset/www/index.html?noaudio" to disable audio and hopefully get everything working on your tablet.

EDIT2: I decided to go ahead and build some WebGL and WebAudio detection code into the app, the attached code has been updated to android_101.zip - the tutorial is exactly the same - so don't worry.
android_101 will check for webgl and webaudio before the game is loaded and will create the webgl or noaudio arguments automatically if your device supports these features.

 

[AgentMolder]

In your instruction use android 7.1 (Nougut) if my phone is 5.1 (lollypop) Can I play my Game?

Now I installing android studio it GB in size take so long to download and instal..

[Edit]
Now I finished Android studio install but when I Open your "Android" file it take a longgg time and download something from "jcenter.bintray.com\......\....." and now for 1 hour and still downloading??? anything wrong with this?

 

[Xilefian]

In your instruction use android 7.1 (Nougut) if my phone is 5.1 (lollypop) Can I play my Game?

In the build.gradle for the app there are the two lines;

minSdkVersion 11
targetSdkVersion 25​

The minSdkVersion is set to API 11 (Android 3.0 Honeycomb), which means you need at minimum Android 3.0 Honeycomb to play your game, which equates to roughly 99% of all Google Play Store Android devices on the planet.

The targetSdkVersion describes the features that the app will be using, which includes security features. By selecting the highest possible targetSdkVersion, we enable the latest security and performance features. If some of these features are not available for older devices, there is code to enable fall-back versions.

You can see this in the Java source files as;

if ( Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT ) {
    ... // Code to run on Kitkat and higher devices (API 19+)
} else {
    ... // Code to run on older devices, with versions lower than Kitkat (API < 19)
}

In the app code, I've written it so full-screen features will be enabled if you are running a later devices, otherwise it will fall-back to the next-best thing for versions lower than the latest.

 

[AgentMolder]

Thanks for your fast response, I load your "android101" and follow every step (Except phone emulation because I have samsung Note 3 that Andrid5.1 ) and finally APK was built!!!

but when I install to my phone it said "Your browser does not support WebGL." like Emilien guy, I tried to follow your advice but for your android_101 is not have this line "<string name="mv_project_index">blah blah blah</string>

Can you fix this problem?

or Can I change to lollypop API5.1 instead?

 

[Xilefian]

Do not follow my advice for Emilien, that is for the old version; android_101 is supposed to fix the problem.

I will need time to investigate this issue. A version android_102 will be made to fix it.

EDIT: android_102.zip has been uploaded (attached to first post again). Sorry about the problems with the old version. Once again, the tutorial hasn't changed.

The issue was that my code for detecting WebGL was relying on your device telling the truth, as it turns out, most devices lie and say "I support WebGL!" even though they do not...

I decided to copy RPG Maker MV's code for detecting WebGL (and WebAudio, although that was already working), so the logic is more sound, but now it depends on a page being fully loaded before being called.

Because of this, I added a dummy page when the app first loads, the dummy page is black (to match the black background of RPG Maker MV) and has a simple copyright notice at the bottom right of the screen, which disappears almost immediately.

This also fixes an obscure bug with the game not loading at all on some emulated devices (they needed a landing page before Javascript is ran).

 

[AgentMolder]

YES!!! Finally The APK can install and the Game Can RUN!!! (included sound)

Thanks a lot for your response and your Help

But now the problem is the game was lagged and after playing for 2 - 3 minute it will force close, I think it come from Map and event issue in individual game, my game have a tons of plugin and event (even it is a demo for 5 minute play lol) so I will tried to make the other APK for simple map and simple event, and I will report in this topic again

Regard

 

[Xilefian]

Not much can be done about the bad performance when your device doesn't allow WebGL to be used. WebGL helps with performance a lot.

This is probably where Crosswalk could help - probably. When I have some free time, I'll experiment with Crosswalk and see if it can boost performance. I'm apprehensive about using it as it is a 3rd-party dependency (makes your app much bigger) and it is officially discontinued (they are no longer updating it, could be much worse in the future).

 

[AgentMolder]

For some reason Crosswalk can not run properly in many cases (mee too) I tried official RMMV help file but it still Exited non exit zero code1. I search over internet there are so many people have same problem I don't know why ;-/

In some WebBoard said that original official technique will make APK that can run fast and less problem with any phone, but still have many issue about lagged and sound BGM.

I'll keep in touch with your future work for Android deployment, Thanks again for your help.

 

[Xilefian]

I've added Crosswalk into a version android_103

Here's how you switch between Crosswalk and WebView (pick whichever one works best for your game);

First, open Build Variants on the left of Android Studio (with your app project open).

In this window, you can click in the Build Variant column to open a list of the build variants.

Only debug variants will work until you learn how to publish a real Android app. Do not select "release".

From here, you can choose to either use Android's native "WebView", or the older, more compatible Intel "Crosswalk".

Choose webviewDebug for WebView or crosswalkDebug for Crosswalk.

Android Studio should automatically shuffle the app around when you select either of these. You can then click Play or Debug (as in the original tutorial) and you can see how Crosswalk or WebView performs for you on your device.

\	WebView	Crosswalk
Minimum Android API	11 (Android 3.0 Honeycomb)	16 (Android 4.1 Jelly Bean)
Loading times	Faster	Slower
Sound loading speed	Faster	Slower
WebAudio compatibility	Okay	Excellent
Canvas performance	Bad	Good
WebGL performance	Good	Good
WebGL compatibility	Bad	Better
Security features	Up-to-date with your version of Android	Potentially bad (development ended early 2017)

* This data is based on my own observations. Your mileage will definitely vary depending on your device.

EDIT: I've uploaded android_103. The part of the Tutorial that tests the APK before the www folder is copied into the assets will not display the error screen for Crosswalk, a different error will appear (it's the same type of error though).

I've also added a quit message to 1.0.3, so when you press the back-button a message will pop-up asking you if you definitely wanted to quit and warning you about lost save-games.

 

[Emilien]

Everything works perfectly for me.
Xilefian are really do quality work and it's appreciable that you answer as quickly !
Thanks you !

And have a good game making all !

 

[AgentMolder]

For me Crosswalk a little bit better frame rate than Webview

but the problem that force close in game was the same (the same scene both build variant) I think it come from BGM issue that mention on many RMMV webboard around the world (include Thailand). If I have time today I will make new project for simple event simple BGM and simple plugin and test again.

Anyway Thanks a lot for your help, let me know if you have New stuff.

 

[princeofbluh]

"Installation failed with message Failed to finalize session : INSTALL_FAILED_TEST_ONLY: installPackageLI.
It is possible that this issue is resolved by uninstalling an existing version of the apk if it is present, and then re-installing.

WARNING: Uninstalling will remove the application data!

Do you want to uninstall the existing application?"

not the best at android studio lmao...any help?