Onyx Club Blackjack 1.0.0: guia do comprador

Jogo HTML5 de simulação de blackjack com apostas paralelas e créditos fictícios gratuitos. Código-fonte editável incluído.

Guia de personalização (receitas)

EnglishPortuguêsEspañol

Visão geral

Onyx Club Blackjack é um jogo HTML5 de simulação de blackjack com apostas paralelas: um clube de jazz Art Déco dos anos 1920 à noite, com uma pantera negra de smoking marfim como crupiê. Vem como jogo pronto para hospedar (game/) e como projeto completo editável (source/). Roda em qualquer navegador atual, em celulares, tablets e computadores, em pé e deitado, sem servidor, banco de dados ou conta.

Recursos: blackjack clássico contra um crupiê animado (uma pantera negra de smoking marfim que dá as cartas, bate palmas, dá de ombros e acena), até 3 mãos ao mesmo tempo em telas largas, todas as jogadas (pedir, parar, dobrar, dividir até 4 mãos, desistir, seguro), duas apostas paralelas (Perfect Pairs e 21+3), a dica de estratégia básica, três mesas com limites e salão próprios, níveis do jogador que abrem as mesas, roleta diária de prêmios, moedas grátis por tempo, comemorações de vitória grande/mega/épica, estatísticas e conquistas, 14 idiomas, voz de locutor gravada e música.

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

Uma mão em jogo: as jogadas à direita e a dica de estratégia básica.
Uma mão em jogo: as jogadas à direita e a dica de estratégia básica.

Instalar no seu site

O jogo jogável é a pasta game/. É HTML, CSS e JavaScript puros: não precisa de build, Node.js nem banco de dados para hospedar.

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

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

Colocar dentro de uma página (iframe)

<iframe src="/games/onyx-club/" 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 do jogo quando publicar para o público.

