Mahjong Cosmic Quest: guia do comprador

Jogo HTML5 de combinar peças com tema espacial, versão 1.0.0

1. Visão geral

Mahjong Cosmic Quest é um jogo de combinar trios de peças com tema espacial. Toque nas peças livres para enviá-las a uma bandeja de 7 lugares: três peças iguais somem. Limpe o tabuleiro para vencer.

60 fases em 4 mundos: Nebula Landing, Starlight Ocean, Cosmic Garden e Golden Planet. Cada mundo tem fundo de partida, mapa de fases e 12 figuras de peças próprios. Um robô astronauta simpático é o mascote (poses feliz, apontando, vitória e triste).

Ajudas de Desfazer, Dica e Embaralhar, moedas e estrelas, tutorial guiado na fase 1, mapa de fases de cada mundo, partículas de estrelas, transições animadas, efeitos sonoros e música, Ajustes com volume de efeitos e música, idioma e vibração. 14 idiomas de interface. Layouts para celular (em pé e deitado), tablet, computador e telas ultralargas.

Sem anúncios, sem conta, sem ranking online, sem rastreamento e sem requisições externas: o jogo é HTML, CSS e JavaScript estáticos. O progresso fica salvo no navegador do jogador.

2. Instalar

Envie somente o conteúdo da pasta game/ para qualquer hospedagem de site estático (HTTPS recomendado), mantendo pastas e caminhos. Abra o endereço no navegador. O servidor não precisa de banco de dados, PHP nem Node.js.

Não abra game/index.html com clique duplo: os navegadores bloqueiam módulos ES em endereços file:// e a tela fica vazia. Para testar no computador use npm run serve (veja Projeto editável) ou qualquer servidor web local.

Não coloque source/, o ZIP baixado nem esta documentação no endereço público do jogo.

Para mostrar o jogo dentro de outra página, use um iframe com o endereço do jogo, por exemplo <iframe src="https://seu-site.com/cosmic/" width="100%" height="640" allow="autoplay; fullscreen"></iframe>.

3. Requisitos

Funciona em todos os navegadores atuais, no computador e no celular: Chrome, Edge, Firefox, Safari (macOS, iPhone e iPad), Opera, Brave, Samsung Internet e outros navegadores modernos. 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().

Os navegadores só liberam o som depois do primeiro toque ou clique; por isso o jogo abre com a tela "Toque para começar". A vibração funciona só em aparelhos e navegadores que a suportam (a maioria dos celulares Android).

4. 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. Se a bandeja encher com 7 peças sem trio, a fase está perdida: dá para desfazer a última peça ou recomeçar.
• Ajudas por fase: Desfazer 3, Dica 3, Embaralhar 2. A Dica faz um trio brilhar; Embaralhar mistura as peças que sobraram (a fase continua com solução).
• Estrelas: 3 sem usar ajuda, 2 com 1 ou 2 ajudas, 1 com mais. Moedas: +1 por trio e +10 por vitória.
• Cada fase é gerada a partir de uma semente fixa e conferida para ter solução (os testes jogam as 60 fases).

5. Telas

Telas numeradas. Os números correspondem à lista abaixo de cada imagem.

1 2 3 4 5

1. Jogar: abre o mapa de fases
2. Som: volume dos efeitos e da música
3. Ajustes: volumes, idioma, vibração
4. Logo do jogo (assets/cosmic/logo.png)
5. Robô mascote (assets/cosmic/robo-feliz.png)

1 2 3 4 5

1. Uma fase: toque para jogar (fases bloqueadas mostram um cadeado)
2. Mundo anterior (a seta do próximo mundo fica à direita)
3. Som
4. Ajustes
5. Voltar ao menu

1 2 3 4 5 6 7 8 9 10

1. Número da fase
2. Moedas
3. Som
4. Pausa (continuar, recomeçar, fases, idioma, vibração)
5. Tabuleiro: toque numa peça livre (não coberta)
6. Bandeja: 7 lugares, três peças iguais somem
7. Desfazer (3 por fase)
8. Dica (3 por fase)
9. Embaralhar (2 por fase)
10. Robô mascote: reage ao jogo

6. Galeria

Capturas reais desta edição (1280 x 720 e celular em pé 390 x 844). Clique numa imagem para abrir em tamanho cheio.

7. Arquivos

O que vem no pacote:

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

Receitas passo a passo para quem não programa (trocar fundos, robô, peças, logo, sons, música, textos, cores, fonte, dificuldade, ajudas e moedas), com o arquivo exato de cada parte da tela: CUSTOMIZATION.html (também no topo do pacote; em inglês).

