Reproductor de Cinemáticas

Para qué sirve este sistema

Una pantalla de presentación, una cinemática de introducción o una escena tras derrotar a un jefe necesitan lo mismo: reproducir una secuencia de momentos temporizados — fundir a negro, ejecutar un Timeline, esperar, volver del fundido — en orden, sin colgar jamás el juego si uno de esos momentos se porta mal. Las cadenas de corrutinas hechas a mano lo consiguen una vez, y se rompen en cuanto alguien añade una etapa o porta el proyecto a WebGL, donde un contexto de audio atascado puede congelar cualquier cosa que espere por él.

El Reproductor de Cinemáticas de Serenity modela una cinemática como una lista ordenada de etapas reproducida por un único servicio. Cada etapa — y la cinemática entera — corre bajo un timeout duro de reloj de pared, así que la reproducción es segura de invocar durante el arranque, antes de que el resto del juego haya despertado, sin arriesgar una pantalla de carga congelada.

El problema en Unity

La secuenciación cinemática en Unity tiende a acumularse: una corrutina aquí, una llamada al PlayableDirector allá, un Invoke para el fundido, y ningún lugar único que posea el orden ni los tiempos. Añadir una etapa significa editar código. Probar una cinemática significa entrar en modo Play y verla ocurrir en tiempo real, etapa a etapa, sin forma de rebobinar hasta la parte que acaba de romperse.

Las cinemáticas de arranque son aún más arriesgadas. Una pantalla de presentación que se reproduce antes de que el juego termine de inicializarse no puede asumir un framerate sano ni un contexto de audio en marcha, especialmente en WebGL. Una etapa que espera algo que nunca se resuelve puede colgar toda la secuencia de arranque, dejando a los jugadores mirando un logo congelado.

Cómo lo aborda Serenity

Serenity modela una cinemática como una UnityCutsceneDefinition — una lista ordenada de etapas UnityCutsceneStep, cada una tipada como fundido de entrada, fundido de salida, reproducir un Timeline de Unity, esperar o personalizada. ICutscenePlayerService.PlayAsync(id, ct) reproduce una definición de principio a fin, de una pasada o en bucle, dirigiendo un overlay de fundido a pantalla completa y un PlayableDirector sobre el prefab de rig propio de la cinemática a medida que avanza por las etapas.

Cada etapa corre bajo su propio timeout duro, y la cinemática completa bajo un segundo timeout externo, ambos medidos contra el reloj de pared y no contra el delta de frames. Eso significa que un Timeline colgado o un fundido atascado nunca pueden bloquear al llamador indefinidamente — la reproducción siempre termina o expira, y eso es lo que la hace segura de disparar desde el pipeline de arranque antes de que exista el resto del juego.

Cómo encaja en Serenity

El Reproductor de Cinemáticas compone los contratos de orquestación de etapas del Reproductor de Secuencias genérico — ISequenceDefinition e ISequenceStage — mientras posee su propia ejecución de etapas, overlay de fundido y manejo de rig a través de CutsceneStageType. El prefab de rig se instancia durante la reproducción y se destruye después, así que una cinemática sin rig reproduce solo una transición de fundido pura.

El servicio se registra en el ServiceLocator durante la instalación, de modo que cualquier código — incluida una acción de disparo sin código generada — puede resolver ICutscenePlayerService sin cableado manual. Las definiciones se descubren por etiqueta de Addressables desde un asset UnityCutscenePlayerSettings, manteniendo las cinemáticas creadas desacopladas del código que las reproduce.

Flujo de trabajo práctico

1. Abre Tools ▸ Serenity ▸ Create ▸ Cutscenes ▸ Cutscene Wizard y elige una plantilla — Logo splash, Timeline cutscene, Fade transition o Blank — en el paso Template.
2. Reordena, añade o elimina etapas en el paso Stages, configurando la duración, el color del fundido o el asset de Timeline de cada una.
3. Elige un rig en el paso Rig — ninguno, un prefab existente o un prefab vacío nuevo con un PlayableDirector — para las etapas que necesiten contenido visible.
4. Opcionalmente, genera un disparador de reproducción sin código y una tarea de arranque en el paso Trigger, para que la cinemática pueda dispararse desde un SignalEmitterComponent o desde el pipeline de inicialización sin código de juego.
5. Crea la definición y abre la ventana Cutscene Outline para recorrer cada etapa con una vista previa de Timeline en vivo renderizada a través de la cámara del propio rig, completamente fuera del modo Play.
6. Llama a ICutscenePlayerService.PlayAsync(id, ct) desde el código del juego, o despacha la señal de disparo generada, para reproducir la cinemática en runtime.

Qué incluye

• ICutscenePlayerService.PlayAsync(id, ct) con reproducción de una pasada o en bucle, autoacotada por timeouts duros de reloj de pared
• UnityCutsceneDefinition creada como lista ordenada de etapas UnityCutsceneStep — fundido de entrada, fundido de salida, reproducir Timeline, esperar, personalizada
• Asistente Cutscene Wizard de cinco pasos — Template ▸ Stages ▸ Rig ▸ Trigger ▸ Create — con disparador de reproducción sin código y tarea de arranque opcionales
• Ventana Cutscene Outline con vista previa de Timeline en vivo y navegable, renderizada a través de la cámara del propio rig, sin necesidad de modo Play
• Timeouts duros por etapa y para la cinemática completa, seguros de invocar desde el pipeline de arranque sin arriesgar una pantalla de presentación congelada
• Overlay de fundido a pantalla completa dirigido automáticamente por las etapas FadeIn/FadeOut, reutilizado en todas las cinemáticas
• Construido sobre los contratos de orquestación de etapas del Reproductor de Secuencias genérico, mantenidos al margen de las preocupaciones cinemáticas
• Registro en el ServiceLocator para que los disparadores generados y el código del juego resuelvan el reproductor sin cableado manual de dependencias

Cuándo usarlo

• Pantallas de presentación y cinemáticas de introducción que deben reproducirse de forma segura durante el arranque, antes de que el resto del juego se haya inicializado, incluido WebGL.
• Intros de jefes, transiciones de nivel o momentos de historia que combinan un Timeline de Unity con fundidos, creados sin escribir corrutinas a mano.
• Proyectos que quieren una forma sin código de disparar una cinemática desde un botón, una acción de input o un volumen de trigger a través de una señal generada.
• Equipos que necesitan revisar los tiempos y el contenido de una cinemática en el editor — recorriendo cada etapa — sin entrar en modo Play cada vez.

Sistemas relacionados

• Reproductor de Secuencias Un único motor asíncrono genérico para todo flujo ordenado de varios pasos — avisos de tutorial, intros de jefe, cambios de fase — reproducidos por el mismo servicio, declarativo en lugar de corrutinas anidadas.
• Sistema de Game Mode Transiciones de estado de juego tipadas con señales, estrategias de pausa y una puerta de disponibilidad a la que otros sistemas pueden suscribirse.
• Reproductor de música Música de fondo dirigida por definiciones de pista, transiciones configurables y señales tipadas que puedes enganchar al estado del juego.
• Screen Shake, Hit Stop y Screen Flash Screen shake, camera shake, UI shake, hit stop y flash de pantalla completa — todo creado en un FeedbackDefinition y disparado con una única llamada al servicio.