Requisitos

  • Qualquer hospedagem estática HTTP ou HTTPS (hospedagem compartilhada, 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 precisa de 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 TAP TO PLAY, escolhe uma mesa no salão, pega uma ficha na bandeja, toca um lugar de aposta e toca DEAL (DAR CARTAS). O crupiê dá duas cartas a cada mão e duas para si, uma virada para baixo. O jogador joga cada mão; depois o crupiê revela a carta e compra até 17. Todos os valores são créditos fictícios de demonstração.

O salão: as mesas num carrossel (aqui com todas as mesas abertas). 1 2 3 4 5 6
O salão: as mesas num carrossel (aqui com todas as mesas abertas).
  1. carrossel de mesas: setas, deslizar ou um toque
  2. roleta diária
  3. saldo de créditos grátis de demonstração (o + abre as moedas grátis)
  4. nível do jogador e XP
  5. menu: ajustes, regras, estatísticas, mesas
  6. regras desta mesa

O salão: três mesas, três ambientes

As mesas esperam num carrossel: setas, deslizar o dedo, tocar numa mesa do lado ou as setas do teclado mudam a mesa, e PLAY (ou um toque na mesa escolhida) senta. Uma mesa trancada mostra um cadeado e o nível que a abre. Cada mesa tem limites, fichas e ambiente próprios:

  • MESA SALÃO (apostas 10 - 500): o salão principal do clube, sobre feltro esmeralda
  • MESA PALCO (apostas 100 - 5.000): de frente para o palco de jazz, sobre feltro rubi
  • MESA TERRAÇO (apostas 1.000 - 50.000): o terraço sobre o horizonte da cidade à noite, sobre feltro safira

Apostar

Toque numa ficha da bandeja e depois num lugar. Telas largas mostram 3 lugares (o celular em pé mostra um). Os círculos pequenos ao lado do lugar do meio são as apostas paralelas. CLEAR devolve as apostas, REBET repete as apostas da rodada anterior, ×2 dobra as apostas, DEAL começa a rodada. Toda aposta fica entre o mínimo e o máximo da mesa.

Apostando na primeira mesa (MESA SALÃO): três lugares numa tela larga, as apostas paralelas ao lado do lugar do meio. 1 2 3 4 5 6 7 8 9 10 11 12 13
Apostando na primeira mesa (MESA SALÃO): três lugares numa tela larga, as apostas paralelas ao lado do lugar do meio.
  1. saldo de créditos grátis de demonstração (o + abre as moedas grátis)
  2. nível do jogador e XP
  3. menu: ajustes, regras, estatísticas, mesas
  4. regras desta mesa
  5. lugar de aposta
  6. aposta paralela Perfect Pairs
  7. aposta paralela 21+3
  8. bandeja de fichas (as cinco fichas da mesa)
  9. CLEAR: devolve as apostas
  10. REBET: repete as apostas da última rodada
  11. ×2: dobra as apostas
  12. DEAL: começa a rodada
  13. o aviso de créditos grátis (mantenha visível)

Jogar uma mão

Jogada O que faz
Pedir (Hit) mais uma carta
Parar (Stand) fica com a mão como está
Dobrar (Double) dobra a aposta e recebe exatamente mais uma carta (com quaisquer duas primeiras cartas, também depois de dividir)
Dividir (Split) duas cartas de mesmo valor viram duas mãos, cada uma com sua aposta (até 4 mãos)
Desistir (Surrender) abandona a mão na primeira decisão e recebe metade da aposta de volta (depois que o crupiê confere o blackjack)
Seguro (Insurance) quando o crupiê mostra um Ás: uma aposta extra de metade da aposta que paga 2 para 1 se ele tiver blackjack

O balão de dica mostra a jogada da estratégia básica para a mão (o jogador pode desligar em SETTINGS). Valores das cartas: 2 a 10 valem o número, J, Q e K valem 10, o Ás vale 1 ou 11. Um Ás e uma carta de valor 10 nas duas primeiras cartas é um blackjack e paga 3 para 2. O crupiê para em todo 17.

Uma mão em jogo: as jogadas à direita e a dica de estratégia básica. 1 2 3 4 5 6
Uma mão em jogo: as jogadas à direita e a dica de estratégia básica.
  1. HIT: mais uma carta
  2. STAND: fica com a mão
  3. DOUBLE: dobra a aposta, uma carta
  4. SPLIT: um par vira duas mãos
  5. SURRENDER: metade da aposta de volta
  6. dica de estratégia básica
Um par de oitos dividido em duas mãos.
Um par de oitos dividido em duas mãos.

Resultados e comemorações

Depois da vez do crupiê, cada mão mostra o resultado no feltro (WIN, PUSH, BUST, DEALER BUSTS) e as fichas se movem: apostas perdidas vão para o crupiê, vitórias são pagas ao lado da aposta. Um blackjack tem título próprio. Quando uma rodada paga pelo menos 4 vezes a aposta, o jogo faz uma comemoração BIG WIN (MEGA a partir de 10×, EPIC a partir de 25×) com moedas voando para o saldo.

Uma mão vencedora na segunda mesa (MESA PALCO), no seu próprio ambiente.
Uma mão vencedora na segunda mesa (MESA PALCO), no seu próprio ambiente.
Um blackjack: título e pagamento próprios.
Um blackjack: título e pagamento próprios.
Uma divisão com duas dobras que paga um BIG WIN.
Uma divisão com duas dobras que paga um BIG WIN.

Apostas paralelas

São decididas pelas primeiras cartas, antes de a rodada ser jogada, e pagam "para 1" sobre a aposta paralela:

Aposta paralela Ganha quando Paga
Perfect Pairs as duas primeiras cartas do jogador formam um par: mesmo naipe (perfeito) / mesma cor (colorido) / misto 25 para 1 / 12 para 1 / 6 para 1 (perfeito / colorido / misto)
21+3 as duas cartas do jogador e a carta aberta do crupiê formam uma mão de pôquer trinca do mesmo naipe 100 para 1, straight flush 40 para 1, trinca 30 para 1, sequência 10 para 1, flush 5 para 1

Recompensas fora da mesa

Os níveis (o selo ao lado do saldo) crescem com os créditos jogados; cada nível novo dá créditos grátis e abre as próximas mesas. A roleta diária dá créditos grátis (oferecida em toda visita no ajuste de demonstração de fábrica). O botão de presente dá 1.000 créditos grátis a cada 3 horas. Quando os créditos acabam, é oferecida uma recarga grátis de 25.000.

A roleta diária de créditos grátis. 1 2 3
A roleta diária de créditos grátis.
  1. a roleta: 12 prêmios de créditos grátis
  2. SPIN (girar)
  3. fechar

Menu: ajustes, regras e estatísticas

O menu abre SETTINGS (música, efeitos sonoros, voz do locutor, velocidade, a dica, menos movimento, idioma), as RULES da mesa atual (as jogadas com cartinhas de exemplo, os pagamentos, o conjunto de regras) e as STATISTICS (mãos, vitórias, blackjacks, maior vitória, melhor sequência, conquistas com medalhas).

SETTINGS: música, efeitos, voz, velocidade, a dica, menos movimento e o idioma. 1
SETTINGS: música, efeitos, voz, velocidade, a dica, menos movimento e o idioma.
  1. fechar o painel
RULES: cada jogada com cartinhas de exemplo.
RULES: cada jogada com cartinhas de exemplo.
STATISTICS e as conquistas com suas medalhas.
STATISTICS e as conquistas com suas medalhas.
A terceira mesa (MESA TERRAÇO) e seu ambiente.
A terceira mesa (MESA TERRAÇO) e seu ambiente.
No celular em pé: um lugar, as jogadas embaixo da mesa. 1 2 3 4 5 6 7 8 9
No celular em pé: um lugar, as jogadas embaixo da mesa.
  1. saldo de créditos grátis de demonstração (o + abre as moedas grátis)
  2. nível do jogador e XP
  3. menu: ajustes, regras, estatísticas, mesas
  4. HIT: mais uma carta
  5. STAND: fica com a mão
  6. DOUBLE: dobra a aposta, uma carta
  7. SPLIT: um par vira duas mãos
  8. SURRENDER: metade da aposta de volta
  9. dica de estratégia básica

Teclado

Na jogada: H pedir, S parar, D dobrar, P dividir, R desistir. Enter ou Espaço dá as cartas (apostando) e repete as apostas (depois de uma rodada). No salão: as setas escolhem a mesa e Enter senta.

O que vem no pacote

onyx-club-static-1.0.0/
  START-HERE.txt          primeiros passos
  DOCUMENTATION.html      abre este guia
  CUSTOMIZATION.html      abre o guia de personalização (receitas, sem programar)
  CHANGELOG.txt
  SCOPE.md                o que o produto é e o que a licença não permite
  documentation/          este guia e o guia de personalização (EN/PT/ES), capturas
  game/                   ENVIE O CONTEÚDO DESTA PASTA
    index.html            a página
    onyx-club.config.js    seus ajustes (edite na hospedagem, sem build)
    modules/              o JavaScript, um arquivo legível por módulo do código-fonte (mais _virtual/preload-helper.js,
                          o pequeno carregador que o Vite acrescenta para o módulo do crupiê, carregado sob demanda)
    assets/ui/            as folhas de estilo (quatro arquivos)
    art/                  imagens (WebP)
    audio/                sons, voz e música (MP3)
    SCOPE.md, DOCUMENTATION.txt
  source/                 o projeto completo editável
    index.html            a página (versão de desenvolvimento)
    src/main.js           início, telas, layout, carrossel do salão, apostas, roleta diária, ajustes, entrada
    src/flow/round.js     uma rodada: cartas, jogadas, seguro, apostas paralelas, resultados, blackjack, comemorações (parte do main.js)
    src/config.js         padrões, eventos, chave do save
    src/logic/            rules.js (mesas e regras), engine.js (sapato, mãos, créditos), strategy.js (a dica), progress.js
    src/ui/               table.js (o feltro), sheets.js (painéis), wheel.js, fx.js, feel.js, theme.js, art.js, styles*.css
    src/bear/             sprite-bear.js: o crupiê animado
    src/locales/          os 14 idiomas (en.js é a referência)
    src/audio/audio.js    a lista de sons, músicas e vozes
    public/               art/, audio/, onyx-club.config.js (copiados para o build como estão)
    tests/                npm test
    tools/                vantagem da casa, conferência das traduções, robô de teste, conferência de textos, formatador do build
    package.json, package-lock.json, vite.config.js, .prettierrc, README.md
    licenses/             licenças das ferramentas de desenvolvimento
  THIRD-PARTY-LICENSES/   os mesmos textos de licença

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

Ajustes (onyx-club.config.js)

game/onyx-club.config.js é lido toda vez que o jogo abre, então você pode mudar estes ajustes na hospedagem com um editor de texto, sem build. Todo campo é opcional: tire o // da frente da linha para usá-la. Um valor errado para o jogo com uma mensagem que diz o que corrigir.

window.BLACKJACK_CONFIG = {
  brand: { name: 'Onyx Club Blackjack', storageKey: 'meusite.onyx-club' },
  language: 'auto',
  languages: ['en', 'pt', 'es'],
  texts: { tapToPlay: 'JOGAR', de: { tapToPlay: 'LOS!' } },
  audio: { volume: 0.8, muted: false },
  tips: true,
  lobby: true,
  ageGate: true,
  notice: true,
  rules: { preset: 'vegas', decks: 6, blackjackPays: [3, 2], dealerHitsSoft17: false, startBalance: 25000 },
  progress: { wheel: { alwaysReady: false, everyHours: 24 }, coins: { everyHours: 3, amount: 100 } },
  winTiers: { big: 4, mega: 10, epic: 25 },
};
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 onyx-club.template.save.v1); mude para começar um save novo
language 'auto' = o idioma do aparelho (inglês se não houver), ou um código: en pt es fr de it nl pl tr ru id ja ko zh. A escolha do jogador em SETTINGS e ?lang=xx no endereço vêm antes
languages os idiomas oferecidos em SETTINGS (padrão: os 14). Um só esconde o seletor
texts troca qualquer texto de src/locales/en.js em todos os idiomas, ou em um (texts: { pt: {...} })
audio volume inicial (0 a 1) e mudo
tips a dica de estratégia básica (o jogador pode desligar)
lobby false pula o salão: o jogador senta na primeira mesa
ageGate true mostra o selo 18+ e o aviso de cassino social
notice o aviso de créditos de uma linha sob os controles. Deixe ligado: o SCOPE.md exige em publicações abertas
showEdge mostra a vantagem da casa medida na folha de regras (defina rules.houseEdge depois de rodar npm run edge)
debug só para teste, veja "Link de teste" abaixo
rules as regras da mesa e o salão, veja "Regras e limites das mesas"
progress níveis (enabled, need, reward), a roleta diária (enabled, alwaysReady, everyHours, prizes, weights) e moedas grátis (enabled, everyHours, amount). Valores em múltiplos da menor aposta da primeira mesa
winTiers a partir de quantas vezes a aposta da rodada começam as comemorações big, mega e epic
integration, callbacks eventos para a sua página, veja "Eventos"

