Plugin del motor de minijuegos de WeChat: guía completa de configuración y trampas comunes

Tu minijuego está listo, compilas y miras el tamaño del paquete: 5,2 M.

Lo subes al panel de WeChat y te lo devuelven al momento: el paquete principal no puede superar 4 M.

Borras recursos, comprimes texturas, recortas audio… tras un buen rato lo dejas en 3,9 M y por fin puedes subirlo. Pero los jugadores tardan varios segundos en abrir el juego; algunos se van directamente.

La raíz del problema: el código del motor ocupa mucho espacio.

El plugin del motor de minijuegos de WeChat es una función añadida en WeChat v7.0.7 que separa el código del motor y lo cachea por separado. Si un jugador ya abrió otro juego con el plugin activado, al abrir el tuyo no tiene que volver a descargar el motor: el arranque puede ser entre 0,5 y 2 segundos más rápido.

La configuración no es complicada, pero hay varias trampas. En este artículo recopilo el flujo completo y las soluciones para que no pierdas tiempo probando a ciegas.

Qué es el plugin del motor y por qué acelera el arranque

Primero conviene entender cómo funciona el plugin del motor; así verás por qué sirve.

En el modo normal, cada minijuego descarga el código completo del motor. Si desarrollas con Cocos Creator, al abrir tu juego el jugador descarga todo el motor de Cocos — unos 1~2 M.

A partir de WeChat v7.0.7, el motor puede cachearse como plugin por separado. Eso implica:

El primer jugador que abre tu juego: descarga el motor completo + el código del juego; el motor se guarda en caché en el cliente de WeChat.

El segundo jugador que abre tu juego: si ya tiene en caché la misma versión del motor, lo reutiliza sin volver a descargarlo.

Un jugador abre otro juego del mismo motor: si ese juego también usa el plugin del motor y la versión coincide, el código del motor se reutiliza directamente.

Imagina que alguien acaba de jugar al juego A (Cocos 2.2.0) y ahora abre tu juego B (también 2.2.0). El motor ya está en caché: se reutiliza y el tiempo de arranque pasa de 4 segundos a 2, o incluso menos.

¿Y si la versión del motor es distinta? Por ejemplo, el jugador tiene v2.2.0 en caché y tu juego usa v2.2.1. WeChat descarga solo las diferencias, no todo el paquete. En pruebas reales, la actualización incremental suele reducir más del 50 % de la descarga.

Los datos oficiales hablan de entre 0,5 y 2 segundos más rápido. Puede sonar poco, pero los datos de abandono duelen: un juego que tarda 4 segundos en arrancar tiene un 60 % más de probabilidad de perder jugadores que uno que arranca en 1 segundo. Cada segundo cuenta.

Hoy soportan el plugin del motor tres motores: Cocos Creator, Egret y LayaAir. Este artículo se centra en Cocos Creator; los demás funcionan igual en principio, con pequeñas diferencias en la configuración.

Cómo activar el plugin del motor (flujo completo)

A partir de Cocos Creator 2.2.1, la función del plugin del motor ya viene integrada. Configurarlo es más sencillo de lo que parece: el editor hace la mayor parte del trabajo.

Paso 1: Marcar «Separar motor» en el panel de compilación

Abre Cocos Creator, ve a Proyecto → Compilar y publicar, o pulsa el botón Compilar en la parte superior del editor.

En el panel de compilación, busca la plataforma de minijuegos de WeChat y marca «Separar motor». Según la versión del editor, el nombre puede variar — «Usar plugin del motor» o «Permitir separar motor» — pero la función es la misma.

Dos requisitos importantes:

1. Debes usar el motor integrado del editor, no un motor personalizado. Los motores personalizados no soportan el modo plugin.
2. No compiles en modo depuración. En depuración, el código del motor se empaqueta completo y no se separa.

Pulsa Compilar. Al terminar, verás tres archivos nuevos en el directorio de salida:

• game.json: configuración del juego, con el campo plugins añadido
• plugin.json: configuración del plugin, con el punto de entrada
• signature.json: firma de verificación de los archivos del plugin

El editor los genera automáticamente; no hace falta editarlos a mano.

Paso 2: Abrir el proyecto en las herramientas de desarrollo de WeChat

Abre el directorio de salida de la compilación (normalmente build/wechatgame) con las herramientas de desarrollo de WeChat.

Aquí hay una trampa: el appid debe ser el tuyo, no el id de prueba genérico que trae el editor por defecto.

