Guía completa de compilación y depuración de minijuegos de WeChat con Cocos Creator: del panel Build a las herramientas de desarrollo

Llevas semanas trabajando en tu juego con Cocos Creator.

El código está listo, los assets importados y las animaciones funcionan. Abres el panel Build para publicar en la plataforma de minijuegos de WeChat y descubres que los verdaderos problemas empiezan aquí.

Errores en el campo libVersion. Pantalla negra en dispositivo real. Paquete que supera el límite. Compilación de iOS que falla directamente. Ninguno de estos temas aparece en los tutoriales de desarrollo de juegos, pero cualquiera puede dejar tu proyecto atascado en el paso de publicación.

Este artículo aborda exactamente eso. Desde cómo rellenar cada parámetro del panel Build hasta qué hace cada archivo del directorio de salida, pasando por los pasos concretos de depuración en dispositivo real con las herramientas de desarrollo de WeChat: todo el flujo, paso a paso. Al final también interpretamos las políticas de incentivos de minijuegos de WeChat en 2026, porque maximizar ingresos conviene planificarlo con antelación.

Si estás preparando la publicación de un proyecto Cocos en minijuegos de WeChat, o ya has tropezado con alguno de estos problemas, esta guía debería ayudarte.

Configuración práctica de parámetros del panel Build

Abre primero el panel Build.

En Cocos Creator hay dos formas: menú «Proyecto → Compilar y publicar», o el atajo Ctrl+Shift+B (en Mac, Cmd+Shift+B). Al abrirlo verás muchos parámetros: ruta de publicación, escena inicial, MD5 Cache, AppID… La primera vez puede resultar abrumador.

Pero vamos uno por uno.

Parámetros generales: configuración básica

Ruta de publicación: ubicación del directorio de salida de la compilación. Por defecto se genera una carpeta build en la raíz del proyecto. Puedes cambiarla, pero recomiendo mantener la predeterminada: la estructura de salida queda fija y es más fácil localizarla al depurar.

Escena inicial: la primera escena que carga el juego al arrancar. Suele ser Boot o Loading. Si el proyecto tiene varias entradas, elige la principal.

Escenas incluidas en la compilación: lista todas las escenas del proyecto; marca las que quieras empaquetar. Las no marcadas no entran en el paquete final. Error frecuente: marcar todas las escenas y que el paquete se dispare de tamaño. Mejor incluir solo las necesarias y dejar el resto en un servidor de recursos remoto.

MD5 Cache: ¿activarlo o no?

Al activarlo, todos los nombres de archivo de recursos llevan un sufijo MD5. Ventaja: al actualizar recursos, el cliente detecta cambios y evita cargar caché antigua. Inconveniente: hay que cambiar cómo accedes a los recursos en el código.

Por ejemplo, antes usabas resources.load('texture/hero'); con MD5 Cache activo, la URL pasa a algo como texture/hero-abc123.png. Entonces necesitas este método para obtener la URL correcta:

// Obtener la ruta del recurso con sufijo MD5
const url = assetManager.utils.getUrlWithUuid('texture/hero', {
    isScene: false,
    type: 'png'
});

Esta API es el uso estándar en Cocos Creator 3.x. En 2.x la lógica varía un poco, pero la idea es la misma: no codifiques rutas a mano; deja que el motor las resuelva.

Parámetros específicos de minijuegos de WeChat: configuración de plataforma

AppID: obligatorio.

Sin AppID, al pulsar compilar aparece un error. Puedes usar un AppID de prueba, pero tiene muchas limitaciones: sin dominio de datos abiertos, sin publicación oficial y funciones de monetización publicitaria restringidas.

Para solicitar un AppID: inicia sesión en la plataforma pública de WeChat → Gestión de miniprogramas → Añadir minijuego → obtener AppID. La revisión suele tardar 1-3 días; conviene adelantarlo.

Modo de depuración: la salida de compilación incluye código y recursos extra de depuración. En publicación oficial conviene desactivarlo; en desarrollo ahorra mucho tiempo.

Separación del motor: reduce notablemente el tamaño del paquete.

