Lucky Clover 1.0.0: guia do comprador

Jogo HTML5 de slot em simulação, com créditos fictícios gratuitos. Código-fonte editável incluído.

Guia de personalização (receitas)

EnglishPortuguêsEspañol

Visão geral

Lucky Clover é um jogo de simulação de slot em HTML5: 5 rolos, 3 fileiras e 20 linhas fixas, com um tema irlandês de boa sorte: um duende alegre, trevos de quatro folhas, potes de ouro, harpas douradas e ferraduras. Ele vem pronto para hospedar (game/) e com o código-fonte completo e editável (source/). Funciona em qualquer navegador atual, em celulares, tablets e computadores, na vertical e na horizontal, sem servidor, banco de dados ou conta.

Recursos: WILD nos rolos 2 a 4, rodadas grátis por SCATTER com multiplicador crescente, o bônus Locked Coins com os jackpots MINI, MINOR, MAJOR e GRAND, o botão BUY BONUS, comemorações de ganhos big, mega e epic, giro automático e turbo, níveis do jogador, roleta diária e moedas grátis periódicas, 14 idiomas na interface, voz de locutor gravada e música.

Apenas simulação. O jogador recebe créditos de demonstração gratuitos e fictícios. Eles não têm valor monetário e não podem ser comprados, transferidos, vendidos nem resgatados. Não há depósitos, saques, prêmios nem recompensas de valor econômico. O preço é de uma licença de software, não de participação em jogo de azar. A licença não permite o uso em jogo de azar com dinheiro real ou com qualquer outra coisa de valor real. Leia o SCOPE.md (na raiz do pacote e dentro de game/): ele faz parte dos termos da licença.

A tela do jogo (1280×720) depois de um prêmio de linha.
A tela do jogo (1280×720) depois de um prêmio de linha.

Instalar no seu site

O jogo pronto para jogar é a pasta game/. É HTML, CSS e JavaScript puros: não precisa de build, de Node.js nem de banco de dados para hospedá-lo.

  1. Abra o gerenciador de arquivos da sua hospedagem ou conecte-se com um programa de FTP (por exemplo, o FileZilla).
  2. Crie uma pasta para o jogo, por exemplo /games/lucky-clover/.
  3. Envie o conteúdo de game/ para ela: index.html, lucky-clover.config.js, SCOPE.md, DOCUMENTATION.txt e as pastas art/, audio/, assets/ e modules/.
  4. Abra o endereço no navegador, por exemplo https://your-site.example/games/lucky-clover/.

