pippygames/docs/game-engine/examples/README.md

# Ejemplos y perfiles de conformidad

Estos archivos acompañan a la [especificación v1](../../game-engine-proposal.md). Son datos completos para los esquemas comunes y decisiones de diseño para las reglas. **No son paquetes instalables ni incorporan juegos nuevos al catálogo.** Las rutas de módulos, esquemas particulares y recursos describen la distribución futura; esos archivos no se han creado bajo estas rutas.

## Qué se puede verificar ahora

| Archivo                                            | Contenido                                                                                                |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| [conecta4.game.json](conecta4.game.json)           | Manifiesto de juego público por turnos, tablero, piezas, catálogo y sonido.                              |
| [hundido.game.json](hundido.game.json)             | Manifiesto de juego privado con preparación simultánea, flota, atlas y audio.                            |
| [solitario.game.json](solitario.game.json)         | Manifiesto de un solitario que referencia definición de baraja e ilustraciones en bibliotecas distintas. |
| [libraries.json](libraries.json)                   | Bibliotecas `playing-cards` y `cards-poker`, ambas con versión exacta.                                   |
| [components.json](components.json)                 | Cuadrícula, las 52 definiciones de una baraja de póquer, dado, ruleta y piezas.                          |
| [poker.resource-set.json](poker.resource-set.json) | Asociación de las 52 caras y reverso a gráficos reutilizables; no contiene imágenes nuevas.              |
| [wire.json](wire.json)                             | Sobres válidos de sincronización, comandos, recibos, resultados, cursores y errores.                     |
| [drop.plan.json](drop.plan.json)                   | Grafo de efectos de una caída ganadora de Conecta 4, con sonido al impacto.                              |

El verificador comprueba manifiestos, referencias entre bibliotecas, componentes, cobertura de las 52 caras, plan y sobres. Los ejemplos de red son casos independientes, **no una sesión completa**. La vista `{ "example": "wire-envelope-only" }` verifica únicamente el sobre: una partida real necesita pasar además los esquemas `view` y `context` del juego correspondiente.

Los gráficos `graphic` se implementarán mediante `GraphicDefinition`: generan un SVG nuevo a partir del recurso, slot, definición e idioma. Por eso un mismo módulo puede representar las 52 caras. El recurso de catálogo también recibe su identificador y distingue portada, miniatura e icono. El código gráfico no modifica reglas ni programa efectos.

En Hundido, el atlas usa las dimensiones y regiones del recurso naval existente como referencia para su futura distribución. En Solitario existe ya una definición compartida de cartas en la aplicación, pero estas bibliotecas empaquetadas y sus gráficos de póquer siguen siendo trabajo futuro.

## Perfil 1: Conecta 4

Objetivo: validar el circuito mínimo completo de una acción pública.

| Elemento      | Contrato                                                                                                  |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| Configuración | 6 filas, 7 columnas, objetivo de 4; otras variantes exigirían validación explícita.                       |
| Datos         | Cuadrícula, número de jugadas y último movimiento. Las casillas contienen asiento o vacío.                |
| Flujo         | Fase `playing`, participación `single`, etapa `move`; un actor habilitado.                                |
| Acción        | `drop`, payload `{ column }`, entero entre 0 y 6; política `match`.                                       |
| Validación    | Actor correcto, columna no llena, partida activa.                                                         |
| Transición    | Ocupa la primera fila libre, evalúa línea y tablero lleno; después cambia actor si continúa.              |
| Evento        | `disc.dropped`, con fila, columna y asiento visibles; victoria con casillas de la línea.                  |
| Resultado     | Ganador y perdedor, o ambos con `draw`.                                                                   |
| Retirada      | En una partida activa de dos jugadores, pérdida del que se retira y victoria del rival según este módulo. |
| Presentación  | Caída → marcador `impact` y sonido → resaltado de línea solo cuando existe victoria.                      |

La posición valida dimensiones, gravedad de las fichas, cantidades, último movimiento y coherencia entre resultado y flujo. `availableActions` devuelve una acción concreta por columna libre.

El plan de ejemplo incluye una línea ganadora; una jugada ordinaria omite ese paso. El recurso sonoro es opcional y no bloquea el turno.

## Perfil 2: Hundido

Objetivo: probar privacidad y operaciones independientes antes de una fase compartida.

