Mahjong Sweet Shop: Guía del comprador

Mahjong Sweet Shop es un juego de rompecabezas HTML5 de emparejar fichas con temática de pastelería. Toca las fichas libres para enviarlas a una bandeja de 7 huecos: tres iguales desaparecen. 60 niveles en 4 tiendas, una gatita pastelera que reacciona a cada jugada, tutorial guiado, 14 idiomas, sin anuncios y sin servicios en línea. Esta guía muestra el juego con capturas reales y explica cómo instalarlo, jugarlo, cambiarlo y publicarlo.

Descripción general

• 60 niveles en 4 tiendas : Dulcería (niveles 1 a 15), Heladería (16 a 30), Panadería (31 a 45) y Chocolatería (46 a 60). Cada tienda tiene su mapa, su escenario en los niveles y 12 imágenes de fichas (48 en total).
• Una gatita pastelera saluda en el mapa, señala en el tutorial, salta cuando ganas y se sienta triste cuando la bandeja se llena.
• Ayudas de Deshacer, Pista y Mezclar , monedas, 1 a 3 estrellas por nivel, mapa de niveles de cada tienda, pétalos de sakura cayendo, transiciones animadas, efectos de sonido y música con volúmenes separados.
• Tutorial guiado en el nivel 1, 14 idiomas , vertical y horizontal en móviles, tabletas y ordenadores, incluidos monitores ultrapanorámicos.
• HTML, CSS y módulos JavaScript simples: sin dependencias, sin compilación, sin anuncios, sin cuenta y sin ranking en línea . El progreso se guarda en el navegador.

Galería de capturas

Capturas reales de esta edición del comprador (1280x720 en el navegador del ordenador y en un móvil en vertical). Abre una imagen para verla en tamaño real.

Móvil (vertical)

Instalación

1. Extrae el ZIP. Abre DOCUMENTATION.html (esta guía) y CUSTOMIZATION.html (cambios paso a paso para quien no programa, en inglés).
2. Sube solo el contenido de la carpeta game/ a cualquier alojamiento web estático por HTTP o HTTPS (hosting compartido, servidor propio, Netlify, GitHub Pages...), manteniendo las carpetas junto a index.html . Por FTP, abre la carpeta game y envía todo lo que hay dentro.
3. Abre la dirección en un navegador. No hace falta base de datos, PHP, cuenta ni Node.js para jugar.
4. No subas source/ , la documentación ni el ZIP completo a la dirección pública del juego.
5. Abrir game/index.html directamente desde el disco (file://) no funciona en la mayoría de los navegadores, porque el juego usa módulos JavaScript. Usa un servidor web o npm run serve de la sección Desarrollo.

Navegadores, dispositivos y sonido

Funciona en todos los navegadores actuales, en ordenador y móvil: Chrome, Edge, Firefox, Safari (macOS, iPhone, iPad), Opera, Brave, Samsung Internet . 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() .

Funcionan ratón y táctil. La primera pantalla dice "Toca para empezar": ese primer toque desbloquea el sonido en el móvil. Efectos y música tienen volúmenes separados en Ajustes; la vibración se puede apagar (Android vibra; iPhone da un toque leve en iOS 18+).

Esta edición se probó automáticamente en Chromium (el motor de Chrome y Edge) en tamaños de móvil y ordenador, jugando niveles completos; el motor del juego también se probó en Firefox y WebKit (Safari). Como con cualquier juego web, prueba en los dispositivos que quieras cubrir antes de publicar.

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 y dan monedas.
• Si la bandeja se llena ( 7 fichas ) sin tres iguales, pierdes el nivel. En esa ventana puedes Deshacer la última ficha o Reiniciar .
• Deshacer devuelve la última ficha, Pista muestra tres fichas que combinan, Mezclar reordena las fichas restantes. Cada nivel tiene 3 deshacer, 3 pistas y 2 mezclas.
• Estrellas: 3 sin ayudas, 2 con 1 o 2 ayudas, 1 con más. Desde el nivel 7 algunas fichas de abajo están boca abajo hasta que salen las de encima.
• El nivel 1 es un tutorial guiado: toca la ficha que brilla y sigue a la gatita. Tras cada victoria el mapa abre el siguiente nivel; los niveles completados se pueden repetir.

Guía de la interfaz (pantallas numeradas)

Cada número de la captura está en la lista de abajo, con el archivo que lo cambia. Más detalles en la guía de personalización.

Menú

1 2 3 4 5

Mapa de niveles de la Dulcería

1 2 3 4 5 6

Nivel 1 con el tutorial guiado

1 2 3 4 5 6 7 8 9 10

Ajustes (volúmenes, idioma, vibración)

1 2 3 4 5

Archivos y dónde cambiar cada cosa

El paquete tiene tres partes principales:

game/                       ready-to-host game: upload THESE CONTENTS
source/                     editable project (plain JavaScript, no dependencies)
  index.html                the page; loads the 4 style files and src/main.js
  css/01-base.css .. 04-theme.css   layered styles (a later file overrides an earlier one)
  src/main.js               entry point
  src/app/                  screens and systems, one small file per subject
  src/game/rules.js         rules of the tray and the tiles
  src/game/levels.js        the 60 levels (tile counts, shapes, how many tile types)
  src/config.js             shops and tile names, helpers, coins, feel numbers, save key
  src/i18n.js               interface texts, 14 languages
  src/render/tiles.js       tiles and tray drawn on the canvas
  src/audio/sfx.js          sound effects and music
  assets/sweet-shop/        artwork of this game (backgrounds, maps, cat, tiles, logo, ribbons, buttons)
  assets/ui/                interface icons and frames
  assets/sfx/, assets/music/, assets/fonts/   sounds, music, Fredoka font
  test/                     rule and language tests
  tools/serve.mjs, build.mjs   local server and the copy-to-game script
documentation/              this guide (index.html, pt.html, es.html), customization.html and img/
DOCUMENTATION.html          opens this guide
CUSTOMIZATION.html          opens the customization guide
THIRD-PARTY-LICENSES/       font license

Las recetas paso a paso (imágenes, gatita, fichas, sonidos, textos, colores, fuente, dificultad, monedas) están en la guía de personalización: CUSTOMIZATION.html

Nombres internos

El motor de este juego se comparte con otros juegos del mismo estudio, así que algunos nombres de archivos y del código están en portugués o vienen del motor. Se mantuvieron a propósito (cambiarlos no cambia el juego). La tabla dice qué es cada uno.

Idiomas

La interfaz del juego tiene 14 idiomas : inglés, portugués, español, francés, alemán, italiano, neerlandés, polaco, ruso, turco, japonés, coreano, chino e indonesio. 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 cambiar un texto o añadir un idioma, edita src/i18n.js y ejecuta npm test : la prueba de idiomas comprueba que todos los idiomas tengan todos los textos. Esta guía está en inglés, portugués de Brasil y español (enlaces arriba).

Progreso guardado

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

mahjong-sweet-shop.template.save.v1:

El progreso pertenece a ese navegador y a esa dirección. Otro navegador, el modo privado, borrar los datos del sitio o mover el juego a otro dominio empieza desde el nivel 1. Si alojas dos copias del juego en el mismo dominio y quieres progreso separado, cambia STORAGE_PREFIX en src/config.js en una de ellas.

Desarrollo con Node.js (opcional)

El juego listo en game/ no necesita nada más. El proyecto editable está en source/ : módulos JavaScript y CSS 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 con tu gestor de paquetes en Linux; debe ser 26.13 o posterior. 2) Cierra y abre el terminal y escribe node -v para comprobarlo. 3) Abre un terminal dentro de la carpeta source (en Windows: abre la carpeta, haz clic en la barra de direcciones, escribe cmd y pulsa Enter). 4) Ejecuta los comandos de abajo uno por uno.

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