Mapa rápido: fundos e mapas dos mundos são PNG em assets/cosmic/; as figuras das peças são as cartelas assets/cosmic/tiles-0.png a tiles-3.png; números (ajudas, moedas) em src/config.js; tamanho das fases em src/game/levels.js; textos em src/i18n.js; sons em assets/sfx/ (escolhidos em src/audio/sfx.js).

9. Nomes internos

Alguns nomes de arquivos, funções e classes estão em português, o idioma do desenvolvedor original. Foram mantidos para o código continuar igual ao jogo testado. Esta tabela explica cada um:

10. Idiomas

A interface oferece 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 se não estiver na lista) e o jogador troca nos Ajustes. Um link como ?lang=de abre o jogo num idioma. Para acrescentar um idioma, adicione uma tabela em src/i18n.js, o nome em LANGS e rode npm test: o teste de idiomas confere se todas as chaves existem. Este guia está em inglês, português do Brasil e espanhol.

11. Saves

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

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 e cada endereço guardam o próprio progresso. Numa janela anônima o progresso some quando a janela fecha. Para zerar o progresso, apague os dados do site do endereço do jogo nas configurações do navegador. Se hospedar duas cópias do jogo no mesmo domínio, troque o prefixo STORAGE_PREFIX em src/config.js de uma delas.

12. Projeto editável

O jogo pronto para hospedar não precisa de Node.js. O projeto editável em source/ usa módulos JavaScript simples, sem dependências e sem compilaçã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 o gerenciador de pacotes no Linux); precisa ser 26.13 ou superior. 2) Feche e reabra o terminal e digite node -v para conferir a versão. 3) Abra um terminal dentro da pasta source (Windows: abra a pasta, clique na barra de endereço, digite cmd e tecle Enter; macOS: botão direito na pasta, Novo Terminal na Pasta). 4) Execute os comandos abaixo um de cada vez.

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 não instala nada porque o projeto não tem dependências; só confere o arquivo de lock. npm test roda os testes de regras e 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, sobrescrevendo arquivos de mesmo nome (apague você mesmo em game/ o que tirou de source/).

• node não é reconhecido / command not found: o Node.js não está instalado ou o terminal foi aberto antes da instalação. Reabra o terminal.
• npm.ps1 não pode ser carregado (PowerShell do Windows): use o cmd em vez do PowerShell, ou rode npm.cmd ci.
• EBADENGINE: seu Node.js é anterior ao 26.13. Instale a LTS atual.
• ENOENT package.json: o terminal não está dentro da pasta source. Use cd para entrar nela.
• npm ci falha atrás de proxy: o projeto não baixa nada, mas o npm pode consultar o registro; configure o proxy (npm config set proxy ...) ou pule o npm ci, os outros comandos funcionam sem ele.
• Porta 8080 ocupada: rode node tools/serve.mjs 8090 e abra http://localhost:8090/.

13. Atualizações e cache

Depois de enviar uma versão nova, navegadores e caches da hospedagem podem guardar os arquivos antigos por um tempo. Se a mudança não aparecer:

• Force a recarga: Ctrl+F5 (Windows/Linux) ou Cmd+Shift+R (macOS).
• Apague as imagens e arquivos em cache do site nas configurações do navegador. Não apague "cookies e dados do site" se quiser manter o progresso salvo.
• Teste numa janela anônima para ver a versão nova sem cache.
• Se a hospedagem ou uma CDN (por exemplo Cloudflare) guarda cache, limpe esse cache.
• Acrescente uma versão ao endereço, por exemplo index.html?v=2, para escapar de cópias antigas da página.

14. Licenças

O código, a arte, os sons e a música do jogo são fornecidos sob a licença do item comprado.

Fonte Fredoka: SIL Open Font License 1.1, veja THIRD-PARTY-LICENSES/ (há uma cópia em assets/fonts/). O projeto não tem outro código de terceiros.

15. Problemas

• Tela vazia ao abrir o index.html da pasta: use um servidor web (veja Instalar).
• Sem som: toque na tela uma vez (o navegador exige), confira os volumes nos Ajustes, o volume do aparelho e o modo silencioso.
• O progresso sumiu: mudou o endereço do jogo, o navegador ou é janela anônima (veja Saves).
• A arte trocada não aparece: limpe o cache (veja Atualizações e cache) e confira se o nome do arquivo é o mesmo de antes.
• O jogo fica pequeno ou grande dentro de um site: dê altura fixa ao iframe ou use o endereço do jogo direto; o layout se adapta ao tamanho do quadro.

16. Suporte

Dúvidas, problemas ou desenvolvimento sob medida (novos temas, fases, recursos, versões para lojas): willian@polargames.com.br. Mande o código de compra, o navegador e o aparelho, e uma captura do problema.