Pipeline de Inicialización

Para qué sirve este sistema

Todo proyecto Unity tiene una secuencia de arranque. Los assets necesitan cargarse, los servicios registrarse, la configuración remota obtenerse y la sesión de juego prepararse antes de que el jugador vea el primer fotograma. Sin una estructura para esa secuencia, el código de arranque acaba disperso entre MonoBehaviours, cadenas de Awake y corrutinas imposibles de probar o extender.

La Pipeline de Inicialización de Serenity reemplaza ese código disperso con un conjunto ordenado de tareas asíncronas. Cada tarea declara su criticidad y peso, la pipeline las ejecuta en secuencia y el progreso y los errores se transmiten a un puerto de telemetría que cualquier pantalla de carga puede consumir.

El problema en Unity

El modelo de inicialización predeterminado de Unity es plano. Awake y Start se disparan en un orden que depende de la configuración del script execution order, frágil e invisible. Los equipos lo compensan con managers singleton, flags estáticos o cadenas de corrutinas que se rompen ante cualquier refactorización. No existe ningún mecanismo estándar para expresar que un paso de arranque es crítico y otro opcional, ni para mostrar una barra de progreso que refleje con precisión el trabajo de boot que queda.

A medida que el proyecto crece, la secuencia de arranque acumula dependencias silenciosas. Un servicio asume que otro ya está inicializado. Una petición remota falla silenciosamente y deja la sesión en un estado parcial. Una pantalla de carga muestra un spinner bloqueado porque nadie conectó los eventos de progreso. Estos problemas solo se manifiestan en tiempo de ejecución y solo en condiciones concretas de dispositivo o red.

Cómo lo aborda Serenity

Serenity modela cada paso de arranque como un ITask con un ID único, un nivel de TaskCriticality y un float Weight. TaskCriticality tiene tres valores: Critical, Required y Degradable. Las tareas Critical abortan la pipeline si fallan. Las Degradable registran el error y permiten que la pipeline continúe. La pipeline se define a través de IInitializationPipelineProfileDefinition, que expone una lista de solo lectura de instancias ITaskDefinition que construyen un ITask concreto en tiempo de ejecución mediante un TaskBuildContext.

El InitializationPipelineService recibe un conjunto ordenado de instancias ITask, un ISkipPolicy, un puerto IInitializationPipelineTelemetry y un ILogService. Construye un plan de registros InitializationPipelineStep y los ejecuta secuencialmente mediante RunAsync, llamando al puerto de telemetría en cada paso para que las pantallas de carga reciban los eventos OnStarted, OnProgress, OnTaskCompleted, OnTaskFailed y OnCompleted sin ningún acoplamiento con los internos de la pipeline.

Cómo encaja en Serenity

La Pipeline de Inicialización vive en el namespace Serenity.InitializationPipeline y sigue la estructura por capas de Dominio, Aplicación e Instalación de la foundation. La capa de Dominio define InitializationPipelineStep. La capa de Aplicación expone IInitializationPipelineProfileDefinition, IInitializationPipelineTelemetry, ISkipPolicy e InitializationPipelineService. La capa de Instalación provee InitializationPipelineInstaller y su DTO de entrada, que transporta los proveedores de tareas, la política de omisión, la implementación de telemetría y el servicio de log.

Las tareas se crean como definiciones basadas en ScriptableObject usando el agregado Task del namespace Serenity.Tasking. ITaskDefinition, ITaskFactory y TaskBuildContext gestionan el límite de creación. La implementación ReflectionCallTask permite apuntar una tarea a cualquier método del código fuente por nombre de tipo y método sin escribir una clase ITask dedicada. La pipeline coopera con el AssetPrefetcher y el flujo de trabajo de Addressables para calentar assets en el arranque, con Game Session para preparar la sesión y con el Event Dispatcher para publicar señales de inicio.

Flujo de trabajo práctico

1. Crea un ScriptableObject UnityInitializationPipelineProfile y añade las definiciones de tarea en el orden de ejecución deseado.
2. Asigna a cada definición de tarea un nivel de TaskCriticality y un float Weight que refleje su parte del tiempo de arranque.
3. Implementa IInitializationPipelineTelemetry en tu pantalla de carga para recibir eventos de progreso y error.
4. Opcionalmente implementa ISkipPolicy para permitir que tareas no críticas se omitan según las condiciones en tiempo de ejecución.
5. Registra la pipeline a través de UnityInitializationPipelineInstaller, pasando los proveedores, la política de omisión y la implementación de telemetría.
6. Llama a RunAsync en InitializationPipelineService al arrancar y espera el resultado booleano para saber si todas las tareas críticas tuvieron éxito.

Qué incluye

• Primitiva ITask con ID, TaskCriticality, Weight, RunAsync y LastError
• Tres niveles de criticidad: Critical, Required y Degradable
• Seguimiento del progreso ponderado a través de registros InitializationPipelineStep
• Puerto IInitializationPipelineTelemetry con OnStarted, OnProgress, OnTaskCompleted, OnTaskFailed y OnCompleted
• ISkipPolicy intercambiable para omitir tareas en tiempo de ejecución sin modificar el perfil
• IInitializationPipelineProfileDefinition y autoría mediante ScriptableObject con UnityInitializationPipelineProfile
• ReflectionCallTask para despacho de métodos sin código adicional y sin necesidad de una clase ITask dedicada
• UnityInitializationPipelineInstaller integrado en el patrón de instaladores de la foundation

Cuándo usarlo

• Proyectos que necesitan una secuencia de arranque fiable y ordenada antes de cargar la primera escena de gameplay.
• Juegos con pantalla de carga que debe reflejar el progreso real a través de tareas de inicio heterogéneas.
• Proyectos en los que algunos pasos de arranque son opcionales u omitibles según feature flags o capacidades del dispositivo.
• Bases de código que quieren que los pasos de inicio se creen desde el inspector de Unity sin escribir nuevas clases de C# para cada uno.

Sistemas relacionados

• Workflow de Addressables Asset prefetcher basado en servicio con contextos, etiquetas, políticas de caché y tareas de prewarm para Unity Addressables.
• Gestión de sesiones de juego Un servicio de sesión centralizado que es dueño del ciclo de vida de cada partida — estado, tiempo transcurrido e identidad — para que ningún subsistema tenga que duplicarlo.
• Precarga de Assets Una caché en memoria de Addressables en runtime con presupuesto de bytes configurable y expulsión LRU, precalentada por etiqueta en el arranque e inspeccionable en vivo con un Cache Inspector.
• 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.