Mahjong Cosmic Quest: guía del comprador

Juego HTML5 de combinar fichas con tema espacial, versión 1.0.0

1. Resumen

Mahjong Cosmic Quest es un juego de combinar tríos de fichas con tema espacial. Toca las fichas libres para enviarlas a una bandeja de 7 huecos: tres fichas iguales desaparecen. Vacía el tablero para ganar.

60 niveles en 4 mundos: Nebula Landing, Starlight Ocean, Cosmic Garden y Golden Planet. Cada mundo tiene su fondo de juego, su mapa de niveles y 12 imágenes de fichas. Un simpático robot astronauta es la mascota (poses feliz, señalando, victoria y triste).

Ayudas de Deshacer, Pista y Mezclar, monedas y estrellas, tutorial guiado en el nivel 1, mapa de niveles de cada mundo, partículas de estrellas, transiciones animadas, efectos de sonido y música, Ajustes con volumen de efectos y música, idioma y vibración. 14 idiomas de interfaz. Diseños para móvil (vertical y horizontal), tableta, ordenador y pantallas ultraanchas.

Sin anuncios, sin cuenta, sin ranking en línea, sin rastreo y sin peticiones externas: el juego es HTML, CSS y JavaScript estáticos. El progreso se guarda en el navegador del jugador.

2. Instalar

Sube solo el contenido de la carpeta game/ a cualquier alojamiento web estático (se recomienda HTTPS), manteniendo carpetas y rutas. Abre la dirección en el navegador. El servidor no necesita base de datos, PHP ni Node.js.

No abras game/index.html con doble clic: los navegadores bloquean los módulos ES en direcciones file:// y la pantalla queda vacía. Para probar en tu ordenador usa npm run serve (ver Proyecto editable) o cualquier servidor web local.

No pongas source/, el ZIP descargado ni esta documentación en la dirección pública del juego.

Para mostrar el juego dentro de otra página, usa un iframe con la dirección del juego, por ejemplo <iframe src="https://tu-sitio.com/cosmic/" width="100%" height="640" allow="autoplay; fullscreen"></iframe>.

3. Requisitos

Funciona en todos los navegadores actuales, en ordenador y móvil: Chrome, Edge, Firefox, Safari (macOS, iPhone e iPad), Opera, Brave, Samsung Internet y otros navegadores modernos. Versiones mínimas: navegadores basados en Chromium 105+, Firefox 121+, Safari 16+ (iOS e iPadOS 16+). El juego usa módulos ES, Canvas 2D, Web Audio, unidades de container queries de CSS y el selector :has().

Los navegadores solo activan el sonido después del primer toque o clic; por eso el juego abre con la pantalla "Toca para empezar". La vibración solo funciona en dispositivos y navegadores que la admiten (la mayoría de los móviles Android).

4. Cómo jugar

• Toca una ficha que no esté cubierta por otra. Vuela a la bandeja de abajo.
• Tres fichas iguales en la bandeja desaparecen. Si la bandeja se llena con 7 fichas sin trío, el nivel se pierde: puedes deshacer la última ficha o reiniciar.
• Ayudas por nivel: Deshacer 3, Pista 3, Mezclar 2. La Pista hace brillar un trío; Mezclar reordena las fichas restantes (el nivel sigue teniendo solución).
• Estrellas: 3 sin usar ayudas, 2 con 1 o 2 ayudas, 1 con más. Monedas: +1 por trío y +10 por victoria.
• Cada nivel se genera con una semilla fija y se comprueba que tenga solución (las pruebas juegan los 60 niveles).

5. Pantallas

Pantallas numeradas. Los números corresponden a la lista bajo cada imagen.

1 2 3 4 5

1. Jugar: abre el mapa de niveles
2. Sonido: volumen de efectos y música
3. Ajustes: volúmenes, idioma, vibración
4. Logo del juego (assets/cosmic/logo.png)
5. Robot mascota (assets/cosmic/robo-feliz.png)

1 2 3 4 5

1. Un nivel: toca para jugar (los niveles bloqueados muestran un candado)
2. Mundo anterior (la flecha del siguiente mundo está a la derecha)
3. Sonido
4. Ajustes
5. Volver al menú

1 2 3 4 5 6 7 8 9 10

