No Way Down

No Way Down es un juego 2D cooperativo web, de supervivencia narrativa y estética retro pixel art, ambientado en la Casa Central del Banco de la Nación Argentina. El proyecto ya superó la etapa de scaffold inicial: cuenta con un frontend jugable en Phaser, una campaña JSON-driven con niveles, cinemáticas y sistemas de misión, más un backend Django REST para persistir el progreso del jugador.

Estado actual del proyecto

• Frontend jugable en /game: aplicación Phaser 3 + TypeScript + Vite con escenas de arranque, precarga, menú principal, intro de campaña, niveles, cinemáticas, diálogo, piso superior y UI.
• Campaña principal integrada: el flujo main_campaign encadena introducción, niveles del subsuelo, planta baja, pisos superiores, rescate en oficina 422, descenso, garage, cinemática exterior y epílogo final.
• Contenido y sistemas de gameplay: existen configuraciones de niveles, rutas, oleadas, combate, objetivos, eventos narrativos, iluminación, audio, assets institucionales y scripts de generación/auditoría de assets.
• Backend funcional en /backend: API Django + Django REST Framework con health check y endpoints de guardado/carga de progreso por user_id.
• Persistencia preparada para local y producción: SQLite en desarrollo y configuración PostgreSQL/Supabase para despliegue en Render.
• Documentación complementaria en /docs: diseños de niveles, layouts ASCII, plan de assets, multijugador local, mantenimiento y notas de arquitectura.

Nota: el frontend está orientado a desktop/laptop. La app bloquea pantallas táctiles, orientación vertical o resoluciones menores a 960×540.

Mirror automático GitHub → GitLab

El repo incluye un workflow de GitHub Actions que replica automáticamente los pushes de GitHub hacia GitLab. No cambies ni intentes renombrar el path del proyecto en GitLab: el mirror debe apuntar al repositorio existente mediante la URL HTTPS exacta que GitLab muestra en Code → Clone with HTTPS. Esa URL debe copiarse completa, incluyendo el sufijo .git.

Configurá los secrets en GitHub desde Settings → Secrets and variables → Actions:

• GITLAB_MIRROR_URL: URL HTTPS exacta del repositorio GitLab, terminada en .git.
• GITLAB_MIRROR_TOKEN: token de GitLab con permiso write_repository.
• GITLAB_MIRROR_USERNAME: usuario asociado al token. Es opcional; si queda vacío, el workflow usa lu-developer476.

El workflow replica pushes a cualquier branch y a cualquier tag. Cuando se mergea un Pull Request a main, GitHub genera un nuevo push sobre main y ese push también se replica a GitLab.

El mirror replica tanto las referencias Git como los objetos de Git LFS necesarios para el commit que disparó el workflow. El checkout mantiene fetch-depth: 0 y lfs: false para evitar un smudge automático inicial, pero antes de actualizar el branch o tag en GitLab el workflow ejecuta esta secuencia obligatoria:

1. Comprueba que git-lfs esté disponible.
2. Ejecuta git lfs install --local.
3. Descarga desde origin en GitHub los objetos LFS requeridos por HEAD con git lfs fetch origin HEAD.
4. Verifica los objetos locales con git lfs fsck.
5. Carga esos objetos a GitLab con git lfs push gitlab HEAD usando autenticación por http.extraheader.
6. Recién después empuja la referencia Git del branch o tag hacia GitLab.

Este orden evita que Render detecte un commit nuevo en GitLab y lo clone antes de que las imágenes reales estén disponibles. Si GitHub LFS no entrega los objetos por cuota, disponibilidad o permisos, el mirror se detiene y no empuja la referencia Git. Si GitLab rechaza o no recibe los objetos LFS, también se detiene el mirror. No desactives git lfs fsck ni ocultes errores de git lfs fetch, git lfs fsck o git lfs push: esa validación impide que Render reciba commits con punteros LFS sin binarios.

Si una branch está protegida en GitLab, GitLab puede rechazar un push no fast-forward aunque el workflow use --force-with-lease para evitar sobrescrituras incondicionales.

Para más detalle operativo, ver docs/github-to-gitlab-mirror.md.

Stack tecnológico

Capa	Tecnologías
Juego web	Phaser 3, TypeScript, Vite, Arcade Physics
Assets y contenido	JSON, SVG, scripts Node.js para generación y auditoría
Backend/API	Python 3.11+, Django 5.1, Django REST Framework
Persistencia	SQLite local, PostgreSQL/Supabase en producción
Deploy previsto	Render + Supabase

Estructura del repositorio

.
├── game/       # Frontend jugable Phaser + TypeScript + Vite
├── backend/    # API Django REST para progreso y health checks
├── docs/       # Documentación técnica, narrativa y de niveles
└── public/     # Referencias visuales estáticas del entorno

Requisitos

• Node.js 20+
• npm
• Python 3.11+
• pip

