Polar Games
Documentation · v1.0.1Documentação · v1.0.1

Thank you for purchasing RICOPOP Obrigado por comprar o RICOPOP

You are minutes away from having your own ricochet arcade game online. This guide walks you through installing it, turning on ads and the leaderboard, and making it yours.

Falta pouco para ter o seu próprio jogo de arcade de ricochete no ar. Este guia mostra como instalar, ligar anúncios e ranking, e deixar o jogo com a sua cara.

HTML5 · no server neededHTML5 · sem servidor 50 levels · 14 languages50 fases · 14 idiomas Optional ads & leaderboardAnúncios e ranking opcionais Works on phone & desktopCelular e computador

1What's in the packageO que vem no pacote

RICOPOP is a complete ricochet arcade game: aim a volley of glowing balls, bounce them off the walls and crystals, set off chain reactions and clear the board before it reaches the line. It is 100% static (plain HTML, CSS and JavaScript), so there is nothing to run on your server.

O RICOPOP é um arcade de ricochete completo: mire uma rajada de bolas brilhantes, quique nas paredes e nos cristais, dispare reações em cadeia e limpe o tabuleiro antes que ele chegue à linha. É 100% estático (HTML, CSS e JavaScript simples), então não há nada para rodar no seu servidor.

ricopop-static-1.0/
├─ game/            ← upload THIS to your website
│  ├─ index.html  style.css  manifest.webmanifest
│  ├─ ricopop.config.js   ← ads & leaderboard settings (edit me)
│  ├─ api/ranking.php     ← optional leaderboard (PHP)
│  ├─ src/                ← the game code (plain JavaScript, no build step)
│  ├─ assets/             ← music, effects, voices, fonts, icons
├─ documentation/   ← this guide (index.html)
└─ source/          ← optional developer tools (NOT for your server)
50 levels50 fases10 chapters of 5 levels, from a gentle tutorial to a grand finale. Up to 3 stars per level (150 in total) and a best score for each one.10 capítulos de 5 fases, de um tutorial tranquilo até um grande final. Até 3 estrelas por fase (150 no total) e um recorde para cada uma.
Chain reactions & PulseReação em cadeia e PulsoExplosive cores blow up their neighbours, and the Pulse power-up (from level 7) turns a ball into a 3×3 blast.Os núcleos explosivos destroem os vizinhos, e o Pulso (a partir da fase 7) transforma uma bola numa explosão 3×3.
14 languages14 idiomasEnglish, Portuguese, Spanish, French, German, Italian, Dutch, Polish, Turkish, Russian, Indonesian, Japanese, Korean and Chinese. Narrator voices in English, Portuguese and Spanish.Inglês, português, espanhol, francês, alemão, italiano, holandês, polonês, turco, russo, indonésio, japonês, coreano e chinês. Vozes do narrador em inglês, português e espanhol.
Solo play, no accountsModo solo, sem contasSix ball styles to unlock with stars, music, effects and an optional leaderboard. No online multiplayer in this package.Seis visuais de bola para liberar com estrelas, música, efeitos e um ranking opcional. Este pacote não tem multiplayer online.

Visual guide: menus and playfieldGuia visual: menus e área de jogo

These numbered maps use actual screenshots of the delivered game. Match each marker to the explanations below. The examples show English and existing local progress; your saved scores and unlocked styles may differ.Estes mapas numerados usam capturas reais do jogo entregue. Relacione os marcadores às explicações abaixo. Os exemplos mostram inglês e progresso local existente; seus recordes e estilos desbloqueados podem ser diferentes.

Home screenTela inicial

Numbered RICOPOP home-screen map / Mapa numerado da tela inicial
Home layout at 1280×720. Narrow screens adapt the controls to the available space.Layout inicial em 1280×720. Telas estreitas adaptam os controles ao espaço disponível.
  1. Continue / Play: opens the next campaign level available in the current browser.Continuar / Jogar: abre a próxima fase disponível neste navegador.
  2. Levels: campaign chapters, level selection, earned stars and locked stages.Fases: capítulos, seleção de fase, estrelas e fases bloqueadas.
  3. Skins: preview and select cosmetic styles; unlock requirements use campaign stars.Skins: visualização e escolha de estilos; desbloqueios usam estrelas da campanha.
  4. Ranking: personal bests are local by default. The optional PHP leaderboard only runs when configured and enabled.Ranking: recordes locais por padrão. O ranking PHP opcional só funciona após configuração e ativação.
  5. Language: changes the interface and level hints. Voice coverage is documented separately.Idioma: altera a interface e as dicas das fases. Os idiomas de voz são documentados separadamente.
  6. Settings: audio, motion and other preferences; the neighboring control opens fullscreen.Ajustes: áudio, movimento e preferências; o controle ao lado abre a tela cheia.

During a levelDurante uma fase

Numbered RICOPOP gameplay map / Mapa numerado da partida
First Spark: the level 1 playfield with the main controls and goals.First Spark: área da fase 1 com os controles e objetivos principais.
  1. Pause: opens the pause menu. The adjacent gear opens settings.Pausa: abre o menu de pausa. A engrenagem ao lado abre os ajustes.
  2. Level information: level number/name, hint, crystals remaining and chapter navigation. Score and personal best appear below.Informações: número/nome, dica, cristais restantes e navegação do capítulo. Pontuação e recorde aparecem abaixo.
  3. Playfield: crystal numbers show remaining hit points. Clear every required crystal while planning bounces and chain reactions.Área de jogo: os números dos cristais mostram os pontos de resistência. Planeje ricochetes e reações em cadeia para limpar os cristais exigidos.
  4. Cannon and ball count: drag to aim and release to fire. Wait for the volley to return before aiming again.Canhão e quantidade de bolas: arraste para mirar e solte para disparar. Aguarde o retorno antes da próxima mira.
  5. Volley and stars: the current volley and thresholds explain the one-, two- and three-star goals.Salva e estrelas: a salva atual e os limites indicam as metas para uma, duas e três estrelas.
  6. Pulse and speed: Pulse unlocks at level 7; its panel shows when it is available. The speed button switches between 1× and 2×.Pulse e velocidade: Pulse é desbloqueado na fase 7; o painel indica sua disponibilidade. O botão de velocidade alterna entre1× e2×.

2Install in 2 minutesInstalar em 2 minutos

Any web host works: shared hosting, a VPS, Netlify, GitHub Pages, S3… You only need to put the files online.

Qualquer hospedagem serve: compartilhada, VPS, Netlify, GitHub Pages, S3… Basta colocar os arquivos no ar.

  1. Unzip the packageDescompacte o pacoteEverything you need is inside the game/ folder.Tudo o que você precisa está na pasta game/.
  2. Upload the contents of game/Envie o conteúdo de game/Use FTP or your host's File Manager (cPanel, hPanel…). Put it in public_html/ for the main address, or in a sub-folder such as public_html/ricopop/. On Netlify, just drag the game folder in.Use FTP ou o Gerenciador de Arquivos da hospedagem (cPanel, hPanel…). Coloque em public_html/ para o endereço principal, ou numa subpasta como public_html/ricopop/. Na Netlify, é só arrastar a pasta game.
  3. Open the address in your browserAbra o endereço no navegadorExample: https://yoursite.com/ or https://yoursite.com/ricopop/. Tap "Tap to start" and you are playing.Exemplo: https://seusite.com/ ou https://seusite.com/ricopop/. Toque em "Tap to start" e já dá para jogar.
