Primeros Pasos

Esta guía te lleva a través de los prerrequisitos y la configuración inicial necesaria para construir tus juegos de RPG Maker MV y MZ como aplicaciones nativas usando Ludens.

Cómo funciona Ludens

Antes de empezar, es útil entender la arquitectura: Ludens no recompila nativamente el código JavaScript de tu juego a Java/Kotlin. En su lugar, toma tu juego de RPG Maker exportado para web y lo envuelve en un contenedor Compose Multiplatform. Ejecuta el juego usando un WebView nativo móvil mientras renderiza una interfaz nativa transparente superpuesta sobre él. Esta interfaz contiene el joystick virtual y los botones de acción, los cuales se comunican con el motor del juego subyacente inyectando eventos JavaScript.

Soporte iOS

La compilación para iOS aún no está completamente configurada y usa la configuración por defecto de la plantilla Compose Multiplatform. Esta guía se centra en Android.

Prerrequisitos

Android Studio

Descarga e instala Android Studio. Se recomienda la versión Otter 2 Feature Drop | 2025.2.2 o superior.

• Descargar Android Studio
• Guía de Instalación
• Guía de Configuración Oficial

Asegúrate de que los siguientes componentes se incluyan durante la instalación:

• Android SDK
• Android SDK Platform-Tools
• Android Virtual Device (recomendado para pruebas)

Java Development Kit (JDK)

El proyecto requiere Java 17 o superior. Android Studio generalmente incluye una versión compatible (JetBrains Runtime), pero puedes instalar JDK 17 manualmente si es necesario. Si compilas fuera de Android Studio, asegúrate de tener configurada la variable de entorno JAVA_HOME.

• Guía Oficial de Instalación del JDK

Herramienta de Compilación Gradle

Ludens incluye un Gradle Wrapper, lo que significa que no necesitas instalar Gradle manualmente. El proyecto usa el script incluido (gradlew para macOS/Linux, gradlew.bat para Windows) para asegurar que se usa la versión correcta de Gradle automáticamente.

Juego de RPG Maker MV/MZ

Necesitas tu proyecto de RPG Maker exportado para despliegue web. Consulta la sección Exportar el Juego para más detalles.

Plugin Recomendado

Incluir el plugin YDP_Ludens.js en tu proyecto de RPG Maker es opcional pero altamente recomendado:

• Corrección de Carga de Fuentes: RPG Maker MV depende de métodos síncronos obsoletos para la carga de fuentes. Los WebViews modernos de Android bloquean esto, resultando en texto invisible. El plugin parchea el motor para usar las APIs asíncronas modernas de Web Fonts.
• Puente con el Motor: Permite una comunicación más fluida entre el cliente nativo de Ludens y el motor del juego.
• Ubicación: Debe ser el primer plugin en la lista de tu gestor de plugins para asegurar que parchea los comportamientos principales antes de que se ejecute cualquier otro plugin.
• La última versión y otros plugins recomendados están disponibles en el repositorio rpgm-plugins.

Compatibilidad de Plugins

Muchos plugins de RPG Maker están diseñados solo para PC (escritorio). Verifica que todos los plugins usados en tu juego sean compatibles con entornos móviles (WebView) antes de compilar.

Obtener el Proyecto

1. Clona el repositorio o descárgalo como ZIP y extráelo:

   git clone https://github.com/yoimerdr/ludens.git

2. Abre Android Studio.
3. Selecciona Open y navega hasta la carpeta del proyecto ludens.
4. Espera a que Gradle termine de sincronizar. Nota: La primera vez que abras el proyecto, Gradle descargará las dependencias necesarias. Este proceso puede tardar varios minutos y descargar alrededor de 500MB de datos.

Orientación del Juego

Por defecto, la aplicación Ludens está configurada para ejecutarse en modo Horizontal (sensorLandscape). Si tu juego está diseñado para modo Vertical (Portrait), necesitarás cambiar esta configuración en el Android Manifest. Consulta la guía de Configuración Android para más detalles.

Estructura de Directorios

Una vez abierto el proyecto, familiarízate con estas ubicaciones clave:

• Directorioludens/

  • DirectoriocomposeApp/

    • Directoriosrc/

      • DirectoriocommonMain/

        • DirectoriocomposeResources/

          • Directoriofiles/ Tu juego va aquí

            • …
  • gradle.properties Configuración de la app
  • keystore.properties.template Plantilla de firma

Siguientes Pasos

Una vez que tu entorno esté listo, procede a:

1. Exportar tu juego desde RPG Maker.
2. Configurar y compilar tu APK de Android.