Frontend (/game)

Instalar dependencias

cd game
npm install

Variables de entorno del frontend

Desde la raíz del repositorio:

cp game/.env.example game/.env

Variables importantes:

• VITE_BACKEND_URL: URL base del backend. Ejemplo: http://127.0.0.1:8000.
• VITE_PLAYER_ID: identificador del jugador usado para guardar/cargar progreso.

Ejecutar en desarrollo

cd game
npm run dev

Por defecto, Vite sirve el juego en http://localhost:5173.

Build de producción

cd game
npm run build

El build ejecuta tsc --noEmit, genera el bundle con Vite y valida el flujo de campaña con scripts/verifyBuildCampaignFlow.mjs.

Scripts útiles

cd game
npm run audit:asset-routes
npm run fix:asset-routes
npm run generate:institutional-tileset

También hay scripts para generar spritesheets de mostradores, mesas, columnas, ventanas, decoración, escaleras y daño zombie.

Backend (/backend)

Crear entorno virtual e instalar dependencias

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Variables de entorno

Desde la raíz del repositorio:

cp backend/.env.example backend/.env

Variables principales:

• DJANGO_ENV: development o production.
• DJANGO_SECRET_KEY: clave secreta de Django.
• DJANGO_DEBUG: True en local, False en producción.
• DJANGO_ALLOWED_HOSTS: hosts permitidos separados por coma.
• GAME_ORIGINS: orígenes CORS permitidos para el frontend.
• POSTGRES_*: configuración de PostgreSQL/Supabase para producción.

Aplicar migraciones y ejecutar servidor

cd backend
python manage.py migrate
python manage.py runserver

Ejecutar tests backend

cd backend
python manage.py test

Endpoints backend

• GET http://127.0.0.1:8000/api/health/: health check del servicio.
• POST http://127.0.0.1:8000/api/progress/: crea o actualiza el progreso de un jugador por user_id.
• GET http://127.0.0.1:8000/api/progress/<user_id>/: obtiene el progreso persistido de un jugador.

El modelo de progreso persiste nivel actual, vida, aliados rescatados, checkpoint, versión de guardado y un snapshot JSON de campaña.

Flujo recomendado para desarrollo local

1. Levantar el backend en http://127.0.0.1:8000.
2. Configurar game/.env con VITE_BACKEND_URL=http://127.0.0.1:8000.
3. Levantar el frontend con npm run dev dentro de /game.
4. Abrir http://localhost:5173 en desktop/laptop.

Producción

La configuración de producción contempla Render para el backend y Supabase/PostgreSQL como base de datos. Ver docs/backend-render-supabase.md para el detalle de variables, despliegue y conexión.

Documentación destacada

• docs/technical-overview.md: panorama técnico del proyecto.
• docs/local-multiplayer.md: diseño de multijugador local.
• docs/maintenance-guide.md: guía de mantenimiento.
• docs/narrative_canon_constraints.md: restricciones narrativas de canon.
• docs/level*_design.md y docs/*_ascii_layout.md: diseño y layouts de niveles.

Producción full-stack en Render

El despliegue de producción usa un único Render Web Service con Django/Gunicorn. Durante el build, Render instala dependencias Python, instala dependencias Node con npm ci, compila el frontend Vite de /game, valida que exista game/dist/index.html y ejecuta collectstatic.

• Build Command: ./scripts/render-build.sh
• Start Command: cd backend && gunicorn config.wsgi:application --bind 0.0.0.0:$PORT
• Runtime: Python 3.11.9
• NODE_VERSION: 20.18.1

Django usa WhiteNoise para servir el build compilado de Vite desde game/dist sin commitear archivos generados. En producción:

• / muestra el videojuego compilado.
• /assets/..., favicons y JSON copiados desde game/public se sirven desde game/dist con sus URLs originales.
• /api/ queda reservado para Django REST Framework.
• /api/health/ devuelve el health check JSON.
• /api/progress/ y /api/progress/<user_id>/ conservan la persistencia de progreso.
• /admin/ sigue apuntando a Django Admin.
• Rutas frontend desconocidas devuelven index.html; rutas /api/ inexistentes devuelven error API y no se disfrazan como HTML.

Para desarrollo local, mantener Vite en http://localhost:5173 y Django en http://127.0.0.1:8000. Configurar game/.env con VITE_BACKEND_URL=http://127.0.0.1:8000. En producción, dejar VITE_BACKEND_URL vacío o sin definir para que el bundle consuma rutas relativas del mismo dominio, como /api/health/ y /api/progress/.

Variables Render a revisar: DJANGO_ENV=production, DJANGO_SECRET_KEY, DJANGO_DEBUG=False, DJANGO_ALLOWED_HOSTS, GAME_ORIGINS, PYTHON_VERSION=3.11.9, NODE_VERSION=20.18.1 y las variables POSTGRES_*/Supabase.