⚠ Upload ONLY the contents of game/Envie SOMENTE o conteúdo de game/ Do not upload the source/ folder: it only holds optional developer tools and has no game inside. Also do not upload the zip itself or an extra parent folder: index.html must be right at the address you open. Não envie a pasta source/: ela só traz ferramentas opcionais para desenvolvedores e não tem jogo dentro. Também não envie o zip em si nem uma pasta extra por cima: o index.html precisa ficar logo no endereço que você abre.
✓ Quick testTeste rápido Play level 1 on your phone and another on a computer. If the menu opens, sounds play after your first tap and the result screen appears when you clear the level, the install is perfect. Jogue a fase 1 no celular e outra no computador. Se o menu abre, os sons tocam depois do primeiro toque e a tela de resultado aparece quando você limpa a fase, a instalação está perfeita.
Good to knowBom saber
  • Use HTTPS. "Add to home screen" and some audio features need it.
  • Use HTTPS. "Adicionar à tela inicial" e alguns recursos de áudio precisam dele.
  • Do not open index.html by double-clicking it (file://): browsers block JavaScript modules there. To test on your own computer, run a tiny server, for example npx serve game.
  • Não abra o index.html com duplo clique (file://): os navegadores bloqueiam módulos JavaScript assim. Para testar no seu computador, rode um servidor simples, por exemplo npx serve game.
  • The game needs an internet connection to load (there is no offline mode in this edition).
  • O jogo precisa de internet para carregar (esta edição não tem modo offline).

3LanguagesIdiomas

The game starts in the player's browser language when it is one of the 14 supported languages (otherwise English). The player can change it any time with the language selector on the title screen or in Settings (the gear icon), and the choice is remembered. You can also force a language with ?lang=pt at the end of the address. Nothing to configure.

O jogo abre no idioma do navegador do jogador quando ele é um dos 14 idiomas (senão, inglês). O jogador pode trocar quando quiser no seletor de idioma da tela inicial ou em Ajustes (a engrenagem), e a escolha fica guardada. Você também pode forçar um idioma com ?lang=pt no fim do endereço. Não há nada para configurar.

The narrator speaks English, Portuguese or Spanish. In the other 11 languages the text is translated and the narrator speaks English. To add or fix a language, see "Make it yours" and the FAQ.

O narrador fala inglês, português ou espanhol. Nos outros 11 idiomas o texto é traduzido e o narrador fala em inglês. Para adicionar ou corrigir um idioma, veja "Personalizar" e o FAQ.

4Ads (optional)Anúncios (opcional)

Ads are off by default: no ad code is even loaded. To earn with the game, open ricopop.config.js in any text editor. No rebuild needed.

Os anúncios vêm desligados: nem o código de anúncio é carregado. Para ganhar com o jogo, abra o ricopop.config.js em qualquer editor de texto. Sem recompilar nada.

window.RICOPOP_CONFIG = {
  ads: {
    provider: 'adsense',              // 'none' | 'adsense' | 'custom' | 'demo'
    adsenseClient: 'ca-pub-XXXXXXXXXXXXXXXX',
    testMode: true,                  // Google TEST ads; set false to go live
    rewarded: true,                  // false = no rewarded-video buttons
    midgame: true, minLevel: 2, midgameEveryMs: 150000,   // ads between levels
  },
  // …
};

What the player seesO que o jogador vê

WhereOndeAdAnúncio
When a new level starts, from level 2 on, at least 2 levels and 2.5 minutes after the previous adInterstitial
Quando uma fase nova começa, da fase 2 em diante, com pelo menos 2 fases e 2,5 minutos desde o anúncio anteriorIntervalo
After failing a levelOptional rewarded video → "one more chance" (that win does not count for records or the leaderboard)
Depois de perder uma faseVídeo com recompensa opcional → "mais uma chance" (essa vitória não vale recorde nem ranking)
Skins screenOptional rewarded video ("Ad Unlock") → unlocks the next ball style
Tela de visuaisVídeo com recompensa opcional ("Ad Unlock") → libera o próximo visual de bola

Ads never appear while a level is being played. You can change "from level 2", "2 levels" and "2.5 minutes" with minLevel and midgameEveryMs (milliseconds), switch off the interstitials with midgame: false, and hide the rewarded buttons with rewarded: false.

Os anúncios nunca aparecem enquanto uma fase está sendo jogada. Você pode mudar "da fase 2", "2 fases" e "2,5 minutos" com minLevel e midgameEveryMs (milissegundos), desligar os de intervalo com midgame: false e esconder os botões de recompensa com rewarded: false.

✓ Try the flow firstTeste o fluxo primeiro Set provider: 'demo' to see a fake 3-second ad screen, exactly where real ads would appear, without any ad account. Put it back to 'none' or 'adsense' afterwards. Use provider: 'demo' para ver uma tela de anúncio de mentira de 3 segundos, exatamente onde os anúncios de verdade apareceriam, sem precisar de conta de anúncios. Depois volte para 'none' ou 'adsense'.

Before going live: interstitial and rewarded ads use Google AdSense for Games, which Google has to approve for your site. Until then the game simply shows no ads. If an ad blocker is on, or no ad is available, the game never waits more than ~2.5 seconds.

Antes de publicar: os anúncios de intervalo e de recompensa usam o Google AdSense para Jogos, que o Google precisa aprovar para o seu site. Até lá o jogo simplesmente não mostra anúncio. Com bloqueador de anúncios, ou sem anúncio disponível, o jogo nunca espera mais que ~2,5 segundos.

Privacy law (GDPR / LGPD / CCPA): the game itself stores data only in the player's browser (no cookies, no tracking, no accounts). If you turn ads on, you are responsible for the consent banner your region requires (for example Google's consent tool).

Leis de privacidade (LGPD / GDPR / CCPA): o jogo só guarda dados no navegador do jogador (sem cookies, sem rastreamento, sem conta). Ao ligar anúncios, você é responsável pelo aviso de consentimento que a sua região exige (por exemplo, a ferramenta de consentimento do Google).

Using another ad network (custom)Usar outra rede de anúncios (custom)

Set provider: 'custom' and define your own adapter in the same file, after the window.RICOPOP_CONFIG block:

Use provider: 'custom' e defina o seu adaptador no mesmo arquivo, depois do bloco window.RICOPOP_CONFIG:

window.RICOPOP_CONFIG.ads.provider = 'custom';
window.RICOPOP_AD_PROVIDER = {
  interstitial() { /* show the ad */ return Promise.resolve(); },    // resolve when it is over
  rewarded()     { /* show the video */ return Promise.resolve(true); }, // true only if watched to the end
};

5Leaderboard (optional)Ranking (opcional)

A one-file PHP leaderboard is included. It is OFF by default: until you turn it on, the Ranking screen only shows each player's own best on their own device (nothing is sent anywhere). The leaderboard score is the total of the best score of every level. No database: scores live in a JSON file. If your host has PHP (almost all shared hosts do), turning it on takes one minute.

Um ranking em PHP, de um arquivo só, já vem incluído. Ele vem DESLIGADO: enquanto você não ligar, a tela de Ranking mostra só o melhor de cada jogador no próprio aparelho (nada é enviado para lugar nenhum). A pontuação do ranking é a soma do melhor resultado de cada fase. Sem banco de dados: os pontos ficam num arquivo JSON. Se a sua hospedagem tem PHP (quase todas têm), ligar leva um minuto.

  1. Turn it onLigueOpen ricopop.config.js in a text editor and change enabled: false to enabled: true inside ranking. Save and upload the file. That is the only switch.Abra o ricopop.config.js num editor de texto e troque enabled: false por enabled: true dentro de ranking. Salve e envie o arquivo. Esse é o único interruptor.
  2. Upload the api/ folderEnvie a pasta api/It is already inside game/, next to index.html. Nothing else to do if you uploaded everything in step 2.Ela já está dentro de game/, ao lado do index.html. Se você enviou tudo no passo 2, não há mais nada a fazer.
  3. Make the folder writableDê permissão de escrita à pastaPermission 755 (or 775/777 if your host requires it) so PHP can create ranking-data.php.Permissão 755 (ou 775/777 se a hospedagem exigir) para o PHP poder criar o ranking-data.php.
  4. Check itConfiraOpen https://yoursite.com/api/ranking.php. You should see {"ok":true,"ranking":"ricopop","writable":true,…}.Abra https://seusite.com/api/ranking.php. Deve aparecer {"ok":true,"ranking":"ricopop","writable":true,…}.

That's all. Players type a nickname at the top of the Ranking screen (if they do not, the server gives them one like "Player 1234"). Every time a level is cleared the new total is sent, and the Today / Month / All time boards update.

Pronto. Os jogadores digitam um apelido no alto da tela de Ranking (se não digitarem, o servidor dá um como "Player 1234"). Toda vez que uma fase é concluída o novo total é enviado e os placares Hoje / Mês / Geral são atualizados.

Switched on but no PHP, or no api/ folder? The game automatically falls back to the private "your best on this device" board. Nothing breaks.Ligou, mas não tem PHP, ou a pasta api/ não foi enviada? O jogo volta sozinho para o placar privado "o seu melhor neste aparelho". Nada quebra.
No leaderboard button at all? Set hide: true in the same ranking block.Não quer botão de ranking nenhum? Use hide: true no mesmo bloco ranking.

Settings (top of ranking.php)Ajustes (no topo do ranking.php)

SettingAjusteWhat it doesPara quê
$TIMEZONEWhen the "day" turns over (e.g. America/New_York, Europe/London). Default UTC.Quando o "dia" vira (ex.: America/Sao_Paulo). Padrão UTC.
$MAX_TOTALLargest total score accepted (default 2,000,000, far above what 50 levels can give). Lower it to block silly scores.Maior pontuação total aceita (padrão 2.000.000, bem acima do que as 50 fases dão). Diminua para barrar pontuações absurdas.
$MIN_SECONDSMinimum time between two submissions of the same player.Tempo mínimo entre dois envios do mesmo jogador.
$MAX_PER_IP_HOURSubmissions accepted per IP address per hour.Envios aceitos por IP por hora.
$TOPHow many rows each board shows (default 50).Quantas linhas cada placar mostra (padrão 50).
  • Backup: copy api/ranking-data.php. Reset: delete it. It starts with a PHP guard line, so it can never be downloaded.
  • Backup: copie o api/ranking-data.php. Zerar: apague o arquivo. Ele começa com uma linha de proteção em PHP, então nunca pode ser baixado.
  • Turn it off: in ricopop.config.js set enabled: false. If you will never use it, you can also delete the api/ folder.
  • Desligar: no ricopop.config.js use enabled: false. Se nunca for usar, pode também apagar a pasta api/.
  • Privacy: it stores nickname, total score and a hashed IP (only for the spam limit).
  • Privacidade: guarda apelido, pontuação total e um hash do IP (só para o limite contra spam).
Honest note: levels are played in the browser, so a determined cheater could send a fake total. The file limits the damage (maximum total, minimum time between submissions, per-IP limit) but cannot make it impossible; this edition does not re-play the levels on the server. It is meant for friendly, casual leaderboards. Need a cheat-resistant leaderboard? That takes a server: see Need custom work?Aviso honesto: as fases rodam no navegador, então quem quiser pode tentar mandar um total falso. O arquivo limita o estrago (total máximo, tempo mínimo entre envios, limite por IP), mas não torna impossível; esta edição não refaz as fases no servidor. Serve para rankings casuais e entre amigos. Precisa de um ranking resistente a fraude? Isso exige servidor: veja Quer algo sob medida?

6Make it yoursPersonalizar

RICOPOP has no build step: the files in game/ are the source code. Edit a file, upload it, hard refresh (Ctrl/Cmd + Shift + R). That's it.

O RICOPOP não tem etapa de compilação: os arquivos de game/ são o código-fonte. Edite um arquivo, envie, atualização forçada (Ctrl/Cmd + Shift + R). Só isso.

Without any tools (edit files)Sem ferramentas (editando arquivos)

I want to…Quero…Do thisFaça isto
Change the page title / descriptionEdit index.html (<title> and <meta name="description">) and manifest.webmanifest.Mudar o título / descriçãoEdite o index.html (<title> e <meta name="description">) e o manifest.webmanifest.
Change the app iconReplace the PNGs in assets/icons/ (favicon-16, favicon-32, icon-180, icon-192, icon-512, icon-maskable-512) and favicon.ico, keeping the same names.Trocar o ícone do appTroque os PNG em assets/icons/ (favicon-16, favicon-32, icon-180, icon-192, icon-512, icon-maskable-512) e o favicon.ico, mantendo os nomes.
Replace the musicReplace the 3 MP3 files in assets/music/ (same file names). If the new tracks have different lengths, update the "dur" (seconds) of each in assets/audio-manifest.json.Trocar a músicaTroque os 3 MP3 em assets/music/ (mesmos nomes). Se as faixas novas tiverem duração diferente, atualize o "dur" (segundos) de cada uma em assets/audio-manifest.json.
Replace sound effectsReplace the MP3 files in assets/sfx/ (same file names, keep them short).Trocar efeitos sonorosTroque os MP3 em assets/sfx/ (mesmos nomes, mantenha curtos).
Remove the narratorDelete the assets/voice/ folder, then open assets/audio-manifest.json and replace the content of "voice": { … } and "voices": { … } with {}. The game works the same without voices.Tirar o narradorApague a pasta assets/voice/, depois abra o assets/audio-manifest.json e troque o conteúdo de "voice": { … } e de "voices": { … } por {}. O jogo funciona igual sem as vozes.
Start without the "Tap to start" screen, or hide the full-screen buttonIn ricopop.config.js: tapToStart: false and/or fullscreen: false.Abrir sem a tela "Tap to start", ou esconder o botão de tela cheiaNo ricopop.config.js: tapToStart: false e/ou fullscreen: false.
Updated a file and don't see the change? Do a hard refresh (Ctrl/Cmd + Shift + R). If you use Cloudflare or another CDN, purge its cache too (see the FAQ).Mudou um arquivo e não viu a mudança? Faça uma atualização forçada (Ctrl/Cmd + Shift + R). Se usa Cloudflare ou outra CDN, limpe também o cache dela (veja o FAQ).

Editing the game itselfEditando o próprio jogo

The optional tools (a test server, the level checker and tests) are in the source/ folder; its README-DEV.md explains how to use them with Node.js 20+. Where things are:

As ferramentas opcionais (servidor de testes, verificador de fases e testes) estão na pasta source/; o README-DEV.md dela explica como usar com o Node.js 20+. Onde ficam as coisas:

FileArquivoWhat is in itO que tem
src/levels.jsThe 50 levels (map, par, solution). Header comment explains the format.As 50 fases (mapa, meta, solução). O comentário no topo explica o formato.
src/sim/config.jsBalls per volley, ball speed, scoring values.Bolas por rajada, velocidade da bola, valores de pontuação.
src/locales.jsAll texts in the 14 languages.Todos os textos dos 14 idiomas.
src/render/palette.jsBall styles (skins) and the stars needed for each.Visuais de bola (skins) e as estrelas necessárias para cada um.
style.css, index.htmlLook of the menus and HUD; the screens' markup.Aparência dos menus e do HUD; a estrutura das telas.
src/ui/logo.jsThe RICOPOP logo (it is drawn by code, not an image).O logo RICOPOP (é desenhado por código, não é uma imagem).

Useful addresses while testing: ?level=7 opens level 7 directly, ?lang=pt forces a language, ?nosplash skips "Tap to start".

Endereços úteis para testar: ?level=7 abre direto a fase 7, ?lang=pt força um idioma, ?nosplash pula o "Tap to start".

7What is saved, and whereO que é salvo, e onde

Progress (stars, best scores, unlocked ball styles), settings, language and nickname are stored in the player's own browser (localStorage, keys starting with ricopop.). Clearing the browser data resets it. There are no accounts and no cookies. The only server-side data is the optional leaderboard file described above.

O progresso (estrelas, recordes, visuais de bola liberados), as configurações, o idioma e o apelido ficam no próprio navegador do jogador (localStorage, chaves que começam com ricopop.). Limpar os dados do navegador zera tudo. Não há contas nem cookies. O único dado no servidor é o arquivo do ranking opcional descrito acima.

8Troubleshooting & FAQProblemas comuns e perguntas frequentes

Most questions are answered here in under a minute. Tap a question to open it.

A maioria das dúvidas é resolvida aqui em menos de um minuto. Toque numa pergunta para abri-la.

✓ Before you contact support (2 minutes)Antes de pedir suporte (2 minutos)
  1. Do a hard refresh (Ctrl/Cmd + Shift + R) and try again in a private/incognito window.
  2. Faça a atualização forçada (Ctrl/Cmd + Shift + R) e teste de novo numa janela anônima.
  3. Open the game from its real https:// address, never by double-clicking the file.
  4. Abra o jogo pelo endereço https:// de verdade, nunca com duplo clique no arquivo.
  5. Press F12 → Console and note any red error message.
  6. Aperte F12 → Console e anote qualquer mensagem de erro em vermelho.
  7. Test on another browser or phone. If only one device fails, the problem is on that device.
  8. Teste em outro navegador ou celular. Se só um aparelho falha, o problema está nele.
  9. Look for your case in the questions below.
  10. Procure o seu caso nas perguntas abaixo.
Still stuck? Send the report below. With these details the problem is usually solved in one reply. Ainda não resolveu? Envie o relato abaixo. Com esses dados o problema costuma ser resolvido em uma única resposta.
📋 Report a problem: what to send me📋 Relatar um problema: o que me enviar

Copy this, fill it in and send it. Do not post your purchase code, passwords or FTP details in public comments.

Copie, preencha e envie. Não publique o código de compra, senhas ou dados de FTP em comentários públicos.

Game version: (e.g. 1.0)
Page address: https://
Hosting: (e.g. Hostinger shared, cPanel, Netlify, VPS)
Device and system: (e.g. iPhone 13 / iOS 17, Windows 11)
Browser and version: (e.g. Chrome 120, Safari)
What I expected:
What happened instead:
Steps to repeat it:
Red error in the console (F12): (copy the text)
Screenshot or screen recording: (attach)
Did I edit any file? Which ones:
Versão do jogo: (ex.: 1.0)
Endereço da página: https://
Hospedagem: (ex.: Hostinger compartilhada, cPanel, Netlify, VPS)
Aparelho e sistema: (ex.: iPhone 13 / iOS 17, Windows 11)
Navegador e versão: (ex.: Chrome 120, Safari)
O que eu esperava:
O que aconteceu:
Passos para repetir:
Erro em vermelho no console (F12): (copie o texto)
Print ou gravação de tela: (anexe)
Editei algum arquivo? Quais:

Installing & hostingInstalação e hospedagem

The console shows 404 for src/main.js, style.css, ricopop.config.js or imagesO console mostra 404 para src/main.js, style.css, ricopop.config.js ou imagens

The files are not where the page expects them. The most common reasons: the source/ folder was uploaded instead of game/, or the files ended up inside an extra folder. Delete what you uploaded and upload the contents of game/, so that index.html sits right next to style.css, ricopop.config.js and the src/ and assets/ folders.

Os arquivos não estão onde a página espera. Os motivos mais comuns: a pasta source/ foi enviada no lugar da game/, ou os arquivos ficaram dentro de uma pasta extra. Apague o que enviou e envie o conteúdo de game/, de modo que o index.html fique ao lado do style.css, do ricopop.config.js e das pastas src/ e assets/.

The page is blank or nothing loadsA página está em branco ou nada carrega

Make sure you uploaded the contents of game/ (not the zip, not an extra parent folder) and that index.html sits at the address you open. Do not open the file by double-click (file://). Open the browser console (F12) to see any red error.

Confirme que você enviou o conteúdo de game/ (não o zip, nem uma pasta extra por cima) e que o index.html está no endereço que você abre. Não abra o arquivo com duplo clique (file://). Abra o console do navegador (F12) para ver algum erro em vermelho.

Do I need a database, Node.js or a special server?Preciso de banco de dados, Node.js ou servidor especial?

No. The game is plain static files (HTML, CSS, JavaScript): any web host works. PHP is only needed for the optional leaderboard, and even that uses a JSON file, not a database.

Não. O jogo são arquivos estáticos comuns: qualquer hospedagem serve. O PHP só é preciso para o ranking opcional, e mesmo ele usa um arquivo JSON, não um banco de dados.

I see "404", "Index of /" or a list of filesAparece "404", "Index of /" ou uma lista de arquivos

The address you opened has no index.html directly inside it. Usually the files ended up one folder deeper (for example public_html/game/index.html). Move the contents of game/ up, or open the address with that folder in it. Also note that Linux hosts are case-sensitive: Index.html is not index.html, and Assets/ is not assets/. Keep the original names.

O endereço que você abriu não tem um index.html diretamente dentro dele. Em geral os arquivos ficaram uma pasta mais fundo (por exemplo public_html/game/index.html). Mova o conteúdo de game/ para cima, ou abra o endereço com essa pasta. Lembre também que hospedagens Linux diferenciam maiúsculas de minúsculas: Index.html não é index.html, e Assets/ não é assets/. Mantenha os nomes originais.

Some images or sounds are missing, or the console shows 404sFaltam imagens ou sons, ou o console mostra erros 404

The upload was probably incomplete or corrupted. Check that: (1) your FTP program is in Binary or Auto mode, never ASCII (ASCII breaks MP3/PNG files); (2) the upload did not stop halfway; the assets/ folder has many files, so it is common for a transfer to time out. A reliable alternative is to upload the zip of game/ through your host's File Manager and use "Extract" there, then move the contents to the right place.

O envio provavelmente ficou incompleto ou corrompido. Confira: (1) seu programa de FTP está em modo Binário ou Auto, nunca ASCII (o ASCII estraga MP3/PNG); (2) o envio não parou no meio; a pasta assets/ tem muitos arquivos, então é comum a transferência dar timeout. Uma alternativa segura é enviar o zip de game/ pelo Gerenciador de Arquivos da hospedagem e usar "Extrair" lá, depois mover o conteúdo para o lugar certo.

The browser says "Not secure"O navegador diz "Não seguro"

Turn on the free SSL certificate in your host panel (look for "SSL", "Let's Encrypt" or "Force HTTPS") and open the site with https://. Without HTTPS, "Add to home screen" and some audio features do not work.

Ative o certificado SSL gratuito no painel da hospedagem (procure "SSL", "Let's Encrypt" ou "Forçar HTTPS") e abra o site com https://. Sem HTTPS, "Adicionar à tela inicial" e alguns recursos de áudio não funcionam.

I use Cloudflare or a CDN and my changes do not appearUso Cloudflare ou CDN e as mudanças não aparecem

Purge the cache in the CDN panel ("Purge everything" on Cloudflare), then hard refresh the browser. While you are testing you can turn on Cloudflare's "Development Mode".

Limpe o cache no painel da CDN ("Purge everything" na Cloudflare) e depois atualize o navegador à força. Durante os testes você pode ligar o "Development Mode" da Cloudflare.

Can I put it in a sub-folder or on a sub-domain?Posso colocar numa subpasta ou subdomínio?

Yes. All paths are relative, so it works at the root, in a sub-folder (/ricopop/) or on a sub-domain.

Pode. Todos os caminhos são relativos, então funciona na raiz, numa subpasta (/ricopop/) ou num subdomínio.

Can I embed it in a WordPress page or another website?Posso incorporar numa página do WordPress ou em outro site?

The simplest way is to upload the game to its own folder and link to it. To show it inside a page, use an iframe, ideally on the same domain (progress is saved per address, see below):

<iframe src="https://yoursite.com/ricopop/" allow="autoplay; fullscreen"
  style="width:100%;height:90vh;border:0"></iframe>

O jeito mais simples é enviar o jogo para uma pasta própria e linkar para ela. Para mostrar dentro de uma página, use um iframe, de preferência no mesmo domínio (o progresso é salvo por endereço, veja abaixo):

<iframe src="https://seusite.com/ricopop/" allow="autoplay; fullscreen"
  style="width:100%;height:90vh;border:0"></iframe>
Can players install it like an app?Os jogadores podem instalar como um aplicativo?

It can be added to the home screen and then opens full screen like an app (iPhone: Safari → Share → "Add to Home Screen"; Android: Chrome menu → "Add to Home screen"), but this edition is not an offline app: it needs an internet connection to load.

Pode ser adicionado à tela inicial e então abre em tela cheia como um app (iPhone: Safari → Compartilhar → "Adicionar à Tela de Início"; Android: menu do Chrome → "Adicionar à tela inicial"), mas esta edição não é um app offline: precisa de internet para carregar.

Can I publish it on Google Play, the App Store or game portals?Posso publicar na Google Play, App Store ou em portais de jogos?

This item is a web game. Wrapping it for the stores (Capacitor, Cordova, Trusted Web Activity…) or submitting it to game portals is possible in principle, but it is not included and not covered by support: each store and portal has its own rules, SDKs, signing and review. Check the license terms and the store rules before you plan it.

Este item é um jogo web. Empacotar para as lojas (Capacitor, Cordova, Trusted Web Activity…) ou enviar a portais de jogos é possível em princípio, mas não está incluído nem coberto pelo suporte: cada loja e portal tem regras, SDKs, assinatura e revisão próprios. Leia a licença e as regras da loja antes de planejar.

Which browsers and devices are supported?Quais navegadores e aparelhos são compatíveis?

Recent versions of Chrome, Edge, Firefox and Safari on computers, Android phones and iPhone/iPad. The game uses canvas and a little WebGL for its glow effects. Internet Explorer is not supported. If something looks broken on an old device, update the browser first and try turning off "Glow effects" in Settings.

Versões recentes do Chrome, Edge, Firefox e Safari em computadores, celulares Android e iPhone/iPad. O jogo usa canvas e um pouco de WebGL nos efeitos de brilho. O Internet Explorer não é compatível. Se algo estiver quebrado num aparelho antigo, atualize o navegador primeiro e tente desligar "Glow effects" (efeitos de brilho) em Ajustes.

Playing & soundJogando e som

There is no soundNão tem som

Browsers only allow sound after the first tap or click, so tap anywhere once. On iPhone, also check the silent switch and the volume. Check Settings (gear) that Music, Effects and Voice are on.

Os navegadores só liberam som depois do primeiro toque ou clique, então toque em qualquer lugar uma vez. No iPhone, confira também a chave de silêncio e o volume. Veja em Configurações (engrenagem) se Música, Efeitos e Narrador estão ligados.

The sound stops after switching apps (iPhone)O som para depois de trocar de aplicativo (iPhone)

iOS pauses web audio when you leave the page. The game restores it when you come back; if it does not, tap the screen once. Also check that the phone is not in silent or Low Power mode.

O iOS pausa o áudio da página quando você sai dela. O jogo o restaura ao voltar; se não voltar, toque na tela uma vez. Confira também se o celular não está no modo silencioso ou de economia de bateria.

The narrator speaks the wrong languageO narrador fala no idioma errado

The narrator has recordings in English, Portuguese and Spanish, and follows the language chosen in Settings. In the other 11 languages the text is translated but the narrator speaks English: that is expected. To switch her off, see "Remove the narrator" in "Make it yours".

O narrador tem gravações em inglês, português e espanhol e segue o idioma escolhido em Ajustes. Nos outros 11 idiomas o texto é traduzido, mas o narrador fala em inglês: isso é esperado. Para desligá-lo, veja "Tirar o narrador" em "Personalizar".

The game is slow or stutters on an old phoneO jogo fica lento ou trava num celular antigo

Update the browser, close other tabs and apps, and turn off battery-saver / Low Power mode (it limits animations). Try turning off "Glow effects" in Settings. The game uses no heavy 3D, but very old devices can still struggle. If it is only slow on your site and not on the demo, check your host's speed and that the files are served with compression (gzip/brotli).

Atualize o navegador, feche outras abas e aplicativos e desligue a economia de bateria (ela limita animações). Tente desligar "Glow effects" (efeitos de brilho) em Ajustes. O jogo não usa 3D pesado, mas aparelhos muito antigos ainda podem sofrer. Se só está lento no seu site e não na demonstração, confira a velocidade da hospedagem e se os arquivos são servidos com compressão (gzip/brotli).

A player's progress disappeared or is different on another deviceO progresso de um jogador sumiu ou é diferente em outro aparelho

Progress is saved in each browser, per address. It is separate on every device and browser, and also between http and https, www and non-www, and sub-domains. It is lost when the player clears site data or uses a private window. There are no accounts to sync it. Tip: pick your final address before launch and redirect the others to it, so players do not "lose" progress when the address changes.

O progresso fica salvo em cada navegador, por endereço. É separado em cada aparelho e navegador, e também entre http e https, www e sem www, e subdomínios. Some quando o jogador limpa os dados do site ou usa janela anônima. Não há contas para sincronizar. Dica: escolha o endereço final antes do lançamento e redirecione os outros para ele, para o jogador não "perder" o progresso quando o endereço mudar.

How do I reset my own progress for testing?Como zerar o meu progresso para testar?

Clear the site data in your browser (Settings → Privacy → Site data), or use a private window.

Limpe os dados do site no navegador (Configurações → Privacidade → Dados do site), ou use uma janela anônima.

How do I test a specific level quickly?Como testo uma fase específica rapidamente?

Add ?level=7 (or any number from 1 to 50) to the address: the game opens straight on that level. Progress is saved as usual, so use a private window if you do not want to change your own saved game.

Acrescente ?level=7 (ou qualquer número de 1 a 50) ao endereço: o jogo abre direto nessa fase. O progresso é salvo normalmente, então use uma janela anônima se não quiser mexer no seu próprio jogo salvo.

I replaced something but still see the old versionTroquei um arquivo e ainda vejo a versão antiga

Do a hard refresh (Ctrl/Cmd + Shift + R). If it persists, your host or CDN is caching the old file: purge the CDN cache (see the Cloudflare question above) or ask the host to clear its cache. This edition has no service worker, so there is no hidden offline cache.

Faça a atualização forçada (Ctrl/Cmd + Shift + R). Se persistir, a hospedagem ou a CDN está guardando o arquivo antigo: limpe o cache da CDN (veja a pergunta sobre Cloudflare acima) ou peça à hospedagem para limpar o cache. Esta edição não tem service worker, então não existe cache offline escondido.

Levels, styles & contentFases, visuais e conteúdo

How many levels are there? Is there an ending?Quantas fases existem? Tem um final?

50 levels in 10 chapters of 5. Each level gives up to 3 stars (150 in total) depending on how few volleys you need, and six ball styles unlock as stars are collected. After level 50 the game shows a champion screen with the player's total.

50 fases em 10 capítulos de 5. Cada fase dá até 3 estrelas (150 no total) conforme o número de rajadas necessárias, e seis visuais de bola são liberados conforme as estrelas. Depois da fase 50 o jogo mostra uma tela de campeão com o total do jogador.

How do I change a level or add my own?Como mudo uma fase ou crio as minhas?

Levels are text maps in src/levels.js: 7 columns per row, . is empty, a number is a crystal with that much health, R8 is a reinforced crystal and C is an explosive core (the file header explains everything). After changing a map, raise that level's v number (old records of that level stop counting) and run node tools/validate.mjs --solve 12 from the developer kit to find a winning solution for level 12. Your AI assistant can do this with you: use the prompt at the end of this page.

As fases são mapas em texto no src/levels.js: 7 colunas por linha, . é vazio, um número é um cristal com essa vida, R8 é um cristal reforçado e C é um núcleo explosivo (o cabeçalho do arquivo explica tudo). Depois de mudar um mapa, aumente o número v daquela fase (os recordes antigos dela deixam de valer) e rode node tools/validate.mjs --solve 12 no kit de desenvolvedor para achar uma solução vencedora da fase 12. Sua IA pode fazer isso com você: use o prompt no fim desta página.

Can I change the number of balls, the speed or the scoring?Posso mudar o número de bolas, a velocidade ou a pontuação?

Yes: src/sim/config.js has BALLS (balls per volley, now 10), SPEED and the PTS_* scoring values. Careful: the levels were designed and checked with the current values, so after changing them run node tools/validate.mjs to see which levels are still winnable. Also change $MAX_TOTAL in ranking.php if you raise the scoring a lot.

Pode: o src/sim/config.js tem BALLS (bolas por rajada, hoje 10), SPEED e os valores de pontuação PTS_*. Cuidado: as fases foram desenhadas e conferidas com os valores atuais, então depois de mudar rode node tools/validate.mjs para ver quais fases ainda têm solução. Mude também o $MAX_TOTAL no ranking.php se aumentar muito a pontuação.

Can I rename the game, change the colors or the logo?Posso trocar o nome do jogo, as cores ou o logo?

Yes. The page title and icons are plain files (see "Make it yours"). The name inside the menus and the level names are texts in src/locales.js, colors are in style.css, and the RICOPOP logo is drawn by code in src/ui/logo.js, so changing it is a small coding job: a good one for the AI prompt at the end of this page. Some narrator recordings pronounce the game's name: remove the narrator (see "Make it yours") or re-record them if you rename it.

Pode. O título da página e os ícones são arquivos simples (veja "Personalizar"). O nome dentro dos menus e os nomes das fases são textos no src/locales.js, as cores estão no style.css, e o logo RICOPOP é desenhado por código em src/ui/logo.js, então trocá-lo é um pequeno trabalho de programação: um bom pedido para o prompt de IA no fim desta página. Algumas falas do narrador pronunciam o nome do jogo: tire o narrador (veja "Personalizar") ou regrave se você trocar o nome.

Can I add another language, or fix a translation?Posso adicionar outro idioma, ou corrigir uma tradução?

Yes. All texts are in src/locales.js. To fix a text, edit it in that language's block. To add a language, copy the whole en block, translate it, and register the new code in the LANGS, HTML_LANG and NUMBER_LOCALE lists at the top of the file (if you run the tests, update the "14 languages" number in test/i18n.test.mjs). Any text missing in a language simply shows in English. The narrator will speak English in the new language.

Pode. Todos os textos estão no src/locales.js. Para corrigir um texto, edite no bloco daquele idioma. Para adicionar um idioma, copie o bloco en inteiro, traduza e registre o novo código nas listas LANGS, HTML_LANG e NUMBER_LOCALE no topo do arquivo (se rodar os testes, atualize o número "14 idiomas" em test/i18n.test.mjs). Qualquer texto que faltar num idioma aparece em inglês. O narrador falará inglês no idioma novo.

I found a wrong or odd translationAchei uma tradução errada ou estranha

The 14 languages were produced with AI assistance and have not all been reviewed by native speakers, so some wording can be improved. Please tell us the language and the text (see the report above), or fix it yourself in src/locales.js as described in the previous question.

Os 14 idiomas foram produzidos com auxílio de IA e nem todos foram revisados por falantes nativos, então algumas frases podem melhorar. Avise o idioma e o texto (veja o relato acima), ou corrija você mesmo no src/locales.js como na pergunta anterior.

Ads & earningsAnúncios e ganhos

Ads do not showOs anúncios não aparecem

Check: provider is 'adsense'; adsenseClient looks like ca-pub-1234567890123456; your site is approved by AdSense for Games (interstitial/rewarded); you are not using an ad blocker; the site is on HTTPS. Interstitials only appear when a new level starts, from level 2 on, at least 2 levels and 2.5 minutes after the previous one, so play a few levels before judging. Keep testMode: true while testing. To see where ads would appear without any ad account, use provider: 'demo'. Press F12 → Console: a message starting with "[ricopop] Ads disabled" tells you what is wrong with the settings.

Confira: provider é 'adsense'; adsenseClient parece ca-pub-1234567890123456; o site foi aprovado no AdSense para Jogos (intervalo/recompensa); você não está com bloqueador de anúncios; o site está em HTTPS. Os anúncios de intervalo só aparecem quando uma fase nova começa, da fase 2 em diante, com pelo menos 2 fases e 2,5 minutos desde o anterior, então jogue algumas fases antes de concluir. Deixe testMode: true enquanto testa. Para ver onde os anúncios apareceriam sem nenhuma conta, use provider: 'demo'. Aperte F12 → Console: uma mensagem começando com "[ricopop] Ads disabled" mostra o que está errado nas configurações.

AdSense says my site is not ready, or rejected itO AdSense disse que meu site não está pronto, ou recusou

Approval is decided by Google, not by this item, and support cannot speed it up. Sites are usually reviewed more favourably with their own domain, a privacy policy, a contact page, and some real content and traffic. Games (interstitial and rewarded ads) also need the separate AdSense for Games approval. While you wait, leave provider: 'none', or use another network through the custom adapter (see Ads).

A aprovação é decidida pelo Google, não por este item, e o suporte não consegue acelerá-la. Os sites costumam ser avaliados melhor com domínio próprio, política de privacidade, página de contato e algum conteúdo e tráfego reais. Jogos (anúncios de intervalo e com recompensa) também precisam da aprovação separada do AdSense para Jogos. Enquanto espera, deixe provider: 'none', ou use outra rede pelo adaptador custom (veja Anúncios).

Ads show but I earn nothingOs anúncios aparecem mas não ganho nada

With testMode: true Google serves test ads that pay nothing. After your site is approved and everything works, set testMode: false and upload the file. Earnings also depend on traffic, visitors' countries and ad blockers, and new accounts take a few days to show numbers. Nobody can promise a figure.

Com testMode: true o Google mostra anúncios de teste, que não pagam. Depois que o site for aprovado e tudo estiver funcionando, coloque testMode: false e envie o arquivo. Os ganhos dependem também do tráfego, do país dos visitantes e de bloqueadores, e contas novas levam alguns dias para mostrar números. Ninguém pode prometer um valor.

AdSense asks for an ads.txt fileO AdSense pede um arquivo ads.txt

Create a text file named ads.txt in the root of the domain (even if the game is in a sub-folder) with the line AdSense shows you. It looks like this (use your own ID, without ca-):

google.com, pub-1234567890123456, DIRECT, f08c47fec0942fa0

Crie um arquivo de texto chamado ads.txt na raiz do domínio (mesmo que o jogo esteja numa subpasta) com a linha que o AdSense mostra. Ela é assim (use o seu ID, sem o ca-):

google.com, pub-1234567890123456, DIRECT, f08c47fec0942fa0
Do I need a privacy policy or a cookie/consent banner?Preciso de política de privacidade ou de aviso de cookies/consentimento?

If you show ads, ad networks normally require a privacy policy page on your site, and visitors from the EU/UK and some other regions must be asked for consent. The game itself includes neither. In AdSense you can switch on Google's free consent message (look for "Privacy & messaging"). For your policy, the facts are: progress is stored on the player's device; the optional leaderboard stores a nickname, a total score and a hashed IP address; the ad network sets its own cookies. If your audience includes children, check your ad network's rules for child-directed content. This is general information, not legal advice: ask a professional for your country.

Se você mostra anúncios, as redes normalmente exigem uma página de política de privacidade no seu site, e visitantes da UE/Reino Unido e de algumas outras regiões precisam ser consultados sobre consentimento. O jogo em si não inclui nenhum dos dois. No AdSense você pode ativar a mensagem de consentimento gratuita do Google (procure "Privacidade e mensagens"). Para a sua política, os fatos são: o progresso fica no aparelho do jogador; o ranking opcional guarda apelido, pontuação total e um hash do IP; a rede de anúncios usa os próprios cookies. Se o seu público inclui crianças, confira as regras da rede de anúncios para conteúdo infantil. Isto é informação geral, não aconselhamento jurídico: consulte um profissional do seu país.

Ads appear too often, or I want to change whenOs anúncios aparecem demais, ou quero mudar quando aparecem

Edit ricopop.config.js: midgameEveryMs is the minimum time between interstitials in milliseconds (150000 = 2.5 minutes), minLevel is the first level that can show one, and midgame: false switches them off. rewarded: false hides the rewarded-video buttons. Fewer, well-placed ads usually keep players longer, which earns more over time.

Edite o ricopop.config.js: midgameEveryMs é o tempo mínimo entre anúncios de intervalo em milissegundos (150000 = 2,5 minutos), minLevel é a primeira fase que pode mostrar um, e midgame: false desliga. rewarded: false esconde os botões de vídeo com recompensa. Menos anúncios, bem colocados, costumam manter o jogador por mais tempo, o que rende mais ao longo do tempo.

Leaderboard (PHP)Ranking (PHP)

I do not want a leaderboard at allNão quero ranking nenhum

By default nothing is sent anywhere and the Ranking screen only shows the player's own best on that device. If you do not even want the Ranking button, set hide: true in the ranking block of ricopop.config.js. You may delete the api/ folder if you like.

Por padrão nada é enviado a lugar nenhum e a tela de Ranking mostra só o melhor do próprio jogador naquele aparelho. Se não quiser nem o botão de Ranking, use hide: true no bloco ranking do ricopop.config.js. Pode apagar a pasta api/ se quiser.

The Ranking shows only my own name and scoreO Ranking mostra só o meu nome e a minha pontuação

First: the online leaderboard is off by default (the screen says "Online leaderboard is off"). In ricopop.config.js make sure ranking has enabled: true, save, upload, and hard refresh. If it is already on, the game could not reach the PHP file. Open /api/ranking.php in the browser: it must show {"ok":true,"ranking":"ricopop",…}. If it shows PHP code or a 404, PHP is not running there or the api/ folder is missing. If "writable":false, fix the folder permission (see Leaderboard). Also check that ranking.url is './api/ranking.php'. Remember that a score is sent when a level is cleared.

Primeiro: o ranking online vem desligado (a tela diz "Online leaderboard is off"). No ricopop.config.js confira se ranking tem enabled: true, salve, envie e faça a atualização forçada. Se já estiver ligado, o jogo não conseguiu falar com o arquivo PHP. Abra /api/ranking.php no navegador: precisa mostrar {"ok":true,"ranking":"ricopop",…}. Se mostrar código PHP ou erro 404, o PHP não está rodando ali ou a pasta api/ não foi enviada. Se aparecer "writable":false, ajuste a permissão da pasta (veja Ranking). Confira também se ranking.url é './api/ranking.php'. Lembre que a pontuação é enviada quando uma fase é concluída.

Where do players type their nickname?Onde os jogadores digitam o apelido?

At the top of the Ranking screen ("Your name on the ranking"). It can be changed any time and, with the online leaderboard on, the new name also applies to the scores the player already has. A player who never types one appears as "Player 1234".

No alto da tela de Ranking ("Seu nome no ranking"). Pode ser trocado quando quiser e, com o ranking online ligado, o nome novo vale também para as pontuações que o jogador já tem. Quem nunca digitar um aparece como "Player 1234".

Why does the Today board show the same number as All time?Por que o placar de Hoje mostra o mesmo número do Geral?

The leaderboard score is the total of the best score of every level. "Today" and "Month" list the players who cleared a level in that period, with their total at that moment; "All time" lists everyone with their highest total. A player who only plays levels they already beat does not move up.

A pontuação do ranking é o total do melhor resultado de cada fase. "Hoje" e "Mês" listam os jogadores que concluíram uma fase naquele período, com o total deles naquele momento; "Geral" lista todos com o maior total. Quem só joga fases que já venceu não sobe.

Opening ranking.php shows a 500 error or a blank pageAbrir o ranking.php dá erro 500 ou página em branco

Most likely the PHP version is too old. The file needs PHP 7.4 or newer. In your host panel look for "PHP version" / "Select PHP Version" and choose 7.4, 8.0 or later. If it persists, read your host's error_log and send me the last line.

O mais provável é a versão do PHP ser antiga. O arquivo precisa do PHP 7.4 ou mais novo. No painel da hospedagem procure "Versão do PHP" / "Selecionar versão do PHP" e escolha 7.4, 8.0 ou mais. Se continuar, leia o error_log da hospedagem e me envie a última linha.

The scores disappeared after I updated the gameOs pontos sumiram depois que atualizei o jogo

The scores live in api/ranking-data.php. If you delete the api/ folder or overwrite that file when updating, they are gone. Before every update, download a copy of that file. Then upload the new files over the old ones, without deleting the folder first.

Os pontos ficam em api/ranking-data.php. Se você apagar a pasta api/ ou sobrescrever esse arquivo ao atualizar, eles se perdem. Antes de cada atualização, baixe uma cópia desse arquivo. Depois envie os arquivos novos por cima dos antigos, sem apagar a pasta antes.

How do I remove a player (cheater or bad nickname)?Como removo um jogador (trapaceiro ou apelido inadequado)?

Nicknames are not filtered automatically. Download api/ranking-data.php, open it in a plain text editor (not Word), keep the first line (<?php … ?>) and, inside "players", delete the whole entry whose "n" is that nickname (from its long id to the closing }, mind the commas). Upload it back. To start from zero, delete the file; it is recreated on the next match. Always keep a backup.

Os apelidos não são filtrados automaticamente. Baixe o api/ranking-data.php, abra num editor de texto simples (não no Word), mantenha a primeira linha (<?php … ?>) e, dentro de "players", apague a entrada inteira cujo "n" é aquele apelido (do id longo até o } que fecha, cuidando das vírgulas). Envie de volta. Para começar do zero, apague o arquivo; ele é recriado na próxima partida. Mantenha sempre um backup.

When do the Today / Month boards reset?Quando os placares Hoje / Mês zeram?

At midnight in the time zone set by $TIMEZONE in ranking.php (the month on its 1st day). "All time" never resets.

À meia-noite no fuso definido em $TIMEZONE no ranking.php (o mês, no dia 1º). "Geral" nunca zera.

Honest players are not countedJogadores honestos são barrados por "muitas partidas" ou não pontuam

If many players share one IP (a school, a company, or a proxy in front of your site) they share the per-hour limit. Raise $MAX_PER_IP_HOUR at the top of ranking.php. Submissions closer together than $MIN_SECONDS are ignored on purpose. Behind Cloudflare the real visitor IP is read automatically.

Se muitos jogadores compartilham um IP (escola, empresa ou um proxy na frente do seu site), eles dividem o limite por hora. Aumente $MAX_PER_IP_HOUR no topo do ranking.php. Envios mais próximos que $MIN_SECONDS são ignoradas de propósito. Atrás da Cloudflare o IP real do visitante é lido automaticamente.

Is the leaderboard cheat-proof?O ranking é à prova de fraude?

No: levels run in the browser and this edition trusts the total it receives (within the limits in ranking.php), so it is meant for casual leaderboards (see the note in Leaderboard). A cheat-resistant leaderboard needs a server that re-plays the levels, which is a different, custom job: see Need custom work?

Não: as fases rodam no navegador e esta edição confia no total que recebe (dentro dos limites do ranking.php), então serve para rankings casuais (veja o aviso em Ranking). Um ranking resistente a fraude exige um servidor que refaça as fases, que é outro trabalho, sob medida: veja Quer algo sob medida?

Updates, license & supportAtualizações, licença e suporte

How do I update to a new version without losing my settings?Como atualizo para uma nova versão sem perder as minhas configurações?

1) Download your own ricopop.config.js, api/ranking-data.php and ads.txt as a backup. 2) Upload the new game/ contents over the old ones. 3) Put your ricopop.config.js back (or copy your values into the new one). 4) Hard refresh. If you changed the source code, compare your edits with the new files before replacing them.