- `placement` tiene participación `multiple`; cada jugador habilitado está en etapa `arrange`.
- `placeShip` y `ready` usan política `actor`. Una operación solo altera la flota y preparación de su autor, salvo la barrera que inicia batalla cuando ambos han terminado.
- La preparación completa valida límites, tamaños, solapes y la política de adyacencia que se fije en la configuración. No se deja implícita una variante naval.
- `battle` tiene participación `single`, etapa `fire`; `fire({ row, column })` usa política `match`. El disparo valida límites y que esa celda no se haya atacado.
- La regla de conservar o pasar turno tras un acierto forma parte de la configuración validada y de las pruebas del módulo.
- La proyección incluye flota propia, impactos recibidos y conocimiento autorizado del tablero rival. No incluye flota rival no descubierta, ni coordenadas en eventos de preparación.
- Un rival puede saber que hubo actividad por las revisiones, pero no qué barco se colocó. Ocultar también la actividad no es objetivo del perfil v1.
- La retirada durante preparación cancela sin ganador; durante batalla aplica derrota del retirado. Esta es la política propuesta para este perfil, pendiente de contrastar con la variante actual antes de migrar.
- La última flota destruida completa el resultado. Sonido de agua, explosión y hundimiento se eligen desde eventos visibles, nunca inspeccionando estado oculto.

Caso decisivo: p0 y p1 preparan con la misma época y sus revisiones privadas. Una colocación de p0 aumenta la revisión global y la privada de p0; la de p1 sigue siendo válida. Cuando `ready` inicia batalla, cambia la época: ningún comando antiguo puede volver a colocar barcos.

## Perfil 3: Solitario Klondike

Objetivo: probar un participante, instancias de cartas y derrota sin ganador.

- Configuración propuesta inicial: robo de una carta, sin límite de vueltas al mazo. La variante debe quedar fijada al crear la partida.
- `mainDeck` contiene una copia de `poker52`: 52 instancias en zonas de mazo, descarte, siete columnas y cuatro bases.
- La preparación reparte 1–7 cartas a las columnas y mantiene explícitamente orientación y conocimiento de cada carta. Estar en una columna pública no revela cartas boca abajo.
- Fase `playing`, participación `single`, etapa `move`. Acciones propuestas: `draw`, `recycle`, `moveStack`, `moveToFoundation` y `giveUp`, todas con política `match`.
- Las bases crecen desde as a rey por palo; las columnas decrecen alternando color y los huecos admiten rey. Se valida toda la secuencia movida.
- Ganar exige las 52 cartas en bases. Rendirse produce `p0: loss`. No se declara derrota por una comprobación ingenua de «sin movimientos» cuando aún cabe reciclar; resolver matemáticamente la posición no forma parte de v1.
- Se ofrecen movimientos parametrizados para evitar listar combinaciones arbitrarias. El servidor vuelve a comprobar origen, destino, secuencia y visibilidad.
- La proyección oculta orden del mazo y caras cubiertas. El cliente no recibe identidades con las que rastrear cartas ocultas.
- El arte proviene de `cards-poker/standard`; la regla depende solo de `playing-cards/poker52`.

Una partida perdida debe terminar sin asignar una victoria ficticia a su único participante. El fixture de resultado y su variante cooperativa comprueban esta posibilidad a nivel de protocolo.

## Perfil 4: Brisca y juegos con azar animado

Brisca comprobará la baraja española, reglas propias de valor y orden, reparto, manos privadas, triunfo, bazas y descarte. Cada jugador recibe sus cartas y cantidades de las manos ajenas. Un evento de robo privado no puede revelar la cara a los demás. Los resultados exactos de la variante actual se conservarán mediante fixtures antes de migrarla.

Oca y Serpientes comprobarán el ciclo tirada → lectura opcional → recorrido → efecto de casilla → cierre. El servidor ya habrá resuelto todo el movimiento cuando llegue la vista. Un cambio de pestaña o la cancelación de la animación mostrará el destino confirmado sin volver a tirar.

## Perfil 5: cooperación y rol

Una misión cooperativa puede terminar con todos los participantes en `loss`, varios ganadores o resultados distintos por objetivo. La retirada no convierte automáticamente al último jugador en ganador; el módulo decide si la misión sigue, fracasa o se cancela.

Un juego de rol necesitará un paquete concreto que declare personajes, atributos, inventarios, acciones, visibilidad por rol y las reglas de tiradas. Los dados pueden usar componentes comunes; mapas, retratos, objetos y audio se declaran como recursos locales o bibliotecas versionadas. No se ha inventado un sistema universal de rol ni se ha creado un manifiesto que simule tener reglas que todavía no están definidas.

## Condición para convertir un ejemplo en juego publicable

Completar los archivos referenciados, implementar las funciones del SDK, fijar los esquemas de datos y proyección, aportar todos los recursos requeridos y superar los casos de aceptación de la especificación. Solo entonces el publicador puede generar un lock real y activar ese juego.