¿Por qué? El plugin del motor necesita verificar permisos; el id de prueba genérico no los pasa y el plugin deja de funcionar.

En las herramientas de desarrollo, haz clic en Detalles en la esquina superior derecha y escribe tu appid en Configuración local. Si aún no tienes appid, regístrate en la plataforma de WeChat como cuenta de minijuego; tras la revisión lo obtienes.

Paso 3: Verificar en dispositivo real

En las herramientas de desarrollo, pulsa Vista previa para generar el código QR y escanéalo con el móvil.

Abre el panel de depuración (vConsole). Verás un log parecido a este:

plugin ***** inject success!

Si aparece inject success, el plugin del motor se cargó bien. Si ves inject fail, hay un problema — en el siguiente capítulo detallo las trampas y soluciones.

Lista de requisitos de versión

Antes de configurar, confirma que cumples estos requisitos:

Elemento	Versión requerida	Notas
Cliente WeChat	>= 7.0.7	Por debajo no soporta el plugin del motor
Herramientas de desarrollo WeChat	>= 1.02.1911181	La versión RC basta
Biblioteca base	>= 2.9.0	Configúrala en las herramientas de desarrollo
Cocos Creator	>= 2.2.1	Versiones antiguas no soportan el plugin

Si las versiones no alcanzan, el plugin del motor no se activa, pero el juego sigue funcionando: solo que el código del motor se empaqueta completo en el paquete principal.

Datos reales de mejora de rendimiento

La teoría no basta; veamos números concretos.

Misma versión del motor: reutilización total

Supón que en el móvil del jugador ya está en caché el motor Cocos Creator v2.2.0. Tu juego usa la misma versión y tiene activado el plugin del motor.

Al abrir tu juego:

• Modo normal: descarga motor 1,5 M + código del juego 2,5 M = 4 M total, arranque ~4 s
• Modo plugin: reutiliza el motor, solo descarga código del juego 2,5 M, arranque ~2 s

Es el caso ideal: no hace falta descargar el motor.

Versiones distintas del motor: actualización incremental

Si tu juego usa v2.2.1 y el jugador tiene v2.2.0 en caché, la situación cambia un poco.

WeChat compara las dos versiones y descarga solo lo que cambió. En actualizaciones menores la diferencia suele ser pequeña; la descarga incremental ronda el 10 %~30 % del paquete completo.

Ejemplo:

• Modo normal: descarga motor 1,5 M (v2.2.1 completo)
• Modo plugin: descarga incremental 0,150,45 M, ahorro de más del 70 %

Caso real de optimización del paquete

Un proyecto casual de carrera con datos de prueba bastante representativos:

Antes de optimizar:

• Paquete total 6,8 M (supera el límite, no se puede subir)
• Texturas 3,06 M (45 %)
• Audio 1,7 M (25 %)
• Fuentes 1,02 M (15 %)
• Código del motor 0,68 M (10 %)
• Otros 0,34 M (5 %)

Tras activar el plugin del motor + optimizar recursos:

• Paquete total 3,2 M (subida sin problemas)
• Tiempo de carga inicial de 5 s a 3 s, un 40 % más rápido

Este caso muestra que el plugin del motor es solo una parte. Para superar de verdad el límite de 4 M hace falta combinar compresión de recursos y recorte de código — lo veremos más adelante.

Resumen comparativo de velocidad de arranque

Escenario	Modo normal	Modo plugin	Efecto
Primer arranque, misma versión del motor	Descarga motor completo	Reutiliza motor en caché	Entre 0,5 y 2 s más rápido
Arranque con versión distinta del motor	Descarga completa 1,5 M	Descarga incremental 0,15~0,45 M	Reduce ~70 % la descarga
WeChat antiguo (7.0.6)	Funciona con normalidad	Plugin inactivo	Requiere compatibilidad

Fuente: documentación oficial de Cocos + casos de prueba en CSDN. Cada proyecto varía, pero la tendencia es clara: el plugin del motor reduce mucho la descarga y acelera el arranque.

5 trampas habituales y cómo resolverlas

La configuración parece simple, pero en la práctica surgen problemas. Resumo las 5 trampas más comunes, cada una con solución concreta.

Trampa 1: Usar el id de prueba genérico impide probar

Síntomas:

Tras compilar, abres el proyecto en las herramientas de desarrollo y pulsas Vista previa. El juego corre en el móvil, pero el panel de depuración muestra:

plugin ***** inject fail!

O directamente no hay logs del plugin del motor.

Causa:

