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

Ejemplos y perfiles de conformidad

Estos archivos acompañan a la especificación v1. 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	Manifiesto de juego público por turnos, tablero, piezas, catálogo y sonido.
hundido.game.json	Manifiesto de juego privado con preparación simultánea, flota, atlas y audio.
solitario.game.json	Manifiesto de un solitario que referencia definición de baraja e ilustraciones en bibliotecas distintas.
libraries.json	Bibliotecas playing-cards y cards-poker, ambas con versión exacta.
components.json	Cuadrícula, las 52 definiciones de una baraja de póquer, dado, ruleta y piezas.
poker.resource-set.json	Asociación de las 52 caras y reverso a gráficos reutilizables; no contiene imágenes nuevas.
wire.json	Sobres válidos de sincronización, comandos, recibos, resultados, cursores y errores.
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.