Al marcarla, el código del motor Cocos no se empaqueta en el juego y se carga desde los servidores de WeChat. Requisitos previos:

• Debug Base Library ≥ 2.9.0 (configurado en las herramientas de desarrollo de WeChat)
• WebAssembly requiere cliente WeChat ≥ v7.0.17

Ventaja: el paquete inicial puede quedarse por debajo de 4 MB. Inconveniente: cargar el motor lleva tiempo y la primera entrada del jugador tendrá una breve espera. Si el proyecto tiene muchos recursos, la separación del motor casi es imprescindible.

Configuración de subdominio: si el juego usa ranking, compartir con amigos u otras funciones del dominio de datos abiertos, aquí configuras la información del subdominio. Es un entorno de ejecución independiente, aislado del juego principal, dedicado a datos sociales. Una mala configuración invalida el ranking.

Un detalle que se pasa por alto con facilidad

En la parte inferior del panel Build hay un botón «Compilar» y, al lado, otro de «Generar».

Mucha gente pulsa «Compilar» y cree que ya terminó. En realidad «Compilar» solo genera el directorio de salida; el empaquetado final de código ocurre al pulsar «Generar», que crea game.js, game.json y demás archivos de entrada.

La primera vez que publiqué, compilé e importé el proyecto en las herramientas de desarrollo de WeChat. Error: archivo de entrada no encontrado. Causa: no había pulsado «Generar». Está en la documentación oficial, pero es fácil pasarlo por alto.

Análisis de la salida de compilación y lista de errores típicos

Tras compilar, mira la carpeta build en la raíz del proyecto.

Dentro habrá un directorio wechatgame: la salida para la plataforma de minijuegos de WeChat. Al abrirlo verás archivos y carpetas; algunos los genera Cocos, otros son configuración propia de WeChat. Repasemos su función.

Interpretación de archivos de configuración clave

game.js: punto de entrada del motor.

Al cargar el juego, la plataforma de minijuegos de WeChat ejecuta primero este archivo. Contiene la inicialización del motor Cocos y la lógica de carga de escenas. No hace falta editarlo a mano, pero si la compilación falla, revisa si hay errores de sintaxis.

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

game.json: configuración global.

{
    "deviceOrientation": "portrait",
    "networkTimeout": {
        "request": 60000,
        "connectSocket": 60000,
        "uploadFile": 60000,
        "downloadFile": 60000
    },
    "enginePlugins": [
        "cocos"
    ],
    "optimization": {
        "render": true,
        "fps": true
    }
}

Campos clave:

• deviceOrientation: orientación de pantalla; portrait vertical, landscape horizontal
• networkTimeout: tiempo de espera de peticiones de red, en milisegundos
• enginePlugins: plugins del motor; con separación activada aparece "cocos"
• optimization: opciones de rendimiento; render y fps activos por defecto

project.config.json: configuración del proyecto en las herramientas de desarrollo de WeChat.

{
    "miniprogramRoot": "./",
    "setting": {
        "urlCheck": false,
        "es6": true,
        "postcss": true,
        "minified": true
    },
    "compileType": "game",
    "libVersion": "2.25.0",
    "appid": "wx1234567890abcdef",
    "projectname": "my-game"
}

Aquí hay una trampa: el campo libVersion.

Lista de errores típicos: cinco problemas frecuentes

Trampa 1: libVersion inválido

Síntoma: las herramientas de desarrollo de WeChat muestran error de versión de biblioteca base inválida.

Causa: el libVersion generado automáticamente por Cocos puede no ser una versión que WeChat soporte actualmente. Por ejemplo, la salida es "2.25.0" pero en las herramientas solo aparecen "2.20.3" o "latest".

Solución: edita manualmente project.config.json y cambia libVersion a "widelyUsed" o "latest".

{
    "libVersion": "widelyUsed"
}

widelyUsed es la versión estable recomendada por WeChat, con mejor compatibilidad. latest es la más reciente, con más funciones pero posibles sorpresas. Empieza con widelyUsed y prueba latest cuando todo esté estable.

Trampa 2: self is not defined

