Código-fonte de jogo de minigolfe: buracos, física e mapa dos cursos 3D

Um código-fonte de jogo de minigolfe se prova numa tarefa só: criar um buraco novo. Quem quer um percurso com a marca do cliente, uma fase de Natal ou um logotipo no green abre primeiro os arquivos de fase, e se o buraco estiver enterrado no código do motor, o projeto empaca. No Puttide, nosso template de minigolfe 3D, cada percurso tem o próprio arquivo de buracos em JavaScript simples, e o manual explica como criar um.

Este guia segue o pacote do jeito que um desenvolvedor encontra: as pastas, as bibliotecas, os arquivos dos percursos, a ordem das mudanças, a hospedagem e a licença. Os nomes de arquivo vêm do manual que acompanha o jogo.

Resposta curta para quem tem pressa: o Puttide é JavaScript formatado, com Three.js para o desenho e Rapier para a física da bola, os dois já incluídos. Sem build, sem CDN e sem código de servidor.

O que vem no código-fonte do jogo de minigolfe

O Puttide é um jogo pronto com 30 buracos em cinco percursos de ilha: Sunlit Ruins, Lantern Pier, Frost Peaks, Cloud Garden e Volcano Forge, seis buracos cada. Rampas, portais, bumpers e moinhos transformam os buracos em pequenos quebra-cabeças. Cada buraco dá três estrelas (terminar, fazer o par ou menos e achar a moeda escondida), e medalhas de bronze, prata e ouro premiam as melhores voltas.

Além dos percursos, há um desafio diário com uma variação (vento, green congelado, bola pesada, paredes saltitantes, chuva de moedas ou caça ao birdie), um armário onde as moedas compram bolas, rastros e outros visuais, e partidas de dois a quatro jogadores revezando no mesmo aparelho. A interface vem em 14 idiomas.

• game/: a versão pronta para enviar, a única pasta que você publica.
• source/: o mesmo jogo como edição de desenvolvimento, com README e package.json.
• documentation/: um manual ilustrado em inglês e português.
• THIRD-PARTY-LICENSES/: licenças das bibliotecas e das fontes.
• Versão 1.1.0, atualizada em 22 de outubro de 2026.

Abrir a página do Puttide: demo, manual e preço

Three.js, Rapier e o resto da tecnologia

A bola é simulada pelo Rapier 3D 0.21.0, que roda como WebAssembly, e a cena é desenhada com o Three.js r186. Os dois ficam em lib/three/ e lib/rapier/ com as licenças, e o index.html tem um import map que aponta o jogo para eles. O manual avisa que os arquivos das bibliotecas não tiveram o comportamento alterado; só foram formatados para leitura.

Isso importa por dois motivos. Primeiro, nada é carregado de CDN, então um portal ou um cliente com política de segurança rígida só precisa do seu servidor. Segundo, atualizar uma biblioteca é um passo manual e consciente: o source/package.json lista as versões exatas, e você copia os novos arquivos de módulo por cima da pasta correspondente em lib/, mantendo os caminhos do import map.

• Three.js r186: licença MIT.
• Rapier 3D compat 0.21.0, com WebAssembly embutido: licença Apache-2.0.
• Fontes Rubik e Fredoka: SIL Open Font License 1.1.
• Duas músicas: music/menu.mp3 e music/play-1.mp3.

Onde ficam os buracos, as moedas e os textos

Os caminhos são iguais em source/ e game/. Os dados dos percursos estão divididos por ilha, o que deixa cada arquivo curto o bastante para ler de uma vez.

• src/course/courses.js: ordem dos percursos e requisitos para liberar cada um.
• src/course/holes.js: os buracos de Sunlit Ruins, com geometria, par e obstáculos.
• src/course/pier.js, ice.js, lava.js e sky.js: os buracos dos outros quatro percursos.
• src/sim/constants.js: ajuste da física.
• src/game/economy.js: bolas, rastros e roupas, com os preços.
• src/ui/i18n.js e arquivos irmãos: os dicionários dos 14 idiomas, incluindo nomes e dicas dos buracos.
• src/game/localRecords.js: recordes dos percursos guardados no navegador.
• src/audio/audio.js: efeitos e o mapeamento das músicas, em probeTracks.
• css/style.css: cores, fontes e estilos responsivos da interface.

Criando um buraco, passo a passo

É a mudança que a maioria dos compradores faz, e o manual descreve em poucas linhas. Aqui está na ordem que nós mesmos seguiríamos.

1. Escolha o arquivo do percurso onde o buraco vai entrar, por exemplo lava.js para o Volcano Forge.
2. Duplique um buraco existente parecido com o que você quer.
3. Dê um id único. Repetir um id bagunça o progresso salvo.
4. Defina o par, a posição de saída e a do buraco, depois mova ou troque os obstáculos.
5. Inclua o buraco no percurso em courses.js.
6. Coloque o nome e a dica nos dicionários de idioma, em todos os idiomas que você vai publicar.
7. Jogue: teste colisões, a volta da bola quando sai da pista e as três estrelas, inclusive a moeda escondida.