1. Número de nivel
2. Monedas
3. Sonido
4. Pausa (continuar, reiniciar, niveles, idioma, vibración)
5. Tablero: toca una ficha libre (no cubierta)
6. Bandeja: 7 huecos, tres fichas iguales desaparecen
7. Deshacer (3 por nivel)
8. Pista (3 por nivel)
9. Mezclar (2 por nivel)
10. Robot mascota: reacciona al juego

6. Galería

Capturas reales de esta edición (1280 x 720 y móvil vertical 390 x 844). Haz clic en una imagen para abrirla en tamaño completo.

7. Archivos

Qué incluye el paquete:

game/                         upload THE CONTENTS of this folder to your web host
  index.html                  the page
  css/  src/  assets/         same files as in source/ (made by npm run build)
source/                       the editable project (plain JavaScript, no dependencies)
  index.html                  loads the 4 style files in css/ and src/main.js
  css/01-base.css ... 04-overrides.css   layered styles: the LAST file that sets a rule wins
  src/main.js                 entry point
  src/app/                    screens and systems, one small file per subject
  src/game/rules.js           the rules (tray, trios, undo, hint, shuffle)
  src/game/levels.js          the 60 levels (number of tiles per level)
  src/config.js               worlds, tile names, helpers per level, coins, feel numbers
  src/i18n.js                 interface texts in 14 languages
  src/audio/sfx.js            which sound file plays for each event, music
  src/render/tiles.js         draws the tiles (reads the tile sheets)
  assets/cosmic/              space artwork: backgrounds, maps, robot, tiles, buttons, windows
  assets/ui/                  small interface images (glows, sparkles, helper badges)
  assets/sfx/  assets/music/  sounds and music (MP3)
  assets/fonts/               Fredoka font + its license
  test/                       rule and language tests (npm test)
  tools/serve.mjs             local web server (npm run serve)
  tools/build.mjs             copies the game files to ../game (npm run build)
documentation/index.html      this guide;  documentation/customization.html  step-by-step changes
DOCUMENTATION.html            opens this guide;  CUSTOMIZATION.html  opens the customization guide
THIRD-PARTY-LICENSES/         font license

8. Personalizar

Recetas paso a paso para quien no programa (cambiar fondos, robot, fichas, logo, sonidos, música, textos, colores, fuente, dificultad, ayudas y monedas), con el archivo exacto de cada parte de la pantalla: CUSTOMIZATION.html (también en la raíz del paquete; en inglés).

Mapa rápido: fondos y mapas de los mundos son PNG en assets/cosmic/; las imágenes de las fichas son las hojas assets/cosmic/tiles-0.png a tiles-3.png; números (ayudas, monedas) en src/config.js; tamaño de los niveles en src/game/levels.js; textos en src/i18n.js; sonidos en assets/sfx/ (elegidos en src/audio/sfx.js).

9. Nombres internos

Algunos nombres de archivos, funciones y clases están en portugués, el idioma del desarrollador original. Se conservan para que el código siga igual al juego probado. Esta tabla los explica:

10. Idiomas

La interfaz ofrece 14 idiomas: inglés, portugués, español, francés, alemán, italiano, neerlandés, polaco, ruso, turco, japonés, coreano, chino e indonesio. El juego empieza en el idioma del dispositivo (inglés si no está en la lista) y el jugador lo cambia en Ajustes. Un enlace como ?lang=de abre el juego en un idioma. Para añadir un idioma, agrega una tabla en src/i18n.js, su nombre en LANGS y ejecuta npm test: la prueba de idiomas comprueba que existan todas las claves. Esta guía está en inglés, portugués de Brasil y español.

11. Guardado

El progreso (niveles desbloqueados, estrellas, monedas), los volúmenes, la vibración y el idioma se guardan en el navegador con localStorage, en claves que empiezan por:

mahjong-cosmic-quest.template.save.v1:progress
mahjong-cosmic-quest.template.save.v1:vol-sfx  /  vol-music  /  vibe
mahjong-cosmic-quest.template.save.v1:lang

Cada navegador y cada dirección guardan su propio progreso. En una ventana privada el progreso se pierde al cerrarla. Para reiniciar el progreso, borra los datos del sitio de la dirección del juego en los ajustes del navegador. Si alojas dos copias del juego en el mismo dominio, cambia el prefijo STORAGE_PREFIX en src/config.js de una de ellas.