Síntoma: la compilación termina bien, pero en dispositivo real aparece self is not defined.

Causa: el proyecto usa la librería socket.io. El entorno de minijuegos de WeChat no tiene el objeto global window.self y algunas versiones de socket.io intentan acceder a él.

Solución: usar socket.io v1.4.4.

npm install [email protected] --save

v1.4.4 es la última versión estable compatible con minijuegos de WeChat. Versiones superiores refactorizaron mucho código pero introdujeron dependencia de self. Si necesitas una versión más alta, parchea el código fuente y sustituye self por window o global.

Trampa 3: error JSON por referencia circular

Síntoma: error en compilación indicando referencia circular en algún JSON.

Causa: algún objeto global se serializó incorrectamente. Por ejemplo, window.global guarda un objeto complejo y Cocos intenta convertirlo a JSON, detectando una referencia circular interna.

Solución: revisa la inicialización de window.global.

// Incorrecto: el objeto global se referencia a sí mismo
window.global = {
    self: window.global  // referencia circular
};

// Correcto: evitar auto-referencia
window.global = {
    config: {},
    gameState: {}
};

Elimina estas referencias circulares antes de compilar. Si debes guardar objetos complejos, usa JSON.stringify y JSON.parse manualmente, omitiendo las partes circulares.

Trampa 4: MiniGameCenter desaparece tras separar el motor

Síntoma: con separación del motor activada, la compilación termina bien pero en las herramientas de desarrollo de WeChat no aparecen funciones de MiniGameCenter.

Causa: MiniGameCenter es un componente de servicio de minijuegos de WeChat que depende del código del motor. Con el motor separado, parte de sus funciones deja de estar disponible.

Solución: desactiva temporalmente la separación del motor.

Si necesitas MiniGameCenter completo (pruebas de anuncios, compras in-app), desactiva la separación y empaqueta el motor en el paquete inicial. Cuando las funciones estén probadas, antes del lanzamiento oficial valora si activar la separación.

Trampa 5: fallo de compilación en iOS

Síntoma: al compilar para iOS aparece error de dependencia o recurso no encontrado.

Causa: el flujo de iOS es más complejo que el de minijuegos de WeChat. Revisa:

• Versión de Xcode (recomendado Xcode 12+)
• Rutas de dependencias (Podfile o Carthage)
• Recursos completos (imágenes, audio)

Solución:

1. Abre Xcode, revisa el log de compilación y localiza el error concreto
2. Confirma que las versiones del Podfile coinciden con las instaladas localmente
3. Limpia la caché: rm -rf build/ios y recompila

Los problemas de iOS son variados y hay que analizarlos caso por caso. En la mayoría, limpiar caché y recompilar basta.

Límites de tamaño del paquete: cómo controlarlos

Los minijuegos de WeChat tienen dos límites:

• Paquete principal: 4 MB
• Paquete total: 20 MB (principal + subpaquetes)

¿Qué hacer si se superan?

Opción 1: recursos remotos

Coloca la mayoría de imágenes y audio en un servidor remoto; el paquete principal solo lleva código y recursos pequeños imprescindibles. assetManager de Cocos permite cargar desde URL remota:

assetManager.loadRemote('https://your-server.com/assets/hero.png', (err, texture) => {
    if (err) {
        console.error('Error al cargar el recurso', err);
        return;
    }
    // Usar el recurso cargado
});

Inconveniente: la primera carga tarda y la experiencia se retrasa. Deja en el paquete principal lo más usado y mueve lo demás a remoto.

Opción 2: carga por subpaquetes

WeChat admite subpaquetes. Divide el juego en módulos; cada uno es un subpaquete que se carga al entrar en la escena correspondiente.

// Configurar subpaquetes en game.json
{
    "subpackages": [
        {
            "name": "level-1",
            "root": "subpackages/level-1"
        },
        {
            "name": "level-2",
            "root": "subpackages/level-2"
        }
    ]
}

La carga por subpaquetes requiere configurar además el flujo de compilación de Cocos. Los pasos detallados están en el capítulo «Compilación por subpaquetes» de la documentación oficial.

