Sistema de Oleadas

Para qué sirve este sistema

Los juegos por oleadas — shooters de supervivencia, niveles de tower defense, shmups arcade — necesitan la misma columna vertebral: guionizar una ráfaga de spawns, esperar a que el jugador la limpie y empezar la siguiente, hasta terminar el escenario. Sin un sistema dedicado, esa lógica acaba dispersa entre corrutinas y números mágicos, con posiciones de spawn cableadas a referencias de Transform que se rompen en cuanto cambia el layout del nivel.

El Sistema de Oleadas de Serenity lo separa en dos mitades que componen limpiamente. Una oleada es una ráfaga guionizada — qué actor, qué punto de spawn, qué retardo, cuántos, con qué cadencia — creada como datos. Un escenario es el contenedor espacial que posee los puntos de spawn con nombre donde esas entradas aparecen. Los Wave Sets encadenan oleadas en orden y avanzan automáticamente a medida que cada una se limpia, sin pegamento de corrutinas.

El problema en Unity

La lógica de oleadas hecha a mano tiende a cablear las posiciones de spawn como referencias de escena, los conteos como números en línea y la regla de avance como una comprobación ad hoc en algún Update. Reutilizar un layout de oleadas en un segundo escenario significa duplicarlo y recablearlo todo. Balancear una oleada significa editar código y volver a entrar en modo Play para ver el resultado.

Los puntos de spawn son un problema relacionado pero distinto: las posiciones de spawn de un nivel pertenecen a su layout espacial, no a una oleada concreta. Acoplar los datos de oleada directamente a Transforms de escena hace imposible crear oleadas fuera de una escena concreta, y cambiar el layout de un nivel implica reescribir cada oleada que spawnea en él.

Cómo lo aborda Serenity

Una oleada es un UnityWaveConfigSO con una lista ordenada de valores UnitySpawnEntry — actor, id de punto de spawn, retardo, cantidad y cadencia. Un UnityWaveSetSO ordenado encadena las oleadas de un escenario, e IWaveService dirige la progresión: configura desde el set, spawnea las entradas de la oleada 0, y cuando RemainingActors llega a cero en la oleada activa avanza automáticamente a la siguiente, hasta AllWavesClearedSignal.

Los puntos de spawn viven aparte, en el Escenario: un prefab con un StageRoot e hijos SpawnPoint con nombre, recogidos por un SpawnPointRegistry opcional en una tabla que el servicio de oleadas usa para resolver el id de punto de spawn de cada entrada. Cambiar el escenario donde corre un wave set, o reutilizar un layout de spawns entre niveles, es cuestión de apuntar a otro prefab de escenario — los datos de oleada quedan intactos.

Cómo encaja en Serenity

Oleadas compone WaveClearedSignal y AllWavesClearedSignal a través del event dispatcher: el servicio emite WaveClearedSignal cuando el conteo de actores restantes de una oleada llega a cero y él mismo lo consume para disparar la siguiente, así que el avance automático no requiere cableado externo. AllWavesClearedSignal es el gancho al que reacciona un oyente de finalización de Escenario cuando la partida termina.

El Escenario no posee datos de oleada propios — su StageRoot y su SpawnPointRegistry existen puramente para darle al servicio de oleadas un resolutor de ids de punto de spawn, manteniendo la autoría espacial (dónde ocurren las cosas) y el contenido guionizado (qué ocurre y cuándo) como piezas independientes y recombinables.

Flujo de trabajo práctico

1. Construye un prefab de escenario con un StageRoot, un SpawnPointRegistry y un conjunto de hijos SpawnPoint con nombre marcando dónde deben aparecer los actores.
2. Abre Tools ▸ Serenity ▸ Create ▸ Wave ▸ Create Wave Set y recorre Intent ▸ Stage ▸ Waves ▸ Timeline ▸ Preview ▸ Done para crear todas las oleadas de ese escenario en una sola pasada.
3. Aprovecha la validación de puntos de spawn en vivo del paso Stage, que informa del prefab exacto y el estado de los puntos de spawn del escenario elegido antes de crear una sola entrada.
4. Define las entradas de cada oleada — actor, id de punto de spawn, retardo, cantidad y cadencia — y deja que el asistente las encadene en un UnityWaveSetSO ordenado en la misma pasada.
5. Conecta ConfigureFromWaveSet y SetSpawnPointResolver en la raíz de composición y llama a StartNextWave para arrancar la oleada 0; todas las siguientes avanzan automáticamente.
6. En modo Play, abre el inspector de depuración en runtime para ver una tabla de oleadas en vivo — estado, actores totales y restantes por oleada — más un botón Force Next Wave para saltar adelante mientras pruebas.

Qué incluye

• IWaveService con configuración desde set, progresión con avance automático y WaveClearedSignal / AllWavesClearedSignal
• Ráfagas de spawn UnityWaveConfigSO que guionizan actor, id de punto de spawn, retardo, cantidad y cadencia por entrada
• Cadenas UnityWaveSetSO ordenadas que dirigen una oleada cada vez y avanzan automáticamente al limpiarse cada una
• Asistente Create Wave Set — Intent ▸ Stage ▸ Waves ▸ Timeline ▸ Preview ▸ Done — que crea la cadena completa de oleadas de un escenario en una pasada
• Validación de puntos de spawn en vivo en el asistente, informando del prefab de escenario y el estado de los puntos antes de crear entradas
• Puntos de spawn propiedad del escenario — StageRoot más hijos SpawnPoint con nombre recogidos por un resolutor SpawnPointRegistry
• Inspector de depuración en runtime con tabla de oleadas en vivo y botón Force Next Wave para iterar rápido
• 1.3.0: la limpieza de una oleada libera solo los actores que esa oleada spawneó, nunca los actores de pool de otros sistemas

Cuándo usarlo

• Shooters de supervivencia, niveles de tower defense o juegos arcade que necesitan ráfagas de enemigos guionizadas encadenadas en la progresión de un nivel.
• Proyectos que quieren reutilizar el mismo layout de spawns en varios wave sets, o las mismas oleadas en varios layouts de escenario.
• Equipos que quieren balancear tiempos y cantidades de spawn como datos, validados por un asistente, en lugar de editar corrutinas.
• Juegos donde las oleadas deben convivir con otros sistemas de spawn — encuentros guionizados, spawners ambientales — sin que un sistema libere los actores de pool de otro.

Sistemas relacionados

• Sistema de Spawn y Object Pooling Un servicio de spawn de entidades que abstrae el pooling de objetos detrás de handles opacos para que la lógica de juego nunca toque la instanciación del motor directamente.
• Sistema de Personajes Un sistema de arquetipos de personaje que valida cada soldado, tanque y jefe como datos, sigue cada instancia viva por su ciclo de vida completo y se empareja con una máquina de estados de arma pura para el combate.
• Sistema de Movimiento sobre Raíles Un servicio de raíles pasivo basado en snapshots que rastrea el progreso normalizado de 0 a 1 a lo largo de caminos de nodos con nombre, manteniendo los sistemas de movimiento, IA y cámara completamente desacoplados.
• 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.