12. Proyecto editable

El juego listo para alojar no necesita Node.js. El proyecto editable en source/ usa módulos JavaScript simples, sin dependencias ni compilación. Node.js 26.13 o posterior (la LTS actual) solo sirve para ejecutar las pruebas, abrir el juego en local y copiar los archivos a game/.

¿Nuevo en Node.js? 1) Instala la versión LTS desde nodejs.org (instalador para Windows o macOS, o el gestor de paquetes en Linux); debe ser 26.13 o posterior. 2) Cierra y abre el terminal y escribe node -v para comprobar la versión. 3) Abre un terminal dentro de la carpeta source (Windows: abre la carpeta, haz clic en la barra de direcciones, escribe cmd y pulsa Enter; macOS: clic derecho en la carpeta, Nuevo Terminal en la Carpeta). 4) Ejecuta los comandos de abajo uno por uno.

cd source
npm ci
npm test
npm run serve
# open http://localhost:8080/
npm run build
# copies index.html, css/, src/ and assets/ to ../game

npm ci no instala nada porque el proyecto no tiene dependencias; solo comprueba el archivo de bloqueo. npm test ejecuta las pruebas de reglas e idiomas. npm run serve abre el juego en http://localhost:8080/ (Ctrl+C lo detiene). npm run build copia index.html, css/, src/ y assets/ a la carpeta game, junto a source, sobrescribiendo los archivos con el mismo nombre (borra tú en game/ lo que quitaste de source/).

• node no se reconoce / command not found: Node.js no está instalado o el terminal se abrió antes de instalarlo. Vuelve a abrir el terminal.
• npm.ps1 no se puede cargar (PowerShell de Windows): usa cmd en lugar de PowerShell, o ejecuta npm.cmd ci.
• EBADENGINE: tu Node.js es anterior a 26.13. Instala la LTS actual.
• ENOENT package.json: el terminal no está dentro de la carpeta source. Usa cd para entrar.
• npm ci falla detrás de un proxy: el proyecto no descarga nada, pero npm puede consultar el registro; configura el proxy (npm config set proxy ...) u omite npm ci, los demás comandos funcionan sin él.
• Puerto 8080 ocupado: ejecuta node tools/serve.mjs 8090 y abre http://localhost:8090/.

13. Actualizaciones y caché

Después de subir una versión nueva, los navegadores y las cachés del alojamiento pueden conservar los archivos antiguos un tiempo. Si un cambio no aparece:

• Fuerza la recarga: Ctrl+F5 (Windows/Linux) o Cmd+Shift+R (macOS).
• Borra las imágenes y archivos en caché del sitio en los ajustes del navegador. No borres "cookies y datos del sitio" si quieres conservar el progreso.
• Prueba en una ventana privada para ver la versión nueva sin caché.
• Si tu alojamiento o una CDN (por ejemplo Cloudflare) guarda caché, púrgala.
• Añade una versión a la dirección, por ejemplo index.html?v=2, para evitar copias antiguas de la página.

14. Licencias

El código, el arte, los sonidos y la música del juego se suministran bajo la licencia del artículo comprado.

Fuente Fredoka: SIL Open Font License 1.1, ver THIRD-PARTY-LICENSES/ (hay una copia en assets/fonts/). El proyecto no tiene otro código de terceros.

15. Problemas

• Pantalla vacía al abrir index.html desde la carpeta: usa un servidor web (ver Instalar).
• Sin sonido: toca la pantalla una vez (el navegador lo exige), revisa los volúmenes en Ajustes, el volumen del dispositivo y el modo silencio.
• El progreso desapareció: cambió la dirección del juego, el navegador o es una ventana privada (ver Guardado).
• El arte cambiado no aparece: borra la caché (ver Actualizaciones y caché) y comprueba que el nombre del archivo sea el mismo.
• El juego se ve pequeño o grande dentro de un sitio: da una altura fija al iframe o usa la dirección del juego directamente; el diseño se adapta al tamaño del marco.

16. Soporte

Dudas, problemas o desarrollo a medida (nuevos temas, niveles, funciones, versiones para tiendas): willian@polargames.com.br. Incluye tu código de compra, el navegador y el dispositivo, y una captura del problema.