Depuración práctica con las herramientas de desarrollo de WeChat

Compilación lista: toca abrir las herramientas de desarrollo de WeChat.

Muchos fallan aquí: pulsan «Nuevo proyecto» y eligen un directorio incorrecto. Lo correcto es «Importar proyecto» y seleccionar build/wechatgame generado por Cocos.

Tras importar verás la pantalla de configuración. Ajustes clave:

Versión de biblioteca base

En la esquina superior derecha, botón «Detalles» → pestaña «Configuración local».

Ahí está el desplegable «Biblioteca base de depuración». Elige widelyUsed o latest, igual que al editar project.config.json. Si eliges una versión inexistente, la herramienta fallará.

No verificar dominios legales

En pruebas, el dominio del servidor de recursos puede no estar registrado aún en la plataforma pública de WeChat. Marca «No verificar dominios legales, web-view (dominios de negocio), versión TLS ni certificados HTTPS».

Así no se bloquean peticiones a dominios no registrados. Antes del lanzamiento oficial, añade el dominio a la lista blanca; si no, los jugadores no podrán cargar recursos remotos.

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Flujo de depuración en dispositivo real

Pulsa «Depuración en dispositivo real» en la barra de herramientas.

Desde la versión v1.05+, las herramientas ofrecen depuración en dispositivo real v2. Respecto a la versión anterior:

1. Vista previa por código QR más estable
2. Depuración remota integrada con Chrome DevTools
3. Puntos de interrupción y monitorización de rendimiento sincronizados

Flujo:

1. Pulsa «Depuración en dispositivo real» y genera un código QR
2. Abre WeChat en el móvil y escanea para entrar en modo depuración
3. A la derecha aparece el panel de depuración, similar a Chrome DevTools

Funciones habituales del panel:

• Console: logs en tiempo real de console.log
• Sources: código fuente con puntos de interrupción
• Network: peticiones de red y carga de recursos
• Memory: análisis de memoria y fugas

La depuración en dispositivo real es más fiel que el emulador. El rendimiento en simulador y en gama baja Android difiere mucho. Conviene probar varias veces en distintos dispositivos.

Herramientas de monitorización de rendimiento: cómo usarlas

Las herramientas de desarrollo de WeChat incluyen un conjunto completo de monitorización.

Pulsa «Caja de herramientas de I+D» (barra derecha) para abrir el panel de diagnóstico. Funciones principales:

Monitorización de rendimiento en dispositivo real

Tras escanear el código QR, el juego corre en el móvil y la herramienta muestra FPS, memoria y CPU en tiempo real.

Los datos aparecen en gráficos. Puedes ver de un vistazo:

• Si el FPS es estable (60 FPS es el ideal; por debajo de 30 se nota el tirón)
• Si la memoria crece sin parar (posible fuga)
• Si la CPU supera el 50 % (carga de cálculo alta)

Análisis de renderizado de primera pantalla

En «Renderizado de primera pantalla», la herramienta registra el tiempo desde el arranque hasta que la primera pantalla se muestra por completo.

Es un dato crítico. Más de 3 segundos de espera aumenta claramente la tasa de abandono. Si superas ese umbral, optimiza:

• Menos recursos en la primera pantalla
• Imágenes de menor tamaño
• Carga diferida de lo no imprescindible

Análisis de rendimiento de carga

La herramienta lista el tiempo de carga de cada recurso. Identificas cuál es el más lento y actúas en consecuencia.

Por ejemplo, un PNG de 2 MB que tarda 500 ms:

• Convertir a WebP (30-50 % menos volumen)
• Comprimir resolución
• Precargar en caché

Análisis de rendimiento en ejecución

Registra cuellos de botella durante la partida.

Si al cambiar de escena el FPS cae de golpe, la herramienta señala la causa: animación con mucho cálculo, script que tarda demasiado, etc.

Modo de alto rendimiento: optimización específica para iOS

En dispositivos iOS, los minijuegos de WeChat tienen un «modo de alto rendimiento».

Al activarlo, el juego corre en un proceso independiente, no compartido con el cliente de WeChat. Ventaja: CPU y memoria más aislados; mejora de rendimiento notable.