1) Baixe o seu ricopop.config.js, o api/ranking-data.php e o ads.txt como backup. 2) Envie o conteúdo novo de game/ por cima do antigo. 3) Devolva o seu ricopop.config.js (ou copie seus valores para o novo). 4) Atualização forçada. Se você alterou o código-fonte, compare suas alterações com os arquivos novos antes de substituir.

Which license do I need? Can I charge players or resell it?Qual licença eu preciso? Posso cobrar dos jogadores ou revender?

Envato licenses are per project. The Regular License is for a single end product that end users are not charged for; the Extended License is for a single end product that users can be charged for (for example paid access or subscriptions). You may not resell, share or redistribute the files themselves, and each website or project needs its own license. Read the exact terms at codecanyon.net/licenses; if in doubt, ask Envato before you buy.

As licenças da Envato são por projeto. A Regular License é para um único produto final pelo qual os usuários não pagam; a Extended License é para um único produto final pelo qual os usuários podem ser cobrados (por exemplo acesso pago ou assinaturas). Você não pode revender, compartilhar nem redistribuir os arquivos em si, e cada site ou projeto precisa da própria licença. Leia os termos exatos em codecanyon.net/licenses; na dúvida, pergunte à Envato antes de comprar.

What does support include, and what does it not?O que o suporte inclui, e o que não inclui?

