Ludens

Leer en Español | Build Guide | Web Docs

Ludens is a Compose Multiplatform wrapper built in Kotlin to port RPG Maker MV/MZ games to mobile devices. It embeds your HTML5 export inside a native app and provides configurable mobile controls and settings.

Download Sample APK

Features

• Optimized WebView integration for RPG Maker MV/MZ.
• On-screen controls (overlay):
  • Virtual joystick.
  • Configurable buttons (A, B, X, Y).
• Complete settings screen:
  • System: Theme (Light/Dark/System), Language (System/English/Spanish).
  • Tools: Mute Audio, Show FPS, Toggle WebGL.
  • Controls: Enable/Disable, Opacity, Button Positions, Key Mapping.
  • Actions: Configurable quick actions menu (Order, Enable/Disable).
• Easy app/build configuration from ludens.properties.
• Efficient asset management in composeResources/files.

Note

This project does not include a built-in native save system. Save files are managed by RPG Maker inside WebView (LocalStorage/IndexedDB).

Quick Start

Warning

iOS build is not fully configured yet (currently template defaults). This guide focuses on Android.

Tip

Always validate on emulator or physical device. Some RPG Maker plugins may not behave correctly on mobile WebView.

Prerequisites

• Android Studio Otter 2 Feature Drop (2025.2.2) or higher.
  • Setup Guide
• JDK 17 or higher.
• RPG Maker MV/MZ project exported for web.
  • Optional: enable YDP_Ludens.js for extra compatibility/features in the client.
  • Get latest plugin and related plugins in rpgm-plugins.
  • Recommendation: place it as the first plugin in your plugin manager.
  • Compatibility: useful for older WebView font-loading issues.
  • Important: verify mobile compatibility for all plugins used by your game.

Export the Game

Export from RPG Maker using Android / iOS (recommended). If unavailable, use Web Browsers.

Depending on MV/MZ version, you may get either a game folder containing www or only the www folder. In both cases, index.html is required.

Import Assets

You have two valid options to import your game assets:

Option A (Recommended): Root Folder Place your full www folder at the root of the project: project/www/

Note

The build system will automatically synchronize these files into the required internal location during build. This automatic synchronization will only occur if the project/www/ folder contains more than just the index.html file.

Option B: Internal Folder Move the full www folder directly to the internal Compose resources path: composeApp/src/commonMain/composeResources/files/www/

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.

Required internal structure after import or sync:

files/
  └── www/
       ├── audio/
       ├── img/
       ├── js/
       ├── ...
       └── index.html

Android Configuration

Edit ludens.properties:

# Unique application identifier
ludens.android.id=com.yourorganization.sample

# Version visible to users
ludens.android.version=1.0.0

# Internal integer version code
ludens.android.versionCode=1

# App name in settings
ludens.android.name=Game Name

# Launcher label
ludens.android.launcherName=Game

gradle.properties is still used for Gradle/Kotlin build options. Ludens app identity/settings are configured in ludens.properties.

Build

For the full build flow with screenshots and release-signing details, see BUILD.md.

• Debug: ./gradlew assembleDebug
  • Output: composeApp/build/outputs/apk/debug/
• Release: ./gradlew assembleRelease
  • Create keystore.properties first (see keystore.properties.template).
  • Output: composeApp/build/outputs/apk/release/

iOS

Coming soon. Current setup follows default Compose Multiplatform template configuration.

Contributing

Contributions are welcome! Please read our CONTRIBUTING.md for details on our code of conduct, development setup, and the process for submitting pull requests.

License

Apache 2.0. See LICENSE.

Links

• Web Docs
• GitHub Repository
• Issue Tracker
• Kotlin Multiplatform
• Compose Multiplatform

Acknowledgments

• Compose Multiplatform
• Compose WebView Multiplatform
• Compose Virtual Joystick

---

If this project helps you, consider giving it a star.