BUILD.md

Step-by-Step Build Guide

Leer en Español | Web Docs

This guide details the complete process to configure, customize, and generate an APK/AAB file for your RPG Maker MV/MZ game using Ludens.

Environment Setup

Android Studio

Download and install Android Studio. For this project, Otter 2 Feature Drop | 2025.2.2 or higher is recommended.

• Download Link: developer.android.com/studio
• Installation Guide: developer.android.com/studio/install
• Official Configuration Guide

Figure 1: Android Studio welcome screen where you can verify the installed version.

Ensure the following are included during installation:

• Android SDK
• Android SDK Platform-Tools
• Android Virtual Device (Recommended for testing)

Java Development Kit (JDK)

The project requires Java 17. Android Studio usually includes a compatible version (JetBrains Runtime), but you can install JDK 17 manually if you prefer.

• Official Installation Guide: How to install the JDK

Game Prerequisites (RPG Maker)

Before exporting your game, consider the following:

Plugins and Compatibility

• Warning: Many RPG Maker plugins are designed for PC (desktop) only. Verify that your plugins are compatible with mobile environments (WebView).
• Recommended Plugin: YDP_Ludens.js. You can find the latest version and other recommended plugins at the rpgm-plugins repository.
  • This plugin helps fix font loading issues on older WebView versions and enables extra functionalities.
  • Important: Place it as the first plugin in your list.

Figure 2: The YDP_Ludens.js plugin must be placed at the top of the list to ensure correct loading.

Ludens Project Configuration

Get the Project

1. Clone this repository or download it as a ZIP and extract it.
2. Open Android Studio.
3. Select Open and navigate to the ludens project folder.
4. Wait for Gradle to finish syncing (Download/Sync).

Figure 3: View of the project in Android Studio once Gradle sync is complete.

Directory Structure

Familiarize yourself with the location of key files:

• composeApp/src/commonMain/composeResources/files: Your game goes here.
• ludens.properties: Main Ludens configuration (app identity, manifest flags, permissions, settings preset).
• gradle.properties: Gradle/Kotlin performance and build-system options.
• keystore.properties: Local release signing credentials (do not commit).

Exporting the Game

1. Open your project in RPG Maker MV or MZ.
2. Go to File > Deployment.
3. Select the Android / iOS platform (Recommended). If unavailable, use Web Browsers.
4. Export the game.

Figure 4: Select the Android / iOS option when deploying your game.

Asset Integration

This is the most critical step.

Warning

Case Sensitivity: Windows file system is case-insensitive (/Path/Example = /path/example), but Android and iOS use case-sensitive file systems. Ensure that all file references in your game's code (images, audio, data files) use exact matching names. If a file is named MyImage.png, you must reference it as MyImage.png, not myimage.png. This is a common source of silent failures on mobile.

Tip: You can use the plugin YDP_CrossAssets from the rpgm-plugins repository to automatically normalize file paths and avoid this issue.

1. Navigate to the project folder in your file explorer: composeApp/src/commonMain/composeResources/files
2. Copy the entire www folder from your export and paste it inside files, or if you only have the game assets, create the www folder and paste the files inside it.

Mandatory Structure: The application expects to find index.html inside www.

Figure 5: Android Studio view showing the www folder and index.html file inside composeResources/files

Android

Customization

Edit the ludens.properties file in the project root.

# Android application id
ludens.android.id=com.mystudio.rpg

# Visible version (e.g. 1.0.0)
ludens.android.version=1.0.0

# Integer version code
ludens.android.versionCode=1

# Name in Settings
ludens.android.name=My Epic RPG

# Name in Launcher (Icon)
ludens.android.launcherName=My RPG

Important

Ludens now reads ludens.properties first. If missing, it can read the same ludens.* keys from gradle.properties; legacy keys like ludens.applicationId are not supported.

Figure 6: Modifying project properties to customize ID, version, and name.

Optional Android Runtime/Manifest Configuration

You can also customize Android behavior using ludens.properties:

# Manifest placeholders
ludens.android.manifest.allowBackup=true
ludens.android.manifest.largeHeap=true
ludens.android.manifest.hardwareAccelerated=true
ludens.android.manifest.screenOrientation=sensorLandscape
ludens.android.manifest.usesCleartextTraffic=false
ludens.android.manifest.resizeableActivity=false

# Generated permissions manifest.
# All listed permissions are optional; 
# The wrapper does not require or use features that depend on them.
# If your game needs permissions beyond basic network access, 
# you may need to edit the wrapper source code.
ludens.android.permissions.internet=false
ludens.android.permissions.networkState=false
ludens.android.permissions.wakeLock=false
ludens.android.permissions.accessWifiState=false
ludens.android.permissions.changeWifiState=false

These values are consumed by the custom build-logic plugins and injected during build.

Tip

Ludens supports additional configuration properties. Review ludens.properties directly to see the full list and descriptions.

App Icon

Replace the images in composeApp/src/androidMain/res/mipmap-* or use the Image Asset Studio tool:

1. Right-click on composeApp/src/androidMain/res.
2. New > Image Asset.

Figure 7: Using Image Asset Studio to update the application icon.

Build and Test (Debug)

For testing during development, you can use the terminal or create a configuration in Android Studio.

Option A: Run Configuration (Recommended)

If you prefer using the Android Studio interface:

1. Open the configurations menu and select Edit Configurations....

Figure 8: Accessing the configurations menu.

2. Add a new Gradle task.

Figure 9: Creating a new Gradle task.

3. Name the task (e.g., assembleDebug) and in the Arguments field type: assembleDebug.

Figure 10: Configuring the task arguments.

Option B: Terminal

1. Open the Terminal tab in Android Studio.
2. Run:

   ./gradlew assembleDebug

Result

Regardless of the method, the APK will appear in: composeApp/build/outputs/apk/debug/composeApp-debug.apk.

Tip

Install this APK on an emulator or real device to verify that the game loads and plugins work correctly.

Figure 11: Successful build result.

Create Production Version (Release)

To generate the final signed APK:

Option A: Android Studio Wizard

This option guides you step-by-step to sign your application.

1. Go to Build > Generate Signed Bundle / APK.

Figure 12: Starting the signing wizard.

2. Select APK and click Next.

3. Configure your Keystore.

   • Create New: If you don't have one, click Create new....

     
     Figure 13: Creating a new Keystore. Keep your password and the .jks file safe.

   • Use Existing: If you already have one, load it and enter credentials.

     
     Figure 14: Keystore credentials.

4. Select the release build flavor and click Create.

Figure 15: Output variant selection.

5. Result:

Figure 16: Notification of successfully generated APK.

Option B: Gradle Task (Configurable)

Similar to the Debug process, this option is ideal for automating the build but requires prior manual configuration.

1. Ensure you have your .jks file (Keystore) generated (you can use step 3 of Option A to create it).

2. Create/Edit the keystore.properties file in the project root with the path and credentials:

   storePassword=your_store_password
   keyPassword=your_key_password
   keyAlias=your_alias
   storeFile=C:/Path/To/Your/key.jks

   You can use keystore.properties.template as reference.

3. Run the assembleRelease task from the configurations window (as seen in the Debug section) or from the terminal:

   ./gradlew assembleRelease

4. Result:

Figure 17: Build result from Gradle.

File Location

• If you used Option A (Wizard): By default, Android Studio usually places it in composeApp/release/ (or the folder you selected during the destination step).
• If you used Option B (Gradle): The file will be in composeApp/build/outputs/apk/release/composeApp-release.apk.

iOS

Coming soon - The current configuration is the default for Compose Multiplatform.