Mahjong Sweet Shop: Guia do comprador

Mahjong Sweet Shop é um jogo de quebra-cabeça HTML5 de combinar peças com tema de confeitaria. Toque nas peças livres para enviá-las a uma bandeja de 7 lugares: três iguais somem. 60 fases em 4 lojas, uma gatinha confeiteira que reage a cada jogada, tutorial guiado, 14 idiomas, sem anúncios e sem serviços online. Este guia mostra o jogo com capturas reais e explica como instalar, jogar, alterar e publicar.

Visão geral

• 60 fases em 4 lojas : Doceria (fases 1 a 15), Sorveteria (16 a 30), Padaria (31 a 45) e Chocolateria (46 a 60). Cada loja tem mapa próprio, cenário próprio nas fases e 12 figuras de peças (48 no total).
• Uma gatinha confeiteira acena no mapa, aponta no tutorial, pula quando você vence e senta triste quando a bandeja enche.
• Ajudas de Desfazer, Dica e Embaralhar , moedas, 1 a 3 estrelas por fase, mapa de fases de cada loja, pétalas de sakura caindo, transições animadas, efeitos sonoros e música com volumes separados.
• Tutorial guiado na fase 1, 14 idiomas , retrato e paisagem em celulares, tablets e computadores, inclusive monitores ultralargos.
• HTML, CSS e módulos JavaScript simples: sem dependências, sem compilação, sem anúncios, sem conta e sem ranking online . O progresso fica salvo no navegador.

Galeria de capturas

Capturas reais desta edição do comprador (1280x720 no navegador do computador e no celular em pé). Abra uma imagem para ver em tamanho real.

Celular (em pé)

Instalação

1. Extraia o ZIP. Abra DOCUMENTATION.html (este guia) e CUSTOMIZATION.html (mudanças passo a passo para quem não programa, em inglês).
2. Envie somente o conteúdo da pasta game/ para qualquer hospedagem estática em HTTP ou HTTPS (hospedagem compartilhada, servidor próprio, Netlify, GitHub Pages...), mantendo as pastas ao lado de index.html . Pelo FTP, abra a pasta game e envie tudo o que está dentro dela.
3. Abra o endereço no navegador. Não é preciso banco de dados, PHP, conta nem Node.js para jogar.
4. Não envie source/ , a documentação nem o ZIP completo para o endereço público do jogo.
5. Abrir game/index.html direto do disco (file://) não funciona na maioria dos navegadores, porque o jogo usa módulos JavaScript. Use um servidor web ou o npm run serve da seção de Desenvolvimento.

Navegadores, aparelhos e som

Funciona em todos os navegadores atuais, no computador e no celular: Chrome, Edge, Firefox, Safari (macOS, iPhone, iPad), Opera, Brave, Samsung Internet . Versões mínimas: navegadores baseados em Chromium 105+, Firefox 121+, Safari 16+ (iOS e iPadOS 16+). O jogo usa módulos ES, Canvas 2D, Web Audio, unidades de container query do CSS e o seletor :has() .

Mouse e toque funcionam. A primeira tela diz "Toque para começar": esse primeiro toque libera o som no celular. Efeitos e música têm volumes separados nos Ajustes; a vibração pode ser desligada (Android vibra; iPhone dá um toque leve no iOS 18+).

Esta edição foi testada automaticamente no Chromium (o motor do Chrome e do Edge) em tamanhos de celular e computador, jogando fases inteiras; o motor do jogo também foi testado no Firefox e no WebKit (Safari). Como em qualquer jogo web, teste nos aparelhos que você pretende atingir antes de publicar.

Como jogar

• Toque numa peça que não esteja coberta por outra. Ela voa para a bandeja embaixo.
• Três peças iguais na bandeja somem e dão moedas.
• Se a bandeja encher ( 7 peças ) sem três iguais, a fase é perdida. Nessa janela dá para Desfazer a última peça ou Recomeçar .
• Desfazer devolve a última peça, Dica mostra três peças que combinam, Embaralhar mistura as peças que sobraram. Cada fase tem 3 desfazer, 3 dicas e 2 embaralhar.
• Estrelas: 3 sem usar ajuda, 2 com 1 ou 2 ajudas, 1 com mais. A partir da fase 7, algumas peças de baixo ficam viradas até as de cima saírem.
• A fase 1 é um tutorial guiado: toque na peça que brilha e siga a gatinha. Depois de cada vitória o mapa abre a próxima fase; fases concluídas podem ser jogadas de novo.

Guia da interface (telas numeradas)

Cada número da captura está na lista abaixo dela, com o arquivo que o muda. Mais detalhes no guia de personalização.

Menu

1 2 3 4 5

Mapa de fases da Doceria

1 2 3 4 5 6

Fase 1 com o tutorial guiado

1 2 3 4 5 6 7 8 9 10

Ajustes (volumes, idioma, vibração)

1 2 3 4 5

Arquivos e onde mudar cada coisa

O pacote tem três partes principais:

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

As receitas passo a passo (imagens, gatinha, peças, sons, textos, cores, fonte, dificuldade, moedas) estão no guia de personalização: CUSTOMIZATION.html

Nomes internos

O motor deste jogo é compartilhado com outros jogos do mesmo estúdio, então alguns nomes de arquivos e do código estão em português ou vêm do motor. Foram mantidos de propósito (renomear não muda o jogo). A tabela diz o que é cada um.

Idiomas

A interface do jogo tem 14 idiomas : inglês, português, espanhol, francês, alemão, italiano, holandês, polonês, russo, turco, japonês, coreano, chinês e indonésio. O jogo começa no idioma do aparelho (inglês quando não está na lista) e o jogador troca nos Ajustes. Um link como ?lang=de abre o jogo num idioma. Para mudar um texto ou acrescentar um idioma, altere src/i18n.js e rode npm test : o teste de idiomas confere se todos os idiomas têm todos os textos. Este guia está em inglês, português do Brasil e espanhol (links no topo).

Progresso salvo

O progresso (fases liberadas, estrelas, moedas), os volumes, a vibração e o idioma ficam no navegador (localStorage), em chaves que começam com:

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

O progresso pertence àquele navegador e àquele endereço. Outro navegador, modo anônimo, limpar os dados do site ou mudar o jogo de domínio começa da fase 1. Se você hospedar duas cópias do jogo no mesmo domínio e quiser progresso separado, mude STORAGE_PREFIX em src/config.js numa delas.

Desenvolvimento com Node.js (opcional)

O jogo pronto em game/ não precisa de mais nada. O projeto editável está em source/ : módulos JavaScript e CSS simples, sem dependências e sem compilação . O Node.js 26.13 ou superior (a LTS atual) só serve para rodar os testes, abrir o jogo localmente e copiar os arquivos para game/ .

Nunca usou Node.js? 1) Instale a versão LTS em nodejs.org (instalador para Windows ou macOS) ou pelo gerenciador de pacotes no Linux; precisa ser 26.13 ou superior. 2) Feche e reabra o terminal e digite node -v para conferir. 3) Abra um terminal dentro da pasta source (no Windows: abra a pasta, clique na barra de endereço, digite cmd e tecle Enter). 4) Rode os comandos abaixo um de cada vez.

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 não instala nada (o projeto não tem dependências; só confere o arquivo de lock). npm test roda os testes de regras e de idiomas. npm run serve abre o jogo em http://localhost:8080/ (Ctrl+C para parar). npm run build copia index.html , css/ , src/ e assets/ para a pasta game ao lado de source ; depois envie o conteúdo de game/ .