Included: questions about how the item works and how to install it, and fixes for bugs in the delivered game. Not included: custom changes and new features, problems caused by edits you made, your hosting, domain or DNS settings, third-party services (such as the AdSense approval), and store publishing. Item support runs for the period shown on the item page and can be extended there. Requests are answered in the order received, on business days. If you need more, see Need custom work?

Incluído: dúvidas sobre como o item funciona e como instalá-lo, e correção de erros do jogo entregue. Não incluído: alterações sob medida e funções novas, problemas causados por edições suas, as configurações da sua hospedagem, domínio ou DNS, serviços de terceiros (como a aprovação do AdSense) e publicação em lojas. O suporte do item vale pelo período mostrado na página do item e pode ser estendido lá. Os pedidos são respondidos na ordem de chegada, em dias úteis. Se precisar de mais, veja Quer algo sob medida?

It broke after I edited a fileQuebrou depois que editei um arquivo

Put the original file back from the package and check that it works again, then repeat your change in small steps. Editors like Word add invisible characters: use a code/text editor (VS Code, Notepad++). A missing quote or comma in ricopop.config.js is the most common cause: the console (F12) shows a "SyntaxError" with the line. Your AI assistant can find it quickly if you paste the file and the error.

Devolva o arquivo original do pacote e confira se voltou a funcionar, depois refaça a sua alteração em pequenos passos. Editores como o Word colocam caracteres invisíveis: use um editor de código/texto (VS Code, Notepad++). Uma aspa ou vírgula faltando no ricopop.config.js é a causa mais comum: o console (F12) mostra um "SyntaxError" com a linha. Sua IA acha rápido se você colar o arquivo e o erro.