El panel de compilación de Cocos Creator suele traer un appid de prueba genérico (algo como wx1234567890abcdef). Ese id sirve solo para depuración local y no tiene permisos formales de minijuego. El plugin del motor exige verificación de permisos; el id genérico no la pasa.

Pasos para resolverlo:

1. Entra en la plataforma de WeChat y confirma que tu appid tiene permisos de minijuego (no de miniprograma)
2. En las herramientas de desarrollo, Detalles → Configuración local
3. Escribe tu appid
4. Borrar caché → Borrar todo, y vuelve a compilar y previsualizar

Cómo verificar:

Tras la vista previa, el panel de depuración debe mostrar plugin ***** inject success!.

Trampa 2: «Plugin no autorizado, añade el plugin»

Síntomas:

En vista previa en dispositivo real, el juego no arranca y aparece:

插件未授权使用，请添加插件

Causa:

El plugin aún no está añadido a tu proyecto de minijuego. WeChat exige que autorices el plugin de forma explícita.

Pasos para resolverlo:

1. Pulsa «Añadir plugin» en el cuadro de aviso
2. En la lista, busca el plugin CocosCreator y añádelo
3. Vuelve a compilar el juego
4. Si dice que no hay plugins disponibles, borra toda la caché en las herramientas de desarrollo e inténtalo otra vez

Cómo verificar:

Tras añadirlo, el juego arranca y el panel de depuración confirma la inyección del plugin.

Trampa 3: «Error al descomprimir el paquete» o «El usuario no es desarrollador»

Síntomas:

Al previsualizar o subir aparece:

代码包解包失败，请检查代码包

O:

登录用户不是该小程序的开发者

Causa:

Appid mal configurado, o la cuenta de WeChat con la que iniciaste sesión no tiene permisos de desarrollador en ese minijuego.

Pasos para resolverlo:

1. Confirma que el appid es correcto (no el id de prueba genérico)
2. En la plataforma de WeChat, comprueba que tu cuenta tiene permisos de desarrollador
3. Si no los tiene, pide al administrador que te añada
4. Vuelve a iniciar sesión en las herramientas de desarrollo con una cuenta autorizada

Cómo verificar:

La vista previa en dispositivo real funciona sin errores.

Trampa 4: WeChat antiguo no arranca bien

Síntomas:

Configuras el plugin, las pruebas en dispositivo van bien, pero tras publicar algunos usuarios no pueden abrir el juego o tarda muchísimo.

Causa:

WeChat anterior a 7.0.7 no soporta el plugin del motor. Esos usuarios descargan el motor completo. Si tu paquete principal ya rozaba 4 M, sumar el motor entero puede superar el límite y bloquear el arranque.

Pasos para resolverlo:

Dos enfoques:

Opción A: Mantener el motor completo (compatible con versiones antiguas)

En el panel de compilación, no marques «Separar motor». El código del motor va entero al paquete principal y todas las versiones de WeChat pueden jugar. El coste es un paquete principal más grande; compensa con optimización de recursos.

Opción B: Pedir actualizar WeChat

Al arrancar, detecta la versión de WeChat; si es inferior a 7.0.7, muestra: «Actualiza WeChat a la última versión para la mejor experiencia». Tras actualizar, el plugin del motor se activa.

La mayoría elige la opción A: la compatibilidad pesa más.

Cómo verificar:

Prueba en un móvil con WeChat 7.0.6 o inferior. Si el juego arranca, la compatibilidad está bien.

Trampa 5: Motor personalizado incompatible con el plugin

Síntomas:

Usas un motor personalizado en Cocos Creator (modificaste el código fuente del motor). Marcas «Separar motor» y la compilación falla, o compila pero el plugin no funciona.

Causa:

El plugin del motor solo admite la versión oficial integrada de Cocos Creator. Un motor personalizado no puede entrar en la biblioteca pública de plugins de WeChat.

Pasos para resolverlo:

Dos enfoques:

Opción A: Volver al motor integrado

Si tus cambios al motor son pocos, mueve esa lógica al código del juego, deja el motor personalizado y usa motor integrado + plugin del motor.

Opción B: Renunciar al plugin del motor

Si necesitas el motor personalizado tal cual, olvídate del plugin. Empaqueta el motor completo en el paquete principal y controla el tamaño con optimización de recursos.

Cómo verificar:

Revisa si en el panel de compilación está marcado «Usar motor personalizado». Si lo está, el plugin del motor no se activará.

Plugin del motor y optimización del paquete en conjunto