O arquivo do pacote lista todas as opções com comentário. Os padrões completos estão em source/src/config.js, source/src/logic/rules.js e source/src/logic/progress.js.

Link de teste

Na sua própria máquina (localhost, 127.0.0.1 ou um endereço da rede de casa como 192.168.x.x) o endereço ?debug=1 liga um modo de teste, sem mudar nenhum arquivo: &seed=123 repete o mesmo sapato, &deal=AS,KH,9D,7C põe essas cartas no topo do sapato, &level=20 começa nesse nível (todas as mesas abertas) e &coins=500000 começa com esse saldo. Numa hospedagem pública isso é ignorado, a menos que você ponha debug: true no onyx-club.config.js (não deixe ligado para os jogadores). O robô de teste e os testes usam esse modo.

Regras e limites das mesas

Tudo fica em rules: { } do onyx-club.config.js (ou source/src/logic/rules.js). A mesa de fábrica:

  • preset: 'vegas': um conjunto de regras pronto. 'vegas' (6 baralhos, o crupiê confere o blackjack, dobrar com quaisquer duas cartas, desistência tardia), 'european' (sem carta fechada: o crupiê pega a segunda carta depois dos jogadores, dobrar com 9 a 11, sem desistência) ou 'social' (2 baralhos, Ases divididos podem ser divididos de novo e pedir carta). Qualquer chave abaixo substitui o preset.
  • decks: 6 (1 a 8); penetration: 0.75 (parte do sapato distribuída antes de embaralhar de novo).
  • dealerHitsSoft17: false; blackjackPays: [3, 2], [6, 5], [1, 1] ou [2, 1]; peek: o crupiê confere o blackjack sob um Ás ou um 10.
  • double: 'any', '9-11', '10-11' ou 'none'; doubleAfterSplit; maxHands (1 = sem divisão); splitByValue (K + 10 pode dividir); resplitAces; hitSplitAces.
  • surrender: 'late' ou 'none'; insurance: true ou false.
  • seats: lugares de aposta ao mesmo tempo em telas largas (1 a 3).
  • sideBets: perfectPairs e twentyOnePlusThree, cada uma com enabled e pays; max é a maior aposta paralela como parte da aposta máxima da mesa.
  • startBalance: 25.000 (também a recarga grátis).
  • tables: o salão, uma linha por mesa: id, minBet, maxBet, chips (1 a 5 valores, do menor ao maior) e unlock (o nível do jogador que abre a mesa). Valores em múltiplos de 10 para todo pagamento ser inteiro.