Edite em source/, copie os arquivos alterados para os mesmos caminhos em game/ e sirva a pasta por HTTP para testar. O package.json tem um script serve, ou você pode rodar python -m http.server 8765. O Node.js é opcional e só serve se você quiser usar o npm para gerenciar as versões das bibliotecas.

As outras mudanças, numa ordem que faz sentido

1. Marca e cores: logotipo, cores e fontes em css/style.css. White label é permitido, então a sua marca pode substituir a nossa.
2. Preços do armário: economy.js. Visuais baratos deixam um site casual mais simpático; caros esticam uma campanha longa.
3. Textos: frases e dicas nos arquivos i18n.
4. Música: as duas faixas incluídas podem ser trocadas por gravações que você tenha licença para usar. Copie o arquivo e atualize o mapeamento explícito em audio.js (probeTracks); a música de cada cena cai na faixa de jogo quando não há outra.
5. Física: constants.js, por último e em passos pequenos, porque cada buraco foi ajustado com os valores atuais.

Para um projeto parecido com a mesma linha de JavaScript simples, e sem nenhuma biblioteca 3D, o nosso template de sinuca é feito do mesmo jeito.

Velvet Pool: sinuca bola 8 em JavaScript puro e WebGL2

Sunset Rally: tênis de mesa 3D com campanha de nove partidas

Hospedagem, tipos MIME e apps

Envie tudo o que está dentro de game/ para uma pasta como public_html/puttide/, mantenha as subpastas e abra o endereço por HTTPS. No servidor não é preciso npm, PHP, banco de dados nem conta. Abrir o index.html direto do computador não funciona, porque o navegador bloqueia os módulos em file://.

O Puttide tem um detalhe de hospedagem que um jogo 2D não tem: a física roda em WebAssembly. O servidor precisa enviar .js com tipo MIME de JavaScript e .wasm como application/wasm. Se a hospedagem errar isso, aparece tela vazia ou erro de módulo, então confira no primeiro dia.

• O navegador precisa de JavaScript, módulos ES, WebAssembly e WebGL2.
• Em iframe de portal, permita tela cheia e autoplay.
• Em tela de toque: arrastar para mirar e tacar, dois dedos para girar a câmera, pinça para o zoom.
• Não é app offline instalável: cada carregamento novo acessa o seu servidor.

Projetos de app nativo não vêm no pacote. Se você planeja publicar numa loja, reserve orçamento para o empacotamento e para testes em celulares reais, porque um jogo 3D com física pesa mais que um jogo de cartas nos aparelhos antigos.

O que não vem, e a licença

Esta é a edição local para navegador: sem multiplayer ou salas online, sem ranking online, sem contas na nuvem, sem SDK de anúncios, sem apps nativos e sem hospedagem. Recordes, progresso diário e partidas no mesmo aparelho ficam no navegador do jogador, e nenhuma pontuação é enviada. O save pertence à origem do navegador, então mudar de domínio faz o jogador começar do zero.

O Puttide custa US$ 39 de tabela; até 30 de novembro de 2026 a promoção de Black Friday deixa por US$ 33,15, e comprar dois ou mais templates no mesmo pedido soma de 5% a 20% de desconto. A licença é perpétua e não exclusiva para um produto final, seu ou de um cliente. Você pode trocar a marca, mudar código, arte e áudio e deixar o jogador entrar de graça ou com anúncios, mas não pode revender o template ou o código sozinhos. O suporte dura seis meses, ou doze com a extensão; buracos sob encomenda, integrações e hospedagem são orçados a pedido.

Termos completos de licença, suporte e reembolso

Perguntas frequentes sobre o código do Puttide

O código-fonte do minigolfe é em TypeScript?

Não. O Puttide é JavaScript simples e formatado em source/src e game/src, sem arquivos nossos minificados ou empacotados.

Posso criar buracos ou percursos meus?

Pode. Duplique um buraco no arquivo do percurso, dê um id único, defina par, saída e buraco, inclua em courses.js e coloque nome e dica nos arquivos de idioma.

Ele carrega o Three.js de um CDN?

Não. Three.js, Rapier, fontes e músicas estão dentro de game/, então o jogo só precisa do seu servidor.

Por que a minha hospedagem mostra tela vazia?

Quase sempre são os tipos MIME. Sirva .js como JavaScript e .wasm como application/wasm, abra o jogo por HTTP(S) e confira se o WebGL2 está ativo.

Dá para jogar com amigos?

Dá, de dois a quatro jogadores revezando no mesmo aparelho. Jogo online não faz parte desta edição.

É a base de minigolfe certa para você?

O Puttide serve para portal de família ou de esportes, para agência que monta um percurso com a marca de um cliente e para quem quer ver Three.js e Rapier trabalhando juntos num código legível. Serve menos para um projeto que precisa de partidas online ou ranking compartilhado desde o primeiro dia.

Jogue um percurso inteiro da demo no celular e depois leia a parte do manual sobre criar um buraco. Se aquilo parecer uma tarde de trabalho para você, o resto do jogo já está pronto.

Jogar a demo do Puttide e comprar a licença