Tras los cuatro capítulos anteriores, quizá pienses: ¿activar el plugin reduce el paquete 1~2 M de golpe?

Hay un matiz importante: aunque el código del motor se separe, sigue contando para el tamaño del paquete principal.

La regla de WeChat es: límite de 4 M para el paquete principal, 30 M en total. Con el plugin del motor, el código del motor no cuenta en la «descarga real», pero sí en el «tamaño declarado del paquete principal». Si el paquete principal más el motor supera 4 M, pueden rechazarlo igual.

Por eso el plugin del motor es solo el primer paso de la cadena. Para superar de verdad 4 M hace falta combinar otras optimizaciones.

Análisis de la composición del paquete

Mira la composición típica de un minijuego:

Tipo	Proporción	Descripción
Texturas	45 %	PNG, atlas
Audio	25 %	WAV, MP3, OGG
Fuentes	15 %	TTF
Código del motor	10 %	Motor Cocos Creator
Otros	5 %	Configuración, JSON

Las texturas pesan más; ahí conviene centrarse. El motor es solo el 10 %, pero al separarlo con el plugin otros juegos se benefician de la caché.

Cadena completa de optimización

Para pasar de más de 6 M a menos de 3 M, conviene hacer estas cuatro cosas de forma sistemática:

Paso 1: Separar el motor (ya explicado)

Activa el plugin del motor para no descargar el motor completo cada vez. Es el paso más simple: marcar una casilla.

Paso 2: Optimizar texturas

Las texturas son el 45 % del paquete; el impacto es el mayor.

• Comprime PNG con TinyPNG (web o CLI)
• Al generar atlas con TexturePacker, usa RGBA4444 (el volumen baja ~50 %)
• Marca «Permitir rotación» para mejorar el uso del atlas ~15 %

Un paquete de texturas de 2 M puede quedar en 1 M.

Paso 3: Reducir audio

El audio es el 25 %; muchos usan WAV — pesado y innecesario.

• Música de fondo: WAV a OGG Vorbis Q5 (calidad suficiente, ~70 % menos volumen)
• Efectos: MP3 a 96 kbps (~65 % menos volumen)

1,7 M de audio pueden bajar a 0,5 M.

Paso 4: Recortar código

En Cocos Creator hay módulos del motor que quizá no uses.

• Juego 2D: quita módulos 3D
• Juego offline: quita módulos de red
• Puzzle simple: quita motor de física
• En depuración deja estadísticas; en publicación, quítalas

En el panel de compilación, en «Recorte de módulos del motor», marca solo lo que necesitas; lo demás se elimina.

Efecto conjunto en la práctica

Volviendo al proyecto casual de carrera:

Optimización	Antes	Después	Reducción
Texturas	3,06 M	1,02 M	2,04 M
Audio	1,7 M	0,5 M	1,2 M
Código del motor	0,68 M	Plugin separado	Reutiliza caché
Fuentes	1,02 M	0,34 M (subconjunto)	0,68 M
Paquete total	6,8 M	3,2 M	53 % menos

La carga inicial pasa de 5 s a 3 s, un 40 % más rápida.

Lo bueno de este enfoque: cada optimización funciona por separado. Puedes empezar por el plugin del motor (lo más fácil), medir, luego texturas (el mayor impacto) e ir paso a paso.

Cada proyecto es distinto: unos tienen más texturas, otros más audio. Analiza la composición del paquete en el panel de compilación y optimiza donde más pese.

Conclusión

El plugin del motor es el primer paso — y el más sencillo — para optimizar el arranque de minijuegos de WeChat: marcas la opción y no tocas código.

Pero solo con el plugin no basta. Si tu paquete principal ya rozaba 4 M y sumas el motor completo, los usuarios con WeChat antiguo pueden no poder abrir el juego.

Lo que de verdad funciona:

1. Activa el plugin del motor para mejorar la experiencia en WeChat reciente
2. Analiza la composición del paquete: texturas, audio, fuentes
3. Optimiza en consecuencia: texturas RGBA4444, audio a OGG/MP3, subconjuntos de fuentes
4. Prueba en WeChat 7.0.6 e inferiores en dispositivo real
5. Compara datos antes y después; no te fíes solo de la intuición

Con esa cadena, pasar de 6,8 M a 3,2 M y acelerar el arranque un 40 % es alcanzable. Los jugadores esperan menos y la tasa de abandono baja.

Yo me peleé con estas trampas y perdí tiempo explorando. Dejo el flujo completo aquí para que te ahorres trabajo. Si tienes dudas, comenta y intentaré responder.