Mesa Apostas Fichas Abre no nível
MESA SALÃO 10 - 500 10, 20, 50, 100, 500 1
MESA PALCO 100 - 5.000 100, 200, 500, 1.000, 5.000 5
MESA TERRAÇO 1.000 - 50.000 1.000, 2.000, 5.000, 10.000, 50.000 12

Não existe "porcentagem de vitória" para configurar: o sapato é embaralhado ao acaso e a vantagem da casa vem só destas regras. npm run edge (em source/) joga milhões de mãos com a estratégia básica usando seus ajustes e mostra a vantagem. Os testes do motor (npm test) conferem cada regra.

Idiomas

A interface está traduzida em 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 (BLACKJACK, BIG WIN, MEGA WIN, EPIC WIN, DAILY WHEEL) ficam em inglês em todos os idiomas. O jogo abre no idioma do aparelho; o jogador pode trocar em SETTINGS, e ?lang=pt no endereço força um.

Os textos ficam em source/src/locales/<código>.js, um arquivo por idioma, com as mesmas chaves do en.js (os nomes das mesas são table_<id>). Uma chave que falta usa o inglês. Para trocar alguns textos sem build, use texts no onyx-club.config.js. Depois de editar os arquivos de idioma, rode npm run locales para conferir que nenhuma tradução perdeu um marcador {valor}.