Datos oficiales: en iPhone 11 Pro Max, el demo Acuario pasó de 13 a 49 FPS. Una mejora considerable.

Cómo activarlo

1. Inicia sesión en la plataforma pública de WeChat
2. Entra en la página de gestión de «Paquete de eficiencia de producción»
3. Activa el servicio de modo de alto rendimiento en iOS

Tras activarlo, añade en game.json:

{
    "iOSHighPerformance": true
}

Atención a los límites de memoria

El modo de alto rendimiento impone límites adicionales:

• Dispositivos con 2 GB de RAM (iPhone 8, iPhone 7): límite 1 GB
• Dispositivos con 3 GB de RAM (iPhone 11, iPhone 12): límite 1,4 GB

Superarlos dispara avisos de memoria e incluso cierres inesperados. Si el juego tiene muchos recursos, controla el pico de memoria.

Recomendación práctica:

• Con el modo activado, el FPS sube mucho pero también el uso de memoria
• En gama baja (iPhone 8), mantén recursos por debajo de 800 MB
• En gama alta (iPhone 12), puedes llegar a 1,2 GB

Tras activar el modo, ejecuta monitorización en dispositivo real y confirma que FPS y memoria están en rango seguro.

Interpretación de las políticas de minijuegos de WeChat en 2026

Juego publicado: toca operación e ingresos.

En 2026, WeChat lanzó nuevas políticas de incentivos para desarrolladores. Resumen de las cláusulas principales.

Nuevos incentivos para monetización IAP (compras in-app)

Si el juego monetiza con compras in-app, el periodo de lanzamiento trae incentivos extra.

Proporción de incentivo: 100 %+

Desglose:

• Reparto base: 70 % (desarrollador 70 %, plataforma WeChat 30 %)
• Incentivo de lanzamiento: 40 % adicional

En total, en el periodo de lanzamiento el desarrollador recibe 70 % + 40 % = 110 %. Sí, un 10 % por encima de los ingresos brutos.

La ventana cubre los primeros 10 millones de ingresos del lanzamiento de un juego nuevo. Por encima de ese umbral, vuelve al 70 % base.

Tope de incentivos: 4 millones de yuanes (primer semestre de 2026)

Por juego, máximo 4 millones en el periodo de lanzamiento. Si los ingresos superan 10 millones, el incentivo se calcula proporcionalmente: 10 millones × 40 % = 4 millones, justo el tope.

Incentivo de crecimiento en lanzamiento: 5 % en efectivo extra cada 200 millones de ingresos

Se suma al incentivo de lanzamiento. Ejemplo: 6 millones de ingresos en lanzamiento:

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

• Reparto base: 6 M × 70 % = 4,2 M
• Incentivo de lanzamiento: 6 M × 40 % = 2,4 M (sin superar el tope de 4 M)
• Incentivo de crecimiento: 6 M ÷ 200 M = 3 tramos de 5 %, total 6 M × 15 % = 0,9 M

Total: 4,2 + 2,4 + 0,9 = 7,5 millones

Sin políticas de incentivo, 6 millones de ingresos darían 4,2 millones. Con incentivos, 3,3 millones más.

Nuevos incentivos para monetización IAA (publicidad)

Si monetizas con anuncios (IAA), también hay incentivos.

Juegos IAA ligeros: 40 % de incentivo sobre ingresos de los primeros 30 días

Juegos ligeros: casual, puzzle, match-3, etc. Mucho volumen de usuarios, baja disposición a pagar; encajan bien con anuncios.

Cálculo: ingresos publicitarios de los primeros 30 días × 40 % como incentivo.

Juegos IAA de intensidad media-alta: 35 % sobre los primeros 90 días

Juegos de acción, RPG, estrategia, etc. Menos usuarios, pero sesiones más largas y más impresiones publicitarias.

Cálculo: ingresos publicitarios de los primeros 90 días × 35 %.

Estrategia para maximizar ingresos

Cláusulas claras: ¿cómo sacar el máximo partido?

Planificación del momento de lanzamiento