Where do I ask for a refund, or suggest a feature?Onde peço reembolso, ou sugiro uma novidade?

Refunds are handled by Envato under its refund policy (your Downloads page on CodeCanyon). Feature ideas are welcome in the item comments and may appear in future updates; for a feature you need now, see Need custom work?

Reembolsos são tratados pela Envato conforme a política de reembolso dela (na sua página de Downloads na CodeCanyon). Ideias de novidades são bem-vindas nos comentários do item e podem entrar em atualizações futuras; para uma função de que você precisa agora, veja Quer algo sob medida?

9Support & creditsSuporte e créditos

Support covers installation questions and bugs in the delivered game, through the item page where you bought it. Custom changes are not included, but the section below helps you (or your AI assistant) make them.

O suporte cobre dúvidas de instalação e erros do jogo entregue, pela página do item onde você comprou. Alterações sob medida não estão incluídas, mas a seção abaixo ajuda você (ou a sua IA) a fazê-las.

License: your use of this item is governed by the Envato license you purchased.

Licença: o uso deste item segue a licença Envato que você comprou.

CreditsCréditos

  • Font Chakra Petch (SIL Open Font License; the license file is in assets/fonts/).
  • Fonte Chakra Petch (SIL Open Font License; o arquivo da licença está em assets/fonts/).
  • Characters, crystals, artwork and interface are original to this item. The game has no third-party code libraries.
  • Personagem, cristais, ilustrações e interface são originais deste item. O jogo não usa bibliotecas de código de terceiros.
  • Sound effects and the narrator's voices were generated with ElevenLabs (the prompts are in assets/audio-manifest.json).
  • Os efeitos sonoros e as vozes do narrador foram gerados com o ElevenLabs (os prompts estão em assets/audio-manifest.json).