O jogo usa caminhos relativos, então funciona em qualquer pasta ou subdomínio. Abrir o index.html direto do seu disco (file://) não funciona, porque os navegadores bloqueiam módulos JavaScript nesse caso: teste numa hospedagem web ou com a prévia local descrita em "Editar o código-fonte".

Colocar dentro de uma página (iframe)

<iframe src="/games/lucky-clover/" style="width:100%;aspect-ratio:16/9;border:0" allow="fullscreen; autoplay"></iframe>

Deixe visível o aviso de créditos na tela e mantenha o SCOPE.md junto com o jogo quando publicá-lo para o público.

Requisitos

  • Qualquer hospedagem web estática, HTTP ou HTTPS (hospedagem compartilhada, uma CDN, GitHub Pages, Netlify...). Sem PHP, banco de dados ou código de servidor.
  • Um navegador atual: Chrome, Edge, Firefox, Safari (macOS e iOS), Samsung Internet ou Opera.
  • Só para editar o código-fonte: Node.js 26 LTS (a linha LTS atual) e npm, veja "Editar o código-fonte".
  • Não é preciso internet para jogar: arte, sons e código estão todos dentro de game/. O jogo não faz requisições a outros sites.

Como jogar e as telas

O jogador toca em TAP TO PLAY (tocar para jogar), escolhe a aposta com – e + (ou MAX BET, a aposta máxima) e toca no botão de girar. As combinações pagam da esquerda para a direita nas 20 linhas fixas. Todos os valores são créditos de demonstração fictícios.

A tela do jogo (1280×720) depois de um prêmio de linha. 1 2 3 4 5 6 7 8 9 10 11 12 13 14
A tela do jogo (1280×720) depois de um prêmio de linha.
  1. Saldo de créditos de demonstração (+ = recarga grátis quando acaba)
  2. Jackpots do bônus Locked Coins
  3. Nível do jogador
  4. Moedas grátis (a cada poucas horas)
  5. Menu: regras, som, tela cheia
  6. BUY BONUS (pago com créditos de demonstração)
  7. Rolos: 5 × 3, 20 linhas
  8. Aposta – / +
  9. MAX BET (aposta máxima)
  10. Ganho da rodada e a linha premiada
  11. Girar (Espaço ou Enter)
  12. Giro automático
  13. Turbo
  14. Aviso dos créditos (mantenha visível)
  • WILD (trevo de quatro folhas) aparece nos rolos 2, 3 e 4 e substitui todos os símbolos, exceto SCATTER e COIN.
  • SCATTER: 3, 4 ou 5 em qualquer posição pagam 2×, 10× ou 50× a aposta total e dão 8, 12 ou 20 rodadas grátis. Durante as rodadas grátis, os ganhos em linha são multiplicados: o multiplicador começa em ×2 e sobe 1 a cada giro com ganho em linha, até ×5. Mais scatters acrescentam giros (até 50 por bônus).
  • Locked Coins: 6 ou mais símbolos COIN ficam travados no lugar e dão 3 novos giros (respins); cada moeda nova também trava e volta os respins para 3. No fim, o valor de cada moeda é pago. As moedas MINI, MINOR e MAJOR pagam o jackpot delas; preencher as 15 posições soma o GRAND.
  • BUY BONUS inicia as rodadas grátis na hora, por um preço pago nos mesmos créditos de demonstração gratuitos. Não é uma compra.
  • Nenhuma rodada paga mais de 5.000× a aposta total.
A comemoração de um grande ganho (valores em créditos fictícios de demonstração).
A comemoração de um grande ganho (valores em créditos fictícios de demonstração).
Rodadas grátis: o cenário muda e o multiplicador aparece no canto superior direito dos rolos.
Rodadas grátis: o cenário muda e o multiplicador aparece no canto superior direito dos rolos.
Locked Coins: as moedas ficam presas; as três luzes mostram as rodadas extras restantes.
Locked Coins: as moedas ficam presas; as três luzes mostram as rodadas extras restantes.

Recompensas fora dos rolos

Os níveis (o botão redondo com o número) sobem conforme se joga e dão créditos grátis; apostas maiores são liberadas conforme os níveis sobem. A roleta diária dá créditos grátis uma vez por dia (na configuração de demonstração que vem no pacote, ela aparece em toda visita). O botão de presente dá moedas grátis a cada poucas horas. Quando os créditos acabam, é oferecida uma recarga grátis.

A roda diária (créditos de demonstração gratuitos). 1 2 3
A roda diária (créditos de demonstração gratuitos).
  1. A roda e seus prêmios em créditos de demonstração
  2. Girar a roda
  3. Depois

Menu, regras e opções

O botão de menu abre as regras (tabela de pagamentos, regras dos bônus, as 20 linhas) e as opções: música, efeitos sonoros, menos movimento e o idioma.

Regras: tabela de pagamentos, regras dos bônus, as 20 linhas e as opções. 1 2 3 4 5
Regras: tabela de pagamentos, regras dos bônus, as 20 linhas e as opções.
  1. Tabela de pagamentos da aposta atual
  2. Regras de WILD, SCATTER, rodadas grátis e Locked Coins
  3. As 20 linhas
  4. Opções: música, efeitos, menos movimento, idioma
  5. Fechar (Esc)
Opções em português, com os 14 idiomas.
Opções em português, com os 14 idiomas.
Celular em pé (390×844): o mesmo jogo, reorganizado. 1 2 3 4 5 6 7 8 9 10
Celular em pé (390×844): o mesmo jogo, reorganizado.
  1. Saldo de créditos de demonstração (+ = recarga grátis quando acaba)
  2. Jackpots do bônus Locked Coins
  3. Menu: regras, som, tela cheia
  4. Rolos: 5 × 3, 20 linhas
  5. Aposta – / +
  6. Ganho da rodada e a linha premiada
  7. Girar (Espaço ou Enter)
  8. Giro automático
  9. Turbo
  10. BUY BONUS (pago com créditos de demonstração)

Teclado

Espaço ou Enter gira. As setas mudam a aposta, M liga e desliga o som, T liga e desliga o turbo e Escape fecha o menu ou um painel aberto.

O que vem no pacote

lucky-clover-static-1.0.0/
  START-HERE.txt          first steps
  DOCUMENTATION.html      opens this guide
  CUSTOMIZATION.html      opens the customization guide (recipes, no coding)
  CHANGELOG.txt
  SCOPE.md                what the product is and what the licence does not allow
  documentation/          this guide and the customization guide (EN/PT/ES), screenshots
  game/                   UPLOAD THE CONTENTS OF THIS FOLDER
    index.html            the page
    lucky-clover.config.js  your settings (edit on the host, no rebuild)
    modules/              the JavaScript, one readable file per source module
    assets/ui/            the stylesheets
    art/                  images (WebP)
    audio/                sounds, voice and music (MP3)
    SCOPE.md, DOCUMENTATION.txt
  source/                 the complete editable project
    index.html            the page (development version)
    src/main.js           start-up, spins, celebrations, bonuses, menus
    src/config.js         defaults, events, save key
    src/logic/            math.js (symbols, pays, reels, RTP profiles), engine.js, progress.js
    src/ui/               reels, effects, wheel, sheets, theme.js, styles-1..3.css, i18n.css
    src/locales/          the 14 languages (en.js is the reference)
    src/audio/audio.js    the list of sounds, music and voices
    public/               art/, audio/, lucky-clover.config.js (copied to the build as they are)
    tests/                npm test
    tools/                RTP simulator, translation check, seed finder, in-page checks, build formatter
    package.json, package-lock.json, vite.config.js, .prettierrc, README.md
    licenses/             licences of the development tools
  THIRD-PARTY-LICENSES/   the same licence texts

game/ é exatamente o que o npm run build gera a partir de source/ (conferido arquivo por arquivo antes de empacotar). Edite source/ e gere o build de novo, ou edite só o lucky-clover.config.js na hospedagem.

Configurações (lucky-clover.config.js)

O game/lucky-clover.config.js é lido toda vez que o jogo abre, então você pode mudar estas configurações na sua hospedagem com um editor de texto, sem refazer o build. Todos os campos são opcionais: tire o // da frente de uma linha para usá-la. Um valor errado interrompe o jogo com uma mensagem dizendo o que corrigir.

window.LUCKY_CLOVER_CONFIG = {
  brand: { name: 'Lucky Clover', storageKey: 'mysite.lucky-clover' },
  language: 'auto',
  languages: ['en', 'pt', 'es'],
  texts: { tapToPlay: 'PLAY NOW', de: { tapToPlay: 'LOS!' } },
  audio: { volume: 0.8, muted: false },
  ageGate: true,
  notice: true,
  showRtp: true,
  math: { profile: 'standard', startBalance: 1000000, bets: [200, 400, 1000, 2000, 4000, 10000, 20000], maxWin: 5000 },
  progress: { wheel: { alwaysReady: false, everyHours: 24 }, coins: { everyHours: 3, amount: 50 } },
  winTiers: { big: 10, mega: 25, epic: 50 },
};
Opção O que faz
brand.name nome do jogo usado na página e nas mensagens
brand.storageKey prefixo dos dados salvos no navegador (padrão lucky-clover.template.save.v1); mude-o para começar com dados salvos novos
language 'auto' = o idioma do aparelho (inglês quando ele não é oferecido), ou um código: en pt es fr de it nl pl tr ru id ja ko zh. A escolha do jogador em OPTIONS e ?lang=xx no endereço têm prioridade
languages os idiomas oferecidos em OPTIONS (padrão: todos os 14). Com um só idioma, o seletor some
texts substitui qualquer texto de src/locales/en.js em todos os idiomas, ou em um só (texts: { pt: {...} })
audio volume inicial (0 a 1) e se começa sem som
ageGate true mostra o selo 18+ e o aviso de cassino social
notice o aviso de créditos de uma linha embaixo dos controles. Deixe ligado: o SCOPE.md exige isso em publicações para o público
showRtp mostra o RTP do perfil ativo no painel de regras
debug só para testes: permite ?seed=123 no endereço (as mesmas rodadas toda vez) em qualquer hospedagem
math profile ('generous' cerca de 97% de RTP, 'standard' cerca de 95%, 'house' cerca de 92,5%), startBalance, bets (múltiplos de 20), maxWin, jackpots, buyBonus: false para tirar o botão BUY BONUS. Rode npm run rtp depois de mudar
progress níveis (levels.enabled, need, reward, unlock), a roleta diária (enabled, alwaysReady, everyHours, prizes, weights) e as moedas grátis (enabled, everyHours, amount). Os valores são múltiplos da menor aposta
winTiers a partir de quantas vezes a aposta total começam as comemorações big, mega e epic
integration, callbacks eventos para a sua própria página, veja "Eventos"

O arquivo do pacote lista cada opção com um comentário. Os valores padrão completos estão em source/src/config.js, source/src/logic/math.js e source/src/logic/progress.js.

Idiomas

A interface está traduzida para 14 idiomas: inglês, português, espanhol, francês, alemão, italiano, holandês, polonês, turco, russo, indonésio, japonês, coreano e chinês (simplificado). A voz do locutor e os títulos pintados (BIG WIN, FREE SPINS...) são em inglês em todos os idiomas. O jogo abre no idioma do aparelho; o jogador pode mudar em OPTIONS, e ?lang=pt no endereço força um idioma.

Os textos ficam em source/src/locales/<code>.js, um arquivo por idioma, com as mesmas chaves do en.js. Quando falta uma chave, o jogo usa o texto em inglês. Para mudar alguns textos sem refazer o build, use texts no lucky-clover.config.js. Depois de editar os arquivos de idioma, rode npm run locales para conferir se nenhuma tradução perdeu um marcador {value}.

Dados salvos

O jogo guarda o saldo, o nível, as configurações e os temporizadores das recompensas no localStorage do navegador, em chaves que começam com lucky-clover.template.save.v1. (por exemplo lucky-clover.template.save.v1.balance). Nada é enviado para lugar nenhum. Limpar os dados do site no navegador zera o jogo. Se você publicar duas cópias do jogo no mesmo domínio, dê a cada uma o seu próprio brand.storageKey.

Eventos para a sua página

O jogo envia eventos para que a sua página possa mostrar estatísticas, conquistas ou um ranking de pontuações fictícias. Eles não são uma interface de contabilidade ou de pagamento e não devem ser usados como tal.

  • callbacks no lucky-clover.config.js: onReady, onSpin(round), onWin(round), onBalance({ balance }), onBonus({ kind, amount, balance }), onError.
  • window.LuckyClover.on('spin', fn), window.LuckyClover.getBalance(), window.LuckyClover.version.
  • Eventos DOM em window: luckyclover:spin, luckyclover:win...
  • Com integration: { postMessage: true, targetOrigin: 'https://your-site.example' } o jogo também envia { source: 'lucky-clover', type, payload } para a página pai quando roda dentro de um iframe.

round.spent são os créditos de demonstração colocados numa rodada e round.payout, os créditos de demonstração que ela devolveu.

Editar o código-fonte (Node.js para iniciantes)

Você só precisa disto para mudar código, estilos, arte ou sons e gerar um novo game/. Para mudar configurações, edite o lucky-clover.config.js.

1. Instalar o Node.js

  1. Acesse https://nodejs.org e baixe a versão LTS (Node.js 26 LTS). Windows e macOS: rode o instalador com as opções padrão. Linux: use o gerenciador de pacotes ou os binários oficiais.
  2. Feche o terminal e abra de novo (Windows: PowerShell ou Prompt de Comando; macOS: Terminal).
  3. Confira as versões: os dois comandos precisam mostrar um número, e o Node precisa ser 26.13.0 ou mais novo.
node --version
npm --version

2. Instalar as ferramentas do projeto

Abra o terminal na pasta source/ (Windows: abra a pasta no Explorador de Arquivos, clique na barra de endereço, digite powershell e aperte Enter; macOS: arraste a pasta até o ícone do Terminal). Depois rode:

npm ci

Isso instala as versões exatas do package-lock.json (Vite e Prettier) em node_modules/. Precisa de internet uma vez.

3. Testar, ver a prévia e gerar o build

npm test
npm run dev
npm run build
  • npm test roda os testes do motor (pagamentos, bônus, créditos, níveis, roleta, RTP). Todos precisam passar.
  • npm run dev abre uma prévia local em http://localhost:5211/ que recarrega quando você salva um arquivo. Aperte Ctrl+C para parar.
  • npm run build grava o jogo pronto em source/dist/. Envie o conteúdo de dist/ para a sua hospedagem (ele substitui o game/). O build não é minificado e é formatado com o Prettier, então continua legível.

Outros comandos

  • npm run rtp mostra o RTP real da sua matemática (src/logic/math.js mais o math do public/lucky-clover.config.js). node tools/simulate.mjs buy mede novos preços para o BUY BONUS.
  • npm run locales confere as traduções.
  • node tools/find-seeds.mjs lista seeds que mostram um bônus no primeiro giro; abra http://localhost:5211/?seed=N para ver (as seeds funcionam no localhost ou com debug: true).
  • npm run format formata o projeto inteiro com o Prettier.

Problemas comuns

  • node ou npm não é reconhecido: o Node.js não está instalado ou o terminal foi aberto antes da instalação. Reinstale e abra um terminal novo.
  • O Windows diz que a execução de scripts está desabilitada (npm.ps1): use o Prompt de Comando ou rode npm.cmd ci.
  • ENOENT ... package.json: o terminal não está na pasta source/.
  • EBADENGINE: o seu Node.js é mais antigo que 26.13.0. Instale a LTS atual.
  • npm ci falha com erro de rede: confira a conexão ou o proxy da rede da sua empresa e rode de novo.
  • npm ci diz que o arquivo de lock está fora de sincronia: você mudou o package.json; rode npm install uma vez e o npm ci volta a funcionar.
  • A porta 5211 está ocupada: o Vite escolhe a próxima porta livre e mostra qual é.

Personalizar e trocar o visual

O guia de personalização (CUSTOMIZATION.html) tem receitas passo a passo para quem não programa: trocar símbolos, fundos, o logo, o mascote, sons e música, cores, textos, apostas e recompensas. Em resumo:

  • Arte: source/public/art/ (ou game/art/ na hospedagem). Troque um arquivo por outro WebP com o mesmo nome e o mesmo tamanho. s0.webp a s10.webp são os símbolos.
  • Sons: source/public/audio/ (ou game/audio/). Troque um MP3 por outro com o mesmo nome.
  • Cores do tema e efeitos: source/src/ui/theme.js (cor de destaque, faíscas, o fundo dos rolos, os raios de luz das comemorações, como cada símbolo se mexe quando paga). Só aparência: nada ali muda um resultado.
  • Layout e estilos: source/src/ui/styles-1.css a styles-3.css (variáveis da paleta no topo do styles-1.css).
  • Textos: texts no lucky-clover.config.js ou source/src/locales/.
  • Matemática: source/src/logic/math.js ou math no lucky-clover.config.js, depois npm run rtp.

Mudanças em source/ precisam de npm run build. Mudanças em arquivos de game/ na hospedagem (arte, áudio, lucky-clover.config.js) não precisam de build.

Nomes internos

O motor é compartilhado com outros temas, então alguns nomes no código descrevem a arte para a qual foram feitos primeiro. São só nomes:

wild-hammer.webp, wild-banner.webp, bolt-0..3.webp, reels.wild.hammer the three painted layers of the WILD symbol (the clover, its WILD ribbon and the glitter trail); the shared engine calls the top layer "hammer"
frost.webp, fx.frost(), reels.freeze(), "ice", "shards" the veil of light that falls over the reels when Locked Coins starts, and the burst when a coin locks; comments of the shared engine describe it as ice
fx.snow, THEME.ambient the ambient particles (here: fireflies rising, THEME.ambient.rise = true)
.bg-aurora, "aurora" the light layer over the background that comes down on the biggest wins, and the swirl inside the SCATTER ring
.entry-hoard the three floating symbols on the title screen
CreditBank, round.spent, round.payout the fictional demo credits: credits put into and won by one round (no money)

Atualizar o jogo e limpar o cache

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

  • Recarregue sem o cache: Ctrl+F5 ou Ctrl+Shift+R (Windows/Linux), Cmd+Shift+R (macOS). No celular, feche a aba e abra de novo.
  • Limpe os arquivos em cache do site nas configurações do navegador ("Imagens e arquivos armazenados em cache"). Não limpe "cookies e dados do site", a menos que queira zerar o jogo salvo.
  • Teste numa janela anônima (privada).
  • Se a sua hospedagem ou CDN (por exemplo, a Cloudflare) tiver cache, limpe esse cache (purge).
  • Acrescente uma versão ao endereço uma vez, por exemplo index.html?v=2.

Os dados salvos continuam depois de uma atualização, desde que o brand.storageKey não mude.

O que o produto é (e o que não é)

  • Só créditos de demonstração gratuitos e fictícios, sem valor monetário. Eles não podem ser comprados, transferidos, vendidos nem resgatados. Não há prêmios de nenhum tipo.
  • Não há sistema de pagamento, depósito, saque, conta ou carteira: nenhum está escondido, desligado ou incluído no pacote.
  • A licença padrão não permite usar este jogo, ou qualquer versão modificada dele, para jogo de azar com dinheiro real ou com qualquer coisa de valor real: nada de compra de créditos, nada de saque, nada de prêmios baseados em resultados, nenhuma conexão com carteira de jogo de azar, sistema de pagamento ou operador de dinheiro real, nenhuma publicidade de jogo de azar com dinheiro real.
  • Você deve seguir as leis de todos os lugares onde publicar o jogo (classificação etária, menores de idade, defesa do consumidor). Mantenha o aviso de créditos visível; ageGate: true acrescenta um aviso de 18+.
  • O suporte não cobre carteira, depósito, saque nem qualquer integração com dinheiro real; esses pedidos são recusados.

O texto completo está no SCOPE.md.

Perguntas e problemas

  • A página fica em branco. Confira se você enviou o conteúdo de game/ (com modules/ e assets/) e se está abrindo por http(s), não por file://. O console do navegador (F12) mostra o arquivo que falta.
  • Sem som. Os navegadores só liberam som depois de um toque: o jogo liga o som no TAP TO PLAY. Confira o menu (botão de som), OPTIONS (música, efeitos) e o volume do aparelho.
  • Posso mudar o RTP? Sim: math.profile escolhe um de três perfis medidos; a sua própria matemática é medida com npm run rtp.
  • Os jogadores podem comprar créditos ou ganhar prêmios? Não. O jogo não tem sistema de pagamento nem de prêmios, e a licença não permite acrescentar um.
  • Funciona offline? Depois de carregado, sim; não precisa de nenhum outro site.
  • Posso tirar o aviso de créditos? Numa publicação para o público ele precisa ficar visível (veja o SCOPE.md).
  • A roleta diária abre em toda visita. Essa é a configuração de demonstração alwaysReady: true; defina progress: { wheel: { alwaysReady: false } }.
  • Como testo um bônus? No localhost, use ?seed=N do node tools/find-seeds.mjs, ou defina debug: true durante os testes.

Suporte e créditos

E-mail de suporte: willian@polargames.com.br (bugs, instalação, layout nos navegadores suportados, traduções, personalização visual e de áudio e as configurações deste guia). Inclua o seu código de compra ou de licença, o navegador e o aparelho, e uma captura de tela.

Ferramentas de desenvolvimento: Vite e Prettier (licenças MIT em THIRD-PARTY-LICENSES/). Nenhum código de terceiros vai em game/. Arte, música, voz e efeitos fazem parte do jogo e estão cobertos pela licença da sua compra.