Sistema d'Onades

Per a què serveix aquest sistema

Els jocs per onades — shooters de supervivència, nivells de tower defense, shmups arcade — necessiten la mateixa columna vertebral: guionitzar una ràfega de spawns, esperar que el jugador la netegi i començar la següent, fins a acabar l'escenari. Sense un sistema dedicat, aquesta lògica acaba dispersa entre corrutines i números màgics, amb posicions de spawn cablejades a referències de Transform que es trenquen quan canvia el layout del nivell.

El Sistema d'Onades de Serenity ho separa en dues meitats que composen nètament. Una onada és una ràfega guionitzada — quin actor, quin punt de spawn, quin retard, quants, amb quina cadència — creada com a dades. Un escenari és el contenidor espacial que posseeix els punts de spawn amb nom on aquestes entrades apareixen. Els Wave Sets encadenen onades en ordre i avancen automàticament a mesura que cadascuna es neteja, sense pegament de corrutines.

El problema a Unity

La lògica d'onades feta a mà tendeix a cablejar les posicions de spawn com a referències d'escena, els recomptes com a números en línia i la regla d'avanç com una comprovació ad hoc en algun Update. Reutilitzar un layout d'onades en un segon escenari significa duplicar-ho i recablejar-ho tot. Balancejar una onada significa editar codi i tornar a entrar en mode Play per veure el resultat.

Els punts de spawn són un problema relacionat però diferent: les posicions de spawn d'un nivell pertanyen al seu layout espacial, no a una onada concreta. Acoblar les dades d'onada directament a Transforms d'escena fa impossible crear onades fora d'una escena concreta, i canviar el layout d'un nivell implica reescriure cada onada que hi spawneja.

Com ho aborda Serenity

Una onada és un UnityWaveConfigSO amb una llista ordenada de valors UnitySpawnEntry — actor, id de punt de spawn, retard, quantitat i cadència. Un UnityWaveSetSO ordenat encadena les onades d'un escenari, i IWaveService dirigeix la progressió: configura des del set, spawneja les entrades de l'onada 0, i quan RemainingActors arriba a zero a l'onada activa avança automàticament a la següent, fins a AllWavesClearedSignal.

Els punts de spawn viuen a part, a l'Escenari: un prefab amb un StageRoot i fills SpawnPoint amb nom, recollits per un SpawnPointRegistry opcional en una taula que el servei d'onades fa servir per resoldre l'id de punt de spawn de cada entrada. Canviar l'escenari on corre un wave set, o reutilitzar un layout de spawns entre nivells, és qüestió d'apuntar a un altre prefab d'escenari — les dades d'onada queden intactes.

Com encaixa a Serenity

Onades composa WaveClearedSignal i AllWavesClearedSignal a través de l'event dispatcher: el servei emet WaveClearedSignal quan el recompte d'actors restants d'una onada arriba a zero i ell mateix el consumeix per disparar la següent, així que l'avanç automàtic no requereix cablejat extern. AllWavesClearedSignal és el ganxo al qual reacciona un oient de finalització d'Escenari quan la partida acaba.

L'Escenari no posseeix dades d'onada pròpies — el seu StageRoot i el seu SpawnPointRegistry existeixen purament per donar al servei d'onades un resolutor d'ids de punt de spawn, mantenint l'autoria espacial (on passen les coses) i el contingut guionitzat (què passa i quan) com a peces independents i recombinables.

Flux de treball pràctic

1. Construeix un prefab d'escenari amb un StageRoot, un SpawnPointRegistry i un conjunt de fills SpawnPoint amb nom marcant on han d'aparèixer els actors.
2. Obre Tools ▸ Serenity ▸ Create ▸ Wave ▸ Create Wave Set i recorre Intent ▸ Stage ▸ Waves ▸ Timeline ▸ Preview ▸ Done per crear totes les onades d'aquest escenari en una sola passada.
3. Aprofita la validació de punts de spawn en viu del pas Stage, que informa del prefab exacte i l'estat dels punts de spawn de l'escenari triat abans de crear cap entrada.
4. Defineix les entrades de cada onada — actor, id de punt de spawn, retard, quantitat i cadència — i deixa que l'assistent les encadeni en un UnityWaveSetSO ordenat a la mateixa passada.
5. Connecta ConfigureFromWaveSet i SetSpawnPointResolver a l'arrel de composició i crida StartNextWave per arrencar l'onada 0; totes les següents avancen automàticament.
6. En mode Play, obre l'inspector de depuració en runtime per veure una taula d'onades en viu — estat, actors totals i restants per onada — més un botó Force Next Wave per saltar endavant mentre proves.

Què inclou

• IWaveService amb configuració des de set, progressió amb avanç automàtic i WaveClearedSignal / AllWavesClearedSignal
• Ràfegues de spawn UnityWaveConfigSO que guionitzen actor, id de punt de spawn, retard, quantitat i cadència per entrada
• Cadenes UnityWaveSetSO ordenades que dirigeixen una onada cada vegada i avancen automàticament en netejar-se cadascuna
• Assistent Create Wave Set — Intent ▸ Stage ▸ Waves ▸ Timeline ▸ Preview ▸ Done — que crea la cadena completa d'onades d'un escenari en una passada
• Validació de punts de spawn en viu a l'assistent, informant del prefab d'escenari i l'estat dels punts abans de crear entrades
• Punts de spawn propietat de l'escenari — StageRoot més fills SpawnPoint amb nom recollits per un resolutor SpawnPointRegistry
• Inspector de depuració en runtime amb taula d'onades en viu i botó Force Next Wave per iterar ràpid
• 1.3.0: la neteja d'una onada allibera només els actors que aquesta onada va spawnejar, mai els actors de pool d'altres sistemes

Quan fer-lo servir

• Shooters de supervivència, nivells de tower defense o jocs arcade que necessiten ràfegues d'enemics guionitzades encadenades en la progressió d'un nivell.
• Projectes que volen reutilitzar el mateix layout de spawns en diversos wave sets, o les mateixes onades en diversos layouts d'escenari.
• Equips que volen balancejar temps i quantitats de spawn com a dades, validats per un assistent, en lloc d'editar corrutines.
• Jocs on les onades han de conviure amb altres sistemes de spawn — encontres guionitzats, spawners ambientals — sense que un sistema alliberi els actors de pool d'un altre.

Sistemes relacionats

• Sistema de Spawn i Object Pooling Un servei de spawn d'entitats que abstrau el pooling d'objectes darrere de handles opacs perquè la lògica de joc no toqui mai la instanciació del motor directament.
• Sistema de Personatges Un sistema d'arquetips de personatge que valida cada soldat, tanc i cap com a dades, segueix cada instància viva pel seu cicle de vida complet i s'aparella amb una màquina d'estats d'arma pura per al combat.
• Sistema de Moviment sobre Rails Un servei de rails passiu basat en snapshots que rastreja el progrés normalitzat de 0 a 1 al llarg de camins de nodes amb nom, mantenint els sistemes de moviment, IA i càmera completament desacoblats.
• Gestió de sessions de joc Un servei de sessió centralitzat que és propietari del cicle de vida de cada partida — estat, temps transcorregut i identitat — perquè cap subsistema no l'hagi de duplicar.