npm ci no instala nada (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 ; después sube el contenido de game/ .

Problemas comunes: "node no se reconoce" significa que Node.js no está instalado o no se reabrió el terminal; "EBADENGINE" significa Node.js anterior a 26.13; en PowerShell de Windows, si la política de ejecución bloquea npm , usa cmd o ejecuta npm.cmd .

Actualización y caché

• Tras subir una versión nueva, el navegador puede seguir mostrando los archivos antiguos. Recarga con Ctrl+F5 (Windows) o Cmd+Shift+R (Mac). En el móvil, cierra la pestaña y abre la dirección otra vez.
• Si sigue antiguo: borra solo las imágenes y archivos en caché del navegador (no "cookies y datos del sitio", que borrarían el progreso), o abre una ventana privada para comprobarlo.
• Si tu alojamiento o una CDN (por ejemplo Cloudflare) tiene su propia caché, púrgala tras subir. Añadir ?v=2 a la dirección (por ejemplo https://tu-sitio.com/juego/?v=2 ) ayuda a ver si llegaron los archivos nuevos.
• Sube todos los archivos cambiados juntos y mantén la misma dirección, para que los jugadores conserven su progreso.

Licencias

El código del juego, el arte, los sonidos y la música se entregan bajo la licencia del artículo comprado. La fuente Fredoka usa la SIL Open Font License 1.1: el aviso está en THIRD-PARTY-LICENSES/ y junto a los archivos de la fuente en assets/fonts/ . El proyecto no tiene dependencias de ejecución ni de desarrollo.

Solución de problemas

• Página en blanco: comprueba que se subieron todas las carpetas de game/ y que la dirección usa http(s). Abre la consola del navegador (F12): una línea roja 404 indica el archivo que falta.
• Sin sonido: toca la pantalla una vez (el navegador solo permite sonido tras un toque), revisa los volúmenes en Ajustes y el interruptor de silencio del móvil.
• Se reinició el progreso: cambió la dirección (con o sin www, http o https, otra carpeta), se borraron los datos del sitio o está activo el modo privado.
• Error de módulo JavaScript (tipo MIME): el servidor debe enviar .js como text/javascript . La mayoría lo hace; en un servidor antiguo, añade AddType text/javascript .js al .htaccess .
• Una imagen cambiada no aparece: borra la caché (sección anterior) y revisa el nombre y la carpeta del archivo.

Soporte

Para dudas, problemas o cambios a medida, escribe a willian@polargames.com.br . Envía la versión del producto (1.0.0), navegador y dispositivo, la dirección del juego, los pasos para reproducirlo y una captura.