A mesma mesa em português.
A mesma mesa em português.

Dados salvos

O jogo guarda saldo, nível, estatísticas, ajustes, a mesa escolhida e os relógios das recompensas no localStorage do navegador, em chaves que começam com onyx-club.template.save.v1. (por exemplo onyx-club.template.save.v1.balance). Nada é enviado a lugar nenhum. Uma rodada interrompida por recarregar a página devolve as apostas da mesa. Limpar os dados do site no navegador zera o jogo. Se publicar duas cópias do jogo no mesmo domínio, dê a cada uma o seu brand.storageKey.

Eventos para a sua página

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

  • callbacks no onyx-club.config.js: onReady(info), onRound(round), onWin(round), onBalance({ balance }), onBonus({ kind, amount, balance }), onError.
  • window.OnyxBlackjack.on('round', fn), window.OnyxBlackjack.getBalance(), window.OnyxBlackjack.version, window.OnyxBlackjack.rules.
  • Eventos DOM no window: blackjack:round, blackjack:win, blackjack:bonus...
  • Com integration: { postMessage: true, targetOrigin: 'https://seu-site.example' } o jogo também envia { source, type, payload } para a página-mãe quando roda num iframe.

round.spent são os créditos de demonstração colocados na rodada (apostas, dobras, divisões, apostas paralelas, seguro), round.payout os créditos que ela devolveu, round.net a diferença, round.hands as cartas e o resultado de cada mão, round.table o id da mesa. bonus.kind é 'wheel', 'coins', 'level' ou 'refill'.

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

Só precisa disto para mudar código, estilos, arte ou sons e gerar um novo game/. Para mudar ajustes, edite o onyx-club.config.js.

