Forge TON Realms - Telegram WebApp Game

Un juego idle/tycoon para Telegram WebApp con economía sostenible play-to-earn basado en TON Blockchain.

🎮 Características

Sistema de Juego

• Objetos que Generan Energía: Los objetos generan energía al activarse (no la consumen)
• Activación Manual: Cada objeto debe activarse cada 4 horas para generar 40 de energía
• Cap de Energía: 120 base (la energía extra se pierde si se llena)
• Conversión a TON: 100,000 energía = 1 TON (conversión manual)
• Rarezas: Común, Raro, Épico, Legendario

Minijuego de Construcción

• Juego de timing para obtener nuevos objetos
• Ruleta de rarezas basada en performance
• Mejores scores = mayor probabilidad de rarezas altas
• Legendario siempre tiene baja probabilidad

Inventario

• Slots limitados (2 iniciales)
• Compra de slots adicionales con TON (precio progresivo)
• Cada slot cuesta el doble del anterior (0.5 TON base)

Shop & Monetización

Boosts pagados con TonConnect:

• x2 próxima activación: 0.1 TON
• +1 activación hoy: 0.15 TON
• x2 por 8 horas: 0.2 TON
• Activación automática 2 días: 0.3 TON

Onboarding

• Misión inicial obligatoria: unirse al canal de Telegram
• Recompensa: 1 objeto común inicial

🛠️ Stack Tecnológico

• Frontend: React + Framer Motion + TonConnect UI
• Backend: FastAPI + Python
• Base de Datos: MongoDB
• Blockchain: TON (testnet por defecto)
• Telegram: WebApp SDK

📋 Configuración

Backend (.env)

MONGO_URL="mongodb://localhost:27017"
DB_NAME="forge_ton_realms"
CORS_ORIGINS="*"

# Telegram
TELEGRAM_BOT_TOKEN="your_bot_token_from_botfather"
TELEGRAM_CHANNEL="@forge_ton_realms"

# TON Configuration
TON_NETWORK="testnet"  # Change to "mainnet" for production
BOT_WALLET_ADDRESS="UQtest_wallet_address_here"
TON_API_KEY="your_toncenter_api_key"

# Game Configuration
ENERGY_CAP_BASE=120
ENERGY_PER_ACTIVATION=40
ENERGY_TO_TON_RATE=100000
INITIAL_INVENTORY_SLOTS=2

Frontend (.env)

REACT_APP_BACKEND_URL=__BACKEND_URL__
REACT_APP_TON_MANIFEST_URL=__FRONTEND_URL__/tonconnect-manifest.json

🚀 Instalación y Despliegue

1. Crear Bot de Telegram

1. Habla con @BotFather en Telegram
2. Usa el comando /newbot
3. Sigue las instrucciones para obtener tu bot token
4. Configura el bot token en /app/backend/.env

2. Configurar TON Testnet

1. Obtén una API key de TON Center
2. Crea una wallet testnet para recibir pagos
3. Configura BOT_WALLET_ADDRESS y TON_API_KEY en el .env

Para obtener TON testnet:

• Usa el TON Testnet Faucet

3. Configurar Manifest de TonConnect

Edita /app/frontend/public/tonconnect-manifest.json:

{
  "url": "https://tu-dominio.com",
  "name": "Forge TON Realms",
  "iconUrl": "https://tu-dominio.com/icon.png",
  "termsOfUseUrl": "https://tu-dominio.com/terms",
  "privacyPolicyUrl": "https://tu-dominio.com/privacy"
}

4. Configurar Canal de Telegram

1. Crea un canal público en Telegram
2. Obtén el handle del canal (ej: @tu_canal)
3. Configura TELEGRAM_CHANNEL en el .env

5. Iniciar Servicios

Los servicios ya están configurados y en ejecución:

# Verificar estado
sudo supervisorctl status

# Reiniciar si es necesario
sudo supervisorctl restart backend frontend

📱 Uso

Como Usuario

1. Abre el bot en Telegram
2. Completa la misión de onboarding (unirse al canal)
3. Recibe tu primer objeto común
4. Activa objetos cada 4 horas para generar energía
5. Juega el minijuego de construcción para obtener más objetos
6. Convierte energía a TON o compra boosts

Para Desarrolladores

Endpoints Principales

Autenticación:

• POST /api/auth/register - Registrar usuario
• POST /api/auth/me - Obtener usuario actual

