Juego TUKU: aprende recreando un videojuego web

TUKU: No Te Caigas es un runner web en pixel art donde cada edición del balón entra al TUKU Lab a superar pruebas de agarre, rebote y resistencia hasta reunir 1.000 puntos y quedar certificada para la cancha.

Es un proyecto educativo completo: juego en Canvas, servidor en Node.js y ranking global en la nube con Firebase. Podés jugarlo, estudiarlo y crear tu propia versión.

Enlaces rápidos

• Jugar la versión original: tuku-juego.ai.studio
• Código fuente en GitHub: github.com/Ssrrb/arai-demo
• Importarlo en Google AI Studio: copiá la URL del repo y usá la opción Import from GitHub.

Cómo se juega

• Elegís una de 4 ediciones: Nebula, Fuego, Oro y Metal. Son solo visuales, no cambian dificultad ni física.
• Saltás obstáculos con Espacio, ↑ o W en PC, o tocando la pantalla en el celu. Si mantenés pulsado, el salto es más alto.
• Juntás fichas de rendimiento y núcleos de certificación, esquivás bloques de impacto y drones de calibración.
• Tu récord queda guardado en localStorage y, si entrás al ranking, compite con todos en tiempo real.
• Al final hay un botón para visitar la Tienda TUKU con el modelo activo.

Con qué está construido

Todo el código es abierto con licencia MIT.

Dónde entra Firebase

Esta es la parte más importante para entender el proyecto: sin Firebase el juego funcionaría solo en tu navegador, con Firebase compite todo el mundo en el mismo ranking.

Firebase Firestore se usa para dos cosas:

1. Ranking global (leaderboard_scores)

   • Cada récord guarda player_key, name, score, distance, bananas (fichas), achieved_at.
   • El servidor consulta el top 10 ordenado por score y distance con getLeaderboardScores().
   • Con subscribeToLeaderboard() y onSnapshot el ranking se actualiza en vivo, sin recargar.
   • saveLeaderboardScore() solo guarda si es tu mejor marca. Si ya existís y el puntaje es menor, lo rechaza.
   • isNameAvailable() evita nombres duplicados.

2. Estado de ronda (round_state/current)

   • Guarda status, duration, remaining, is_finished, updated_at.
   • Sirve para eventos en vivo: cuando la ronda termina, el ranking se bloquea con setRoundLocked(true) y no acepta más puntajes.
   • Las reglas firestore.rules refuerzan esto del lado del servidor: solo aceptan puntajes válidos, con nombre alfanumérico de 2 a 16 caracteres, números dentro de rango, y solo si la ronda sigue activa.

En criollo: localStorage guarda tu mejor marca en tu dispositivo. Firebase guarda la tabla de todos y decide quién va primero, en tiempo real y con reglas anti-trampas.

Para correrlo vos necesitás tu propio proyecto de Firebase y completar firebase-applet-config.json + .env (HOST, PORT, FIREBASE_API_KEY). Sin eso el juego anda igual, pero sin ranking en la nube.

Estructura del repositorio

arai-demo/
  index.html              # todo el juego (Canvas, UI, WebSocket client)
  server.js               # servidor Node: estáticos + ranking + validación
  firebase.js             # conexión a Firestore y funciones de ranking
  firestore.rules         # reglas de seguridad del ranking
  firebase-applet-config.json  # config del proyecto Firebase
  profanity.js            # filtro de nombres
  assets/tuku/            # sprites pixel art 16-bit + README con prompts
  test/                   # npm test: marca, CTA, sintaxis, sprites
  Dockerfile + compose.yaml

Recréalo con AI Studio en 4 pasos

1. Importá el repo en Google AI Studio con la URL https://github.com/Ssrrb/arai-demo.
2. Pegale el prompt de abajo y pedile primero que te explique la estructura antes de tocar nada.
3. Pedile cambios de a uno: personaje, fondo, dificultad, música, reglas. Probá cada cambio.
4. Cuando tengas tu versión, pedile que te genere tu propio firestore.rules y tu firebase.js con tu proyecto de Firebase.

Para correrlo local necesitás Node.js 22:

cp .env.example .env
npm install
npm start
# http://localhost:8080

Validar y testear:

npm test
npm run check

Deploy con Docker:

docker compose up --build -d

Prompt listo para copiar a tu IA

Copiá y pegá esto en ChatGPT, Gemini, AI Studio o tu IA favorita:

Quiero recrear el juego TUKU: No Te Caigas para aprender a programar.

Repositorio original: https://github.com/Ssrrb/arai-demo
Demo jugable: https://tuku-juego.ai.studio

Actuá como mi profesor de programación. Primero explicame en simple:
1. Cómo está organizado el proyecto (index.html, server.js, firebase.js, firestore.rules, assets/tuku).
2. Cómo funciona el juego en Canvas: salto variable, obstáculos, puntaje, localStorage.
3. Cómo funciona el ranking global con Firebase Firestore: colecciones leaderboard_scores y round_state/current, funciones getLeaderboardScores, saveLeaderboardScore, subscribeToLeaderboard con onSnapshot, y las reglas anti-trampas.
4. Cómo funciona el WebSocket para el ranking en tiempo real.
5. Qué necesito para correrlo local con Node.js 22 (npm install, npm start) y testearlo con npm test.

Después guiame paso a paso para crear MI propia versión con mi temática [contale tu idea: ej. un tero que salta en la rambla].
Quiero cambiar personaje, fondo, nombre, colores y dificultad, uno por vez, explicándome qué hace cada cambio.
Al final ayudame a conectar MI propio proyecto de Firebase para tener mi propio ranking.
Explicame todo en español simple, sin asumir que sé programar.

Ideas para personalizarlo

• Cambiá el balón por tu mascota, tu producto o tu barrio.
• Cambiá fichas por monedas, mates, libros, lo que quieras.
• Ajustá velocidad, gravedad y salto para hacerlo más fácil o imposible.
• Agregá niveles, vidas o power-ups.
• Conectalo con tu propia tienda o landing con el CTA final.

Usá la IA como guía, pero revisá y entendé el código antes de publicarlo. Los tests (npm test) te avisan si rompiste sprites, marca o sintaxis.

Equipo ARAI

Laboratorio y recursos educativos