1. Instalar o Node.js

  1. Entre em 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 e abra o terminal de novo (Windows: PowerShell ou Prompt de Comando; macOS: Terminal).
  3. Confira as versões: os dois comandos têm de mostrar um número, e o Node tem de 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 Explorer, clique na barra de endereço, digite powershell e Enter; macOS: arraste a pasta para o ícone do Terminal). Depois rode:

npm ci

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

3. Testar, ver a prévia e gerar

npm test
npm run dev
npm run build
  • npm test roda os testes do motor (sapato, valores das mãos, cada jogada, seguro, desistência, apostas paralelas, créditos, estratégia básica, vantagem da casa). Todos têm de passar.
  • npm run dev abre uma prévia local em http://localhost:5223/ que recarrega ao salvar um arquivo. Ctrl+C para parar. O link de teste funciona nela (?debug=1&deal=AS,KH,9D,7C).
  • npm run build grava o jogo pronto em source/dist/. Envie o conteúdo de dist/ para a hospedagem (ele substitui game/). O build não é minificado e é formatado com Prettier, então continua legível.

Outros comandos

  • npm run edge mostra a vantagem da casa das suas regras (src/logic/rules.js mais o rules de public/onyx-club.config.js), medida em milhões de mãos.
  • npm run locales confere as traduções.
  • npm run format formata o projeto inteiro com Prettier.
  • npm run robot joga rodadas de verdade num navegador, em tamanho de celular e de computador, e confere que todo saldo está exato (veja "Robô de teste").
  • tools/qa-fit.js é uma conferência dentro da página para a prévia: no console do navegador, (await import('/tools/qa-fit.js')).check() lista qualquer texto que não cabe na sua placa.

Robô de teste

