Ejemplos

Esta página proporciona ejemplos prácticos para flujos de trabajo comunes al usar Ludens.

Ejemplo 1: Configuración Mínima

La configuración más simple posible — exporta tu juego y compila con ajustes por defecto.

Pasos

1. Exporta tu juego de RPG Maker MV o MZ con la opción de despliegue Android / iOS. Si no está disponible, selecciona Web Browsers (Navegadores Web).
2. Copia el contenido de la carpeta www exportada a:

   project/www/

   Nota: El sistema de compilación sincronizará automáticamente estos archivos en el directorio interno de recursos durante la compilación. Si prefieres la gestión manual sin sincronización automática, coloca tus archivos directamente en composeApp/src/commonMain/composeResources/files/www/.
3. Edita ludens.properties:

   # ----- Identidad Android -----
   ludens.android.id=com.ejemplo.mijuego
   ludens.android.version=1.0.0
   ludens.android.versionCode=1
   ludens.android.minSDK=21
   ludens.android.targetSDK=36
   ludens.android.name=Mi Juego
   ludens.android.launcherName=Mi Juego

4. Ejecuta:

   ./gradlew assembleDebug

Resultado

Un APK de debug en composeApp/build/outputs/apk/debug/composeApp-debug.apk listo para pruebas.

---

Ejemplo 2: Icono Personalizado y Release Firmado

Un flujo de trabajo completo de producción con branding personalizado usando el Generador Automático de Iconos.

Pasos

1. Completa la Configuración Mínima anterior.

2. Configura tu icono personalizado:

   • Coloca tu imagen de icono origen (recomendado: vectorial icon.svg, o un icon.png de alta resolución de al menos 512×512 px) en la carpeta project/assets/icons/.
   • Configura las propiedades del generador en ludens.properties:

     # Nombre del icono maestro origen en project/assets/icons/
     ludens.icons.name=icon
     
     # Nombre de la capa adaptativa de primer plano (opcional)
     ludens.icons.foreground=icon_foreground
     
     # Color de fondo hexadecimal sólido o referencia de recurso
     ludens.icons.background=#FDFDFD
     
     # Habilitar generación para Android e iOS
     ludens.icons.android.enable=true
     ludens.icons.android.format=webp
     ludens.icons.android.playstore=true
     ludens.icons.ios.enable=true
     
     # Escala del elemento de primer plano dentro del viewport de icono adaptativo
     ludens.icons.scale=0.62

   Alternativa: Configuración Manual

   Si prefieres configurar manualmente tus iconos usando Image Asset Studio de Android Studio (clic derecho en composeApp/src/androidMain/res > New > Image Asset), primero debes desactivar el generador automático configurando ludens.icons.android.enable=false y ludens.icons.ios.enable=false en ludens.properties.

3. Crea un keystore de firma (si no tienes uno):

   • En Android Studio: Build > Generate Signed Bundle / APK
   • Selecciona APK, clic en Next
   • Clic en Create new… y completa los datos del keystore
   • Guarda el archivo .jks de forma segura

4. Configura la firma:

   keystore.properties

   storePassword=mi_password_seguro
   keyPassword=mi_key_password
   keyAlias=mi_alias
   storeFile=C:/llaves/mi-juego-key.jks

5. Compila el APK release:

   ./gradlew assembleRelease

Resultado

Un APK release firmado en composeApp/build/outputs/apk/release/composeApp-release.apk listo para distribución.

---

Ejemplo 3: Usando el Plugin YDP_Ludens

Integra el plugin recomendado para una mejor compatibilidad con WebView y diálogos de diagnóstico de errores.

Pasos

1. Localiza el plugin YDP_Ludens.js dentro de la carpeta resources/ de este proyecto (o descarga la última versión desde el repositorio rpgm-plugins).

2. Colócalo en la carpeta js/plugins/ de tu proyecto RPG Maker.

3. Abre tu proyecto de RPG Maker y ve al Gestor de Plugins.

4. Agrega YDP_Ludens y muévelo a la parte superior de la lista de plugins.

5. Guarda y vuelve a exportar el juego.

6. Copia el contenido de la carpeta www actualizada a project/www/ y recompila.

Beneficios

• Corrige errores de verificación de carga de fuentes en versiones antiguas de WebView.
• Habilita la intercepción nativa de stack traces de errores y diálogos de traceback si ludens.debug.errors=true está configurado.

---

Ejemplo 4: Referencia de Estructura de Archivos

Una vista completa de la estructura del proyecto después de la configuración:

• Directorioludens/

  • DirectoriocomposeApp/

    • Directoriosrc/

      • DirectorioandroidMain/

        • Directoriores/

          • mipmap-* (Iconos de la app autogenerados)
      • DirectoriocommonMain/

        • DirectoriocomposeResources/

          • Directoriofiles/

            • Directoriowww/ Tu juego (Ruta de la Opción B, o salida auto-sincronizada)

              • index.html
    • Directoriobuild/

      • Directoriooutputs/

        • Directorioapk/

          • Directoriodebug/ Salida APK debug

            • …
          • Directoriorelease/ Salida APK release

            • …
  • Directorioproject/ Carpeta origen principal de tus recursos

    • Directorioassets/

      • Directoriofonts/ Fuentes personalizadas (auto-sincronizadas)

        • …
      • Directoriolanguages/ Origen de traducciones/localización (archivos xml)

        • …
      • Directorioicons/ Assets de icono maestro de la app (SVG/PNG)

        • …
    • Directoriowww/ Archivos del juego de RPG Maker (Ruta de la Opción A, auto-sincronizada)

      • …
  • ludens.properties Configuración principal de Ludens
  • gradle.properties Configuración de Gradle
  • keystore.properties Credenciales de firma
  • keystore.properties.template Referencia de plantilla