Problemas comuns: "node não é reconhecido" quer dizer que o Node.js não está instalado ou o terminal não foi reaberto; "EBADENGINE" quer dizer Node.js anterior ao 26.13; no PowerShell do Windows, se o npm for bloqueado pela política de execução, use o cmd ou rode npm.cmd .

Atualização e limpeza de cache

• Depois de enviar uma versão nova, o navegador pode continuar mostrando os arquivos antigos. Recarregue com Ctrl+F5 (Windows) ou Cmd+Shift+R (Mac). No celular, feche a aba e abra o endereço de novo.
• Se continuar antigo: limpe só as imagens e arquivos em cache do navegador (não "cookies e dados do site", que apagariam o progresso), ou abra uma janela anônima para conferir.
• Se a hospedagem ou uma CDN (por exemplo a Cloudflare) tiver cache próprio, limpe esse cache depois do envio. Acrescentar ?v=2 ao endereço (por exemplo https://seu-site.com/jogo/?v=2 ) ajuda a ver se os arquivos novos chegaram.
• Envie todos os arquivos alterados juntos e mantenha o mesmo endereço, para os jogadores não perderem o progresso.

Licenças

O código do jogo, a arte, os sons e a música são fornecidos sob a licença do item comprado. A fonte Fredoka usa a SIL Open Font License 1.1: o aviso está em THIRD-PARTY-LICENSES/ e ao lado dos arquivos da fonte em assets/fonts/ . O projeto não tem dependências de execução nem de desenvolvimento.

Solução de problemas

• Página em branco: confira se todas as pastas de game/ foram enviadas e se o endereço usa http(s). Abra o console do navegador (F12): uma linha vermelha 404 diz qual arquivo falta.
• Sem som: toque na tela uma vez (o navegador só libera o som depois de um toque), confira os volumes nos Ajustes e a chave de silencioso do celular.
• Progresso zerou: o endereço mudou (com ou sem www, http ou https, outra pasta), os dados do site foram apagados ou o modo anônimo está ativo.
• Erro de módulo JavaScript (tipo MIME): o servidor precisa enviar .js como text/javascript . A maioria envia; num servidor antigo, acrescente AddType text/javascript .js ao .htaccess .
• Uma imagem trocada não aparece: limpe o cache (seção acima) e confira o nome do arquivo e a pasta.

Suporte

Para dúvidas, problemas ou mudanças sob medida, escreva para willian@polargames.com.br . Envie a versão do produto (1.0.0), navegador e aparelho, o endereço do jogo, os passos para reproduzir e uma captura de tela.