tools/play-robot.mjs aposta, dá as cartas e joga pelos próprios botões do jogo (todas as jogadas, apostas paralelas, seguro, painéis, REBET / NEW BET) e relata erros da página, rodadas que nunca terminam e qualquer saldo diferente do que o jogo diz que a rodada pagou. Instale o navegador dele uma vez com npx playwright install chromium, rode npm run dev num terminal e npm run robot em outro. O relatório fica em robot-report/report.json.

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á desativada (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 empresa e rode de novo.
  • npm ci diz que o lockfile está fora de sincronia: você mudou o package.json; rode npm install uma vez, depois o npm ci volta a funcionar.
  • A porta 5223 está ocupada: o Vite escolhe a próxima livre e mostra.
  • O robô diz que falta o navegador: rode npx playwright install chromium.

Personalizar e trocar o tema

O guia de personalização (CUSTOMIZATION.html) tem receitas passo a passo para quem não programa: trocar os fundos e os ambientes, o logo, o crupiê, as cartas, as fichas, sons e música, cores, textos, regras das mesas 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: um tema novo é uma pasta de arte mais o source/src/ui/theme.js.
  • Sons: source/public/audio/ (ou game/audio/). Troque um MP3 por outro com o mesmo nome.
  • Cores e efeitos do tema: source/src/ui/theme.js. Tempos: source/src/ui/feel.js. Só apresentação: nada ali muda uma carta ou um pagamento.
  • Layout e estilos: source/src/ui/styles.css e os três arquivos que vêm depois dele (styles-placement.css, styles-polish.css, styles-final.css, carregados nessa ordem).
  • Textos: texts no onyx-club.config.js ou source/src/locales/.
  • Regras e limites das mesas: rules no onyx-club.config.js ou source/src/logic/rules.js, depois npm run edge.

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

Nomes internos

Alguns nomes no código descrevem outra coisa do que dizem. São só nomes:

Nome no código O que é
src/bear/, sprite-bear.js, bear, bear-sprites/, bear-*.webp o crupiê animado (a pantera negra) e suas figuras: os nomes vêm do motor compartilhado
lounge, stage, rooftop os ids das três mesas em rules.tables (os arquivos de arte usam os mesmos nomes)
iceFont, font-ice os algarismos pintados claros (apostas, totais); goldFont / font-gold são os dourados (saldo, vitórias)
crystal-*.webp, flake-*.webp, ice-arrow.webp, title-bust-ice.webp ornamentos Art Déco, brilhos dourados, a seta do carrossel e o título BUST: nomes de arquivo mantidos do motor compartilhado
auroraGlow(), @keyframes aurora, .bg-glow as luzes do ambiente: um véu lento de luz sobre as janelas que brilha por um instante depois de uma vitória (nomes do motor compartilhado)
fx.snow, snowCount, FEEL.ambient.snowDesktop / snowTouch as partículas do ambiente: pó dourado subindo devagar neste tema (THEME.ambient.rise = true)
fx.frost(), fx.crack(), fx.shards(), 'bust-ice' o estouro, as rachaduras e os estilhaços desenhados num BUST e numa nova faixa de comemoração, e a chave do painel BUST (nomes do motor compartilhado)
Bank, bank.balance os créditos fictícios de demonstração do jogador (sem dinheiro)
.nine, nine.js placas e botões esticados em nove pedaços (9-slice) para as pontas decoradas manterem a forma
window.__bj o ajudante de teste do link de teste (?debug=1, só na sua máquina)

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 aparece:

  • 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 em cache"). Não limpe "cookies e dados do site", a menos que queira zerar o jogo salvo.
  • Teste numa janela anônima.
  • Se a hospedagem ou a CDN (por exemplo a Cloudflare) tiver cache, limpe.
  • Acrescente uma versão ao endereço uma vez, por exemplo index.html?v=2.

Os dados salvos continuam depois de uma atualização enquanto o brand.storageKey não mudar.

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

  • Só créditos fictícios de demonstração, gratuitos e sem valor monetário. Não podem ser comprados, transferidos, vendidos ou resgatados. Nenhum prêmio de nenhum tipo.
  • Nenhum sistema de pagamento, depósito, saque, conta ou carteira: nenhum está escondido, desligado ou incluído no pacote.
  • As cartas saem de um sapato embaralhado ao acaso; nada no jogo ajusta a chance de ganhar.
  • A licença padrão não permite usar este jogo, ou qualquer versão modificada dele, para apostas com dinheiro real ou qualquer coisa de valor real: nada de comprar créditos, sacar, prêmios por resultado, ligação a carteira de apostas, sistema de pagamento ou operador de dinheiro real, nem propaganda de apostas com dinheiro real.
  • "Seguro", "apostas paralelas" e "dobrar" são jogadas do jogo de cartas e gastam os mesmos créditos fictícios; não são compras.
  • Você tem de seguir as leis de cada lugar onde publicar o jogo (classificação etária, menores, defesa do consumidor). Mantenha o aviso de créditos visível; ageGate: true acrescenta um aviso 18+.
  • O suporte não cobre carteira, depósito, saque ou qualquer integração com dinheiro real; pedidos assim são recusados.

O texto completo é o SCOPE.md.

Perguntas e problemas

  • A página fica em branco. Confira se enviou o conteúdo de game/ (com modules/ e assets/) e se abre por http(s), não file://. O console do navegador (F12) mostra o arquivo que falta.
  • Sem som. Os navegadores só liberam som depois de um toque: o jogo começa no TAP TO PLAY. Confira SETTINGS (música, efeitos, voz) e o volume do aparelho. Se o celular cortar o som (uma ligação, outro app), o próximo toque traz de volta.
  • Posso mudar a vantagem da casa? Sim, só pelas regras (blackjackPays, decks, dealerHitsSoft17, double, surrender, pagamentos das apostas paralelas...); npm run edge mede a sua mesa. Não há taxa de vitória escondida.
  • Posso pôr uma quarta mesa? Sim: acrescente uma linha em rules.tables e o nome dela como table_<id> nos idiomas (ou em texts). Ela usa o primeiro ambiente, a menos que você acrescente arte e estilos para ela (guia de personalização, receita 3).
  • 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 outro site.
  • Posso tirar o aviso de créditos? Numa publicação aberta ele tem de ficar visível (veja SCOPE.md).
  • A roleta diária abre em toda visita. É o ajuste de demonstração alwaysReady: true; ponha progress: { wheel: { alwaysReady: false } }.
  • Como mostrar cartas escolhidas? Na prévia local acrescente ?debug=1&deal=AS,KH,9D,7C (as cartas vão para o jogador, o crupiê, o jogador, o crupiê...).

Suporte e créditos

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

Ferramentas de desenvolvimento: Vite, Prettier e Playwright (licenças 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.