Código fuente de juego de minigolf: hoyos, física y mapa de los campos 3D
Cómo guarda Puttide sus 30 hoyos, dónde están Three.js y Rapier, y cómo agregar un hoyo propio.
Un código fuente de juego de minigolf se pone a prueba con una sola tarea: agregar un hoyo. Quien quiere un campo con la marca de un cliente, un nivel de temporada o un logo en el green abre primero los archivos de niveles, y si el hoyo está enterrado en el código del motor, el proyecto se atora. En Puttide, nuestra plantilla de minigolf 3D, cada campo tiene su propio archivo de hoyos en JavaScript simple, y el manual explica cómo agregar uno.
Esta guía recorre el paquete como lo encuentra un desarrollador: las carpetas, las bibliotecas, los archivos de los campos, el orden de los cambios, el hosting y la licencia. Los nombres de archivo vienen del manual que acompaña al juego.
Respuesta corta: Puttide es JavaScript formateado, con Three.js para dibujar y Rapier para la física de la pelota, ambos incluidos. Sin compilación, sin CDN y sin código de servidor.
Qué incluye el código fuente del juego de minigolf
Puttide es un juego terminado con 30 hoyos en cinco campos de isla: Sunlit Ruins, Lantern Pier, Frost Peaks, Cloud Garden y Volcano Forge, seis hoyos cada uno. Rampas, portales, bumpers y molinos convierten cada hoyo en un pequeño acertijo. Cada hoyo da tres estrellas (terminarlo, hacer par o menos y encontrar la moneda escondida), y medallas de bronce, plata y oro premian las mejores rondas.
Además de los campos hay un reto diario con una variante (viento, green helado, pelota pesada, paredes rebotadoras, lluvia de monedas o cacería de birdies), un casillero donde las monedas compran pelotas, estelas y otros cosméticos, y partidas de dos a cuatro jugadores por turnos en el mismo dispositivo. La interfaz viene en 14 idiomas.
- game/: la versión lista para subir, la única carpeta que publicas.
- source/: el mismo juego como edición para desarrollo, con README y package.json.
- documentation/: un manual ilustrado en inglés y portugués.
- THIRD-PARTY-LICENSES/: licencias de las bibliotecas y de las fuentes.
- Versión 1.1.0, actualizada el 22 de octubre de 2026.
Abrir la ficha de Puttide: demo, manual y precio
Three.js, Rapier y el resto de la tecnología
La pelota la simula Rapier 3D 0.21.0, que corre como WebAssembly, y la escena se dibuja con Three.js r186. Ambas están en lib/three/ y lib/rapier/ con sus licencias, y index.html tiene un import map que dirige el juego hacia ellas. El manual aclara que los archivos de las bibliotecas no cambiaron su comportamiento; solo se formatearon para poder leerlos.
Esto importa por dos razones. Primero, nada se carga de un CDN, así que un portal o un cliente con una política de seguridad estricta solo necesita tu servidor. Segundo, actualizar una biblioteca es un paso manual y a propósito: source/package.json lista las versiones exactas, y copias los nuevos archivos de módulo sobre la carpeta correspondiente en lib/, conservando las rutas del import map.
- Three.js r186: licencia MIT.
- Rapier 3D compat 0.21.0, con WebAssembly integrado: licencia Apache-2.0.
- Fuentes Rubik y Fredoka: SIL Open Font License 1.1.
- Dos pistas de música: music/menu.mp3 y music/play-1.mp3.
Dónde viven los hoyos, las monedas y los textos
Las rutas son iguales en source/ y en game/. Los datos de los campos están divididos por isla, así cada archivo es lo bastante corto para leerlo de una sentada.
- src/course/courses.js: orden de los campos y requisitos para desbloquearlos.
- src/course/holes.js: los hoyos de Sunlit Ruins, con geometría, par y obstáculos.
- src/course/pier.js, ice.js, lava.js y sky.js: los hoyos de los otros cuatro campos.
- src/sim/constants.js: ajuste de la física.
- src/game/economy.js: pelotas, estelas y atuendos, con sus precios.
- src/ui/i18n.js y sus archivos hermanos: los diccionarios de los 14 idiomas, con nombres y consejos de los hoyos.
- src/game/localRecords.js: récords de cada campo guardados en el navegador.
- src/audio/audio.js: efectos y el mapeo de música, en probeTracks.
- css/style.css: colores, fuentes y estilos adaptables de la interfaz.
Agregar un hoyo, paso a paso
Es el cambio que hace casi todo comprador, y el manual lo describe en pocas líneas. Aquí está en el orden que seguiríamos nosotros.
- Elige el archivo del campo donde irá el hoyo, por ejemplo lava.js para Volcano Forge.
- Duplica un hoyo existente parecido al que quieres.
- Dale un id único. Repetir un id confunde el progreso guardado.
- Define el par, la posición de salida y la del hoyo, y luego mueve o cambia los obstáculos.
- Agrega el hoyo a su campo en courses.js.
- Pon su nombre y su consejo en los diccionarios de idioma, en todos los idiomas que vayas a publicar.
- Juégalo: prueba colisiones, la recuperación cuando la pelota sale de la pista y las tres estrellas, incluida la moneda escondida.
Edita en source/, copia los archivos cambiados a las mismas rutas en game/ y sirve la carpeta por HTTP para probar. El package.json trae un script serve, o puedes ejecutar python -m http.server 8765. Node.js es opcional y solo sirve si quieres que npm administre las versiones de las bibliotecas.
Los demás cambios, en un orden razonable
- Marca y colores: logo, colores y fuentes en css/style.css. Se permite marca blanca, así que tu marca puede ir en lugar de la nuestra.
- Precios del casillero: economy.js. Cosméticos baratos hacen más amable un sitio casual; caros alargan una campaña.
- Textos: frases y consejos en los archivos i18n.
- Música: las dos pistas incluidas se pueden cambiar por grabaciones con licencia tuya. Copia el archivo y actualiza el mapeo explícito en audio.js (probeTracks); la música de cada escena recurre a la pista de juego si no hay otra.
- Física: constants.js, al final y en pasos pequeños, porque cada hoyo se ajustó con los valores actuales.
Para un proyecto parecido con el mismo JavaScript simple, y sin ninguna biblioteca 3D, nuestra plantilla de billar está hecha igual.
Velvet Pool: billar de bola 8 en JavaScript puro y WebGL2
Sunset Rally: tenis de mesa 3D con campaña de nueve partidos
Hosting, tipos MIME y apps
Sube todo lo que está dentro de game/ a una carpeta como public_html/puttide/, conserva las subcarpetas y abre la dirección por HTTPS. En el servidor no hace falta npm, PHP, base de datos ni cuenta. Abrir index.html directo desde la computadora no funciona, porque el navegador bloquea los módulos en file://.
Puttide tiene un detalle de hosting que un juego 2D no tiene: la física corre en WebAssembly. Tu servidor debe enviar .js con tipo MIME de JavaScript y .wasm como application/wasm. Si el hosting se equivoca, verás una pantalla en blanco o un error de módulo, así que revísalo desde el primer día.
- El navegador necesita JavaScript, módulos ES, WebAssembly y WebGL2.
- En un iframe de portal, permite pantalla completa y reproducción automática.
- En pantallas táctiles: arrastrar para apuntar y tirar, dos dedos para girar la cámara, pellizcar para el zoom.
- No es una app instalable sin conexión: cada carga nueva llega a tu servidor.
Los proyectos de app nativa no vienen en el paquete. Si planeas publicarlo en una tienda, reserva presupuesto para el empaquetado y para pruebas en celulares reales, porque un juego 3D con física pesa más que un juego de cartas en equipos viejos.
Lo que no incluye, y la licencia
Esta es la edición local para navegador: sin multijugador ni salas en línea, sin ranking en línea, sin cuentas en la nube, sin SDK de anuncios, sin apps nativas y sin hosting. Récords, progreso diario y partidas en el mismo dispositivo se quedan en el navegador del jugador, y no se envía ninguna puntuación. Lo guardado pertenece al origen del navegador, así que cambiar de dominio hace que el jugador empiece de cero.
Puttide tiene un precio de lista de 39 USD; hasta el 30 de noviembre de 2026 la promoción de Black Friday lo deja en 33.15 USD, y comprar dos o más plantillas en el mismo pedido suma entre 5% y 20% de descuento. La licencia es perpetua y no exclusiva para un producto final, tuyo o de un cliente. Puedes cambiar la marca, modificar código, arte y audio y dejar entrar a los jugadores gratis o con anuncios, pero no revender la plantilla ni su código por separado. El soporte dura seis meses, o doce con la extensión; hoyos a medida, integraciones y hosting se cotizan a pedido.
Términos completos de licencia, soporte y reembolso
Preguntas frecuentes sobre el código de Puttide
¿El código fuente del minigolf está en TypeScript?
No. Puttide es JavaScript simple y formateado en source/src y game/src, sin archivos nuestros minificados ni empaquetados.
¿Puedo agregar mis propios hoyos o campos?
Sí. Duplica un hoyo en el archivo del campo, dale un id único, define par, salida y hoyo, agrégalo en courses.js y pon su nombre y consejo en los archivos de idioma.
¿Carga Three.js desde un CDN?
No. Three.js, Rapier, las fuentes y la música están dentro de game/, así que el juego solo necesita tu servidor.
¿Por qué mi hosting muestra una pantalla en blanco?
Casi siempre son los tipos MIME. Sirve .js como JavaScript y .wasm como application/wasm, abre el juego por HTTP(S) y revisa que WebGL2 esté activo.
¿Pueden jugar varios amigos?
Sí, de dos a cuatro jugadores por turnos en el mismo dispositivo. El juego en línea no forma parte de esta edición.
¿Es la base de minigolf que necesitas?
Puttide encaja en un portal familiar o de deportes, en una agencia que arma un campo con la marca de un cliente y en quien quiere ver Three.js y Rapier trabajando juntos en código legible. Encaja menos en un proyecto que necesita partidas en línea o un ranking compartido desde el primer día.
Juega un campo completo de la demo en el celular y luego lee la parte del manual sobre agregar un hoyo. Si eso te parece una tarde de trabajo, el resto del juego ya está hecho.