Skip to content

OFFLINE.md

Latest commit

 

History

History
147 lines (102 loc) · 5.31 KB

OFFLINE.md

File metadata and controls

147 lines (102 loc) · 5.31 KB
Raw

Juegos offline y Service Worker

Cómo funciona la descarga de juegos, la caché PWA y el service worker (sw.js).

Visión general

¿Para qué sirve?

Permitir que el hub cargue como PWA y que cada juego pueda descargarse individualmente para jugarse sin conexión. El service worker sirve los archivos cacheados cuando no hay red.

¿Cuándo interviene?

  • Al instalar la PWA: precache del hub (index.html, games.json, shell del engine).
  • Al pulsar el botón de descarga en una tarjeta de juego: main.js guarda ese juego y todas sus dependencias en la misma caché.
  • Al navegar offline: sw.js responde desde caché si la red falla.

¿Cómo está organizado?

games.json          ← manifest con cache.hubPrecache + extraCacheFiles por juego
     ↓
sw.js               ← estrategias fetch + migración de caché
main.js             ← botón descargar / eliminar / actualizar
scan-games.js       ← genera games.json y detecta deps desde index.html

Nombre de caché activa: js-games-v4 (definido en games.json → cache.name).

Estrategias del Service Worker

¿Para qué sirven?

Equilibrar actualizaciones rápidas online con juego offline fiable.

¿Cuándo aplica cada una?

Estrategia Recursos Comportamiento
Network-First .html, .js, .css, .json, /games/*, /dist/assets/* Red primero; si falla, caché. Online siempre recibe la versión nueva.
Cache-First Imágenes SVG del hub, assets binarios Caché primero; si no existe, red y guardar.
Bypass URLs con ?_nocache Siempre red (comprobación de actualizaciones).

¿Cómo funciona en código?

Ver sw.js:

  • install → lee games.json y precachea cache.hubPrecache.
  • activate → migra entradas de js-games-v1/js-games-v2/js-games-v3 a js-games-v4 y borra cachés legacy.
  • fetch → enruta según tipo de recurso.

Descarga manual de un juego

¿Para qué sirve?

Guardar un juego concreto y todas sus dependencias para jugarlo sin internet (el hub online puede seguir mostrando juegos no descargados).

¿Cuándo usarlo?

Cuando el usuario pulsa el icono de descarga en la tarjeta del juego. No descarga automáticamente todos los juegos del catálogo.

¿Qué archivos se guardan?

Por cada juego, main.js construye la lista con buildGameCacheUrls():

  1. Base del juego: index.html, style.css, script.js, imagen de tarjeta.
  2. Shell compartido: engine/game-shell.css (siempre).
  3. Dependencias auto-detectadas: scripts y CSS del engine referenciados en el index.html del juego (extraCacheFiles en games.json).
  4. Assets extra: definidos manualmente en scripts/scan-games.js (p. ej. words.js, sprites, imágenes del ahorcado).

Ejemplo de dependencias (detectadas por scan-games.js de los <script> tags en index.html):

engine/game-shell.css
engine/pixi.min.js          (si se usa PIXI)
engine/littlejs.min.js       (si se usa LittleJS)
engine/sprite-processor.js   (si se usa)

Los módulos ESM del motor (src/) son empaquetados por Vite en dist/assets/ y no necesan entrada manual en la caché.

¿Cómo actualizar un juego descargado?

Si script.js cambió en el servidor, el botón pasa a estado actualizar (icono azul). Un clic borra la caché antigua del juego y vuelve a descargar la lista completa.

games.json y scan-games.js

¿Para qué sirven?

Fuente única de verdad para el hub, la PWA y la caché offline.

¿Cuándo regenerarlo?

Tras añadir un juego, cambiar scripts del engine en index.html, o modificar assets extra:

node scripts/scan-games.js

¿Qué genera?

{
  "cache": {
    "name": "js-games-v4",
    "hubPrecache": ["./index.html", "./engine/game-shell.css", "..."],
    "gameBaseFiles": ["index.html", "style.css", "script.js"],
    "alwaysInclude": ["engine/game-shell.css"],
    "legacyCaches": ["js-games-v1", "js-games-v2", "js-games-v3"]
  },
  "games": [
    {
      "id": "snake",
      "path": "games/snake/",
      "extraCacheFiles": ["engine/game-shell.css", "..."]
    }
  ]
}

extraCacheFiles se construye desde scan-games.js, que analiza el index.html del juego en busca de <script> y <link> tags. Los módulos ESM del motor son empaquetados por Vite y no requieren entrada manual.

Migración de caché v1 → v2 → v3 → v4

¿Por qué?

La caché v4 actualizó el nombre a js-games-v4 para reflejar cambios en la estructura del engine y migración desde v1/v2/v3.

¿Qué hace el SW al activarse?

  1. Copia todas las entradas de js-games-v1, js-games-v2 y js-games-v3 a js-games-v4.
  2. Elimina las cachés legacy (js-games-v1, js-games-v2, js-games-v3).
  3. Los juegos ya descargados siguen funcionando; conviene re-descargar cada juego para incluir los nuevos módulos del engine.

Limitaciones

  • CDN externo (Font Awesome): no se cachea; iconos pueden no verse offline.
  • Multijugador online: PeerJS requiere red; el modo offline solo aplica a juegos locales.
  • Primer visitante offline: solo tiene lo precacheado del hub, no juegos no descargados.

Documentación relacionada