★For AI assistantsPara assistentes de IA

Using ChatGPT, Claude, Gemini or Copilot to install or customize the game? Copy the prompt below and paste it into your assistant. The technical brief after it contains everything it needs to know.

Vai usar o ChatGPT, Claude, Gemini ou Copilot para instalar ou personalizar o jogo? Copie o prompt abaixo e cole no seu assistente. O resumo técnico logo depois traz tudo o que ele precisa saber.

You are helping me install and customize "RICOPOP", an HTML5 ricochet arcade game I bought (a static website: no backend, no build step). Answer in the same language I write in. Be concrete, give exact file paths and complete file contents when I must edit something, and never invent features that are not described below.

PROJECT BRIEF
- Product: RICOPOP — solo ricochet arcade, plain HTML + CSS + JavaScript ES modules + Canvas (no framework, no bundler). 50 levels in 10 chapters, 6 ball skins, 14 interface languages (narrator voices only in en/pt/es). No online multiplayer in this package.
- Deliverable layout: game/ (upload to the web host), documentation/index.html, source/ (optional developer tools: package.json, tools/, test/, README-DEV.md — they must be copied next to game/index.html on the developer's computer; they are not for the server).
- The files in game/ ARE the source: index.html (all screens as DOM, ids like scr-title, scr-levels, scr-skins, scr-rank, scr-results), style.css, manifest.webmanifest, ricopop.config.js (buyer settings), src/, assets/, api/ranking.php.
- Install: upload the CONTENTS of game/ to any web host (root or sub-folder; HTTPS recommended). Do not open via file:// (ES modules are blocked). All paths are relative. There is no service worker, so changes need only a hard refresh.
- Settings live only in game/ricopop.config.js (a classic script loaded before the game; edit without rebuilding):
  window.RICOPOP_CONFIG = { ads: { provider: 'none'|'adsense'|'custom'|'demo', adsenseClient: 'ca-pub-…', testMode: true, rewarded: true, midgame: true, minLevel: 2, midgameEveryMs: 150000 }, tapToStart: true, fullscreen: true, ranking: { enabled: false, hide: false, url: './api/ranking.php' } }
  - provider 'custom' expects window.RICOPOP_AD_PROVIDER = { interstitial(): Promise<void>, rewarded(): Promise<boolean> } defined after the config block. 'demo' shows a fake 3-second ad (for testing the flow). With 'none' no ad code or request exists.
  - Ads: interstitial when a new level starts (from minLevel, at least 2 levels and midgameEveryMs since the last ad, never during play); rewarded "one more chance" after failing a level (that win does not count for records/leaderboard) and rewarded skin unlock ("Ad Unlock"). rewarded:false hides both.
  - ranking.enabled (default false) turns the online leaderboard on; false = a private "your best on this device" board in localStorage and no request to api/. ranking.hide:true removes the Ranking button. ranking.url '' also disables the online mode.
- Leaderboard (api/ranking.php, PHP 7.4+, no database): GET (no params) = health {ok,ranking:'ricopop',writable,php,timezone}; GET ?period=day|week|month|all&limit=50&pid=… = {ok,period,resetsAt,total,entries[{rank,name,score,me}],me:{rank,score}}; POST JSON {action:'submit',pid,name,total} = {ok,name,score,day,week,month,all:{rank,score}} or {action:'name',pid,name}. Score = sum of the best score of each level (sent when a level is cleared). Data file api/ranking-data.php (JSON behind a PHP guard line). Settings at the top: $TIMEZONE, $MAX_TOTAL, $MIN_SECONDS, $MAX_PER_IP_HOUR, $TOP. It is not cheat-proof (the total comes from the browser).
- Browser storage keys: ricopop.save (progress), ricopop.settings, ricopop.lang, ricopop.nick, ricopop.rank.pid, ricopop.rank.name, ricopop.rank.local.v1.

CODE MAP
- src/main.js: boot, screens, settings, ranking UI, ads flow, main loop. src/game.js: level controller (input → simulation → events → sound/visual). src/sim/*: deterministic fixed-step simulation at 120 Hz (config.js = tuning and scoring, sim.js, physics.js, replay.js, verify.js, dmath.js). src/levels.js: the 50 levels. src/save.js: progress, stars, skins unlocking. src/render/*: canvas view, sprites, post effects (WebGL glow), palette.js (SKINS and the stars each needs). src/ui.js + src/ui/logo.js (the logo is drawn by code). src/audio/sound.js: WebAudio, reads assets/audio-manifest.json. src/i18n.js + src/locales.js: 14 languages, English is the fallback, elements use data-i18n attributes. src/input.js. src/storage.js. src/platform.js: ads adapter. src/ranking.js: leaderboard client.
- Levels (src/levels.js): { id, v, par, map: [rows of 7 cells separated by spaces], pulse: {enabled}, waves?, witness: [volleys] }. Cell tokens: '.' empty, 'N' = common crystal with N health (e.g. 3, N12), 'R8' reinforced crystal with 8 health, 'C' explosive core ('C4' = 4 health). waves = extra rows that fall in one per volley. witness = a winning sequence of volleys [angle in hundredths of a degree (9000 = straight up), uses Pulse 0|1, End Shot step or -1], checked by the real simulation. When a map changes: raise its v (old records of that level stop counting) and run node tools/validate.mjs --solve <n> (developer kit, Node 20+) to find a new witness. node tools/validate.mjs checks all levels (takes minutes); node --test test/*.test.mjs runs the tests.
- Changing sim/config.js values (BALLS, SPEED, PTS_*) can make levels unwinnable: re-run validate. Raise $MAX_TOTAL in ranking.php if scoring grows a lot.
- Texts: add/fix in src/locales.js (copy the whole en block for a new language and register it in LANGS, HTML_LANG, NUMBER_LOCALE; test/i18n.test.mjs expects 14). Missing keys fall back to English.
- Branding: index.html (<title>, meta), manifest.webmanifest, assets/icons/*, style.css, src/ui/logo.js. Remove narrator: delete assets/voice/ and set "voice" and "voices" to {} in assets/audio-manifest.json. Replace music: same file names in assets/music/ and update "dur" (seconds) in the manifest.
- URL options for testing: ?lang=pt, ?level=7, ?nosplash, ?debug (exposes window.__ricopop), ?ads=none.

RULES FOR YOU
1. Do not suggest adding multiplayer, accounts or a backend; this is a static game.
2. Prefer editing game/ricopop.config.js for ads/leaderboard changes. Do not add a build step or a framework unless I ask.
3. For anything involving ads, remind me that AdSense for Games needs Google approval and that I am responsible for the cookie/consent notice in my region.
4. If I need something this static package cannot do (Node/VPS servers, online multiplayer, a cheat-resistant leaderboard, big custom features) and I cannot do it myself, tell me the author takes freelance work: willian@polargames.com.br · https://polargames.com.br
5. Before suggesting a fix, ask me for: where it is hosted (shared/VPS/Netlify…), the exact URL, and any red errors from the browser console (F12).

MY REQUEST:
[describe here what you want to do]
Technical brief (human-readable)Resumo técnico (para humanos)

The prompt above is the technical brief. In short: the game is plain HTML/CSS/JavaScript with no build step. Buyer settings are in ricopop.config.js; levels are text maps in src/levels.js; texts are in src/locales.js; the optional leaderboard is a single PHP file with a JSON store. There is no server-side code to maintain.

O prompt acima é o resumo técnico. Em poucas palavras: o jogo é HTML/CSS/JavaScript simples, sem etapa de compilação. As configurações do comprador ficam no ricopop.config.js; as fases são mapas em texto no src/levels.js; os textos estão no src/locales.js; o ranking opcional é um único arquivo PHP com armazenamento em JSON. Não há código de servidor para manter.

✉Need something custom? I'm availableQuer algo sob medida? Estou disponível

I'm Willian, from Polar Games. I build browser games for a living and I take freelance work. If you want to go beyond this package, I can help with:

Eu sou o Willian, da Polar Games. Eu crio jogos para navegador e aceito trabalhos freelance. Se você quer ir além deste pacote, posso ajudar com:

Servers & multiplayerServidores e multiplayerNode.js / WebSocket servers, online rooms, VPS setup and deployment.Servidores Node.js / WebSocket, salas online, configuração e publicação em VPS.
LeaderboardsRankingsA cheat-resistant online leaderboard that re-plays the levels on the server, with a database, seasons and rewards.Ranking online mais resistente a fraude, que refaz as fases no servidor, com banco de dados, temporadas e prêmios.
Changes to this gameAlterações neste jogoNew levels and chapters, ball styles, languages, themes, rebranding, other ad networks, new features.Novas fases e capítulos, visuais de bola, idiomas, temas, nova identidade visual, outras redes de anúncio, novos recursos.
Your own gameO seu próprio jogoCustom browser games, integration into your site, publishing on game portals.Jogos para navegador sob medida, integração ao seu site, publicação em portais de jogos.

Want a quote? Send me a short description of what you need and your website (if you have one) to willian@polargames.com.br, or visit polargames.com.br.

Quer um orçamento? Me mande uma breve descrição do que precisa e o seu site (se tiver) para willian@polargames.com.br, ou visite polargames.com.br.

Custom work is a separate paid service and is not part of the support that comes with the item.

O trabalho sob medida é um serviço pago à parte e não faz parte do suporte que acompanha o item.