El periodo de incentivo de lanzamiento cubre solo los primeros 10 millones de ingresos. Si el juego tiene mucho potencial, lanza en periodos de alta actividad (vacaciones escolares, festivos) para acumular ingresos rápido dentro de la ventana.

Ejemplo:

• Lanzamiento en periodo normal: 5 millones en ventana de incentivo, 2 millones de incentivo
• Lanzamiento en vacaciones de invierno: 10 millones en ventana, 4 millones de incentivo (tope)

El doble.

Control del ritmo de ingresos

Los incentivos son proporcionales a los ingresos. Si el crecimiento es demasiado rápido, el periodo de incentivo termina pronto. Puedes promocionar por fases:

1. Lanzamiento: promoción pequeña, prueba de feedback
2. Dentro del periodo de incentivo: promoción amplia, pico de ingresos
3. Tras el periodo: operación estable, control de costos

Así maximizas ingresos en la ventana sin disparar costos de promoción.

Elección del modelo de monetización

¿Compras in-app o anuncios?

• Juego simple, mucho volumen: anuncios; incentivo IAA ligero 40 %
• Juego complejo, usuarios dispuestos a pagar: compras in-app; incentivo de lanzamiento 110 %

Algunos juegos combinan ambos. WeChat admite monetización mixta; los incentivos se calculan por separado.

Lista de requisitos para la revisión

Antes de publicar, prepara:

• Registro de software: certificado de derechos de autor del código
• Registro ICP: si el juego usa servidor remoto de recursos
• Licencia de publicación: número de publicación de juegos en red; obligatorio para publicación formal (los minijuegos pueden empezar en «periodo de prueba» y completar la licencia después)
• Política de privacidad: mostrarla al arrancar; el usuario debe aceptar antes de entrar
• Protección de menores: verificación de identidad, límite de tiempo de juego, tope de recargas

Plazos habituales:

• Registro de software: 1-2 meses
• Registro ICP: 1-2 semanas
• Licencia de publicación: 3-6 meses (la más larga)
• Funciones anti-adicción: 1-2 semanas de desarrollo, integración con APIs oficiales de WeChat

Conviene planificar con antelación. La licencia tarda más; puedes iniciar el trámite durante el desarrollo.

La información proviene de la documentación oficial de políticas de incentivos 2026 en la comunidad de WeChat. Las cláusulas pueden cambiar; antes de publicar confirma la versión más reciente en la plataforma pública de WeChat.

Para cerrar

Publicar minijuegos de WeChat con Cocos Creator no es un proceso corto, pero cada paso tiene su lógica.

Parámetros del panel Build: AppID obligatorio, conversión de URL con MD5 Cache activado, requisitos de separación del motor, diferencia entre compilar y generar.

Directorio de salida: game.js, game.json, project.config.json, cada uno con su función. Los cinco problemas de la lista — libVersion inválido, self no definido, referencias circulares, desaparición de MiniGameCenter, fallo en iOS — tienen solución concreta.

Depuración con las herramientas de desarrollo de WeChat: importar proyecto, biblioteca base, depuración en dispositivo real, monitorización de rendimiento. El modo de alto rendimiento en iOS sube mucho el FPS, pero vigila los límites de memoria.

Políticas 2026: 110 % en lanzamiento IAP, tope de incentivos 4 millones, IAA 35-40 %. Si planificas bien el momento de lanzamiento, el ritmo de ingresos y el modelo de monetización, los ingresos pueden duplicarse.

Si vas a publicar, sigue este orden:

1. Revisa la configuración del Build, parámetro por parámetro
2. Tras compilar, pasa la lista de errores típicos
3. Depura varias rondas en dispositivo real; monitoriza FPS y memoria
4. Antes de publicar, reúne los requisitos y planifica el lanzamiento para maximizar incentivos

La plataforma de minijuegos de WeChat evoluciona rápido en políticas y detalles técnicos. Este artículo se basa en documentación oficial y experiencia del primer semestre de 2026; conviene reconfirmar si hay actualizaciones. El flujo de compilación y los métodos de depuración, en cambio, son bastante estables.

Si tienes dudas, comenta abajo.