Onboarding:

• POST /api/onboarding/complete - Completar onboarding

Objetos:

• POST /api/items/list - Listar objetos del usuario
• POST /api/items/activate - Activar un objeto
• GET /api/items/library - Biblioteca de objetos

Construcción:

• POST /api/construction/play - Jugar minijuego

Inventario:

• POST /api/inventory/purchase-slot - Comprar slot

Energía:

• POST /api/energy/convert - Convertir energía a TON

Pagos:

• POST /api/payments/initiate-payment - Iniciar pago
• GET /api/payments/transaction-status/{id} - Estado de transacción

Configuración:

• GET /api/game/config - Configuración del juego
• GET /health - Health check

🎨 Diseño

El juego usa un tema cyberpunk minimalista dark con:

• Colores principales:
  • Neon Cyan (#00F0FF)
  • Electric Purple (#BD00FF)
  • Laser Green (#00FF94)
• Tipografía:
  • Rajdhani (headings)
  • Chakra Petch (body)
  • JetBrains Mono (datos)

🔒 Seguridad

• ✅ Validación criptográfica de Telegram initData
• ✅ Toda la lógica del juego en backend
• ✅ Sin almacenamiento de claves privadas
• ✅ TonConnect para pagos seguros
• ✅ Rate limiting recomendado para producción

🚦 Cambiar a Mainnet

Para cambiar de testnet a mainnet:

1. Actualiza /app/backend/.env:

TON_NETWORK="mainnet"
BOT_WALLET_ADDRESS="tu_wallet_mainnet"
TON_API_KEY="tu_api_key_mainnet"

2. Reinicia el backend:

sudo supervisorctl restart backend

3. Verifica la configuración:

curl http://localhost:8001/health

📊 Economía del Juego

Balance Deflacionario

• ❌ Sin generación infinita offline
• ✅ Cap de energía previene inflación
• ✅ Activación manual incentiva engagement
• ✅ Precios progresivos de slots
• ✅ Boosts no rompen economía

Incentivos

• 🎯 Entrar 4-6 veces al día (activaciones)
• 🎮 Jugar construcción para nuevos objetos
• 💎 Mejorar timing para rarezas altas
• 🏪 Boosts opcional para conveniencia

🐛 Troubleshooting

Backend no inicia

tail -f /var/log/supervisor/backend.err.log

Frontend no carga

tail -f /var/log/supervisor/frontend.err.log

MongoDB no conecta

sudo supervisorctl status mongodb

Telegram auth falla

• Verifica que TELEGRAM_BOT_TOKEN esté configurado correctamente
• Asegúrate de que el bot esté activo

📦 Estructura del Proyecto

/app/
├── backend/
│   ├── server.py              # FastAPI main
│   ├── models.py              # Pydantic models
│   ├── telegram_auth.py       # Telegram validation
│   ├── game_logic.py          # Game mechanics
│   ├── ton_service.py         # TON payment monitoring
│   ├── requirements.txt       # Python dependencies
│   └── .env                   # Backend config
├── frontend/
│   ├── public/
│   │   └── tonconnect-manifest.json
│   ├── src/
│   │   ├── components/
│   │   │   ├── Layout.js
│   │   │   └── Onboarding.js
│   │   ├── contexts/
│   │   │   └── AuthContext.js
│   │   ├── pages/
│   │   │   ├── Dashboard.js
│   │   │   ├── Inventory.js
│   │   │   ├── Shop.js
│   │   │   └── Construction.js
│   │   ├── App.js
│   │   ├── App.css
│   │   └── index.css
│   ├── package.json
│   ├── tailwind.config.js
│   └── .env                   # Frontend config
└── design_guidelines.json     # Design system

🎯 Próximos Pasos

1. Configurar tu bot de Telegram
2. Obtener TON API keys (testnet)
3. Crear canal de Telegram
4. Actualizar todos los .env con tus credenciales
5. Reiniciar servicios
6. Probar flujo completo
7. Cuando esté listo, cambiar a mainnet

📝 Notas

• El juego está configurado para testnet por defecto
• Todos los pagos usan TonConnect (wallets del usuario)
• La economía está diseñada para ser sostenible
• Los boosts no rompen el balance del juego
• Sistema preparado para futuro APK

🤝 Soporte

Para problemas o preguntas, revisa los logs en /var/log/supervisor/